NV oOS Pro Toolkit CRM
The Pro Toolkit CRM is a complete sales and customer relationship management
system built on WordPress Custom Post Types. It manages the full lifecycle:
lead capture → qualification → deal management → conversion → customer retention.
All entities are stored as CPT records accessible via the toolkit_cpt MCP tool.
WP-CLI Commands
Key mcp-ai WP-CLI commands for CRM operations. Run via terminal:
| Command |
Use for |
wp mcp-ai cron |
Check CRM automation cron events (lead scoring, workflow triggers) |
wp mcp-ai queue |
Inspect CRM background jobs, retry failed imports |
wp mcp-ai bulk |
Bulk import/export CRM records |
wp mcp-ai health |
Verify CRM system health before running automations |
wp mcp-ai log |
View CRM workflow execution logs |
When to use this skill
Trigger when ANY of the following is true:
- Viewing, searching, or filtering leads, deals, companies, customers, or activities.
- Creating or updating CRM records (leads, deals, companies, contacts, customers, activities, tickets).
- Qualifying leads using BANT or MEDDIC frameworks.
- Moving a deal through pipeline stages (inquiry → scoping → qualification → proposal → negotiation → engagement_signed).
- Converting a lead to a deal, or a deal to a customer.
- Logging sales activities: calls, emails, meetings, tasks, notes with dispositions.
- Building company profiles with industry, size, website, and status metadata.
- Managing support tickets with SLA tracking.
- Bulk importing leads or companies from CSV/email sources.
- Triaging the CRM pipeline — identifying hot leads, stalled deals, overdue follow-ups.
- Setting up CRM workflow rules for lead scoring, auto-assignment, or stage progression.
- Searching CRM records by email, company, status, or BANT score.
Mental model — CRM entities and lifecycle
The CRM is organized around six core entity types connected by a lifecycle:
LEAD ──(qualified)──→ DEAL ──(won)──→ CUSTOMER
│ │ │
├── activities ├── activities ├── activities
├── company ├── company ├── company
└── contacts └── contacts └── contacts
TICKET ─── support requests, independent of lifecycle but linked to contacts/companies
Relationships:
- A Lead can be linked to a Company and Contacts (via
_company_id, _contact_id meta).
- A Deal is linked to its source Lead via
lead_id meta.
- A Customer is the post-conversion record after a deal is won.
- Activities link to any entity via
related_type + related_id (e.g., related_type: "lead", related_id: 12398).
- Tickets are independent support records that may reference a customer or company.
CRM Entity Types
All CRM entities are managed through the toolkit_cpt MCP tool. Use the appropriate
post_type slug for each entity:
| CPT Slug |
Label |
Purpose |
Key Meta Fields |
mcp_ai_lead |
Leads |
Inbound lead capture, scored and staged |
first_name, last_name, email, phone, source, lead_status, lifecycle_stage, lead_score, bant_assessment |
mcp_ai_deal |
Deals |
Pipeline opportunities with stage tracking |
lead_id, deal_name, amount, currency, pipeline_stage, expected_close_date, deal_owner, win_probability |
mcp_ai_company |
Companies |
Organization profiles |
_company_industry, _company_size, _company_website, _company_phone, _company_address, _company_status, _company_assigned_to |
mcp_crm_contacts |
Contacts |
Individual contact records |
Custom meta (varies by implementation) |
mcp_ai_customer |
Customers |
Post-conversion customer records |
Custom meta (varies by implementation) |
mcp_ai_crm_activity |
Activities |
Calls, emails, meetings, tasks, notes |
activity_type, related_type, related_id, due_date |
mcp_ai_ticket |
Support Tickets |
ITIL-aligned SLA-tracked tickets |
Custom meta (varies by implementation) |
mcp_ai_sequence |
Sequences |
Automated outreach sequences |
Custom meta |
mcp_crm_campaigns |
Campaigns |
Marketing campaign records |
Custom meta |
mcp_ai_crm_wf_rule |
Workflow Rules |
Automation rules for CRM |
Custom meta |
Lead Meta Fields (detailed)
| Field |
Type |
Description |
Example |
first_name |
string |
Lead's first name |
"Jane" |
last_name |
string |
Lead's last name |
"Doe" |
email |
string |
Contact email address |
"jane.doe@example.com" |
phone |
string |
Contact phone number |
"" |
source |
string |
Lead source channel |
"email", "webform", "referral", "upwork" |
lead_status |
string |
Current lead status |
"new", "contacted", "qualified", "disqualified" |
lifecycle_stage |
string |
Lifecycle stage |
"lead", "mql", "sql", "opportunity" |
lead_score |
string |
Numeric lead score (0-100) |
"62" |
bant_assessment |
object |
BANT qualification scores |
See BANT/MEDDIC section below |
_source_message_id |
string |
Source email message ID |
"19fd8cceb7c8e589" |
Deal Meta Fields (detailed)
| Field |
Type |
Description |
Example |
lead_id |
string |
Source lead post ID |
"12324" |
deal_name |
string |
Descriptive deal name |
"NUGL Media - Growth Capital" |
amount |
string |
Deal amount (string for precision) |
"0", "50000" |
currency |
string |
ISO currency code |
"USD" |
pipeline_stage |
string |
Current pipeline stage |
"qualification" |
stage_history |
array |
Machine-readable transitions (from/to/at/source) |
see JobNavigator section |
stage_changed_at |
string |
ISO 8601 of the last real stage change |
"2026-09-16T09:00:00+00:00" |
last_email_received |
string |
Last inbound reply timestamp |
"2026-09-16T09:00:00+00:00" |
last_email_sentiment |
string |
Sentiment of the last reply |
"positive" |
expected_close_date |
string |
Expected close date |
"", "2026-09-15" |
deal_owner |
string |
WordPress user ID of owner |
"1" |
win_probability |
string |
Win probability (0-1) |
"0.1", "0.75" |
Pipeline stages (standard flow):
inquiry → scoping → qualification → proposal → negotiation → engagement_signed
└──→ won/lost
Activity Meta Fields (detailed)
| Field |
Type |
Description |
Example |
activity_type |
string |
Type of activity |
"task", "call", "email", "meeting", "note" |
related_type |
string |
Entity type this activity belongs to |
"lead", "deal", "company", "customer" |
related_id |
string |
Post ID of the related entity |
"12398" |
due_date |
string |
Due date for tasks |
"2026-08-08" |
Company Meta Fields (detailed)
| Field |
Type |
Description |
Example / Enum |
_company_industry |
string |
Industry vertical |
"Technology", "Healthcare", "Finance" |
_company_size |
string |
Size tier |
"1-10", "11-50", "51-200", "201-1000", "1000+" |
_company_website |
string |
Company website URL |
"https://example.com" |
_company_phone |
string |
Primary phone |
"+1-555-0100" |
_company_address |
string |
Headquarters address |
"123 Main St, Suite 100" |
_company_status |
string |
CRM pipeline status |
"prospect", "lead", "qualified", "customer", "churned" |
_company_assigned_to |
int |
WordPress user ID of owner |
1 |
BANT / MEDDIC Scoring
Leads are automatically scored using BANT (Budget, Authority, Need, Timeline) with
four sub-scores, each 0-100. The bant_assessment object has this structure:
{
"budget": {
"score": 50,
"evidence": "invest; $; "
},
"authority": {
"score": 50,
"evidence": "cto; director; "
},
"need": {
"score": 100,
"evidence": "need; problem; challenge; solution; "
},
"timeline": {
"score": 75,
"evidence": "urgent; by; immediately; "
}
}
Total BANT score = sum of all four sub-scores (max 400).
For enterprise deals, supplement BANT with MEDDIC:
- Metrics: Quantifiable value the solution delivers.
- Economic Buyer: Who controls the budget?
- Decision Criteria: What are the formal evaluation criteria?
- Decision Process: What's the purchasing process?
- Identified Pain: What problem are they solving?
- Champion: Who is your internal advocate?
Use bant_assessment for automated lead scoring. For enterprise deals, manually track
MEDDIC elements in the deal content field or as additional meta.
Available Tools
All CRM operations use the toolkit_cpt MCP tool. This is the single interface
for all CRM CRUD operations.
Discovery
# List all available CRM post types
toolkit_cpt(action: "list_types")
# Get field schema for any CRM type
toolkit_cpt(action: "get_schema", post_type: "mcp_ai_lead")
Upwork job search (search_upwork_jobs)
Freelancer sourcing uses the Upwork CRM tools (search_upwork_jobs,
score_upwork_job, draft_upwork_proposal). Key behaviour:
- Args:
query, location (folded into the GraphQL searchExpression,
e.g. wordpress developer (Remote)), job_type (hourly/fixed/all —
all or omitted = no filter), experience_level
(entry/intermediate/expert/all), skills, budget_min/max,
exclude_keywords (API: boolean NOT (a OR b); fallback: -"a"
operators), sort (recency default — sends GraphQL
sortAttributes: [{field: RECENCY}]; best_match), limit, cursor.
Omitted filters resolve from CRM Settings → Upwork → Search Defaults
(default_search_keywords, default_location, …). "all" sentinels are
normalised away, so preset steps carrying job_type: "all" never leak the
literal into the GraphQL filter.
- Every response echoes its criteria —
criteria (the effective
query/location/skills/filters/sort/limit after defaults) and
criteria_provided (false = unfiltered noise search) — so workflow digests
can tell weak filters from a missing Upwork connection.
- API mode (Remote Sites connection with OAuth creds): returns structured
jobs including a derived
url
(https://www.upwork.com/jobs/<slug>_~<id>/ — the canonical marketplace
job-page form).
- MCP mode (Remote Sites connection with
upwork_mode: mcp, v1.1.89):
routes the search through the official Upwork MCP gateway
(https://mcp.upwork.com/mcp) via WP_MCP_AI_Upwork_MCP_Bridge —
upwork__find_jobs (action search/get) returns envelopes normalized to
the same shape as API mode, and upwork__list_accounts resolves the
upwork_org_uid stored on the connection. Test Connection runs a real MCP
handshake and validates without GraphQL credentials; tokens persist to the
encrypted central mcp_oauth store (auto-refresh via the attached OAuth
client).
- Fallback mode (no connection, or MCP mode without a token blob): two-pass web search — site-restricted
Upwork pass, then a broader pass merged with URL dedupe. Upwork category
landing pages (
/freelance-jobs/{slug}/ — no ~jobId) are filtered out
and reported in filtered_out, as are non-marketplace Upwork subdomains
(community.upwork.com, support.upwork.com) and category/help-centre
page titles; snippets are parsed for job_type, budget/budget_max
(ranges), tier (Entry level/Intermediate/Expert), and published;
skills build a quoted OR group; direct postings rank first.
- Fallback URLs are canonicalised. SERP URLs (the
/freelance-jobs/apply/<slug>_~<jobId>/ SEO form, often with tracking query
strings like referrer_url_path that Upwork's SPA mishandles) are rewritten
to the canonical https://www.upwork.com/jobs/<slug>_~<jobId>/ marketplace
form with the query string dropped — the form that reliably resolves to the
listing (verified against the vanooo/upwork-mcp live-SPA scraper, which
keeps only /jobs/ links). Login-walled SPA surfaces (/nx/…, /o/jobs/…,
/r/…) are dropped as non-listings, except /nx/search/jobs/details/~<jobId>
which is rebuilt to the bare-ID form. Non-Upwork aggregator links pass
through unchanged.
- The fallback needs a real search provider. With the default
DuckDuckGo provider the fallback returns 0 results (Instant Answer API
has no SERPs). Set a Brave/Tavily key in plugin Settings → Web Search.
- A bare query (no keywords, no defaults) returns the guidance notice
("unfiltered marketplace noise") — configure default keywords or pass
query/skills for targeted results.
Reading records
// List leads (most recent first):
{ "action": "list_items", "post_type": "mcp_ai_lead", "orderby": "date", "order": "DESC", "per_page": 20 }
// Search leads by email:
{ "action": "list_items", "post_type": "mcp_ai_lead", "search": "jane.doe@example.com" }
// Filter by meta field:
{ "action": "list_items", "post_type": "mcp_ai_lead", "filters": [{ "key": "lead_status", "value": "new" }] }
// Get a single record:
{ "action": "get_item", "post_type": "mcp_ai_lead", "item_id": 12398 }
Creating records
// Create a lead with BANT scoring:
{ "action": "create_item", "post_type": "mcp_ai_lead", "fields": {
"title": "Jane Smith", "first_name": "Jane", "last_name": "Smith",
"email": "jane@acmecorp.com", "phone": "+1-555-0100", "source": "referral",
"lead_status": "new", "lifecycle_stage": "lead", "lead_score": "50",
"bant_assessment": {
"budget": { "score": 0, "evidence": "" },
"authority": { "score": 25, "evidence": "manager;" },
"need": { "score": 50, "evidence": "looking for;" },
"timeline": { "score": 25, "evidence": "soon;" }
}
} }
// Create a company:
{ "action": "create_item", "post_type": "mcp_ai_company", "fields": {
"title": "Acme Corporation", "_company_industry": "Manufacturing",
"_company_size": "201-1000", "_company_website": "https://acmecorp.com",
"_company_phone": "+1-555-0200", "_company_status": "prospect"
} }
// Log an activity:
{ "action": "create_item", "post_type": "mcp_ai_crm_activity", "fields": {
"title": "Discovery call with Jane Smith (Lead #12400)",
"activity_type": "call", "related_type": "lead", "related_id": "12400",
"due_date": "2026-08-14"
} }
Updating records
// Qualify a lead:
{ "action": "update_item", "post_type": "mcp_ai_lead", "item_id": 12398,
"fields": { "lead_status": "qualified", "lifecycle_stage": "sql" } }
// Move a deal through pipeline stages:
{ "action": "update_item", "post_type": "mcp_ai_deal", "item_id": 12327,
"fields": { "pipeline_stage": "proposal", "win_probability": "0.5",
"expected_close_date": "2026-09-15", "amount": "25000" } }
Bulk operations
// Bulk create leads from a CSV import:
{ "action": "bulk_create", "post_type": "mcp_ai_lead", "items": [
{ "title": "Alice Brown", "first_name": "Alice", "last_name": "Brown",
"email": "alice@example.com", "source": "csv_import", "lead_status": "new" },
{ "title": "Bob Wilson", "first_name": "Bob", "last_name": "Wilson",
"email": "bob@example.com", "source": "csv_import", "lead_status": "new" }
] }
Deleting records
// Delete a lead (prefer disqualifying instead — see Critical Rules):
{ "action": "delete_item", "post_type": "mcp_ai_lead", "item_id": 12398 }
⚠️ Warning: Deleting a record is permanent. Consider using update_item to
change lead_status to "disqualified" instead of deleting, to preserve audit history.
Common Workflows
Lead qualification workflow
1. List new leads: list_items(mcp_ai_lead, filters: [{key: "lead_status", value: "new"}])
2. Review BANT: Check bant_assessment scores. Prioritize high Need + Timeline.
3. Create activity: create_item(mcp_ai_crm_activity, activity_type: "call")
4. Update lead: update_item(mcp_ai_lead, lead_status: "contacted")
5. If qualified: update_item(mcp_ai_lead, lead_status: "qualified", lifecycle_stage: "sql")
create_item(mcp_ai_deal, lead_id: <lead_id>, pipeline_stage: "qualification")
Deal pipeline management
1. Find stalled deals: list_items(mcp_ai_deal, filters per pipeline_stage)
2. Check activities: list_items(mcp_ai_crm_activity, filters: [{key: "related_id", value: "<deal_id>"}])
3. Advance stage: update_item(mcp_ai_deal, pipeline_stage: <next_stage>, win_probability: <new_prob>)
4. Log activity: create_item(mcp_ai_crm_activity, activity_type: "note", content: "<disposition>")
Pipeline stage progression with win probabilities
| Stage |
Win Probability |
Typical Actions |
inquiry |
5% |
Initial contact, needs discovery |
scoping |
10% |
Define requirements, budget range |
qualification |
25% |
BANT/MEDDIC confirmed, champion identified |
proposal |
50% |
Proposal sent, economic buyer engaged |
negotiation |
75% |
Terms negotiation, legal review |
engagement_signed |
90% |
Contract signed, onboarding begins |
won |
100% |
Revenue recognized |
lost |
0% |
Closed-lost with reason |
Building a company profile
1. Research company: Use deep_research or web_search_validated for company info.
2. Create company: create_item(mcp_ai_company, with industry, size, website, status).
3. Link lead: update_item(mcp_ai_lead, adding _company_id reference to the company post ID).
4. Add contacts: create_item(mcp_crm_contacts) for key personas at the company.
Activity logging (call disposition)
After every call/meeting:
1. create_item(mcp_ai_crm_activity, activity_type: "call"|"meeting"|"email")
2. Set title: "<Action> with <Contact Name> (<Entity> #<ID>)"
3. Set related_type: "lead" | "deal" | "company" | "customer"
4. Set related_id: The entity post ID
5. Set content: Summary of the conversation, next steps, disposition
6. Set due_date: For follow-up tasks (activity_type: "task")
Pipeline triage
Weekly pipeline review:
1. list_items(mcp_ai_lead, filters: [{key: "lead_status", value: "new"}])
→ Identify high-score leads (lead_score >= 60) for immediate follow-up.
2. list_items(mcp_ai_deal, filters: [{key: "pipeline_stage", value: "qualification"}])
→ Find deals stuck in qualification for 2+ weeks — they need a champion.
3. list_items(mcp_ai_crm_activity, filters: [{key: "activity_type", value: "task"}])
→ Check for overdue follow-up tasks (due_date < today).
4. list_items(mcp_ai_lead, filters: [{key: "lead_status", value: "disqualified"}])
→ Review disqualified leads — some may be worth re-engaging.
Searching across CRM
// Find all leads from a specific company domain:
{ "action": "list_items", "post_type": "mcp_ai_lead", "search": "@example.com" }
// Find all activities for a lead:
{ "action": "list_items", "post_type": "mcp_ai_crm_activity",
"filters": [{ "key": "related_type", "value": "lead" },
{ "key": "related_id", "value": "12398" }] }
JobNavigator-Adoption Features (v3.2.0)
Adopted from vesaias/JobNavigator;
full plan in docs/developer/crm-toolkit-jobnavigator-adoption-plan.md.
Stage transition history (deals)
Every move_deal_stage (and create_deal) appends a machine-readable
entry to the deal's stage_history meta:
{ "from": "prospecting", "to": "qualification", "at": "2026-09-16T…", "source": "tool" }
source is one of tool, agent, workflow, manual, email_reply, bulk.
stage_changed_at meta stamps the last real change — drives time-in-stage
and stalled-deal detection. No-op stage moves never bump updated_at.
move_deal_stage accepts undo: true to revert the last move without
recording a new transition (audits deal_stage_reverted).
- Helper:
WP_MCP_AI_CRM_Stage_History (record, get_history,
undo_last, time_in_stage, next_open_stage).
Lead dedup, companies, signals
create_lead refuses duplicates by normalized email with a 409
wp_mcp_ai_duplicate_lead error carrying existing_lead_id;
pass allow_duplicate: true to force-create.
create_lead auto-links company_name to a canonical company record
(case/space-insensitive; auto-creates when missing) via
WP_MCP_AI_CRM_Identity. Settings: identity.auto_create_company
(default true), identity.auto_create_company_from_domain (default false),
identity.dedupe_leads (default true).
- Lead/deal email signals:
last_email_received, last_email_snippet
(capped 500), last_email_sentiment (positive|neutral|negative|mixed|unknown).
- Auto-disqualification: settings
auto_disqualify block
(enabled, max_score, min_age_days, only_statuses) — evaluated
on lead create/update, fires wp_mcp_ai_crm_lead_auto_disqualified.
New tools
| Slug |
Purpose |
bulk_move_deal_stages |
Move up to 100 deals to one stage; reports updated/skipped/not_found; supports undo |
record_crm_reply |
Store reply signals on lead + open deals; optionally advance a deal (advance_deal: true) with source email_reply |
get_crm_handover |
Paste-ready plain-text bundle (facts, BANT, stage history, signals, activities + closing ask) for any AI/human handoff |
get_pipeline_digest |
Compact digest text + data: stage totals, pipeline value, stalled deals, hot leads, overdue tasks |
create_tracked_link |
Create a ?nvoos_track=<token> link for a deal; opens recorded on the deal |
delete_deal on a closed_won deal releases the lead lifecycle back to
opportunity when no other won deal remains (hook wp_mcp_ai_crm_deal_deleted).
Gmail reply poller (v3.2.0)
Settings gmail_reply_poll block (enabled default false,
advance_on_positive default false, max_per_poll 10,
min_interval_minutes 15). When enabled, the cron
(wp_mcp_ai_crm_gmail_reply_poll) polls Gmail for unread replies via the
Gmail client + Remote Sites connections, matches senders to leads by
normalized email, classifies sentiment via WP_MCP_AI_CRM_Classifier, and
applies signals through WP_MCP_AI_Tool_Record_CRM_Reply::apply(). Unknown
senders are skipped; the wp_mcp_ai_crm_classify_intent filter can swap in
an LLM classifier. Last-poll stamp: wp_mcp_ai_crm_reply_last_poll option.
Pipeline digest scheduling (recipe asset, no code)
addons/pro/config/pipeline-digest-recipe.json — an importable recipe:
workflow nodes get_pipeline_digest → send_telegram_message
({{digest.result.text}} template) plus a create_pro_schedule daily
config. Apply via the Pro Workflow Builder + Pro Schedule Manager MCP tools;
swap the delivery node for WhatsApp or local persistence as needed.
Critical Rules
- Always use
get_schema first before creating or updating a record to verify available field keys and types.
- Lead scoring is automated — the
lead_score and bant_assessment are populated by the CRM engine. Manual overrides should be rare and documented.
- Never delete leads — use
lead_status: "disqualified" to preserve audit trail and prevent re-import of the same contact.
- Activities are the audit trail — log every meaningful interaction (call, email, meeting, note) with
related_type and related_id.
- Deal pipeline stages are sequential — don't skip stages. Each stage transition should have an activity log.
deal_owner is a WordPress user ID — ensure the user exists and has appropriate CRM capabilities.
win_probability is a float stored as string — use "0.1" not 0.1 in JSON.
- BANT
evidence is semicolon-delimited — the engine parses email content for keyword evidence. When manually setting, use "keyword1; keyword2; " format.
- Bulk operations (
bulk_create) are for imports — each item must be a complete fields object. Existing records with matching IDs will be overwritten.
- Support tickets (
mcp_ai_ticket) are SLA-tracked — create them for customer issues, not sales inquiries.
Common Mistakes
WRONG — deleting a lead instead of disqualifying
{ "action": "delete_item", "post_type": "mcp_ai_lead", "item_id": 12398 }
RIGHT — disqualify to preserve history
{ "action": "update_item", "post_type": "mcp_ai_lead", "item_id": 12398,
"fields": { "lead_status": "disqualified" } }
WRONG — creating a deal without linking to a lead
{ "action": "create_item", "post_type": "mcp_ai_deal",
"fields": { "deal_name": "Some Deal", "pipeline_stage": "qualification" } }
// Missing lead_id — the deal has no source traceability.
RIGHT — always link deals to their source lead
{ "action": "create_item", "post_type": "mcp_ai_deal",
"fields": { "lead_id": "12398", "deal_name": "Acme Corp - Audit Automation",
"pipeline_stage": "scoping", "amount": "0", "currency": "USD", "deal_owner": "1",
"win_probability": "0.1" } }
WRONG — logging an activity without related_type or related_id
{ "action": "create_item", "post_type": "mcp_ai_crm_activity",
"fields": { "title": "Call with prospect", "activity_type": "call" } }
// This activity is orphaned — it can't be found when viewing the lead/deal.
RIGHT — always link activities to their parent entity
{ "action": "create_item", "post_type": "mcp_ai_crm_activity",
"fields": { "title": "Discovery call with Jane Doe (Lead #12398)",
"activity_type": "call", "related_type": "lead", "related_id": "12398" } }
WRONG — skipping pipeline stages
// Moving from "inquiry" directly to "proposal" with no scoping or qualification.
// The pipeline history should reflect the actual sales process.
RIGHT — advance stage-by-stage with activity log
1. update_item: pipeline_stage: "scoping"
2. create_item(activity): "Scope of work discussed"
3. update_item: pipeline_stage: "qualification"
4. create_item(activity): "BANT confirmed, champion identified"
5. update_item: pipeline_stage: "proposal"
WRONG — setting win_probability to 0 or 1 prematurely
// Win probability should reflect real pipeline stage, not optimism/pessimism.
WRONG — searching with filters that use meta keys not in the schema
// Some meta fields may be added dynamically. Always call get_schema first
// to confirm which fields are registered and filterable.
Cross-References
- Run
design-deep-research to research target companies before creating company profiles.
- Run
design-web-research for quick company lookups and competitive intelligence.
- Run
design-pro-workflow-builder to automate CRM workflows (lead scoring, auto-assignment, stage progression).
- Run
design-pro-schedule-manager to schedule recurring CRM tasks (pipeline reviews, follow-up reminders).
- Run
design-document-generation to create proposals, SOWs, and invoices from deal data.
- Run
wp-security-audit on any CRM automation callbacks — CRM data is sensitive and must be access-controlled.
What This Skill Does NOT Cover
- Email integration details (Gmail/Outlook sync) — use
search_gmail for inbox queries.
- Remote WordPress CRM access — use
nv_oos_console_agent_remote_wp_connection for multi-site CRM.
- Paper Store integration — use
paper_store_* tools for research-backed company profiles.
- ERP integration (EZuite) — use
ezuite_erp / ezuite_erp_get_products for ERP-connected CRM data.
- CRM workflow rule configuration — use
toolkit_cpt with post_type: "mcp_ai_crm_wf_rule" and the design-pro-workflow-builder skill.
- Sequence automation — use
toolkit_cpt with post_type: "mcp_ai_sequence".
References
- NV oOS Pro Toolkit CRM admin page:
/wp-admin/admin.php?page=nvoos-pro-toolkit-crm
toolkit_cpt MCP tool — the primary interface for all CRM operations.
- BANT framework: blog.hubspot.com/sales/bant
- MEDDIC framework: meddic.co
1---2type: Skill3name: design-crm4description: Manage the NV oOS Pro Toolkit CRM — leads, deals, companies, contacts, customers, activities, and support tickets. Covers the complete sales pipeline from lead capture through qualification, deal management, and post-conversion customer tracking with BANT/MEDDIC scoring, activity logging, and workflow automation. Use when working with CRM records, managing pipeline stages, qualifying leads, creating company profiles, logging calls/emails/meetings, or troubleshooting CRM data issues.5license: Proprietary. See LICENSE.txt6metadata:7 source: https://skillmd.com/skills/nvdigitalsolutions/design-crm8 type: Skill9---1011# NV oOS Pro Toolkit CRM1213The Pro Toolkit CRM is a complete sales and customer relationship management14system built on WordPress Custom Post Types. It manages the full lifecycle:15**lead capture → qualification → deal management → conversion → customer retention**.16All entities are stored as CPT records accessible via the `toolkit_cpt` MCP tool.1718## WP-CLI Commands1920Key `mcp-ai` WP-CLI commands for CRM operations. Run via `terminal`:2122| Command | Use for |23|---|---|24| `wp mcp-ai cron` | Check CRM automation cron events (lead scoring, workflow triggers) |25| `wp mcp-ai queue` | Inspect CRM background jobs, retry failed imports |26| `wp mcp-ai bulk` | Bulk import/export CRM records |27| `wp mcp-ai health` | Verify CRM system health before running automations |28| `wp mcp-ai log` | View CRM workflow execution logs |2930## When to use this skill3132Trigger when ANY of the following is true:3334- Viewing, searching, or filtering leads, deals, companies, customers, or activities.35- Creating or updating CRM records (leads, deals, companies, contacts, customers, activities, tickets).36- Qualifying leads using BANT or MEDDIC frameworks.37- Moving a deal through pipeline stages (inquiry → scoping → qualification → proposal → negotiation → engagement_signed).38- Converting a lead to a deal, or a deal to a customer.39- Logging sales activities: calls, emails, meetings, tasks, notes with dispositions.40- Building company profiles with industry, size, website, and status metadata.41- Managing support tickets with SLA tracking.42- Bulk importing leads or companies from CSV/email sources.43- Triaging the CRM pipeline — identifying hot leads, stalled deals, overdue follow-ups.44- Setting up CRM workflow rules for lead scoring, auto-assignment, or stage progression.45- Searching CRM records by email, company, status, or BANT score.4647## Mental model — CRM entities and lifecycle4849The CRM is organized around six core entity types connected by a lifecycle:5051```52LEAD ──(qualified)──→ DEAL ──(won)──→ CUSTOMER53 │ │ │54 ├── activities ├── activities ├── activities55 ├── company ├── company ├── company56 └── contacts └── contacts └── contacts5758TICKET ─── support requests, independent of lifecycle but linked to contacts/companies59```6061**Relationships:**62- A **Lead** can be linked to a **Company** and **Contacts** (via `_company_id`, `_contact_id` meta).63- A **Deal** is linked to its source **Lead** via `lead_id` meta.64- A **Customer** is the post-conversion record after a deal is won.65- **Activities** link to any entity via `related_type` + `related_id` (e.g., `related_type: "lead"`, `related_id: 12398`).66- **Tickets** are independent support records that may reference a customer or company.6768## CRM Entity Types6970All CRM entities are managed through the **`toolkit_cpt`** MCP tool. Use the appropriate71`post_type` slug for each entity:7273| CPT Slug | Label | Purpose | Key Meta Fields |74|---|---|---|---|75| `mcp_ai_lead` | Leads | Inbound lead capture, scored and staged | `first_name`, `last_name`, `email`, `phone`, `source`, `lead_status`, `lifecycle_stage`, `lead_score`, `bant_assessment` |76| `mcp_ai_deal` | Deals | Pipeline opportunities with stage tracking | `lead_id`, `deal_name`, `amount`, `currency`, `pipeline_stage`, `expected_close_date`, `deal_owner`, `win_probability` |77| `mcp_ai_company` | Companies | Organization profiles | `_company_industry`, `_company_size`, `_company_website`, `_company_phone`, `_company_address`, `_company_status`, `_company_assigned_to` |78| `mcp_crm_contacts` | Contacts | Individual contact records | Custom meta (varies by implementation) |79| `mcp_ai_customer` | Customers | Post-conversion customer records | Custom meta (varies by implementation) |80| `mcp_ai_crm_activity` | Activities | Calls, emails, meetings, tasks, notes | `activity_type`, `related_type`, `related_id`, `due_date` |81| `mcp_ai_ticket` | Support Tickets | ITIL-aligned SLA-tracked tickets | Custom meta (varies by implementation) |82| `mcp_ai_sequence` | Sequences | Automated outreach sequences | Custom meta |83| `mcp_crm_campaigns` | Campaigns | Marketing campaign records | Custom meta |84| `mcp_ai_crm_wf_rule` | Workflow Rules | Automation rules for CRM | Custom meta |8586### Lead Meta Fields (detailed)8788| Field | Type | Description | Example |89|---|---|---|---|90| `first_name` | string | Lead's first name | `"Jane"` |91| `last_name` | string | Lead's last name | `"Doe"` |92| `email` | string | Contact email address | `"jane.doe@example.com"` |93| `phone` | string | Contact phone number | `""` |94| `source` | string | Lead source channel | `"email"`, `"webform"`, `"referral"`, `"upwork"` |95| `lead_status` | string | Current lead status | `"new"`, `"contacted"`, `"qualified"`, `"disqualified"` |96| `lifecycle_stage` | string | Lifecycle stage | `"lead"`, `"mql"`, `"sql"`, `"opportunity"` |97| `lead_score` | string | Numeric lead score (0-100) | `"62"` |98| `bant_assessment` | object | BANT qualification scores | See BANT/MEDDIC section below |99| `_source_message_id` | string | Source email message ID | `"19fd8cceb7c8e589"` |100101### Deal Meta Fields (detailed)102103| Field | Type | Description | Example |104|---|---|---|---|105| `lead_id` | string | Source lead post ID | `"12324"` |106| `deal_name` | string | Descriptive deal name | `"NUGL Media - Growth Capital"` |107| `amount` | string | Deal amount (string for precision) | `"0"`, `"50000"` |108| `currency` | string | ISO currency code | `"USD"` |109| `pipeline_stage` | string | Current pipeline stage | `"qualification"` |110| `stage_history` | array | Machine-readable transitions (from/to/at/source) | see JobNavigator section |111| `stage_changed_at` | string | ISO 8601 of the last real stage change | `"2026-09-16T09:00:00+00:00"` |112| `last_email_received` | string | Last inbound reply timestamp | `"2026-09-16T09:00:00+00:00"` |113| `last_email_sentiment` | string | Sentiment of the last reply | `"positive"` |114| `expected_close_date` | string | Expected close date | `""`, `"2026-09-15"` |115| `deal_owner` | string | WordPress user ID of owner | `"1"` |116| `win_probability` | string | Win probability (0-1) | `"0.1"`, `"0.75"` |117118**Pipeline stages (standard flow):**119```120inquiry → scoping → qualification → proposal → negotiation → engagement_signed121 └──→ won/lost122```123124### Activity Meta Fields (detailed)125126| Field | Type | Description | Example |127|---|---|---|---|128| `activity_type` | string | Type of activity | `"task"`, `"call"`, `"email"`, `"meeting"`, `"note"` |129| `related_type` | string | Entity type this activity belongs to | `"lead"`, `"deal"`, `"company"`, `"customer"` |130| `related_id` | string | Post ID of the related entity | `"12398"` |131| `due_date` | string | Due date for tasks | `"2026-08-08"` |132133### Company Meta Fields (detailed)134135| Field | Type | Description | Example / Enum |136|---|---|---|---|137| `_company_industry` | string | Industry vertical | `"Technology"`, `"Healthcare"`, `"Finance"` |138| `_company_size` | string | Size tier | `"1-10"`, `"11-50"`, `"51-200"`, `"201-1000"`, `"1000+"` |139| `_company_website` | string | Company website URL | `"https://example.com"` |140| `_company_phone` | string | Primary phone | `"+1-555-0100"` |141| `_company_address` | string | Headquarters address | `"123 Main St, Suite 100"` |142| `_company_status` | string | CRM pipeline status | `"prospect"`, `"lead"`, `"qualified"`, `"customer"`, `"churned"` |143| `_company_assigned_to` | int | WordPress user ID of owner | `1` |144145## BANT / MEDDIC Scoring146147Leads are automatically scored using **BANT** (Budget, Authority, Need, Timeline) with148four sub-scores, each 0-100. The `bant_assessment` object has this structure:149150```json151{152 "budget": {153 "score": 50,154 "evidence": "invest; $; "155 },156 "authority": {157 "score": 50,158 "evidence": "cto; director; "159 },160 "need": {161 "score": 100,162 "evidence": "need; problem; challenge; solution; "163 },164 "timeline": {165 "score": 75,166 "evidence": "urgent; by; immediately; "167 }168}169```170171**Total BANT score** = sum of all four sub-scores (max 400).172173For **enterprise deals**, supplement BANT with MEDDIC:174- **M**etrics: Quantifiable value the solution delivers.175- **E**conomic Buyer: Who controls the budget?176- **D**ecision Criteria: What are the formal evaluation criteria?177- **D**ecision Process: What's the purchasing process?178- **I**dentified Pain: What problem are they solving?179- **C**hampion: Who is your internal advocate?180181Use `bant_assessment` for automated lead scoring. For enterprise deals, manually track182MEDDIC elements in the deal `content` field or as additional meta.183184## Available Tools185186All CRM operations use the **`toolkit_cpt`** MCP tool. This is the single interface187for all CRM CRUD operations.188189### Discovery190191```192# List all available CRM post types193toolkit_cpt(action: "list_types")194195# Get field schema for any CRM type196toolkit_cpt(action: "get_schema", post_type: "mcp_ai_lead")197```198199### Upwork job search (`search_upwork_jobs`)200201Freelancer sourcing uses the Upwork CRM tools (`search_upwork_jobs`,202`score_upwork_job`, `draft_upwork_proposal`). Key behaviour:203204- **Args:** `query`, `location` (folded into the GraphQL `searchExpression`,205 e.g. `wordpress developer (Remote)`), `job_type` (`hourly`/`fixed`/`all` —206 `all` or omitted = no filter), `experience_level`207 (`entry`/`intermediate`/`expert`/`all`), `skills`, `budget_min/max`,208 `exclude_keywords` (API: boolean `NOT (a OR b)`; fallback: `-"a"`209 operators), `sort` (`recency` default — sends GraphQL210 `sortAttributes: [{field: RECENCY}]`; `best_match`), `limit`, `cursor`.211 Omitted filters resolve from **CRM Settings → Upwork → Search Defaults**212 (`default_search_keywords`, `default_location`, …). `"all"` sentinels are213 normalised away, so preset steps carrying `job_type: "all"` never leak the214 literal into the GraphQL filter.215- **Every response echoes its criteria** — `criteria` (the effective216 query/location/skills/filters/sort/limit after defaults) and217 `criteria_provided` (false = unfiltered noise search) — so workflow digests218 can tell weak filters from a missing Upwork connection.219- **API mode** (Remote Sites connection with OAuth creds): returns structured220 jobs including a derived `url`221 (`https://www.upwork.com/jobs/<slug>_~<id>/` — the canonical marketplace222 job-page form).223- **MCP mode** (Remote Sites connection with `upwork_mode: mcp`, v1.1.89):224 routes the search through the official Upwork MCP gateway225 (`https://mcp.upwork.com/mcp`) via `WP_MCP_AI_Upwork_MCP_Bridge` —226 `upwork__find_jobs` (action `search`/`get`) returns envelopes normalized to227 the same shape as API mode, and `upwork__list_accounts` resolves the228 `upwork_org_uid` stored on the connection. Test Connection runs a real MCP229 handshake and validates without GraphQL credentials; tokens persist to the230 **encrypted** central `mcp_oauth` store (auto-refresh via the attached OAuth231 client).232- **Fallback mode** (no connection, or MCP mode without a token blob): two-pass web search — site-restricted233 Upwork pass, then a broader pass merged with URL dedupe. Upwork category234 landing pages (`/freelance-jobs/{slug}/` — no `~jobId`) are filtered out235 and reported in `filtered_out`, as are non-marketplace Upwork subdomains236 (`community.upwork.com`, `support.upwork.com`) and category/help-centre237 page titles; snippets are parsed for `job_type`, `budget`/`budget_max`238 (ranges), `tier` (Entry level/Intermediate/Expert), and `published`;239 `skills` build a quoted OR group; direct postings rank first.240- **Fallback URLs are canonicalised.** SERP URLs (the241 `/freelance-jobs/apply/<slug>_~<jobId>/` SEO form, often with tracking query242 strings like `referrer_url_path` that Upwork's SPA mishandles) are rewritten243 to the canonical `https://www.upwork.com/jobs/<slug>_~<jobId>/` marketplace244 form with the query string dropped — the form that reliably resolves to the245 listing (verified against the vanooo/upwork-mcp live-SPA scraper, which246 keeps only `/jobs/` links). Login-walled SPA surfaces (`/nx/…`, `/o/jobs/…`,247 `/r/…`) are dropped as non-listings, except `/nx/search/jobs/details/~<jobId>`248 which is rebuilt to the bare-ID form. Non-Upwork aggregator links pass249 through unchanged.250- **The fallback needs a real search provider.** With the default251 DuckDuckGo provider the fallback returns 0 results (Instant Answer API252 has no SERPs). Set a Brave/Tavily key in plugin Settings → Web Search.253- A bare query (no keywords, no defaults) returns the guidance notice254 ("unfiltered marketplace noise") — configure default keywords or pass255 `query`/`skills` for targeted results.256257### Reading records258259```json260// List leads (most recent first):261{ "action": "list_items", "post_type": "mcp_ai_lead", "orderby": "date", "order": "DESC", "per_page": 20 }262263// Search leads by email:264{ "action": "list_items", "post_type": "mcp_ai_lead", "search": "jane.doe@example.com" }265266// Filter by meta field:267{ "action": "list_items", "post_type": "mcp_ai_lead", "filters": [{ "key": "lead_status", "value": "new" }] }268269// Get a single record:270{ "action": "get_item", "post_type": "mcp_ai_lead", "item_id": 12398 }271```272273### Creating records274275```json276// Create a lead with BANT scoring:277{ "action": "create_item", "post_type": "mcp_ai_lead", "fields": {278 "title": "Jane Smith", "first_name": "Jane", "last_name": "Smith",279 "email": "jane@acmecorp.com", "phone": "+1-555-0100", "source": "referral",280 "lead_status": "new", "lifecycle_stage": "lead", "lead_score": "50",281 "bant_assessment": {282 "budget": { "score": 0, "evidence": "" },283 "authority": { "score": 25, "evidence": "manager;" },284 "need": { "score": 50, "evidence": "looking for;" },285 "timeline": { "score": 25, "evidence": "soon;" }286 }287} }288289// Create a company:290{ "action": "create_item", "post_type": "mcp_ai_company", "fields": {291 "title": "Acme Corporation", "_company_industry": "Manufacturing",292 "_company_size": "201-1000", "_company_website": "https://acmecorp.com",293 "_company_phone": "+1-555-0200", "_company_status": "prospect"294} }295296// Log an activity:297{ "action": "create_item", "post_type": "mcp_ai_crm_activity", "fields": {298 "title": "Discovery call with Jane Smith (Lead #12400)",299 "activity_type": "call", "related_type": "lead", "related_id": "12400",300 "due_date": "2026-08-14"301} }302```303304### Updating records305306```json307// Qualify a lead:308{ "action": "update_item", "post_type": "mcp_ai_lead", "item_id": 12398,309 "fields": { "lead_status": "qualified", "lifecycle_stage": "sql" } }310311// Move a deal through pipeline stages:312{ "action": "update_item", "post_type": "mcp_ai_deal", "item_id": 12327,313 "fields": { "pipeline_stage": "proposal", "win_probability": "0.5",314 "expected_close_date": "2026-09-15", "amount": "25000" } }315```316317### Bulk operations318319```json320// Bulk create leads from a CSV import:321{ "action": "bulk_create", "post_type": "mcp_ai_lead", "items": [322 { "title": "Alice Brown", "first_name": "Alice", "last_name": "Brown",323 "email": "alice@example.com", "source": "csv_import", "lead_status": "new" },324 { "title": "Bob Wilson", "first_name": "Bob", "last_name": "Wilson",325 "email": "bob@example.com", "source": "csv_import", "lead_status": "new" }326] }327```328329### Deleting records330331```json332// Delete a lead (prefer disqualifying instead — see Critical Rules):333{ "action": "delete_item", "post_type": "mcp_ai_lead", "item_id": 12398 }334```335336**⚠️ Warning:** Deleting a record is permanent. Consider using `update_item` to337change `lead_status` to `"disqualified"` instead of deleting, to preserve audit history.338339## Common Workflows340341### Lead qualification workflow342343```3441. List new leads: list_items(mcp_ai_lead, filters: [{key: "lead_status", value: "new"}])3452. Review BANT: Check bant_assessment scores. Prioritize high Need + Timeline.3463. Create activity: create_item(mcp_ai_crm_activity, activity_type: "call")3474. Update lead: update_item(mcp_ai_lead, lead_status: "contacted")3485. If qualified: update_item(mcp_ai_lead, lead_status: "qualified", lifecycle_stage: "sql")349 create_item(mcp_ai_deal, lead_id: <lead_id>, pipeline_stage: "qualification")350```351352### Deal pipeline management353354```3551. Find stalled deals: list_items(mcp_ai_deal, filters per pipeline_stage)3562. Check activities: list_items(mcp_ai_crm_activity, filters: [{key: "related_id", value: "<deal_id>"}])3573. Advance stage: update_item(mcp_ai_deal, pipeline_stage: <next_stage>, win_probability: <new_prob>)3584. Log activity: create_item(mcp_ai_crm_activity, activity_type: "note", content: "<disposition>")359```360361### Pipeline stage progression with win probabilities362363| Stage | Win Probability | Typical Actions |364|---|---|---|365| `inquiry` | 5% | Initial contact, needs discovery |366| `scoping` | 10% | Define requirements, budget range |367| `qualification` | 25% | BANT/MEDDIC confirmed, champion identified |368| `proposal` | 50% | Proposal sent, economic buyer engaged |369| `negotiation` | 75% | Terms negotiation, legal review |370| `engagement_signed` | 90% | Contract signed, onboarding begins |371| `won` | 100% | Revenue recognized |372| `lost` | 0% | Closed-lost with reason |373374### Building a company profile375376```3771. Research company: Use deep_research or web_search_validated for company info.3782. Create company: create_item(mcp_ai_company, with industry, size, website, status).3793. Link lead: update_item(mcp_ai_lead, adding _company_id reference to the company post ID).3804. Add contacts: create_item(mcp_crm_contacts) for key personas at the company.381```382383### Activity logging (call disposition)384385```386After every call/meeting:3871. create_item(mcp_ai_crm_activity, activity_type: "call"|"meeting"|"email")3882. Set title: "<Action> with <Contact Name> (<Entity> #<ID>)"3893. Set related_type: "lead" | "deal" | "company" | "customer"3904. Set related_id: The entity post ID3915. Set content: Summary of the conversation, next steps, disposition3926. Set due_date: For follow-up tasks (activity_type: "task")393```394395### Pipeline triage396397```398Weekly pipeline review:3991. list_items(mcp_ai_lead, filters: [{key: "lead_status", value: "new"}])400 → Identify high-score leads (lead_score >= 60) for immediate follow-up.401 4022. list_items(mcp_ai_deal, filters: [{key: "pipeline_stage", value: "qualification"}])403 → Find deals stuck in qualification for 2+ weeks — they need a champion.404 4053. list_items(mcp_ai_crm_activity, filters: [{key: "activity_type", value: "task"}])406 → Check for overdue follow-up tasks (due_date < today).407 4084. list_items(mcp_ai_lead, filters: [{key: "lead_status", value: "disqualified"}])409 → Review disqualified leads — some may be worth re-engaging.410```411412### Searching across CRM413414```json415// Find all leads from a specific company domain:416{ "action": "list_items", "post_type": "mcp_ai_lead", "search": "@example.com" }417418// Find all activities for a lead:419{ "action": "list_items", "post_type": "mcp_ai_crm_activity",420 "filters": [{ "key": "related_type", "value": "lead" },421 { "key": "related_id", "value": "12398" }] }422```423424## JobNavigator-Adoption Features (v3.2.0)425426Adopted from [vesaias/JobNavigator](https://github.com/vesaias/JobNavigator);427full plan in `docs/developer/crm-toolkit-jobnavigator-adoption-plan.md`.428429### Stage transition history (deals)430431Every `move_deal_stage` (and `create_deal`) appends a machine-readable432entry to the deal's `stage_history` meta:433434```json435{ "from": "prospecting", "to": "qualification", "at": "2026-09-16T…", "source": "tool" }436```437438- `source` is one of `tool`, `agent`, `workflow`, `manual`, `email_reply`, `bulk`.439- `stage_changed_at` meta stamps the last real change — drives time-in-stage440 and stalled-deal detection. **No-op stage moves never bump `updated_at`.**441- `move_deal_stage` accepts `undo: true` to revert the last move without442 recording a new transition (audits `deal_stage_reverted`).443- Helper: `WP_MCP_AI_CRM_Stage_History` (`record`, `get_history`,444 `undo_last`, `time_in_stage`, `next_open_stage`).445446### Lead dedup, companies, signals447448- `create_lead` refuses duplicates by normalized email with a 409449 `wp_mcp_ai_duplicate_lead` error carrying `existing_lead_id`;450 pass `allow_duplicate: true` to force-create.451- `create_lead` auto-links `company_name` to a canonical company record452 (case/space-insensitive; auto-creates when missing) via453 `WP_MCP_AI_CRM_Identity`. Settings: `identity.auto_create_company`454 (default true), `identity.auto_create_company_from_domain` (default false),455 `identity.dedupe_leads` (default true).456- Lead/deal email signals: `last_email_received`, `last_email_snippet`457 (capped 500), `last_email_sentiment` (positive|neutral|negative|mixed|unknown).458- Auto-disqualification: settings `auto_disqualify` block459 (`enabled`, `max_score`, `min_age_days`, `only_statuses`) — evaluated460 on lead create/update, fires `wp_mcp_ai_crm_lead_auto_disqualified`.461462### New tools463464| Slug | Purpose |465|---|---|466| `bulk_move_deal_stages` | Move up to 100 deals to one stage; reports `updated`/`skipped`/`not_found`; supports `undo` |467| `record_crm_reply` | Store reply signals on lead + open deals; optionally advance a deal (`advance_deal: true`) with source `email_reply` |468| `get_crm_handover` | Paste-ready plain-text bundle (facts, BANT, stage history, signals, activities + closing ask) for any AI/human handoff |469| `get_pipeline_digest` | Compact digest text + data: stage totals, pipeline value, stalled deals, hot leads, overdue tasks |470| `create_tracked_link` | Create a `?nvoos_track=<token>` link for a deal; opens recorded on the deal |471472- `delete_deal` on a `closed_won` deal releases the lead lifecycle back to473 `opportunity` when no other won deal remains (hook `wp_mcp_ai_crm_deal_deleted`).474475### Gmail reply poller (v3.2.0)476477Settings `gmail_reply_poll` block (`enabled` default false,478`advance_on_positive` default false, `max_per_poll` 10,479`min_interval_minutes` 15). When enabled, the cron480(`wp_mcp_ai_crm_gmail_reply_poll`) polls Gmail for unread replies via the481Gmail client + Remote Sites connections, matches senders to leads by482normalized email, classifies sentiment via `WP_MCP_AI_CRM_Classifier`, and483applies signals through `WP_MCP_AI_Tool_Record_CRM_Reply::apply()`. Unknown484senders are skipped; the `wp_mcp_ai_crm_classify_intent` filter can swap in485an LLM classifier. Last-poll stamp: `wp_mcp_ai_crm_reply_last_poll` option.486487### Pipeline digest scheduling (recipe asset, no code)488489`addons/pro/config/pipeline-digest-recipe.json` — an importable recipe:490workflow nodes `get_pipeline_digest` → `send_telegram_message`491(`{{digest.result.text}}` template) plus a `create_pro_schedule` daily492config. Apply via the Pro Workflow Builder + Pro Schedule Manager MCP tools;493swap the delivery node for WhatsApp or local persistence as needed.494495## Critical Rules496497- **Always use `get_schema` first** before creating or updating a record to verify available field keys and types.498- **Lead scoring is automated** — the `lead_score` and `bant_assessment` are populated by the CRM engine. Manual overrides should be rare and documented.499- **Never delete leads** — use `lead_status: "disqualified"` to preserve audit trail and prevent re-import of the same contact.500- **Activities are the audit trail** — log every meaningful interaction (call, email, meeting, note) with `related_type` and `related_id`.501- **Deal pipeline stages are sequential** — don't skip stages. Each stage transition should have an activity log.502- **`deal_owner` is a WordPress user ID** — ensure the user exists and has appropriate CRM capabilities.503- **`win_probability` is a float stored as string** — use `"0.1"` not `0.1` in JSON.504- **BANT `evidence` is semicolon-delimited** — the engine parses email content for keyword evidence. When manually setting, use `"keyword1; keyword2; "` format.505- **Bulk operations (`bulk_create`) are for imports** — each item must be a complete fields object. Existing records with matching IDs will be overwritten.506- **Support tickets (`mcp_ai_ticket`) are SLA-tracked** — create them for customer issues, not sales inquiries.507508## Common Mistakes509510```511WRONG — deleting a lead instead of disqualifying512{ "action": "delete_item", "post_type": "mcp_ai_lead", "item_id": 12398 }513514RIGHT — disqualify to preserve history515{ "action": "update_item", "post_type": "mcp_ai_lead", "item_id": 12398,516 "fields": { "lead_status": "disqualified" } }517518WRONG — creating a deal without linking to a lead519{ "action": "create_item", "post_type": "mcp_ai_deal",520 "fields": { "deal_name": "Some Deal", "pipeline_stage": "qualification" } }521// Missing lead_id — the deal has no source traceability.522523RIGHT — always link deals to their source lead524{ "action": "create_item", "post_type": "mcp_ai_deal",525 "fields": { "lead_id": "12398", "deal_name": "Acme Corp - Audit Automation",526 "pipeline_stage": "scoping", "amount": "0", "currency": "USD", "deal_owner": "1",527 "win_probability": "0.1" } }528529WRONG — logging an activity without related_type or related_id530{ "action": "create_item", "post_type": "mcp_ai_crm_activity",531 "fields": { "title": "Call with prospect", "activity_type": "call" } }532// This activity is orphaned — it can't be found when viewing the lead/deal.533534RIGHT — always link activities to their parent entity535{ "action": "create_item", "post_type": "mcp_ai_crm_activity",536 "fields": { "title": "Discovery call with Jane Doe (Lead #12398)",537 "activity_type": "call", "related_type": "lead", "related_id": "12398" } }538539WRONG — skipping pipeline stages540// Moving from "inquiry" directly to "proposal" with no scoping or qualification.541// The pipeline history should reflect the actual sales process.542543RIGHT — advance stage-by-stage with activity log5441. update_item: pipeline_stage: "scoping"5452. create_item(activity): "Scope of work discussed"5463. update_item: pipeline_stage: "qualification"5474. create_item(activity): "BANT confirmed, champion identified"5485. update_item: pipeline_stage: "proposal"549550WRONG — setting win_probability to 0 or 1 prematurely551// Win probability should reflect real pipeline stage, not optimism/pessimism.552553WRONG — searching with filters that use meta keys not in the schema554// Some meta fields may be added dynamically. Always call get_schema first555// to confirm which fields are registered and filterable.556```557558## Cross-References559560- Run `design-deep-research` to research target companies before creating company profiles.561- Run `design-web-research` for quick company lookups and competitive intelligence.562- Run `design-pro-workflow-builder` to automate CRM workflows (lead scoring, auto-assignment, stage progression).563- Run `design-pro-schedule-manager` to schedule recurring CRM tasks (pipeline reviews, follow-up reminders).564- Run `design-document-generation` to create proposals, SOWs, and invoices from deal data.565- Run `wp-security-audit` on any CRM automation callbacks — CRM data is sensitive and must be access-controlled.566567## What This Skill Does NOT Cover568569- Email integration details (Gmail/Outlook sync) — use `search_gmail` for inbox queries.570- Remote WordPress CRM access — use `nv_oos_console_agent_remote_wp_connection` for multi-site CRM.571- Paper Store integration — use `paper_store_*` tools for research-backed company profiles.572- ERP integration (EZuite) — use `ezuite_erp` / `ezuite_erp_get_products` for ERP-connected CRM data.573- CRM workflow rule configuration — use `toolkit_cpt` with `post_type: "mcp_ai_crm_wf_rule"` and the `design-pro-workflow-builder` skill.574- Sequence automation — use `toolkit_cpt` with `post_type: "mcp_ai_sequence"`.575576## References577578- NV oOS Pro Toolkit CRM admin page: `/wp-admin/admin.php?page=nvoos-pro-toolkit-crm`579- `toolkit_cpt` MCP tool — the primary interface for all CRM operations.580- BANT framework: [blog.hubspot.com/sales/bant](https://blog.hubspot.com/sales/bant)581- MEDDIC framework: [meddic.co](https://meddic.co)