clickmax-pipelines

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 for pipeline/stage/card operations: create or change pipelines and stages, move cards, assign attendants, inspect history/risk, import leads into pipelines, or read pipeline analytics/settings.

Not this skill:

• lead search and identity -> clickmax-leads
• manual tagging or segment/list membership -> clickmax-tags / clickmax-list-segments
• building or reading a saved Insights dashboard of opportunities BI -> clickmax-insights-dashboards

Key assumptions

• stage/pipeline ids must be resolved before mutation
• moving cards can change card status from the destination stage semantics
• won and lost are terminal stage meanings; only put them on stages meant to close opportunities
• auto-assignment strategy changes who owns new/changed cards and should be treated as operational policy, not cosmetic text
• settings can include idle SLA threshold, lost reasons, default priority, temperature, currency, and card display fields
• some move paths may be blocked by stage passage rules
• delete semantics are soft-hide/remove-from-board at the backend level, but still user-visible destructive actions
• attendant assignment/settings writes replace current structures, not patch arbitrary fragments
• Every money amount here is an INTEGER IN CENTS — cardscreate/cardsupdate's value, opportunitiesbulksetvalue's value, cardslist/opportunities_query's valueMin/valueMax, and commissionFixedCents. 19990 = R$ 199,90. Neither side divides or multiplies: a decimal like 199.90 is not "reais", it is a fifth of a cent. Commission PERCENTAGES are basis points instead (525 = 5,25%).
• cards and opportunitiesbulk act on the SAME thing — an opportunity card. The bulk family is not "the lead version" of the single-card tools; opportunitiesbulkapplytags writes the exact same card↔tag link as cardsapplytags, just over a whole selection. Tagging the CONTACT is a different domain entirely (crmtagsapplytoleads, see clickmax-tags).
• Bulk targeting is cardIds (an explicit non-empty list of CARD ids) OR allMatching: true with a scope { pipelineId, stageId?, filters? } — mutually exclusive, one required, and never opportunityIds/leadIds. Sending both or neither is a 400.

• id means a DIFFERENT thing depending on the tool — same param name, no pipelineId/stageId alias to disambiguate. On stageslist, stagescreate, and stagesreorder, id is the PIPELINE id (the stage itself is created/reordered by name/list, not addressed). On stagesupdate and stages_delete, id is the STAGE id. Do not assume it means the same thing across sibling tools — check which one before calling.

Thought process

1. Resolve the exact pipeline/stage/card first.
2. Distinguish card mutation from pipeline metadata/settings mutation.
3. When moving or reordering, preserve board semantics and current anchors.
4. Confirm destructive changes when intent is not already explicit.

Execute guide

• Resolve the board before writes: use pipelineslist to find the pipeline, stageslist with id (the pipeline id, not pipelineId) to map stage ids, and cards_list with pipelineId, stageId, pagination, and optional filters such as search or tagIds when the target card still needs disambiguation.

• Creating a NEW pipeline with its stages already defined (the common "create a pipeline with stages X, Y, Z" ask): pass the stages inline in pipelinescreate's optional stages array ({name, color?, type?, metaPixelEvent?} per stage, type defaults to inprogress — use won/lost on the terminal stages) instead of one pipeline call plus N separate stages_create calls. One call creates the whole board.

• Create cards with cardscreate, passing the target leadIds, pipelineId, and stageId; include value and attendantIds only when the user wants those set at creation time. Do not guess a card-creation tool name outside pipelines — cardscreate is the only one; there is no pipelinescreatecard.

- Brand-new/fictional contacts: create each one first via clickmax-leads's leadscreate (one call per contact, returns the new lead id), THEN batch them into cardscreate calls using that pipeline's pipelineId/stageId and leadIds: [<the returned id>]. - EXISTING contacts (e.g. "pegue os últimos N leads e adicione na pipeline X"): this is a TWO-DOMAIN task — resolve the leads first via clickmax-leads's leadssearch (no special sort needed for "last N", see that skill), resolve the pipeline/stage via pipelineslist/stageslist here, THEN call cardscreate once per resolved lead id with that pipelineId/stageId. Load both skills' guidance for this request — do not treat it as pipelines-only just because a pipeline is named.

