name: zoho-crm description: Guides Zoho CRM tool usage with correct module routing for leads, contacts, deals, and tasks. Use when interacting with Zoho CRM tools. Triggers include "zoho", "leads", "contacts", "deals", "tasks", "overdue", "CRM". metadata: version: 1.0.0 category: operations tags: - zoho - crm - leads - contacts - deals - tasks - mcp author: name: NimbleBrain url: https://www.nimblebrain.ai

Zoho CRM Integration

Critical: Tasks Are a Separate Module

Zoho CRM has separate modules for different record types:

Module	Purpose	Key Fields
Leads	Unqualified prospects	Lead_Status, Email, Phone
Contacts	Qualified individuals	Account_Name, Email, Phone
Deals	Sales opportunities	Stage, Amount, Closing_Date
Accounts	Companies/organizations	Account_Name, Industry
Tasks	Action items with due dates	Subject, Due_Date, Status, Priority

Tasks are NOT fields on Leads. They are standalone records that can be associated with Leads, Contacts, Deals, or Accounts via the What_Id field.

Quick Start: Finding Overdue Tasks

When user asks about "overdue" items, they almost always mean Tasks:

User: "What are the overdue tasks?" or "What leads are overdue?"

Step 1: ZOHOCRM_SEARCH_RECORDS(module="Tasks", criteria="(Due_Date:less_than:TODAY)")

Done. One call to the Tasks module with a date filter.

Situational Handling

Situation: User asks about "overdue" anything

Trigger phrases: "overdue tasks", "overdue leads", "what's past due", "follow-ups due", "what do I need to do"

Required action: Query the Tasks module, NOT Leads.

ZOHOCRM_SEARCH_RECORDS(
  module="Tasks",
  criteria="(Due_Date:less_than:TODAY)"
)

Optional filters:

By status: (Due_Date:less_than:TODAY)and(Status:equals:Not Started)
By priority: (Due_Date:less_than:TODAY)and(Priority:equals:Highest)

Situation: User asks about leads/contacts/deals

Trigger phrases: "show me leads", "list contacts", "what deals are closing"

Required action: Query the appropriate module directly.

# List leads
ZOHOCRM_SEARCH_RECORDS(module="Leads")

# Leads by status
ZOHOCRM_SEARCH_RECORDS(module="Leads", criteria="(Lead_Status:equals:Contacted)")

# Deals closing this month
ZOHOCRM_SEARCH_RECORDS(module="Deals", criteria="(Closing_Date:between:2026-02-01,2026-02-28)")

Situation: User asks to create a task

Required action: Use the Tasks module with required fields.

ZOHOCRM_CREATE_RECORD(
  module="Tasks",
  data={
    "Subject": "Follow up with lead",
    "Due_Date": "2026-02-10",
    "Status": "Not Started",
    "Priority": "High"
  }
)

To associate with a Lead/Contact/Deal, include What_Id:

data={
  "Subject": "Follow up",
  "Due_Date": "2026-02-10",
  "What_Id": "7170963000000598816"  # Lead/Contact/Deal ID
}

Situation: User asks about a specific lead's tasks

Required action: Search Tasks filtered by the associated record.

Step 1: Find the Lead ID (if not known)
ZOHOCRM_SEARCH_RECORDS(module="Leads", criteria="(Full_Name:contains:John)")

Step 2: Search Tasks associated with that Lead
ZOHOCRM_SEARCH_RECORDS(module="Tasks", criteria="(What_Id:equals:<lead_id>)")

Situation: User asks to update a task

Required action: Get task ID first, then update.

Step 1: ZOHOCRM_SEARCH_RECORDS(module="Tasks", criteria="(Subject:contains:follow up)")
Step 2: ZOHOCRM_UPDATE_RECORD(module="Tasks", id=<task_id>, data={"Status": "Completed"})

Module Field Reference

Tasks Module

Field	Type	Values
Subject	String	Task title
Due_Date	Date	YYYY-MM-DD format
Status	Picklist	Not Started, Deferred, In Progress, Completed, Waiting for input
Priority	Picklist	Highest, High, Normal, Low, Lowest
What_Id	Lookup	Associated record ID (Lead, Contact, Deal)
Owner	Lookup	Assigned user

Leads Module

Field	Type	Values
First_Name	String
Last_Name	String
Full_Name	String	Auto-generated
Email	Email
Lead_Status	Picklist	Not Contacted, Contacted, Working, Qualified, etc.
Lead_Source	Picklist	Advertisement, Web, Referral, etc.

Criteria Syntax

Zoho uses COQL-style criteria:

(Field_Name:operator:value)
(Field1:equals:value1)and(Field2:contains:value2)
(Field1:equals:value1)or(Field2:equals:value2)

Operator	Usage	Example
equals	Exact match	`(Status:equals:Completed)`
contains	Partial match	`(Subject:contains:follow)`
starts_with	Prefix match	`(Full_Name:starts_with:John)`
less_than	Date/number comparison	`(Due_Date:less_than:2026-02-01)`
greater_than	Date/number comparison	`(Amount:greater_than:10000)`
between	Range	`(Due_Date:between:2026-02-01,2026-02-28)`

Special value: TODAY - use for current date comparisons.

Error Recovery

Error	Cause	Fix
"Module not found"	Wrong module name	Use exact names: Leads, Contacts, Deals, Accounts, Tasks
"Invalid criteria"	Malformed COQL	Check parentheses and operator syntax
"Field not found"	Wrong field name	Use API names (Full_Name, not "Full Name")
"No records found"	Query too restrictive	Broaden criteria, check spelling

Anti-Patterns

Wrong	Right
Search Leads for "overdue" items	Search Tasks module with Due_Date filter
Look for "Next_Action" field on Leads	Tasks are a separate module, not a field
Ask user for field names	Check available fields via ZOHOCRM_GET_FIELDS
Assume Tasks are part of Leads	Tasks are standalone records linked via What_Id
Use date strings like "today"	Use literal dates (2026-02-05) or TODAY keyword

Common Queries

# All overdue tasks
ZOHOCRM_SEARCH_RECORDS(module="Tasks", criteria="(Due_Date:less_than:TODAY)")

# Overdue tasks not completed
ZOHOCRM_SEARCH_RECORDS(module="Tasks", criteria="(Due_Date:less_than:TODAY)and(Status:not_equal:Completed)")

# High priority tasks
ZOHOCRM_SEARCH_RECORDS(module="Tasks", criteria="(Priority:equals:High)")

# Tasks due this week
ZOHOCRM_SEARCH_RECORDS(module="Tasks", criteria="(Due_Date:between:2026-02-03,2026-02-09)")

# All leads with status "Contacted"
ZOHOCRM_SEARCH_RECORDS(module="Leads", criteria="(Lead_Status:equals:Contacted)")

# Deals closing this month
ZOHOCRM_SEARCH_RECORDS(module="Deals", criteria="(Closing_Date:between:2026-02-01,2026-02-28)")