Skip to main content
Glama

Count who an unsaved filter matches

preview_segment
Read-onlyIdempotent

Use this when the founder wants to know how many contacts a filter matches before anything is saved or touched: to check a filter before create_segment, or before tag_contacts/untag_contacts with a segment + limit ("how many would this touch"). It changes nothing. Not for saving the filter (use create_segment) or for listing the people (use search_audience).

rules is a condition tree: {"match": "and"|"or", "conditions": [...]}. Each condition is either a nested group (same shape, up to 5 deep) or a leaf: {"field": "...", "operator": "...", "value": ...} (the attribute field also needs "key"). An empty or omitted tree matches everyone. An unknown field or an operator illegal for its field is refused, not silently skipped, so a bad filter never gets a count that looks real.

Fields and their legal operators, as of this description (the list may grow; list_segments on an existing segment shows a real one if you want to see the shape in practice):

  • status, trust_tier, deliverability, stage, invite_state, identifier_type, first_source, country, device, browser, os, intent_cluster, unsubscribed_by (contact, owner, complaint; "not" includes people with none recorded), consent (confirmed, signup, imported, owner, v1): eq, neq, in, not_in. value is a string (eq/neq) or an array of strings (in/not_in).

  • referral_count, quality_score: gt, gte, lt, lte (numeric value), or between (value is [min, max]).

  • created_at, verified_at, consented_at: the same comparisons, plus within_last_days (integer value) and exists (no value); verified_at also takes not_exists (not verified, asked or not). ISO 8601 dates.

  • submission_count: eq, gt, gte, lt, lte (numeric value).

  • tag: in / not_in, where value is an array of tag handles (tag_…, from list_segments), or exists (has any tag at all, no value).

  • received_broadcast: in / not_in, where value is an array of 1-50 broadcast handles (bcd_…, must belong to this project) and an optional days (integer, 1-3650) means "sent at least that many days ago". in matches someone who received any of them; not_in matches someone who received none.

  • is_referrer, is_referred: is_true / is_false, no value.

  • awaiting_verification: is_true / is_false, no value. True for someone sent a link to verify their email (an expired one included) who has not clicked it: the Waiting for verification view (with status subscribed) and who recipients: unverified on a broadcast reaches. Someone never asked to verify is false. create_segment refuses it for a few minutes after the update that added it.

  • utm_source, utm_medium, utm_campaign: eq, neq, in, contains, exists.

  • attribute: a captured custom field. Needs "key" (letters, digits, _, . only) alongside field/operator/value. Operators: eq, neq, contains, exists, not_exists, in.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "project": "<project>"
    },
    "name": "preview_segment"
  }
}

Input Schema

NameRequiredDescriptionDefault
rulesNoThe condition tree — see the tool description for the field/operator grammar. Omit to count everyone.
projectYesThe project handle, like `prj_…`.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is structured data. The description still adds real behavior beyond that: empty/omitted tree matches everyone, nesting is capped at 5 deep, unknown fields or illegal operators are refused rather than silently skipped so a bogus filter never yields a plausible count. That is solid added value, but it stops short of saying what the response looks like (just a bare count? any breakdown?), so a 3 under the with-annotations bar.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the routing decision, then a well-organized grammar grouped by operator family (categorical, numeric, date, tag, broadcast, boolean, utm, attribute). The length is largely justified for a free-form nested condition tree, but there is some drift (the `awaiting_verification` section wanders into `create_segment` cooldowns) and the hedge about the list growing adds noise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool whose only real parameter is an open-ended condition tree with no enums and no output schema, the description is nearly complete: it defines the grammar, validation strictness, and default semantics. The one gap is the return value — it never states that the result is a count (and whether it includes anything else), which matters since no output schema exists.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, but the schema only says 'condition tree — see the tool description', so the description carries the entire grammar. It documents the group/leaf shape, per-field legal operators, value types (string vs array vs [min,max]), handle prefixes for tag/broadcast fields, and the `key` requirement for custom attributes — meaning far beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and resource: count how many contacts a filter matches, before anything is saved. It immediately distinguishes itself from `create_segment` (saving) and `search_audience` (listing people), so an agent can route correctly without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use triggers (check a filter before `create_segment`, or before `tag_contacts`/`untag_contacts` with segment+limit) and explicit when-not-to-use with named alternatives. Preconditions and alternatives are both covered.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.