Skip to main content
Glama
thenavidm

Kit MCP Server

by thenavidm
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Filter subscribers by engagement, sign-up date, state, and tags

filter_subscribers
Read-onlyIdempotent

Filter subscribers by engagement, sign-up date, state, tags, custom fields, or location to segment audiences and retrieve matching account data.

Instructions

Filter subscribers by engagement, sign-up date, state, and tags. Reads account data.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
allNoArray of filter conditions where ALL must be met (AND logic)
accountNoNamed private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account.
includeNoOptional. Array of `{ type, ...config }` objects naming additional fields to embed on each subscriber row. Valid types: `attribution`, `tags`, `location`, `canceled_at`, `stats`, `custom_fields`. The `stats` type accepts an optional `range: { start, end }` (YYYY-MM-DD dates, defaulting to the last 90 days). The `custom_fields` type adds a `fields` object with all account custom field values (null for fields the subscriber has not set).
payloadNoComplete JSON body instead of individual body flags. Supports nullable fields and nested bulk structures. Cannot be combined with body flags or payload_file.
sort_fieldNoField to order results by. Base columns (`id`, `first_name`, `email_address`, `created_at`) order by that subscriber attribute. `engagement__ ` orders by an engagement stat over the trailing 90 days: counts (`sent`, `opens`, `clicks`) and rates (`open_rate`, `click_rate`); subscribers with no sends order as 0. `location__distance` orders by great-circle distance and requires a `location` filter in the same request : its `latitude`/`longitude` supply the origin, and subscribers without a primary location are excluded. Distance defaults to nearest-first (`sort_order` defaults to `asc` for this field); pass `sort_order=desc` for farthest-first.created_at
sort_orderNoSort direction (default: desc).
payload_fileNoLocal JSON request body file, at most 5 MB. Contents are validated before the API call and are never logged.
counting_modeNoControls how engagement-filter count thresholds are tallied. `raw` (default) counts every event : five opens of the same email = five. `unique_email` counts distinct emails on which the action occurred : five opens of the same email = one. Applies to every engagement filter (opens, clicks, sent, delivered) in the request; ignored for other filter types.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv2.0.1

TDQS

C2.5/5.0
Behavior2/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is fully covered elsewhere. The description's only behavioral claim, 'Reads account data,' is redundant with readOnlyHint and adds no new context such as authentication/account resolution, pagination, result-size limits, or rate limiting. For a read tool with annotation coverage this leaves the description contributing essentially nothing beyond the structured fields.

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

Conciseness3/5

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

It is short and front-loaded, which is good, but the second sentence 'Reads account data' does not earn its place because it duplicates readOnlyHint. The brevity here reflects under-specification rather than disciplined economy, given the complexity of the underlying schema.

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

Completeness2/5

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

This is a highly complex tool: 8 parameters, deeply nested AND/OR filter objects, a full-body 'payload' alternative, include/sort/counting_mode options, and no output schema. The two-sentence description covers none of that structure and gives the agent no orientation on the nested filter DSL or the payload-vs-flat-parameter choice. The rich schema prevents a score of 1, but the description is far from adequate for the tool's complexity.

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

Parameters3/5

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

Schema description coverage is 100%, so every one of the 8 parameters is documented in detail within the schema itself. The description adds no parameter-level meaning at all, not even which parameters correspond to the engagement/date/state/tag dimensions it names. Baseline 3 is the correct ceiling when the schema carries the full burden.

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

Purpose3/5

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

The description names a specific verb and resource ('Filter subscribers') and lists the filterable dimensions (engagement, sign-up date, state, tags), so the purpose is discernible. However, the first sentence is a verbatim restatement of the tool title, and it offers no differentiation from close siblings such as list_subscribers or search_subscribers, whose names sit directly adjacent. That leaves the agent to infer from the schema which of the three subscriber-listing tools fits a given request.

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

Usage Guidelines2/5

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

There is no guidance on when to use this tool versus list_subscribers or search_subscribers, no mention of prerequisites, and no statement about when filtering is the wrong approach. The description merely names what can be filtered without indicating the conditions that select this tool over its alternatives.

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

Deploy Server

Other Tools