clickmax-leads

As tools abaixo aparecem com os nomes que o MCP da Clickmax registra. Se o seu cliente de IA prefixar nomes de tool (mcp<servidor>, mcp<servidor>, ou outro), use o nome já prefixado que aparecer na sua lista de tools.

When this applies

Use this skill when the user wants lead discovery/inspection OR to create a lead: search/filter contacts, inspect one lead, check whether an email already exists, create a new contact, compare lead-origin patterns, or pull a lead's payments/invoices/products.

Not this skill:

• tagging/classification -> clickmax-tags
• manual lists or dynamic segments -> clickmax-list-segments
• kanban pipelines/opportunity cards -> clickmax-pipelines

Key assumptions

• leadsfilterschema describes the legacy filter model; never use it to build leads_search filters
• leadssearch is the main entry for cohort discovery. filters is required ([] = all leads), and perPage accepts 1-100. Its only sortBy values are opportunitiesasc/opportunities_desc; omitting sortBy returns leads NEWEST-FIRST by createdAt. So "the last N leads" uses filters: [], page: 1, perPage: N (N <= 100) with no sortBy
• leads_get is enriched commercial context, not just a flat row
• payments, invoices, common products, and origin trees are lead-adjacent projections, not separate core entities
• tags, lists, and segments group leads; they do not replace the lead record itself
• lifecycle and temperature are mutable business signals; report them as current state, not immutable history

Thought process

1. Decide whether the user needs one lead, a filtered cohort, or supporting aggregates.
2. If the user describes filters vaguely, inspect the filter schema first.
3. Use leadssearch for cohorts and leadsget for one concrete lead.
4. Pull supporting projections only when they materially answer the request.

Execute guide

• For cohort discovery, follow the leads_search input contract; do not translate fields from the legacy filter-schema operation.
• Search cohorts with leads_search, passing the required filters array ([] when unfiltered) plus optional paging and sort fields. Use this for discovery, comparison, and broad CRM filtering.
• Inspect one known lead with leads_get, passing the lead id. Treat this as the main enriched lead view.
• Add commercial context with leadspayments, leadsinvoices, and leadscommonproducts only when payments, billing status, or bought-product patterns materially change the answer. Unlike its siblings, leadscommonproducts requires filter (not optional) — always pass a filter, even a broad one.
• Use leadsexistsby_email for duplicate-check questions, not enrichment.
• Create one contact with leadscreate — only name is required; pass email/telephone when known and check leadsexistsbyemail first to avoid duplicates. It also accepts tagIds/customFieldValues inline, so a lead can be created pre-tagged/pre-classified in the SAME call instead of a separate tagging step afterward. It returns the new lead id. To seed a pipeline, create each contact here then add them as opportunity cards via clickmax-pipelines (cardscreate needs the returned lead ids). For several contacts, call leadscreate once per contact.
• Use leadsorigins, leadssuborigins, and leadsorigins_tree for source taxonomy and breakdown questions.
• Use leadspaymentsutm_autocomplete when the user needs help discovering UTM values before filtering or diagnosing acquisition patterns.
• Preferred order: cohort question -> leadssearch; single lead question -> leadsget -> supporting projections only if needed; origin or UTM exploration -> origin or UTM helper first -> lead search only when matching contacts are also required.

Report

• Start with what was inspected: one lead, cohort, or origin/UTM diagnostic.
• For one lead: summarize identity, status/context, and only the relevant commercial facts.
• For cohorts: summarize count + the most relevant breakdowns before dumping rows.
• Cap long result sets and show +N more when the cohort is too broad.
• Follow-up actions are opt-in only.

Warnings

• Do not guess filter fields or operators.
• Do not treat lead payments or invoices as if they were the lead record itself.
• leadsexistsby_email answers existence, not ownership or enrichment.

Anti-patterns

• Asking the user for workspace id.
• Using raw origins/UTM helpers as a substitute for lead search.
• Returning every field when the user only asked for one operational answer.