Authenticate with an access token scoped to ZohoCRM.coql.READ and POST to the Zoho CRM COQL query endpoint with a JSON body containing a select_query string
Write the COQL aggregate query using standard SQL-like syntax: SELECT aggregate_function(field), group_field FROM Module WHERE conditions GROUP BY group_field HAVING aggregate_condition ORDER BY ... LIMIT N
Supported aggregate functions include COUNT, SUM, AVG, MIN, MAX — apply them to numeric fields; use COUNT(*) to count all records in a group
Paginate results using the offset and limit clauses within the COQL query itself (rather than a cursor); the maximum LIMIT value per query is 2000 rows
Parse the response data array where each element represents one aggregate result row; field names in the response match the SELECT aliases or default to the function-field combination
For queries across related modules, use dot notation to traverse lookups (e.g., Account_Name.Industry) in the WHERE and SELECT clauses — not all lookup depths are supported, verify with the current Zoho COQL documentation
Known gotchas
COQL does not support subqueries or JOINs across unrelated modules — data that requires joining multiple unrelated modules must be fetched in separate queries and merged on the client side
Aggregate queries with GROUP BY on a text field that contains null values may silently exclude those records from the grouped results — use a HAVING clause or test with records having null values to verify null handling
COQL query strings must be URL-safe and properly JSON-escaped when embedded in the request body; unescaped apostrophes in string literals (e.g., WHERE Company_Name = 'O'Brien') cause a parse error that Zoho reports as an invalid query rather than a syntax hint
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp