clickmax-list-segments

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 manual list operations or dynamic segment logic: create/update/delete lists, manage list membership, build or replace segment filters, preview segment size, reload segments, or inspect list/segment leads.

Not this skill:

• raw lead filtering without creating reusable grouping -> clickmax-leads
• tag-based cohort labeling -> clickmax-tags

Key assumptions

• manual lists and dynamic segments are different grouping models
• segment updates also affect the synced backing list metadata and lead membership lifecycle
• upserting segment filters replaces the full tree
• segment filters are a FLAT ARRAY of {id, order, operator, field, negation, parentId?, value*} items, not nested objects — nesting comes from each item's parentId pointing at its parent GROUP item's own id; group items use field: 'children' + operator: 'childrenAnd'/'childrenOr'. Preserve every existing item (by id) when replacing, not just the branch being edited.
• reload queues recomputation; it is not just a cosmetic refresh
• Read [filter model](references/filter-model.md) before building non-trivial segment logic.

Thought process

1. Decide whether the user needs one-off discovery or reusable grouping.
2. Prefer manual lists for explicit curated membership.
3. Prefer segments for filter-defined dynamic cohorts.
4. Preview count before broad destructive changes when the filter tree is uncertain.

Execute guide

• Manual list lifecycle: use listscreate to create the list, then listsupdateleads to add or remove explicit lead IDs, then listsget_leads to verify the resulting membership.
• List inspection and maintenance: use listslist to browse lists, listsget to inspect one list, and lists_update when the user wants to rename the list or change its emoji.
• Dynamic segment lifecycle: use segmentscreate to create the segment shell, segmentspreviewcount to estimate cohort size from a candidate filter tree, and segmentsupsert_filters to replace the segment's full filter definition.
• For nested AND/OR or negation, model the filter tree from [filter model](references/filter-model.md), preview the count, then upsert the complete tree.
• Segment inspection and recomputation: use segmentsget for the segment record, segmentsgetfilters for the current filter tree, segmentsreload when the user wants membership recomputed, and segmentsgetleads to inspect the resulting cohort.
• Analytics follow-up: use segmentstimeseries or segmentscategories_metrics when the user wants trend or category breakdowns for a segment instead of only raw membership.
• Order of operations: manual list = create or inspect list -> update explicit lead IDs -> verify visible leads. Dynamic segment = inspect current definition -> preview broad or uncertain logic -> replace the full filter tree -> reload when refreshed membership matters -> inspect resulting leads.

Report

• Start with Assumption: manual list or Assumption: dynamic segment when the user's goal could fit both models.
• For lists: report the list name, membership change, current visible count, and show up to 10 notable leads followed by +N more when needed.
• For segments: report the filter logic, preview size, reload state, and current visible count; call out broad conditions that may over-select the cohort.
• Treat follow-up mutations as opt-in: suggest update, reload, or delete only after showing the current state or impact.

Warnings

• Segment filter replacement is full replacement, not append/patch.
• Deleting a segment cascades filters, synced list, and membership.
• Filter-order-only changes may not trigger meaningful recomputation.

Anti-patterns

• Using lists when the user clearly needs a self-updating segment.
• Replacing segment filters without previewing the impact when the logic is broad.
• Treating a synced segment-backed list like an arbitrary manual list.