• Change many cards at once with the opportunitiesbulk* family instead of looping the single-card tools: opportunitiesbulkmove, applytags, assignattendants, setvalue, setpriority, settemperature, setclosingdate, setcustomfield, createnextaction, delete. Resolve the selection first (cardslist or opportunitiesquery), then send it as cardIds, or describe it once as allMatching: true + scope. Each call answers { mode: "sync", affected } up to 200 cards, or { mode: "async", jobId } above that — an async answer means NOTHING has happened yet; poll opportunitiesbulkjob_status with that jobId before reporting the change as done.

• Write an opportunity custom field with opportunitiesbulksetcustomfield — customFieldId from customfieldslist with entityType: "opportunities", and value raw for the field type (string for text/select, number for number, ISO string for date, boolean for boolean, string array for multiselect; null clears it). Only text, number, date, boolean, select and multiselect can be written in bulk — every other type (currency, textarea, link, percentage, radio, rating, file, formula, json) is refused with a 400 Custom field type "<x>" is not supported in bulk update. For those, write per card via cards_update's customFieldValues, or pick a supported type when creating the field.

• Move cards with cards_move, passing the card id, the destination stageId, and the current relative anchor (beforeCardId or afterCardId) so the board order stays intentional; include lossReason only when the move path requires or justifies it.

• Assign attendants in 2 steps: first read pipelinesattendanttypesget for the pipeline's valid attendant type ids, then write cardsassign_attendants with explicit assignments entries containing attendantId, attendantTypeId, and isPrimary.

• Import leads into a pipeline with cardsimportfrom_lists only when the user wants board population from list/segment cohorts rather than one-off card creation.

• Inspect card behavior with cardsget for one card, cardslistbylead for a lead's pipeline presence, cardshistory for move/change history, and cardsat_risk for cards currently flagged as operational risk.

• Update structure only after resolving the exact target object: to add a stage to an EXISTING pipeline, use stagescreate with id = that pipeline's id (not a pipelineId field, and not the new stage's id — the stage has no id yet); stagesupdate/stagesdelete instead take id = the STAGE's own id, since those two target one stage directly. Use stagesreorder (id = pipeline id) to resequence. Use pipelinescreate, pipelinesupdate, or pipelines_delete for pipeline changes.

• Treat settings and analytics as separate from board CRUD: read current configuration with pipelinessettingsget before pipelinessettingsupdate, use pipelinesattendanttypesset only when changing the pipeline's attendant-role structure itself, and use pipelinesanalytics for performance/throughput answers rather than card-by-card inspection.

Report

• For structural changes: report what changed, where, and the resulting status.
• When summarizing one specific created/read pipeline in a visual card, use the pipeline name as the large headline/value. Put stage count, opportunity count, active status, and similar board metrics in pills/secondary metrics instead of replacing the headline with counts.
• For card moves: report origin -> destination and any relevant status/owner effect.
• For analytics/risk: summarize the operational takeaway, not raw board payloads.

Warnings

• Do not guess stage ids from names when several stages are similar.
• A bulk write that comes back mode: "async" has NOT been applied yet. Reporting "done" off that response is how a mass update gets silently lost — poll opportunitiesbulkjobstatus, and use opportunitiesbulkjobhistory to audit or recover a jobId that was not kept.
• Treat a tool result flagged as an error as a FAILURE even though the transport answered 200. MCP reports a failed tool call in the result envelope (isError: true, the message as text), not as a JSON-RPC error — a caller that only inspects error reads "Provide non-empty cardIds OR allMatching=true with scope" as if it were a successful write. Never count rows as written on a result you did not actually read.
• cards_create creates ONE card per call, even when leadIds carries several contacts — that is the multi-contact card, not a shortcut for N cards. For one card per contact, call it once per lead id.
• Card order uses relative positioning semantics; stale anchors can misplace cards.
• Importing from lists/segments skips leads already present in the pipeline.
• If leadscreate (or any write here) returns an empty/unexpected result for a contact you need the id of, do not silently skip it or fabricate an id — call leadsexistsbyemail/leadssearch (see clickmax-leads) to recover the real id before using it in cardscreate, or surface the failure instead of creating a card with no lead.

Anti-patterns

• Treating pipeline settings as harmless cosmetic edits.
• Moving cards without checking destination stage semantics.
• Using card deletion when the user only wants to hide/archive operationally.