clickmax-leads
Use when the user wants to create, find, deduplicate, inspect (including a contact's Raio-X), filter, verify the e-mail of, or compare CRM leads and their commercial context inside Clickmax, or to che
SKILL.mdskills/clickmax-leads/SKILL.md
GitHubWhen 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, verify a contact's e-mail, find contacts with e-mail problems or fraud signals, 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
mcp__plugin_clickmax_clickmax__leads_filter_schemadescribes the legacy filter model; never use it to buildmcp__plugin_clickmax_clickmax__leads_searchfiltersmcp__plugin_clickmax_clickmax__leads_searchis the main entry for cohort discovery.filtersis required ([]= all leads), andperPageaccepts 1-100. Its onlysortByvalues areopportunities_asc/opportunities_desc; omittingsortByreturns leads NEWEST-FIRST bycreatedAt. So "the last N leads" usesfilters: [],page: 1,perPage: N(N <= 100) with nosortBymcp__plugin_clickmax_clickmax__leads_getis 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
- e-mail status lives on the lead (
emailStatus,emailValidatedAt,emailInvalidReason) and comes back in BOTHmcp__plugin_clickmax_clickmax__leads_searchrows andmcp__plugin_clickmax_clickmax__leads_get:pending= not verified yet |valid|invalid(bounces; fix or exclude) |risky(deliverable but disposable/catch-all/role address; sending is still allowed, the user decides). Reading it costs nothing — do not verify just to read it validfrom the automatic background pass only confirms the DOMAIN;mcp__plugin_clickmax_clickmax__leads_validate_emailasks for a mailbox-level check. Editing a contact e-mail already resets it topendingand triggers a check by itselfmcp__plugin_clickmax_clickmax__leads_validate_emailis a PAID provider lookup (1 credit per address), synchronous, limited to 10 calls/min, and repeating it for the same lead within 1 hour just returns the stored verdict. It is for one specific contact, never a base-wide sweepmcp__plugin_clickmax_clickmax__leads_createneedsname+ at least one ofemail/telephone/instagram. Same e-mail = 409; same phone (normalized, BR mobile with/without 9th digit) = NO new contact: the oldest match's id comes back and onlytagIdsare applied to it, the rest of the request is dropped silently; Instagram is not deduplicated on createmcp__plugin_clickmax_clickmax__leads_xraymoney fields are redacted without sales permission (0 / empty / null), so 0 LTV there is not "never bought"; itssummaryis only a cached one (24h, per language), null is normalsuspectedFraud(+suspectedFraudReasonsemail/document) is a read-time warning of card testing, true only when BOTH the e-mail has no relation to the name AND the document is suspect (empty, all zeros, or not 11/14 digits). Nothing is stored or blocked; fixing the e-mail or document clears it. It is a filter field like any other, so it also works in segments
Thought process
- Decide whether the user needs one lead, a filtered cohort, or supporting aggregates.
- If the user describes filters vaguely, inspect the filter schema first.
- Use
leads_searchfor cohorts andleads_getfor one concrete lead. - Pull supporting projections only when they materially answer the request.
Execute guide
- For cohort discovery, follow the
mcp__plugin_clickmax_clickmax__leads_searchinput contract; do not translate fields from the legacy filter-schema operation. - Search cohorts with
mcp__plugin_clickmax_clickmax__leads_search, passing the requiredfiltersarray ([]when unfiltered) plus optional paging and sort fields. Use this for discovery, comparison, and broad CRM filtering. - Inspect one known lead with
mcp__plugin_clickmax_clickmax__leads_get, passing the lead id. Treat this as the main enriched lead view. - Add commercial context with
mcp__plugin_clickmax_clickmax__leads_payments,mcp__plugin_clickmax_clickmax__leads_invoices, andmcp__plugin_clickmax_clickmax__leads_common_productsonly when payments, billing status, or bought-product patterns materially change the answer. Unlike its siblings,mcp__plugin_clickmax_clickmax__leads_common_productsrequiresfilter(not optional) — always pass a filter, even a broad one. - Duplicate check before creating:
mcp__plugin_clickmax_clickmax__leads_check_duplicateswith every identifier you have (e-mail, phone, Instagram) → one oldest match per channel. A match = offer to use/update that contact instead of creating.mcp__plugin_clickmax_clickmax__leads_exists_by_emailonly answers yes/no for an e-mail. - "Raio-X" / "is this contact ready to buy, when do I reach them":
mcp__plugin_clickmax_clickmax__leads_xray(intent level + top 3 signals, LTV/ticket/pending, channels with opt-in and last reply, best 2h slot in São Paulo time, 14-day activity). Useleads_contextinstead when full history or pagination is needed. - "Did my import/export finish?":
mcp__plugin_clickmax_clickmax__leads_bulk_jobs_history(newest first;jobNamecrm.leads.import-csv/crm.leads.export-csv…). Import counts are inresult.meta.details(created/updated/duplicated); an export's file link is inresult.meta.output.url. Starting an import needs a file upload in the app — not possible here. - E-mail health of a cohort: filter
mcp__plugin_clickmax_clickmax__leads_searchwith a filter item on fieldemailStatus, operatorequals,valueString=invalid|risky|pending|valid(addnegation: truefor "anything but"). Fraud signals: a filter item on fieldsuspectedFraud, operatorequals,valueBool= true. Report the count (meta.countItens) before rows. - Verify one contact's e-mail with
mcp__plugin_clickmax_clickmax__leads_validate_email, passing the lead id: it returns the newemailStatusright away. Apendingresult after a failure (provider error / inconclusive) is not a verdict — the automatic job retries later; do not retry in a loop. A lead without e-mail cannot be verified. - "How many contacts do I have in total?" ->
mcp__plugin_clickmax_clickmax__analytics_resource_counts(contacts, merged contacts excluded) is one cheap call; useleads_searchmeta.countItenswhen the count must respect filters. - Create one contact with
mcp__plugin_clickmax_clickmax__leads_create—nameplus at least one ofemail/telephone/instagram; runmcp__plugin_clickmax_clickmax__leads_check_duplicatesfirst. It also acceptstagIds/customFieldValuesinline, so a lead can be created pre-tagged/pre-classified in the SAME call instead of a separate tagging step afterward. It returns{ leadId }(for a phone match, the EXISTING contact's id). To seed a pipeline, create each contact here then add them as opportunity cards viaclickmax-pipelines(cards_createneeds the returned lead ids). For several contacts, callleads_createonce per contact. - Use
mcp__plugin_clickmax_clickmax__leads_origins,mcp__plugin_clickmax_clickmax__leads_sub_origins, andmcp__plugin_clickmax_clickmax__leads_origins_treefor source taxonomy and breakdown questions. - Use
mcp__plugin_clickmax_clickmax__leads_payments_utm_autocompletewhen the user needs help discovering UTM values before filtering or diagnosing acquisition patterns. - Preferred order: cohort question ->
mcp__plugin_clickmax_clickmax__leads_search; single lead question ->mcp__plugin_clickmax_clickmax__leads_get-> 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 morewhen 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.
mcp__plugin_clickmax_clickmax__leads_exists_by_emailanswers existence, not ownership or enrichment.- Never report a
leads_createcall as "contact created" without checking duplicates: a phone match returns an old contact id silently. - Do not present
suspectedFraudas a verdict on the person: it is a heuristic signal, and a missing document alone does not trigger it.
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.
- Calling
mcp__plugin_clickmax_clickmax__leads_validate_emailon many leads to "clean the base" (paid, rate-limited) or just to read a status thatleads_getalready returns.
Clickmax skill revision: 30bc1243c2ed