Provides tools for interacting with the Kit API v4 (newsletter/email marketing platform), covering 85 operations: reading account identity, growth and email statistics; drafting, scheduling, updating and deleting broadcasts with click breakdowns; creating, updating, filtering, unsubscribing and tagging subscribers; managing tags, forms, sequences and individual sequence emails; CRUD on snippets and templates; reading posts and segments; OAuth-only purchase endpoints and asynchronous bulk jobs; and configuring signed webhook endpoints with secret rotation.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Kit MCP Server draft a newsletter broadcast about our spring sale and schedule it for tomorrow"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A local MCP server and a scriptable CLI for Kit API v4. Read account data, draft and schedule broadcasts, manage subscribers and tags, edit sequences and snippets, collect email statistics, and configure signed webhooks. 85 tools: 38 reads and 47 writes. 40 audience, delivery, deletion and secret operations require explicit confirmation.
Kit has an official account MCP. It already maps the v4 API and supports both reads and writes. This package adds a standalone task CLI, named local accounts, private token-file refresh, bounded cursor aggregation and a downloadable desktop bundle. It does not claim extra API coverage or measured token savings over the official server. Choose the official remote server if you prefer Kit-managed OAuth and a hosted connection.
The wrapper is free software under its existing AGPL-3.0-or-later license. Kit account access, plan eligibility and service charges remain separate. This is a community integration by Navid Moazzez, not a Kit-endorsed product.
The terminal illustrates the requested draft workflow; it is not a live account transcript.
The matching navid.me guide is prepared with 20 FAQs; authenticated CMS sync is pending. The installation and operation references in this repository are available now.
Section | What you will find |
Coverage and limits | |
Install, discover and authenticate | |
The same handlers in two surfaces | |
Every supported client and desktop route | |
Flags, JSON, nested bodies and exit codes | |
API keys, OAuth and account selection | |
Draft, review, schedule and inspect | |
Filters, tags, forms and sequences | |
Cursors, limits and async results | |
Private signing secrets | |
Complete operations, schemas and arguments | |
Guards, retries, audit and privacy | |
Source-backed differences | |
What is measured and what is pending | |
All environment variables | |
Common failures and remedies | |
Setup, delivery, templates and costs | |
Reproducible schemas, tests and artifacts | |
Migration from the private legacy source | |
Navid Media and links |
Related MCP server: kit-mcp
The pinned official API v4 snapshot contains 83 operations. This server exposes each one, plus list_accounts and the search_subscribers compatibility alias. The snapshot source, date, hash and reviewed corrections are in api-source.json.
Area | Examples |
Account | Identity, creator profile, growth statistics, email statistics and colors |
Broadcasts | Draft, read, update, delete, statistics and click breakdowns |
Subscribers | Create, update, unsubscribe, filter, location, statistics and tags |
Tags, forms, sequences | Read resources, subscribe to a form or sequence, tag and untag |
Sequence emails | Read, create, edit and delete individual emails |
Snippets and templates | Reusable content CRUD supported by the API; list email templates |
Posts and segments | Read published posts and segment metadata |
Purchases and bulk | OAuth-only purchase endpoints and asynchronous bulk jobs |
Webhook endpoints | Signed endpoints, secret rotation and previous-secret revocation |
Legacy webhooks | Older webhook API preserved separately |
The API does not provide all Kit UI actions. This package does not promise visual automation editing, automatic duplication of a designed broadcast, a block editor, a webhook receiver, a hosted scheduler or a browser session. A successful bulk submission is not proof that its asynchronous job has completed.
Check | Status for 2.0.0 |
Official API snapshot | 83 operations, pinned on 2026-10-02 |
Real local MCP discovery | 85 tools, or 38 with read-only enabled |
Behavior and shared CLI | 36 checks passed against controlled HTTP fixtures |
TypeScript | Build and typecheck passed |
Production dependency audit | Zero findings at review time |
Live account reads and writes | Pending a configured v4 key or authorized OAuth session |
Actual Claude Desktop installation | Pending a GUI check; archive and protocol checked separately |
Matched MCP versus CLI model-token task | Pending; no performance percentages asserted |
Fixture tests check request construction and guards. They do not establish that a particular Kit account or email template accepts a live write. Release artifact checks are reported in the release notes when completed.
Install Node.js 22 or newer, then:
npm install -g @thenavidm/kit-mcp-cli@latest
kit-cli --version
kit-cli
kit-cli list-broadcasts --help
kit-cli schema create-broadcast
kit-cli loginDiscovery, help and schemas work before authentication. login prints setup instructions. It does not open a browser, exchange an OAuth code or save credentials. Configure a v4 API key privately as KIT_API_KEY, then:
kit-cli doctor
kit-cli doctor --network
kit-cli get-account --agent
kit-cli list-broadcasts --per-page 10 --agent --select broadcasts.id,broadcasts.subject,paginationThe local doctor checks configuration. The network doctor reads the default account and reports authentication success without returning account details. It never sends a newsletter or changes subscribers.
For a single invocation without a global install:
npx -y --package @thenavidm/kit-mcp-cli@latest kit-cli toolsINSTALL.md covers Node/PATH on macOS, Windows and Linux, private account setup, every client, updates and removal. No .env file is loaded automatically.
Surface | How it runs | Suitable for |
| Local stdio server launched by an MCP client | Natural language account work in a compatible AI app |
| Schema-derived commands with machine-readable output | Scripts, CI and agents with shell access |
| Local MCP server with bundled production dependencies | Claude Desktop custom extensions |
Official Kit MCP | Hosted | Remote connections and browser-only AI clients |
The CLI creates a real MCP server and client connected through the SDK's in-memory transport. It discovers the server's tools and calls the same schemas, validation, handlers and safety guards. Separate handwritten CLI request logic cannot drift from the MCP path.
An MCP client may send tool schemas or deferred tool names into model context. A shell agent instead needs the skill, help, commands and results. Both consume tokens; neither surface guarantees lower total cost for every task.
kit-cli with no arguments lists commands. kit-mcp with no arguments starts stdio and does not print a banner. Avoid launching an interactive banner on an MCP server's stdout.
The full commands and private configurations are in INSTALL.md. Common registrations, after privately configuring account credentials:
claude mcp add --scope user kit -- npx -y @thenavidm/kit-mcp-cli@latest
claude mcp list
codex mcp add kit -- npx -y @thenavidm/kit-mcp-cli@latest
codex mcp listClaude Desktop can install the .mcpb release or use manual JSON. Cursor, Windsurf and Gemini CLI use their user MCP settings; VS Code supports secure prompted inputs; Zed uses context_servers. Local Cline/Roo-style clients accept the same stdio command through their MCP setup UI. A local stdio process is not a public HTTP connector for ChatGPT on the web. Kit's official hosted MCP is the appropriate remote option there.
Desktop settings accept a sensitive API key or a private OAuth token-file path. API-key authentication cannot use OAuth-only bulk and purchase endpoints. Custom extension availability depends on your installed host and organization policy.
Help me install Kit MCP Server & CLI using INSTALL.md. Check Node and the binary, let me configure my account credentials privately, then run discovery and doctor --network. Do not send email or change subscribers during setup.
For shell agents, make SKILL.md available through the client's supported skills location. npm installation does not register the skill automatically.
Tool names become dashed commands: get_broadcast becomes kit-cli get-broadcast. Both exact underscore tool names and dashed forms are accepted. Argument names have dashed aliases: broadcast_id is --broadcast-id. Use help and schema to discover each operation's current input.
kit-cli tools
kit-cli get-broadcast --help
kit-cli schema get-broadcast
kit-cli get-broadcast --broadcast-id 123 --agentFlag | Behavior |
| Current schema-derived arguments and defaults |
| Structured JSON output |
| Compact JSON on one line |
| JSON, compact, no prompts or color |
| Keep selected fields; dotted paths descend through objects and arrays |
| No terminal colors |
| No interactive prompts |
| House noninteractive flag; never substitutes for |
| Explicit confirmation for the requested guarded operation |
| Select a configured local account on API tools |
| Complete request body as one JSON object |
| Complete request body from a local regular JSON file, at most 5 MB |
Body flags and payload/payload_file are mutually exclusive. Path and query flags remain separate. Objects take JSON; array flags repeat once per array item. Do not pass an array to a flag that expects a single item:
kit-cli list-subscribers --include tags --include stats --per-page 10 --agent
kit-cli create-broadcast --payload-file /absolute/private/path/newsletter.json --confirm --agentA shell flag such as --send-at null is the string null, not JSON null. Use the complete body form to return a scheduled broadcast to draft:
kit-cli update-broadcast --broadcast-id 123 --payload '{"send_at":null}' --confirm --agentThe same applies to nullable text, thumbnail and other nullable fields. In an MCP call, send an actual JSON null. Avoid mixing the nullable complete body with individual body flags.
Code | Meaning | A script's next step |
0 | Success | Use the returned data |
2 | Usage, validation or safety refusal | Correct inputs or obtain the requested authorization |
3 | Not found | Verify the resource ID |
4 | Authentication or permission failure | Check key, OAuth state or endpoint eligibility |
5 | Other API or transport failure | Inspect account state before repeating a write |
7 | Rate limit | Wait; mutating requests are not automatically retried |
10 | Missing or invalid local configuration | Repair private configuration |
Errors are JSON on stderr. On success, field selection shapes output only; it does not limit Kit's original response or its API processing.
Open Kit's Developer settings, click Add a new key, name it and save the value privately when shown. Kit does not let you view that value again afterwards. Set KIT_API_KEY in your local shell or client settings. The server sends it in X-Kit-Api-Key, never a URL query string. Old v3 API secrets are not interchangeable.
Kit documents 120 requests over a rolling 60 seconds per API key and 600 for OAuth API access. The official hosted MCP separately documents 120/minute per token. This wrapper spaces calls per account by 550 ms for keys and 110 ms for OAuth. Other processes using the same credential also count against Kit's limits.
Bulk and purchase endpoints in the tool table are marked OAuth-only. Create your own Kit app and enable API access, then implement the official OAuth authorization flow or Kit's Node example. Keep the app's secret on a private confidential backend. Use the callback URI exactly as registered, a cryptographically random state verified on callback, and HTTPS for a hosted callback.
The current authorization and token endpoints are https://api.kit.com/v4/oauth/authorize and https://api.kit.com/v4/oauth/token. There is no built-in OAuth consent service in this package. The old source's app.kit.com/oauth/token examples are obsolete. Follow Kit's current registered-app instructions; do not invent unsupported fine-grained OAuth scopes from operation-schema security labels.
A private token file can contain:
{
"access_token": "YOUR_OAUTH_ACCESS_TOKEN",
"refresh_token": "YOUR_OAUTH_REFRESH_TOKEN",
"client_id": "YOUR_OWN_KIT_APP_CLIENT_ID",
"client_secret": "YOUR_OWN_KIT_APP_CLIENT_SECRET",
"created_at": 1790899200,
"expires_in": 7200
}These are placeholders; use actual issued expiry metadata. Point KIT_TOKENS_FILE at an absolute private path outside the checkout. It must be a regular JSON file, at most 64 KB; symlinks are refused. Restrict access to your OS user. If expiry metadata is available, refresh happens one minute before expiry. Concurrent refreshes within the same process are deduplicated. Updated tokens are written atomically with mode 0600. On Windows, protect the enclosing folder using user-only ACLs; POSIX mode bits are not a complete Windows access policy.
Alternatively set KIT_ACCESS_TOKEN, KIT_REFRESH_TOKEN, KIT_CLIENT_ID and KIT_CLIENT_SECRET privately. Without a token file, refresh state lasts only in that process. Without refresh credentials, renew an expired access token yourself. An OAuth access token takes precedence over an API key for the selected account.
Set KIT_ACCOUNTS to a private JSON array. Its supported keys are name, api_key, access_token, refresh_token, client_id, client_secret and tokens_file. It replaces the single-account variables:
[
{"name":"work","api_key":"YOUR_WORK_V4_KEY"},
{"name":"personal","tokens_file":"/absolute/private/path/personal-kit.json"}
]Set KIT_DEFAULT_ACCOUNT=work, then:
kit-cli list-accounts --agent
kit-cli list-broadcasts --account work --per-page 10 --agent
kit-cli get-growth-stats --account personal --agentNames must be unique. list_accounts exposes labels, default choice and auth type only, never credentials or file paths. Guard logs omit account names. Separate processes are still preferable when you need strict account isolation.
A create call defaults to public:false and send_at:null. It creates a private unscheduled draft. It still requires confirmation because it changes account content and can accept delivery fields when explicitly supplied.
kit-cli list-email-templates --agent
kit-cli create-broadcast --subject "This week's creator notes" --content '<p>Write the actual newsletter here.</p>' --confirm --agent --select broadcast.id,broadcast.subject,broadcast.send_at
kit-cli get-broadcast --broadcast-id BROADCAST_ID_FROM_RESULT --agentPositive IDs are returned by Kit; replace illustrative markers with real IDs. For an existing draft, validate the intended audience and delivery time before the separate confirmed update:
kit-cli update-broadcast --broadcast-id 123 --payload-file /absolute/private/path/schedule.json --confirm --agentYour private schedule.json contains the ISO timestamp and the audience fields from the current schema, for example send_at with a timezone offset or UTC Z. published_at controls web publication metadata; it is not the email send time. Neither successful creation nor a local confirmation proves delivery. Read the broadcast and statistics afterwards.
The API's content is HTML; it is not Kit's visual editor block tree. Preserve the full email wrapper and required Liquid unsubscribe/address markup when replacing content. Retrieve an existing example and inspect the selected template before updating. Do not replace a whole template with one paragraph if you need its existing branding and legal footer.
Kit's current OpenAPI prose contradicts itself around Starting point templates and required fields. This wrapper accepts a subject plus either content or email_template_id, allows nonempty partial broadcast updates, and exposes the documented allow_starting_point flag. These reviewed corrections are recorded with the snapshot. Starting point behavior remains unverified against a live account, so test with a private unscheduled draft and inspect it in Kit before any send.
kit-cli list-broadcasts --per-page 10 --agent --select broadcasts.id,broadcasts.subject,pagination
kit-cli get-broadcast-stats --broadcast-id 123 --agent
kit-cli get-broadcast-clicks --broadcast-id 123 --agentThe client does not automatically retry POST, PUT, PATCH or DELETE requests. A timeout can have an unknown outcome. Check the existing draft or scheduled broadcast before repeating a write; sending twice cannot be undone by a retry wrapper.
Find an exact email or read a bounded list, then choose a requested audience change:
kit-cli search-subscribers --email-address reader@example.com --agent
kit-cli list-tags --agent
kit-cli tag-subscriber --tag-id 123 --email-address reader@example.com --confirm --agent
kit-cli list-subscriber-tags --subscriber-id 456 --agentThe .example address is illustrative. Do not add or tag real people without the requested account action. Tagging and form/sequence enrollment may trigger existing Kit automations.
filter_subscribers is a read-only POST with nested all/any filters. Use its current schema and a private JSON body; it is not a v3 page-number endpoint. search_subscribers is an exact-email compatibility alias, not a fuzzy search engine.
Sequences now have their own create/update/delete endpoints and individual email operations. Read their schemas and current delay units before using them. Sequence enrollment can deliver email through existing automation, so it is confirmed even if the API call itself merely adds a subscriber.
Custom field and tag creation are reversible configuration writes, so they do not require --confirm; they still disappear in read-only mode. Deletions, audience changes, snippets that can affect email and purchases are guarded. The tool table labels every operation.
Kit v4 uses after, before, start_cursor and end_cursor, not old v3 numeric page arguments. Default per_page is 500, maximum 1000. Ask for a small page when you only need a sample:
kit-cli list-subscribers --per-page 25 --include-total-count --agent
kit-cli list-subscribers --after END_CURSOR_FROM_RESULT --per-page 25 --agent
kit-cli list-subscribers --all-pages --max-items 1000 --agentDo not supply both before and after. all_pages traverses forward and refuses before. It stops at max_items (default 1000, maximum 10000) or 100 pages, and refuses repeated cursors. It reduces each page size to the remaining cap so the returned end cursor does not skip unseen records. Aggregated output includes collected, pages, the last pagination object and truncated.
include_total_count must be requested where supported; total count can add API work. max_items without all_pages is a usage error. This is bounded retrieval, not a backup/export guarantee for an entire large account.
The full API snapshot supplies nested request schemas and endpoint-specific limits. Discover the body and put private batches outside the checkout:
kit-cli schema bulk-create-subscribers
kit-cli bulk-create-subscribers --payload-file /absolute/private/path/subscribers.json --confirm --agentSome bulk operations require a callback URL. Use HTTPS on a receiver you control and inspect its actual completion notification. The wrapper does not deploy or listen for callbacks. Split payloads according to Kit's current per-endpoint limits and the local 5 MB request cap. Do not retry an asynchronous submission merely because its completion has not arrived yet.
The current signed webhook_endpoints family and older webhooks are separate APIs. Prefer signed endpoints for new setups. Discover the accepted event enum from the current schema:
kit-cli schema create-webhook-endpoint
kit-cli create-webhook-endpoint --url https://your-receiver.example/kit --events EVENT_FROM_SCHEMA --secret-name newsletter-hook --confirm --agentReplace both placeholders with your own endpoint and a supported event. Creation and secret rotation require a new secret_name. Before the remote call, the server reserves that filename exclusively under KIT_PRIVATE_DIR (default ~/.config/kit-mcp-cli/secrets) with mode 0600. Existing files are never overwritten.
Returned signing secrets are redacted from model/CLI output and saved to the private file. The result exposes secret_file, not the secret itself. Configure your own receiver's signature verification privately. The package does not provide a receiver or claim that the endpoint is reachable. Protect private folders with Windows ACLs where applicable.
When rotating, update and verify your receiver before revoking the previous secret. If Kit changed the endpoint but local secret storage failed, inspect the remote endpoint before attempting rotation again. Do not paste signing secrets in an AI chat or public issue.
The following catalog is generated from the actual tools/list result. Body-required fields are enforced within payload or individual body arguments at execution; path/query requirements appear in each input schema. schema <command> is the exact machine-readable reference. OAuth-only labels come from the pinned operation security definitions.
Tool | API | Mode | OAuth only |
|
| Read | No |
|
| Read | No |
|
| Write | No |
|
| Read | No |
|
| Read | No |
|
| Read | No |
|
| Read | No |
|
| Write, confirms | No |
|
| Read | No |
|
| Read | No |
|
| Read | No |
|
| Write, confirms | No |
|
| Read | No |
|
| Write, confirms | No |
|
| Write | Yes |
|
| Write, confirms | Yes |
|
| Read | No |
|
| Write | No |
|
| Write, confirms | No |
|
| Write | No |
|
| Read | No |
|
| Write, confirms | Yes |
|
| Read | No |
|
| Read | No |
|
| Write, confirms | No |
|
| Write, confirms | No |
|
| Read | No |
|
| Read | No |
|
| Read | Yes |
|
| Write, confirms | Yes |
|
| Read | Yes |
|
| Read | No |
|
| Read | No |
|
| Write, confirms | No |
|
| Write, confirms | No |
|
| Read | No |
|
| Write, confirms | No |
|
| Read | No |
|
| Write, confirms | No |
|
| Write, confirms | No |
|
| Read | No |
|
| Write, confirms | No |
|
| Read | No |
|
| Write, confirms | No |
|
| Write, confirms | No |
|
| Read | No |
|
| Write, confirms | No |
|
| Read | No |
|
| Write, confirms | No |
|
| Write, confirms | Yes |
|
| Read | No |
|
| Write, confirms | No |
|
| Read | No |
|
| Read | No |
|
| Write, confirms | No |
|
| Write, confirms | No |
|
| Write, confirms | No |
|
| Write, confirms | No |
|
| Write, confirms | No |
|
| Read | No |
|
| Read | No |
|
| Write, confirms | Yes |
|
| Write | Yes |
|
| Write, confirms | Yes |
|
| Write, confirms | Yes |
|
| Read | No |
|
| Write | No |
|
| Write | No |
|
| Write, confirms | No |
|
| Read | No |
|
| Write, confirms | No |
|
| Write, confirms | No |
|
| Write, confirms | No |
|
| Read | No |
|
| Write, confirms | No |
|
| Write, confirms | No |
|
| Read | No |
|
| Write, confirms | No |
|
| Write, confirms | No |
|
| Write, confirms | No |
|
| Read | No |
|
| Write, confirms | No |
|
| Write, confirms | No |
| Alias for GET /v4/subscribers with exact email | Read | No |
| Local labels only | Read | No |
Every API tool accepts optional account. Writes accept confirm; the 40 guarded operations require it to be true. Pagination controls are included only on tools whose schema supports cursor pagination. Body tools accept either their individual body fields or payload/payload_file. list_accounts accepts no arguments.
Get current account. Read-only.
kit-cli get-account --helpArgument | Type | Required | Meaning |
List colors. Read-only.
kit-cli list-colors --helpArgument | Type | Required | Meaning |
Update colors. Reversible configuration write.
kit-cli update-colors --helpArgument | Type | Required | Meaning |
| array | Body | An array of up to 10 color hex codes |
Get Creator Profile. Read-only.
kit-cli get-creator-profile --helpArgument | Type | Required | Meaning |
Get email stats. Read-only.
kit-cli get-email-stats --helpArgument | Type | Required | Meaning |
Get growth stats. Read-only.
kit-cli get-growth-stats --helpArgument | Type | Required | Meaning |
| string | No | See the exact input schema. |
| string | No | See the exact input schema. |
List broadcasts. Read-only.
kit-cli list-broadcasts --helpArgument | Type | Required | Meaning |
| schema | No | See the exact input schema. |
| schema | No | See the exact input schema. |
| boolean | No | See the exact input schema. |
| schema | No | See the exact input schema. |
| schema | No | See the exact input schema. |
| schema | No | See the exact input schema. |
| boolean | No | See the exact input schema. |
| string | No | Values: |
| boolean | No | Read successive cursor pages, bounded by max_items (default 1000). Default false returns one API page. |
| integer | No | Maximum records when all_pages=true. A capped result reports truncation and its continuation cursor. |
Create a broadcast. Requires confirmation.
kit-cli create-broadcast --helpArgument | Type | Required | Meaning |
| integer | No | Id of the email template to use. Uses the account's default template if not provided. 'Starting point' template is not supported. |
| string/null | No | The sending email address to use. Uses the account's sending email address if not provided. |
| string | No | The HTML content of the email. On a |
| string | No | See the exact input schema. |
| boolean | No |
|
| string | No | The published timestamp to display in ISO8601 format. If no timezone is provided, UTC is assumed. |
| string/null | No | The scheduled send time for this broadcast in ISO8601 format. If no timezone is provided, UTC is assumed. |
| string/null | No | See the exact input schema. |
| string/null | No | See the exact input schema. |
| string | No | See the exact input schema. |
| string | Body | See the exact input schema. |
| array | No | Filters your subscribers. At this time, we only support using only one filter group type via the API (e.g. |
| boolean | No | Explicitly allow replacing a Starting point template body, as described in Kit’s current content-field documentation. Review the complete rendered HTML first. |
Body alternatives: content; email_template_id.
Get stats for a list of broadcasts. Read-only.
kit-cli list-broadcast-stats --helpArgument | Type | Required | Meaning |
| schema | No | See the exact input schema. |
| schema | No | See the exact input schema. |
| boolean | No | See the exact input schema. |
| schema | No | See the exact input schema. |
| schema | No | See the exact input schema. |
| schema | No | See the exact input schema. |
| string | No | Values: |
| boolean | No | Read successive cursor pages, bounded by max_items (default 1000). Default false returns one API page. |
| integer | No | Maximum records when all_pages=true. A capped result reports truncation and its continuation cursor. |
Get link clicks for a broadcast. Read-only.
kit-cli get-broadcast-clicks --helpArgument | Type | Required | Meaning |
| schema | Yes | Positive broadcast id. |
Get stats for a broadcast. Read-only.
kit-cli get-broadcast-stats --helpArgument | Type | Required | Meaning |
| schema | Yes | Positive broadcast id. |
Delete a broadcast. Requires confirmation.
kit-cli delete-broadcast --helpArgument | Type | Required | Meaning |
| schema | Yes | Positive broadcast id. |
Get a broadcast. Read-only.
kit-cli get-broadcast --helpArgument | Type | Required | Meaning |
| schema | Yes | Positive broadcast id. |
Update a broadcast. Requires confirmation.
kit-cli update-broadcast --helpArgument | Type | Required | Meaning |
| schema | Yes | Positive broadcast id. |
| integer | No | Id of the email template to use. Uses the account's default template if not provided. 'Starting point' template is not supported. |
| string/null | No | The sending email address to use. Uses the account's sending email address if not provided. |
| string | No | The HTML content of the email. On a |
| string | No | See the exact input schema. |
| boolean | No |
|
| string | No | The published timestamp to display in ISO8601 format. If no timezone is provided, UTC is assumed. |
| string/null | No | The scheduled send time for this broadcast in ISO8601 format. If no timezone is provided, UTC is assumed. |
| string/null | No | See the exact input schema. |
| string/null | No | See the exact input schema. |
| string | No | See the exact input schema. |
| string | No | See the exact input schema. |
| array | No | Filters your subscribers. At this time, we only support using only one filter group type via the API (e.g. |
| boolean | No | Explicitly allow replacing a Starting point template body, as described in Kit’s current content-field documentation. Review the complete rendered HTML first. |
Bulk create custom fields. OAuth-only. Reversible configuration write.
kit-cli bulk-create-custom-fields --helpArgument | Type | Required | Meaning |
| array | Body | See the exact input schema. |
| string/null | No | See the exact input schema. |
Bulk update subscriber custom field values. OAuth-only. Requires confirmation.
kit-cli bulk-update-subscriber-custom-field-values --helpArgument | Type | Required | Meaning |
| array | Body | See the exact input schema. |
| schema | Body | See the exact input schema. |
List custom fields. Read-only.
kit-cli list-custom-fields --helpArgument | Type | Required | Meaning |
| schema | No | See the exact input schema. |
| schema | No | See the exact input schema. |
| boolean | No | See the exact input schema. |
| schema | No | See the exact input schema. |
| boolean | No | Read successive cursor pages, bounded by max_items (default 1000). Default false returns one API page. |
| integer | No | Maximum records when all_pages=true. A capped result reports truncation and its continuation cursor. |
Create a custom field. Reversible configuration write.
kit-cli create-custom-field --helpArgument | Type | Required | Meaning |
| string | Body | See the exact input schema. |
Delete custom field. Requires confirmation.
kit-cli delete-custom-field --helpArgument | Type | Required | Meaning |
| schema | Yes | Positive custom field id. |
Update a custom field. Reversible configuration write.
kit-cli update-custom-field --helpArgument | Type | Required | Meaning |
| schema | Yes | Positive custom field id. |
| string | Body | See the exact input schema. |
List email templates. Read-only.
kit-cli list-email-templates --helpArgument | Type | Required | Meaning |
| schema | No | See the exact input schema. |
| schema | No | See the exact input schema. |
| boolean | No | See the exact input schema. |
| schema | No | See the exact input schema. |
| boolean | No | Read successive cursor pages, bounded by max_items (default 1000). Default false returns one API page. |
| integer | No | Maximum records when all_pages=true. A capped result reports truncation and its continuation cursor. |
Bulk add subscribers to forms. OAuth-only. Requires confirmation.
kit-cli bulk-add-subscribers-to-forms --helpArgument | Type | Required | Meaning |
| array | Body | See the exact input schema. |
| string/null | No | See the exact input schema. |
List forms. Read-only.
kit-cli list-forms --helpArgument | Type | Required | Meaning |
| schema | No | See the exact input schema. |
| schema | No | See the exact input schema. |
| boolean | No | See the exact input schema. |
| schema | No | See the exact input schema. |
| string/null | No | Values: |
| schema | No | See the exact input schema. |
| string | No | See the exact input schema. |
| boolean | No | Read successive cursor pages, bounded by max_items (default 1000). Default false returns one API page. |
| integer | No | Maximum records when all_pages=true. A capped result reports truncation and its continuation cursor. |
List subscribers for a form. Read-only.
kit-cli list-subscribers-for-form --helpArgument | Type | Required | Meaning |
| string/null | No | See the exact input schema. |
| string/null | No | See the exact input schema. |
| schema | No | See the exact input schema. |
| schema | No | See the exact input schema. |
| string/null | No | See the exact input schema. |
| string/null | No | See the exact input schema. |
| schema | Yes | Positive form id. |
| boolean | No | See the exact input schema. |
| schema | No | See the exact input schema. |
| boolean | No | See the exact input schema. |
| string | No | Values: |
| boolean | No | Read successive cursor pages, bounded by max_items (default 1000). Default false returns one API page. |
| integer | No | Maximum records when all_pages=true. A capped result reports truncation and its continuation cursor. |
Add subscriber to form by email address. Requires confirmation.
kit-cli add-subscriber-to-form --helpArgument | Type | Required | Meaning |
| schema | Yes | Positive form id. |
| string | Body | See the exact input schema. |
| string/null | No | See the exact input schema. |
Add subscriber to form. Requires confirmation.
kit-cli add-subscriber-to-form-by-id --helpArgument | Type | Required | Meaning |
| schema | Yes | Positive form id. |
| schema | Yes | Positive subscriber id. |
| string | Body | See the exact input schema. |
List posts. Read-only.
kit-cli list-posts --helpArgument | Type | Required | Meaning |
| schema | No | See the exact input schema. |
| schema | No | See the exact input schema. |
| boolean | No | See the exact input schema. |
| boolean | No | See the exact input schema. |
| schema | No | See the exact input schema. |
| boolean | No | Read successive cursor pages, bounded by max_items (default 1000). Default false returns one API page. |
| integer | No | Maximum records when all_pages=true. A capped result reports truncation and its continuation cursor. |
Get a post. Read-only.
kit-cli get-post --helpArgument | Type | Required | Meaning |
| schema | Yes | Positive post id. |
List purchases. OAuth-only. Read-only.
kit-cli list-purchases --helpArgument | Type | Required | Meaning |
| schema | No | See the exact input schema. |
| schema | No | See the exact input schema. |
| boolean | No | See the exact input schema. |
| schema | No | See the exact input schema. |
| boolean | No | Read successive cursor pages, bounded by max_items (default 1000). Default false returns one API page. |
| integer | No | Maximum records when all_pages=true. A capped result reports truncation and its continuation cursor. |
Create a purchase. OAuth-only. Requires confirmation.
kit-cli create-purchase --helpArgument | Type | Required | Meaning |
| object | Body | See the exact input schema. |
Get a purchase. OAuth-only. Read-only.
kit-cli get-purchase --helpArgument | Type | Required | Meaning |
| schema | Yes | Positive purchase id. |
List segments. Read-only.
kit-cli list-segments --helpArgument | Type | Required | Meaning |
| schema | No | See the exact input schema. |
| schema | No | See the exact input schema. |
| boolean | No | See the exact input schema. |
| schema | No | See the exact input schema. |
| boolean | No | Read successive cursor pages, bounded by max_items (default 1000). Default false returns one API page. |
| integer | No | Maximum records when all_pages=true. A capped result reports truncation and its continuation cursor. |
List sequence emails. Read-only.
kit-cli list-sequence-emails --helpArgument | Type | Required | Meaning |
| schema | No | See the exact input schema. |
| schema | No | See the exact input schema. |
| schema | No | See the exact input schema. |
| boolean | No | See the exact input schema. |
| schema | No | See the exact input schema. |
| schema | Yes | Positive sequence id. |
| string | No | See the exact input schema. |
| boolean | No | Read successive cursor pages, bounded by max_items (default 1000). Default false returns one API page. |
| integer | No | Maximum records when all_pages=true. A capped result reports truncation and its continuation cursor. |
Create a sequence email. Requires confirmation.
kit-cli create-sequence-email --helpArgument | Type | Required | Meaning |
| schema | Yes | Positive sequence id. |
| string | Body | Subject line of the email |
| string/null | No | Preview text shown in email clients before the email is opened |
| string/null | No | HTML body content of the email |
| integer | Body | Number of days or hours to wait before sending this email after the previous one |
| string | Body | Unit for the send delay. Use |
| integer/null | No | ID of the email template to use for layout and styling |
| boolean | No | Whether the email is active and will be sent to subscribers. Defaults to |
| array/null | No | Days of the week this email may be sent. Defaults to all 7 days (inherits the sequence schedule). Pass a subset to restrict delivery, or |
| integer/null | No | Zero-based position of the email in the sequence. Assigned automatically after the last email if omitted |
Delete a sequence email. Requires confirmation.
kit-cli delete-sequence-email --helpArgument | Type | Required | Meaning |
| schema | Yes | Positive email id. |
| schema | Yes | Positive sequence id. |
Get a sequence email. Read-only.
kit-cli get-sequence-email --helpArgument | Type | Required | Meaning |
| schema | Yes | Positive email id. |
| schema | Yes | Positive sequence id. |
| string | No | See the exact input schema. |
Update a sequence email. Requires confirmation.
kit-cli update-sequence-email --helpArgument | Type | Required | Meaning |
| schema | Yes | Positive email id. |
| schema | Yes | Positive sequence id. |
| string | No | New subject line for the email |
| string/null | No | New preview text shown in email clients before the email is opened |
| string/null | No | New HTML body content of the email |
| integer | No | New delay value |
| string | No | New delay unit. Use |
| integer/null | No | New email template ID for layout and styling. Pass |
| boolean | No | Pass |
| array/null | No | Days of the week this email may be sent. Pass a subset to restrict delivery, or |
| integer/null | No | New zero-based position of the email in the sequence |
List sequences. Read-only.
kit-cli list-sequences --helpArgument | Type | Required | Meaning |
| schema | No | See the exact input schema. |
| schema | No | See the exact input schema. |
| boolean | No | See the exact input schema. |
| schema | No | See the exact input schema. |
| string | No | See the exact input schema. |
| boolean | No | Read successive cursor pages, bounded by max_items (default 1000). Default false returns one API page. |
| integer | No | Maximum records when all_pages=true. A capped result reports truncation and its continuation cursor. |
Create a sequence. Requires confirmation.
kit-cli create-sequence --helpArgument | Type | Required | Meaning |
| string | No | The name of the sequence. |
| string | No | The sending email address to use. Uses the account's sending email address if not provided. |
| integer | No | Id of the email template to use. |
| array | No | The days of the week to send the sequence on. Must be one of: |
| integer | No | The hour of the day to send the sequence at. Must be an integer between 0 and 23. |
| string | No | The timezone to use for the sequence. Must be a valid IANA timezone string. |
| boolean | No |
|
| boolean | No | When |
| boolean | No | When |
| array | No | The subscriber sources to exclude from the sequence. |
Delete a sequence. Requires confirmation.
kit-cli delete-sequence --helpArgument | Type | Required | Meaning |
| schema | Yes | Positive sequence id. |
Get a sequence. Read-only.
kit-cli get-sequence --helpArgument | Type | Required | Meaning |
| schema | Yes | Positive sequence id. |
| string | No | See the exact input schema. |
Update a sequence. Requires confirmation.
kit-cli update-sequence --helpArgument | Type | Required | Meaning |
| schema | Yes | Positive sequence id. |
| string | No | The name of the sequence. |
| string | No | The sending email address to use. Uses the account's sending email address if not provided. |
| integer | No | Id of the email template to use. |
| array | No | The days of the week to send the sequence on. Must be one of: |
| integer | No | The hour of the day to send the sequence at. Must be an integer between 0 and 23. |
| string | No | The timezone to use for the sequence. Must be a valid IANA timezone string. |
| boolean | No |
|
| boolean | No | When |
| boolean | No | When |
| array | No | The subscriber sources to exclude from the sequence. |
List subscribers for a sequence. Read-only.
kit-cli list-subscribers-for-sequence --helpArgument | Type | Required | Meaning |
| string/null | No | See the exact input schema. |
| string/null | No | See the exact input schema. |
| schema | No | See the exact input schema. |
| schema | No | See the exact input schema. |
| string/null | No | See the exact input schema. |
| string/null | No | See the exact input schema. |
| boolean | No | See the exact input schema. |
| schema | No | See the exact input schema. |
| schema | Yes | Positive sequence id. |
| string | No | Values: |
| boolean | No | Read successive cursor pages, bounded by max_items (default 1000). Default false returns one API page. |
| integer | No | Maximum records when all_pages=true. A capped result reports truncation and its continuation cursor. |
Add subscriber to sequence by email address. Requires confirmation.
kit-cli add-subscriber-to-sequence --helpArgument | Type | Required | Meaning |
| schema | Yes | Positive sequence id. |
| string | Body | See the exact input schema. |
Add subscriber to sequence. Requires confirmation.
kit-cli add-subscriber-to-sequence-by-id --helpArgument | Type | Required | Meaning |
| schema | Yes | Positive subscriber id. |
| schema | Yes | Positive sequence id. |
List snippets. Read-only.
kit-cli list-snippets --helpArgument | Type | Required | Meaning |
| schema | No | See the exact input schema. |
| schema | No | See the exact input schema. |
| schema | No | See the exact input schema. |
| boolean | No | See the exact input schema. |
| boolean | No | See the exact input schema. |
| schema | No | See the exact input schema. |
| schema | No | See the exact input schema. |
| boolean | No | Read successive cursor pages, bounded by max_items (default 1000). Default false returns one API page. |
| integer | No | Maximum records when all_pages=true. A capped result reports truncation and its continuation cursor. |
Create a snippet. Requires confirmation.
kit-cli create-snippet --helpArgument | Type | Required | Meaning |
Get a snippet. Read-only.
kit-cli get-snippet --helpArgument | Type | Required | Meaning |
| schema | Yes | Positive snippet id. |
Update a snippet. Requires confirmation.
kit-cli update-snippet --helpArgument | Type | Required | Meaning |
| schema | Yes | Positive snippet id. |
Bulk create subscribers. OAuth-only. Requires confirmation.
kit-cli bulk-create-subscribers --helpArgument | Type | Required | Meaning |
| array | Body | See the exact input schema. |
| string/null | No | See the exact input schema. |
List subscribers. Read-only.
kit-cli list-subscribers --helpArgument | Type | Required | Meaning |
| string/null | No | See the exact input schema. |
| string/null | No | See the exact input schema. |
| string | No | See the exact input schema. |
| string | No | See the exact input schema. |
| string | No | See the exact input schema. |
| string | No | See the exact input schema. |
| boolean | No | See the exact input schema. |
| number/null | No | See the exact input schema. |
| boolean | No | See the exact input schema. |
| string | No | Values: |
| string | No | Values: |
| string | No | Values: |
| string | No | See the exact input schema. |
| string | No | See the exact input schema. |
| boolean | No | Read successive cursor pages, bounded by max_items (default 1000). Default false returns one API page. |
| integer | No | Maximum records when all_pages=true. A capped result reports truncation and its continuation cursor. |
Create a subscriber. Requires confirmation.
kit-cli create-subscriber --helpArgument | Type | Required | Meaning |
| string/null | No | See the exact input schema. |
| string | Body | See the exact input schema. |
| string/null | No | Create subscriber in this state ( |
| object | No | Custom field values keyed by the custom field's |
Filter subscribers by engagement, sign-up date, state, and tags. Read-only.
kit-cli filter-subscribers --helpArgument | Type | Required | Meaning |
| string | No | Controls how engagement-filter count thresholds are tallied. |
| array | Body | Array of filter conditions where ALL must be met (AND logic) |
| array | No | Optional. Array of |
| string | No | Field to order results by. Base columns ( |
| string | No | Sort direction (default: desc). Values: |
Get a subscriber. Read-only.
kit-cli get-subscriber --helpArgument | Type | Required | Meaning |
| schema | Yes | Positive subscriber id. |
Update a subscriber. Requires confirmation.
kit-cli update-subscriber --helpArgument | Type | Required | Meaning |
| schema | Yes | Positive subscriber id. |
| string/null | No | See the exact input schema. |
| string | Body | See the exact input schema. |
| object | No | Custom field values keyed by the custom field's |
Unsubscribe subscriber. Requires confirmation.
kit-cli unsubscribe --helpArgument | Type | Required | Meaning |
| schema | Yes | Positive subscriber id. |
Delete a subscriber's location. Requires confirmation.
kit-cli delete-subscriber-location --helpArgument | Type | Required | Meaning |
| schema | Yes | Positive subscriber id. |
Update a subscriber's pinned location. Requires confirmation.
kit-cli update-subscriber-location --helpArgument | Type | Required | Meaning |
| schema | Yes | Positive subscriber id. |
| object | Body | See the exact input schema. |
Pin a subscriber's location. Requires confirmation.
kit-cli pin-subscriber-location --helpArgument | Type | Required | Meaning |
| schema | Yes | Positive subscriber id. |
| object | Body | See the exact input schema. |
List stats for a subscriber. Read-only.
kit-cli get-subscriber-stats --helpArgument | Type | Required | Meaning |
| string | No | See the exact input schema. |
| string | No | See the exact input schema. |
| schema | Yes | Positive subscriber id. |
List tags for a subscriber. Read-only.
kit-cli list-subscriber-tags --helpArgument | Type | Required | Meaning |
| schema | No | See the exact input schema. |
| schema | No | See the exact input schema. |
| boolean | No | See the exact input schema. |
| schema | No | See the exact input schema. |
| schema | Yes | Positive subscriber id. |
| boolean | No | Read successive cursor pages, bounded by max_items (default 1000). Default false returns one API page. |
| integer | No | Maximum records when all_pages=true. A capped result reports truncation and its continuation cursor. |
Bulk delete tags. OAuth-only. Requires confirmation.
kit-cli bulk-delete-tags --helpArgument | Type | Required | Meaning |
| array | Body | Tags to delete, identified by |
| string/null | No | Optional. When the batch is processed asynchronously (more than 100 tags), the results are POSTed to this URL on completion. |
Bulk create tags. OAuth-only. Reversible configuration write.
kit-cli bulk-create-tags --helpArgument | Type | Required | Meaning |
| array | Body | See the exact input schema. |
| string/null | No | See the exact input schema. |
Bulk remove tags from subscribers. OAuth-only. Requires confirmation.
kit-cli bulk-remove-tags-from-subscribers --helpArgument | Type | Required | Meaning |
Bulk tag subscribers. OAuth-only. Requires confirmation.
kit-cli bulk-tag-subscribers --helpArgument | Type | Required | Meaning |
| array | Body | See the exact input schema. |
| string/null | No | See the exact input schema. |
List tags. Read-only.
kit-cli list-tags --helpArgument | Type | Required | Meaning |
| schema | No | See the exact input schema. |
| schema | No | See the exact input schema. |
| boolean | No | See the exact input schema. |
| schema | No | See the exact input schema. |
| string | No | See the exact input schema. |
| boolean | No | Read successive cursor pages, bounded by max_items (default 1000). Default false returns one API page. |
| integer | No | Maximum records when all_pages=true. A capped result reports truncation and its continuation cursor. |
Create a tag. Reversible configuration write.
kit-cli create-tag --helpArgument | Type | Required | Meaning |
| string | Body | See the exact input schema. |
Update tag name. Reversible configuration write.
kit-cli update-tag-name --helpArgument | Type | Required | Meaning |
| schema | Yes | Positive tag id. |
| string | Body | See the exact input schema. |
Remove tag from subscriber by email address. Requires confirmation.
kit-cli untag-subscriber-by-email --helpArgument | Type | Required | Meaning |
| schema | Yes | Positive tag id. |
| string | Yes | See the exact input schema. |
List subscribers for a tag. Read-only.
kit-cli list-subscribers-for-tag --helpArgument | Type | Required | Meaning |
| schema | No | See the exact input schema. |
| schema | No | See the exact input schema. |
| string/null | No | See the exact input schema. |
| string/null | No | See the exact input schema. |
| boolean | No | See the exact input schema. |
| schema | No | See the exact input schema. |
| boolean | No | See the exact input schema. |
| string | No | Values: |
| schema | Yes | Positive tag id. |
| string/null | No | See the exact input schema. |
| string/null | No | See the exact input schema. |
| boolean | No | Read successive cursor pages, bounded by max_items (default 1000). Default false returns one API page. |
| integer | No | Maximum records when all_pages=true. A capped result reports truncation and its continuation cursor. |
Tag a subscriber by email address. Requires confirmation.
kit-cli tag-subscriber --helpArgument | Type | Required | Meaning |
| schema | Yes | Positive tag id. |
| string | Body | See the exact input schema. |
Remove tag from subscriber. Requires confirmation.
kit-cli untag-subscriber --helpArgument | Type | Required | Meaning |
| schema | Yes | Positive subscriber id. |
| schema | Yes | Positive tag id. |
Tag a subscriber. Requires confirmation.
kit-cli tag-subscriber-by-id --helpArgument | Type | Required | Meaning |
| schema | Yes | Positive subscriber id. |
| schema | Yes | Positive tag id. |
List webhook endpoints. Read-only.
kit-cli list-webhook-endpoints --helpArgument | Type | Required | Meaning |
| schema | No | See the exact input schema. |
| schema | No | See the exact input schema. |
| boolean | No | See the exact input schema. |
| schema | No | See the exact input schema. |
| string | No | Values: |
| boolean | No | Read successive cursor pages, bounded by max_items (default 1000). Default false returns one API page. |
| integer | No | Maximum records when all_pages=true. A capped result reports truncation and its continuation cursor. |
Create a webhook endpoint. Requires confirmation.
kit-cli create-webhook-endpoint --helpArgument | Type | Required | Meaning |
| string | Body | See the exact input schema. |
| array | Body | Event types this endpoint subscribes to (e.g. |
| string | No | See the exact input schema. |
| string | No | See the exact input schema. |
| string | Yes | New private filename under KIT_PRIVATE_DIR. Required before creating/rotating a signing secret; never overwritten. |
Delete a webhook endpoint. Requires confirmation.
kit-cli delete-webhook-endpoint --helpArgument | Type | Required | Meaning |
| schema | Yes | Positive webhook endpoint id. |
Get a webhook endpoint. Read-only.
kit-cli get-webhook-endpoint --helpArgument | Type | Required | Meaning |
| schema | Yes | Positive webhook endpoint id. |
Update a webhook endpoint. Requires confirmation.
kit-cli update-webhook-endpoint --helpArgument | Type | Required | Meaning |
| schema | Yes | Positive webhook endpoint id. |
| string | No | See the exact input schema. |
| string | No | See the exact input schema. |
| string | No | See the exact input schema. |
| string | No | Endpoint status. One of: |
| array | No | Event types this endpoint subscribes to (e.g. |
Revoke the previous webhook endpoint secret. Requires confirmation.
kit-cli revoke-previous-webhook-secret --helpArgument | Type | Required | Meaning |
| schema | Yes | Positive webhook endpoint id. |
Rotate a webhook endpoint secret. Requires confirmation.
kit-cli rotate-webhook-secret --helpArgument | Type | Required | Meaning |
| schema | Yes | Positive webhook endpoint id. |
| boolean | No | Rotating again while a previous rotation's overlap window is still open returns |
| string | Yes | New private filename under KIT_PRIVATE_DIR. Required before creating/rotating a signing secret; never overwritten. |
List webhooks. Read-only.
kit-cli list-webhooks --helpArgument | Type | Required | Meaning |
| schema | No | See the exact input schema. |
| schema | No | See the exact input schema. |
| boolean | No | See the exact input schema. |
| schema | No | See the exact input schema. |
| boolean | No | Read successive cursor pages, bounded by max_items (default 1000). Default false returns one API page. |
| integer | No | Maximum records when all_pages=true. A capped result reports truncation and its continuation cursor. |
Create a webhook. Requires confirmation.
kit-cli create-webhook --helpArgument | Type | Required | Meaning |
| string | Body | See the exact input schema. |
| object | Body | See the exact input schema. |
Delete a webhook. Requires confirmation.
kit-cli delete-webhook --helpArgument | Type | Required | Meaning |
| schema | Yes | Positive webhook id. |
Find subscribers by exact email. Read-only.
kit-cli search-subscribers --helpArgument | Type | Required | Meaning |
| string/null | No | See the exact input schema. |
| string/null | No | See the exact input schema. |
| string | No | See the exact input schema. |
| string | No | See the exact input schema. |
| string | Yes | See the exact input schema. |
| string | No | See the exact input schema. |
| boolean | No | See the exact input schema. |
| number/null | No | See the exact input schema. |
| boolean | No | See the exact input schema. |
| string | No | Values: |
| string | No | Values: |
| string | No | Values: |
| string | No | See the exact input schema. |
| string | No | See the exact input schema. |
| boolean | No | Read successive cursor pages, bounded by max_items (default 1000). Default false returns one API page. |
| integer | No | Maximum records when all_pages=true. A capped result reports truncation and its continuation cursor. |
List configured accounts. Read-only.
kit-cli list-accounts --helpNo arguments.
KIT_READ_ONLY=1 hides every write, leaving 38 reads, and also refuses a direct write invocation. KIT_ALLOW_DESTRUCTIVE=0 leaves tools visible but refuses the 40 guarded audience/delivery/deletion/secret operations. There is no --agent or --yes bypass. Confirmation means permission for the actual user-requested operation, not a blanket license to modify an account.
Seven configuration writes (such as creating a tag or custom field) do not require confirmation. They are still writes and are blocked by read-only mode. Tool annotations describe read, destructive, idempotent and open-world behavior; application prompts remain client-dependent.
Requests go directly to https://api.kit.com/v4; no Navid-hosted relay, analytics or telemetry is included. HTTP redirects are refused. Keys, OAuth tokens, client secrets and signing secrets are sanitized from tool results and reflected API errors. Subscriber addresses, email content, reports and other authorized response data are still private business data that your AI client can process. Configure its retention and sharing policy accordingly.
Private OAuth files, webhook-secret files and optional audit files remain local. Audit records contain attempted write names, risk, surface, decision and outcome, without arguments, subscriber addresses, message bodies, account labels or credentials. Audit failure does not block a requested operation. It is a guard-decision log, not proof of remote delivery or complete Kit account audit history.
GET 429 responses can retry up to two times by default, honoring a bounded delay. GET OAuth 401 can refresh and retry once. All mutating requests have zero automatic retries, including 429 and token expiry. A read-only filter POST also has no automatic retry. Treat service data as data, not instructions to execute an unrelated operation.
See SECURITY.md for disclosure, private file handling, dependency limitations and live-validation limits.
Offering | Surface | What the reviewed source establishes | Tradeoff |
Remote MCP, Kit OAuth | v4 account reads and writes; paid Creator/Creator Pro; 120 requests/min/token | Hosted consent/setup; standalone task CLI not identified there | |
Documentation MCP | Read documentation | No account operations | |
This package | Local stdio, CLI, desktop archive | 83 pinned operations + 2 helpers, private account settings and guards | You maintain local credentials; live writes pending |
PHP/Laravel integration and Artisan commands | Kit integration with framework commands | Requires the Laravel application environment | |
Provider data-access CLI | JDBC-backed data access from a CLI | Different provider/license and data-oriented scope |
COMPARISON.md records dated primary sources, scope and limitations. Counts are package discovery results, not evidence that the official server has fewer endpoints. No competitor latency, success rate or total token cost has been measured here.
No fresh Claude Code token benchmark is available for this version. There are no claimed savings or made-up token figures. tools/list and the installed skill are the actual inputs for a future measurement.
Measure the same successful task with: baseline, MCP with eager tool loading, MCP with the client's normal deferred search, CLI with its installed skill, and the official Kit MCP when account authorization is available. Fix client/model versions, account, prompt, selected fields and result size. Record standing context separately from input/output/cache tokens, reasoning, command help, response data, latency and any service costs. Discovery alone does not measure completed-task cost.
A sensible matched task reads the latest five broadcasts and their statistics into one compact summary. A draft-only write comparison must use a test account and explicit approval, and verify equal resulting drafts. Neither comparison should send newsletters during setup. Results remain pending until real client usage and successful task outcomes are captured.
Variable | Default | Meaning |
|
| Personal v4 API key |
|
| Existing OAuth access token |
|
| OAuth refresh token |
|
| Your authorized Kit app ID |
|
| Your private confidential-app secret |
|
| Regular private OAuth JSON, max 64 KB |
|
| Private JSON named accounts; replaces single-account settings |
|
| Default name from KIT_ACCOUNTS |
|
| 1 or true hides and refuses all 47 writes |
|
| 0 or false blocks all 40 guarded operations even with confirm |
|
| Local attempted-write guard log, no request fields |
|
| Private signing-secret folder |
|
| Per-request deadline, integer 100–300000 |
|
| GET 429 retries only, integer 0–5 |
|
| 0 chooses 550 ms keys / 110 ms OAuth; otherwise 1–10000 ms |
The package reads environment variables only. It does not automatically load .env, resolve a secret-manager account, or inherit GUI environment values from a terminal. Private client config examples are in INSTALL.md. Never put real credentials in project MCP files.
Symptom | Resolution |
Binary not found | Install Node 22+, check npm global prefix/PATH, reopen terminal |
PowerShell blocks npm.ps1 | Use npm.cmd or Command Prompt in accordance with your policy |
Local doctor exit 10 | Configure a v4 key or regular OAuth token file in private settings |
GUI works differently from terminal | GUI clients often do not inherit shell env; configure private client env |
API 401 | Verify v4 credentials; OAuth may be expired or revoked |
API 403 / OAuth required | Check current plan permissions and use OAuth for that endpoint |
Read-only missing tools | Set KIT_READ_ONLY=0 only when writes are wanted; reconnect |
Confirmation refused | Supply confirm:true/--confirm only for an explicitly requested operation; check destructive policy |
Invalid request body | Read schema; use payload for nested fields/null; avoid mixing body forms |
No results beyond the first page | Follow end_cursor or use bounded all_pages |
429 | Wait; other integrations share the credential limit; do not blindly retry writes |
Write timeout | Outcome may be unknown; inspect the account before repeating |
Template or Starting point error | See recorded schema contradictions and test an unscheduled private draft |
Secret filename exists | Choose a new private secret_name; files are never overwritten |
Refresh succeeds but file update fails | Repair private folder access and inspect state before another write |
Desktop extension rejected | Validate host custom-extension policy and compatible runtime; try manual stdio setup |
The wrapper is free AGPL software. Your Kit subscription and API eligibility are separate. The official Kit MCP is available on paid Creator and Creator Pro plans; consult Kit for your account’s API access.
Yes. Its account server supports reads and writes across v4. Its separate developer-docs MCP reads documentation and cannot act on your account.
Use it for standalone task commands, shell automation, private named-account settings, token-file refresh, bounded pagination or a local desktop archive. Use Kit’s official server for Kit-managed hosted OAuth. Neither is declared universally better.
No standalone email-account task CLI was identified in the official developer surfaces reviewed on 2026-10-02. Framework-specific and data-provider CLIs exist; see COMPARISON.md.
Discovery shows them, but OAuth-only bulk and purchase endpoints reject API-key calls before HTTP. The tool table marks them. Use an authorized OAuth session for those operations.
No. Configure it privately in your shell or client settings. Help, discovery and schemas work without it.
No. It explains first-time key/OAuth setup. This package does not host a consent flow or copy your browser cookies.
Yes, through local stdio configuration or the custom .mcpb release. GUI installation of this version remains a separate host check.
This local package does not expose an HTTPS connector. Use Kit’s official remote MCP for a compatible web connector.
The wrapper defaults create to private and unscheduled. If you explicitly pass send_at or publication fields, they can change that behavior. All broadcast writes require confirmation; review in Kit before delivery.
No. Use send_at for email delivery. published_at concerns web publication.
Use update_broadcast with a JSON body containing send_at:null, then inspect the broadcast. A shell string null is not JSON null.
Inspect existing template HTML and required Liquid/footer markup before changing content. The API is not a visual block editor. Starting point schema conflicts remain live-account validation pending.
Yes, existing automations can react to tagging, form subscription or sequence enrollment. Those operations require explicit confirmation here.
No. Mutating requests are never automatically retried. A timeout may have an unknown outcome; inspect the account first.
Yes. Use a private KIT_ACCOUNTS array with unique names, then --account. list_accounts returns labels/auth methods without credentials.
Use after or bounded all_pages/max_items. v4 uses cursors. Aggregate output exposes the last cursor and truncation; it is not an unlimited export.
New signed endpoint secrets go to exclusive owner-only files under KIT_PRIVATE_DIR and are redacted from returned tool data. Configure your own receiver privately.
That has not been measured. Model context, discovery, skill, command help, results, cache and task length all matter. No invented savings are advertised.
Create new private settings with a v4 key or authorized OAuth token file. Do not copy old personal SKILL content, cookies or source history into a public repo. See the 2.0 migration notes.
git clone https://github.com/thenavidm/kit-mcp-cli.git
cd kit-mcp-cli
npm ci
npm run typecheck
npm run build
npm test
npm run check:counts
npm run build:mcpb
npm pack --dry-runThe snapshot is checked into scripts/kit-api.snapshot.json; generated operation schemas and the source hash are in src/tools/. To review a future API snapshot, save the official document locally and run node scripts/sync-openapi.mjs /absolute/path/reviewed-v4.json, inspect every diff and re-run the checks. Do not treat new endpoint discovery as a reviewed release. Record current source corrections and verify live behavior when credentials permit.
The CI workflow verifies Node 22 and 24 on Linux and Windows, then builds the desktop archive. The release workflow verifies package/tag/counts/tests, publishes npm with provenance, and attaches the matching desktop archive. Release tags are annotated v<package version>. Topics and npm keywords cover the actual Kit/MCP/CLI surfaces. Credentials use encrypted GitHub secrets or private local configuration and never enter a package.
The npm allowlist includes built code, full setup/skill/comparison/changelog/security/contribution docs and licenses. It excludes source tests, private account files, local .env, build scratch folders and the desktop archive. The .mcpb vendors production dependencies, the server and notices without configured credentials. A build dependency audit can differ from the production audit; see SECURITY.md.
Issues and reproducible bug reports are welcome. This repository does not accept unsolicited pull requests; see CONTRIBUTING.md. Use private vulnerability reporting for security issues.
CHANGELOG.md records dated changes and validation. Version 2.0.0 replaces the private 1.0.0 source with a sanitized public v4 implementation. It preserves the AGPL license and useful operation names, and adds the CLI and desktop surface.
The old source's private account instructions and original commits remain private. Public history starts with the reviewed v2 source; this avoids publishing personal setup data. Only the sanitized public branch is pushed.
Configure a v4 key or private authorized OAuth file; a v3 API secret is insufficient.
Replace numeric page arguments with v4 cursors.
Use current tool IDs and schemas; search_subscribers remains an exact-email alias.
The old browser kit_login and broadcast/sequence/visual-automation duplication helpers are not included. Their private cookie workflows are not part of the v4 API. Use the Kit UI for designed duplication and visual automation work.
API sequence/email CRUD is now available, but it is not a claim of legacy browser feature parity.
Review send_at, draft defaults and explicit confirmation before any delivery or audience change.
Never copy old personal SKILL content, cookies or the private Git history into public files.
This wrapper is AGPL-3.0-or-later, preserving the legacy source's license. See LICENSE and the full AGPL text. Kit's service and documentation retain their own rights and terms. Third-party dependency attribution is in THIRD_PARTY_NOTICES.md.
Navid Moazzez is a leading AI business strategist, and the host of the AI Creator Summit, watched by 100,000+ creators. He helps creators and founders master AI and build their own AI Operating System (AI OS) to automate their business and life. This Kit MCP server and CLI is one piece of that system.
Links
Personal website: navid.me
Link in bio: navid.bio
Navid Media: navid.media
YouTube: @thenavidm and @thenavidai
X: @thenavidm
Instagram: @thenavidm
LinkedIn: thenavidm
© 2026 Navid Media. Made with ❤️ by Navid Moazzez.
Add subscriber to form by email address. May affect delivery, audience membership, published data or irreversible state. Requires confirm=true.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| confirm | No | Must be true for audience/delivery changes, publishing, destructive operations and signing-secret changes. Use only for an action requested by the user. | |
| form_id | Yes | Positive form id. | |
| payload | No | Complete JSON body instead of individual body flags. Supports nullable fields and nested bulk structures. Cannot be combined with body flags or payload_file. | |
| referrer | No | ||
| payload_file | No | Local JSON request body file, at most 5 MB. Contents are validated before the API call and are never logged. | |
| email_address | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and non-idempotent, and the description reinforces this with 'May affect delivery, audience membership, published data or irreversible state.' It goes further than the annotations by flagging the confirm requirement and the irreversible nature, though it doesn't say what specifically becomes irreversible or how failures behave.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the action and followed by the risk and the precondition. No filler, though 'May affect delivery, audience membership, published data or irreversible state' is a somewhat generic risk menu rather than a precise statement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 7-parameter mutation tool with nested payload/payload_file options, no output schema and destructive semantics, the description says enough to avoid misuse (confirm, irreversible effects) but leaves the parameter-selection story and return behavior entirely to the schema. Adequate, not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 71% and the schema documents account, confirm, payload, payload_file and form_id itself. The description adds nothing about these parameters, only echoing the email-address field from the payload. Baseline 3 is appropriate when the schema carries most of the load.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Add subscriber to form') and qualifies it with 'by email address', which distinguishes it from the sibling add_subscriber_to_form_by_id. However, it never explicitly names that sibling or bulk_add_subscribers_to_forms, so the differentiation is left to inference rather than stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The only usage condition given is 'Requires confirm=true', which is a real prerequisite. There is no guidance on when to prefer this tool over add_subscriber_to_form_by_id or bulk_add_subscribers_to_forms, so the agent must infer the selection rule from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add subscriber to form. May affect delivery, audience membership, published data or irreversible state. Requires confirm=true.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| confirm | No | Must be true for audience/delivery changes, publishing, destructive operations and signing-secret changes. Use only for an action requested by the user. | |
| form_id | Yes | Positive form id. | |
| payload | No | Complete JSON body instead of individual body flags. Supports nullable fields and nested bulk structures. Cannot be combined with body flags or payload_file. | |
| referrer | No | ||
| payload_file | No | Local JSON request body file, at most 5 MB. Contents are validated before the API call and are never logged. | |
| subscriber_id | Yes | Positive subscriber id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations (destructiveHint=true, idempotentHint=false, openWorldHint=true) already flag the mutation risk, but the description adds useful specifics beyond them: it names the affected domains (delivery, audience membership, published data) and irreversible state, and states the confirm=true requirement. This is richer than the annotations alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the core action and followed by the risk/confirm caveat. No filler, nothing that doesn't earn its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive, non-idempotent mutation with no output schema, the description covers the side effects and the required confirm flag, which is the key operational detail. It could still say more about what the operation returns or how it interacts with the sibling form-add tools, but it is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 86%, so the schema already documents form_id, subscriber_id, account, confirm, payload, etc. The description adds no parameter-level detail beyond what the schema provides, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a clear verb+resource ('Add subscriber to form') that an agent can act on. However, it does not distinguish this from the close sibling add_subscriber_to_form (the email-based variant) or bulk_add_subscribers_to_forms, so the agent must guess which form-add variant to pick.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives the confirm=true prerequisite but no guidance on when to use this tool versus add_subscriber_to_form, add_subscriber_to_sequence_by_id, or the bulk variant. No when/when-not or alternative routing is offered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add subscriber to sequence by email address. May affect delivery, audience membership, published data or irreversible state. Requires confirm=true.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| confirm | No | Must be true for audience/delivery changes, publishing, destructive operations and signing-secret changes. Use only for an action requested by the user. | |
| payload | No | Complete JSON body instead of individual body flags. Supports nullable fields and nested bulk structures. Cannot be combined with body flags or payload_file. | |
| sequence_id | Yes | Positive sequence id. | |
| payload_file | No | Local JSON request body file, at most 5 MB. Contents are validated before the API call and are never logged. | |
| email_address | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, readOnlyHint=false and idempotentHint=false, so the safety profile is covered. The description nevertheless adds value by naming the blast radius (delivery, audience membership, published data, irreversible state) and the confirm=true precondition, going beyond what the structured fields state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, action and identifier front-loaded, consequence and precondition packed into the second. No filler or restated boilerplate.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive, non-idempotent mutation with a nested payload and no output schema, the description covers purpose, risk scope and the confirm gate adequately. Minor omissions: it doesn't flag that payload and payload_file are mutually exclusive nor that this is the email-keyed alternative to the by_id tool, but the schema handles the former.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 83%, so the schema carries most parameter meaning (account, payload/payload_file mutual exclusivity, email_address, sequence_id format). The description only echoes the confirm requirement already documented in the schema, adding little beyond the structured fields – the baseline 3 for high coverage is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Add), resource (subscriber), container (sequence) and the identifier method (by email address). The 'by email address' phrasing cleanly distinguishes it from the sibling add_subscriber_to_sequence_by_id without needing to open either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gates the call with 'Requires confirm=true' and warns of consequences, which is real usage guidance. However, it never says when to prefer this email-based variant over add_subscriber_to_sequence_by_id, or that self-service use is inappropriate (that constraint lives only in the schema for 'confirm').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add subscriber to sequence. May affect delivery, audience membership, published data or irreversible state. Requires confirm=true.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| confirm | No | Must be true for audience/delivery changes, publishing, destructive operations and signing-secret changes. Use only for an action requested by the user. | |
| sequence_id | Yes | Positive sequence id. | |
| subscriber_id | Yes | Positive subscriber id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, so the risk profile is partly covered. The description still adds real value by naming the affected surfaces (delivery, audience membership, published data, irreversible state) and disclosing the confirm=true gate, which is not derivable from the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short declarative sentences with zero filler; the core action leads and the risk/confirm constraint follows immediately. Nothing needs trimming.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and full schema coverage, the description need not explain return values, and the annotations carry the safety profile. It covers the action, the impact and the confirm gate adequately, though it omits whether re-adding an existing subscriber errors or is a no-op and what a successful result looks like.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so account, confirm, sequence_id and subscriber_id are all documented in the schema itself. The description only restates the confirm requirement, adding no syntax, format or defaulting nuance beyond the schema, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names a specific verb and resource (add subscriber to sequence), so the operation is unambiguous. However, it does not distinguish itself from the near-identical sibling add_subscriber_to_sequence (the by_id vs email variant), leaving the agent to infer the difference from the tool name alone.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
States the precondition 'Requires confirm=true', which is actionable context. But it gives no guidance on when to pick this tool over add_subscriber_to_sequence or add_subscriber_to_form, and no exclusions, so usage is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Bulk add subscribers to forms. May affect delivery, audience membership, published data or irreversible state. Requires confirm=true. Requires OAuth; API keys are not supported for this endpoint.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| confirm | No | Must be true for audience/delivery changes, publishing, destructive operations and signing-secret changes. Use only for an action requested by the user. | |
| payload | No | Complete JSON body instead of individual body flags. Supports nullable fields and nested bulk structures. Cannot be combined with body flags or payload_file. | |
| additions | No | ||
| callback_url | No | ||
| payload_file | No | Local JSON request body file, at most 5 MB. Contents are validated before the API call and are never logged. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true and non-idempotency, so the safety profile is partly covered. The description adds genuine value beyond that: it names what is affected (delivery, audience membership, published data, irreversible state) and discloses an auth requirement (OAuth only, no API keys) that the annotations do not carry.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, all earning their place: intent, impact, and hard invocation requirements. The destructive/confirm constraint is front-loaded where it matters most.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive bulk mutation with no output schema, the description supplies the critical missing context: blast radius, confirm gating, and auth constraints. It is only slightly short on the bulk-vs-single routing an agent needs to pick this over its singular siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67% and the nested payload/additions/payload_file exclusivity is documented in the schema itself. The description only echoes confirm=true, adding no meaning beyond the schema on account, callback_url, or the mutually exclusive body forms. Baseline 3 is appropriate when the schema does most of the work.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names a specific verb and resource ("bulk add subscribers to forms"), and the "bulk" qualifier implicitly separates it from the singular siblings add_subscriber_to_form / add_subscriber_to_form_by_id. However, it never explicitly states the single-vs-multiple distinction, leaving the agent to infer which sibling applies.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete invocation constraints (requires confirm=true, requires OAuth, API keys unsupported), which is real usage context. But it offers no when-to-use-vs-alternatives guidance relative to the single-subscriber sibling tools, nor any when-not condition.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Bulk create custom fields. Changes account configuration. Requires OAuth; API keys are not supported for this endpoint.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| confirm | No | Must be true for audience/delivery changes, publishing, destructive operations and signing-secret changes. Use only for an action requested by the user. | |
| payload | No | Complete JSON body instead of individual body flags. Supports nullable fields and nested bulk structures. Cannot be combined with body flags or payload_file. | |
| callback_url | No | ||
| payload_file | No | Local JSON request body file, at most 5 MB. Contents are validated before the API call and are never logged. | |
| custom_fields | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare write/idempotency/open-world traits, and the description adds non-trivial behavioral context: it mutates account configuration and OAuth is mandatory (API keys rejected). It still does not disclose bulk atomicity (partial-failure behavior) or that a confirm flag gates the operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short, front-loaded sentences with no filler; the mutating nature and auth requirement land first. Efficient, though slightly terse given the tool's breadth.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists and the tool is a complex nested bulk mutation, so the description should do more. It omits partial-failure semantics, the payload vs payload_file mutual exclusion, and when confirmation is required, leaving those entirely to the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67% and the parameters are largely self-documented, including the nested payload/custom_fields structure and the confirm flag. The description adds no parameter meaning at all, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Bulk create custom fields'), and the 'bulk' qualifier implicitly distinguishes it from the single-record create_custom_field sibling. It is clear without opening the schema, though it never explicitly names the sibling it differs from.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a prerequisite (OAuth required, API keys unsupported) but no explicit when-to-use / when-not guidance versus create_custom_field or bulk_update_subscriber_custom_field_values. The auth constraint is context rather than routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Bulk create subscribers. May affect delivery, audience membership, published data or irreversible state. Requires confirm=true. Requires OAuth; API keys are not supported for this endpoint.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| confirm | No | Must be true for audience/delivery changes, publishing, destructive operations and signing-secret changes. Use only for an action requested by the user. | |
| payload | No | Complete JSON body instead of individual body flags. Supports nullable fields and nested bulk structures. Cannot be combined with body flags or payload_file. | |
| subscribers | No | ||
| callback_url | No | ||
| payload_file | No | Local JSON request body file, at most 5 MB. Contents are validated before the API call and are never logged. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, so the mutation risk is flagged structurally. The description goes beyond them by naming the affected surfaces (delivery, audience membership, published data, irreversible state) and adding the auth constraint that API keys are not supported, which annotations do not cover.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four short sentences, front-loaded with the action and immediately followed by risk, confirmation, and auth requirements. Minimal waste; the only redundancy is restating the tool title in the first sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a bulk mutation with nested subscriber objects and no output schema, the description omits batch-size limits, partial-failure behavior, and whether duplicate email_addresses are merged or rejected — all material to calling a bulk endpoint correctly. Risk and auth are covered, but bulk mechanics are not.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67% and the schema itself documents account, confirm, payload, payload_file, and the subscriber fields, so most parameter meaning is already conveyed. The description's only added semantic is that confirm is required here (the schema leaves required empty), which is genuinely useful but thin against six parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Bulk create subscribers'), and the 'Bulk' qualifier distinguishes it from the singular create_subscriber sibling at the name level. However, the description body never explicitly contrasts itself with create_subscriber, bulk_add_subscribers_to_forms, or the payload/body-flag variants, so routing relies mostly on the tool name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It supplies real preconditions — confirm=true is mandatory and OAuth is required (API keys unsupported) — which tells the agent when the tool can be invoked at all. It gives no guidance on when to prefer this over create_subscriber or bulk_add_subscribers_to_forms, so alternative selection is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Bulk create tags. Changes account configuration. Requires OAuth; API keys are not supported for this endpoint.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | ||
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| confirm | No | Must be true for audience/delivery changes, publishing, destructive operations and signing-secret changes. Use only for an action requested by the user. | |
| payload | No | Complete JSON body instead of individual body flags. Supports nullable fields and nested bulk structures. Cannot be combined with body flags or payload_file. | |
| callback_url | No | ||
| payload_file | No | Local JSON request body file, at most 5 MB. Contents are validated before the API call and are never logged. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly=false, destructive=false, idempotent=false, and openWorld=true. The description adds genuine context beyond the annotations by flagging the account-configuration effect and the OAuth-only requirement, but it omits the notable non-idempotency consequence (re-running creates duplicates) and the confirm requirement for potentially risky operations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short, front-loaded sentences with no padding. The scoping/auth constraints appear immediately after the purpose statement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a bulk mutation with nested objects, a confirm gate, and no output schema, the description covers auth but leaves out the confirm prerequisite, the payload vs. body-flags vs. payload_file choice, and the duplicate-creation risk. Adequate but with clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is a moderate 67% and the description explains none of the six parameters. It never mentions the tags body, the account selector, whether confirm is needed, or the payload/payload_file mutual exclusivity, so it fails to compensate for the uncovered parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource+scope ("Bulk create tags"), so an agent knows this creates multiple tags at once. However, the first sentence essentially restates the name/title and it never distinguishes itself from the sibling create_tag (single) or bulk_create_custom_fields.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance and no alternative named. The description states an auth constraint ("Requires OAuth; API keys are not supported"), which is a prerequisite rather than guidance on choosing this tool over create_tag or bulk_tag_subscribers.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Bulk delete tags. May affect delivery, audience membership, published data or irreversible state. Requires confirm=true. Requires OAuth; API keys are not supported for this endpoint.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | Tags to delete, identified by `id`. Batches of 100 or fewer are processed synchronously (200); larger batches are queued and processed asynchronously (202). | |
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| confirm | No | Must be true for audience/delivery changes, publishing, destructive operations and signing-secret changes. Use only for an action requested by the user. | |
| payload | No | Complete JSON body instead of individual body flags. Supports nullable fields and nested bulk structures. Cannot be combined with body flags or payload_file. | |
| callback_url | No | Optional. When the batch is processed asynchronously (more than 100 tags), the results are POSTed to this URL on completion. | |
| payload_file | No | Local JSON request body file, at most 5 MB. Contents are validated before the API call and are never logged. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true and idempotentHint=false, but the description adds substantive context beyond them: the scope of impact (delivery, audience membership, published data, irreversible state), the confirm=true gate, and the auth constraint (OAuth required, API keys unsupported). It does not explain reversibility or recovery, but the safety profile is well disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four short sentences, each earning its place: action, blast radius, precondition, auth constraint. The purpose is front-loaded ahead of the warnings, with zero filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive bulk tool with no output schema, the description covers the critical decision inputs: consequences, confirmation gate, and auth requirement. Async/queued behavior and callback semantics live in the schema, so the omission here is minor; only explicit reversibility/recovery guidance is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all six parameters (including nested tags, payload, callback_url, payload_file) are already richly documented in the schema. The description reinforces the confirm=true requirement but adds no syntax or format detail beyond the schema; baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('Bulk delete tags') that is unambiguous and distinct from mutation siblings like delete_broadcast or delete_custom_field. It does not, however, differentiate itself from closely related tag tools such as bulk_remove_tags_from_subscribers or bulk_tag_subscribers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It discloses prerequisites (confirm=true, OAuth only) and warns of consequences, which is real context. But it gives no explicit when-to-use vs alternatives guidance – e.g., no pointer distinguishing it from bulk_remove_tags_from_subscribers or a single-tag delete – leaving the agent to infer routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Bulk remove tags from subscribers. May affect delivery, audience membership, published data or irreversible state. Requires confirm=true. Requires OAuth; API keys are not supported for this endpoint.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| confirm | No | Must be true for audience/delivery changes, publishing, destructive operations and signing-secret changes. Use only for an action requested by the user. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, so the description's real value is the added auth constraint ('Requires OAuth; API keys are not supported') and the consequence detail ('affect delivery, audience membership, published data or irreversible state'), neither of which appears in 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the operation, then consequences, then the confirm and auth constraints. No filler; every sentence carries distinct information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive mutation with rich annotations and full param coverage, the description supplies the missing auth requirement and consequence scope. No output schema exists, but return values are not critical for this operation, so coverage is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters are already documented. The description reinforces the confirm=true requirement but adds no syntax or format detail beyond what the schema carries, making the baseline 3 appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (remove), resource (tags), and scope (bulk, from subscribers), which an agent can distinguish from siblings like untag_subscriber or bulk_delete_tags. However, the first sentence essentially restates the title and never names the single-item alternative it is distinct from.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides prerequisites (confirm=true, OAuth required, API keys unsupported) but no explicit when-to-use routing against siblings such as untag_subscriber or untag_subscriber_by_email. Usage is implied by the 'bulk' framing rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Bulk tag subscribers. May affect delivery, audience membership, published data or irreversible state. Requires confirm=true. Requires OAuth; API keys are not supported for this endpoint.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| confirm | No | Must be true for audience/delivery changes, publishing, destructive operations and signing-secret changes. Use only for an action requested by the user. | |
| payload | No | Complete JSON body instead of individual body flags. Supports nullable fields and nested bulk structures. Cannot be combined with body flags or payload_file. | |
| taggings | No | ||
| callback_url | No | ||
| payload_file | No | Local JSON request body file, at most 5 MB. Contents are validated before the API call and are never logged. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already flag destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the risk profile is partly covered. The description still adds real value beyond them: the concrete blast radius ('delivery, audience membership, published data or irreversible state') and the non-obvious auth constraint that API keys are not supported for this endpoint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the action and followed by risk and auth constraints. No filler, though the opening sentence contributes nothing over the title and could be replaced with actual scoping information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive, nested-payload, open-world mutation with no output schema and zero required params, the description covers risk and auth but omits the practical mechanics: what the taggings entries mean, how null ids are interpreted, batch limits, and what a successful call returns or how partial failures are handled.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67%, above the midpoint, so the schema carries most parameter documentation. The description only reinforces the confirm requirement and says nothing about the taggings array items (nullable tag_id/subscriber_id), the callback_url, or the payload/payload_file mutual exclusion, which the schema itself describes.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description's first sentence, 'Bulk tag subscribers,' is a verbatim restatement of the tool title and name. It conveys a verb and resource but does no work beyond the identifier itself, and it does not distinguish this tool from nearby siblings such as tag_subscriber, tag_subscriber_by_id, bulk_create_tags, or bulk_remove_tags_from_subscribers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance and no routing to alternatives. The stated conditions ('Requires confirm=true', 'Requires OAuth') are prerequisites, not selection criteria, and nothing tells the agent when to prefer this over single-subscriber tagging or the bulk tag-creation tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Bulk update subscriber custom field values. May affect delivery, audience membership, published data or irreversible state. Requires confirm=true. Requires OAuth; API keys are not supported for this endpoint.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| confirm | No | Must be true for audience/delivery changes, publishing, destructive operations and signing-secret changes. Use only for an action requested by the user. | |
| payload | No | Complete JSON body instead of individual body flags. Supports nullable fields and nested bulk structures. Cannot be combined with body flags or payload_file. | |
| callback_url | No | ||
| payload_file | No | Local JSON request body file, at most 5 MB. Contents are validated before the API call and are never logged. | |
| custom_field_values | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true and idempotentHint=false, but the description adds concrete consequences (delivery, audience membership, published data, irreversible state) plus a hard auth constraint (OAuth only, no API keys). This goes meaningfully beyond the structured hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four tight sentences, purpose first and warnings after, no filler. Every sentence carries information, though the warning list reads slightly like a template.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and a nested bulk payload, the description covers impact and auth but says nothing about the asynchronous nature implied by callback_url, result/status reporting, or batch limits. Adequate but with clear gaps for a 6-parameter nested mutation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67%, near the baseline where the schema does most of the work. The description reinforces the confirm=true requirement, but adds no meaning about payload vs payload_file vs body-flag alternatives or the callback_url field beyond what the schema already states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (bulk update), resource (subscriber custom field values), and scope (bulk), which clearly separates it from siblings like bulk_create_custom_fields, update_custom_field, and update_subscriber. It is clear but does not explicitly name or contrast with those siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It supplies invocation prerequisites (confirm=true, OAuth required, API keys unsupported) but gives no guidance on when to prefer this bulk endpoint over single-subscriber alternatives or when it should be avoided. Usage context is implied by the bulk framing only.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a broadcast. May affect delivery, audience membership, published data or irreversible state. Requires confirm=true.
| Name | Required | Description | Default |
|---|---|---|---|
| public | No | `true` to publish this broadcast to the web. The broadcast will appear in a newsletter feed on your Creator Profile and Landing Pages. | |
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| confirm | No | Must be true for audience/delivery changes, publishing, destructive operations and signing-secret changes. Use only for an action requested by the user. | |
| content | No | The HTML content of the email. On a `Classic` template this is the body, and the template adds the design around it when the broadcast is sent. On a `Starting point` template the design lives in the body, so this is the complete email: keep the wrappers, images, inline styles and Liquid tags, including `{{ unsubscribe_url }}` and `{{ address }}`. Without an unsubscribe link the broadcast can't be sent. A read returns the string that was written, so `GET`, `PUT`, `GET` round-trips, apart from Kit's own "Built with Kit" badge, which a `Starting point` write takes out of the body and re-applies when the email renders. A broadcast built in Kit's editor reads back as Kit's rendered HTML instead, and writing that back replaces its individually-editable blocks with one HTML block. Sending `content` in the same request as a `Starting point` `email_template_id` also needs `allow_starting_point: true`. Omit `content` and name a `Starting point` template in `email_template_id` to create the broadcast with that template's own design. | |
| payload | No | Complete JSON body instead of individual body flags. Supports nullable fields and nested bulk structures. Cannot be combined with body flags or payload_file. | |
| send_at | No | The scheduled send time for this broadcast in ISO8601 format. If no timezone is provided, UTC is assumed. | |
| subject | No | ||
| description | No | ||
| payload_file | No | Local JSON request body file, at most 5 MB. Contents are validated before the API call and are never logged. | |
| preview_text | No | ||
| published_at | No | The published timestamp to display in ISO8601 format. If no timezone is provided, UTC is assumed. | |
| email_address | No | The sending email address to use. Uses the account's sending email address if not provided. | |
| thumbnail_alt | No | ||
| thumbnail_url | No | ||
| email_template_id | No | Id of the email template to use. Uses the account's default template if not provided. 'Starting point' template is not supported. | |
| subscriber_filter | No | Filters your subscribers. At this time, we only support using only one filter group type via the API (e.g. `all`, `any`, or `none` but no combinations). If nothing is provided, will default to all of your subscribers. | |
| allow_starting_point | No | Explicitly allow replacing a Starting point template body, as described in Kit’s current content-field documentation. Review the complete rendered HTML first. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as destructive, non-idempotent, open-world, and not read-only. The description adds meaningful context beyond those hints by naming affected domains: delivery, audience membership, published data, and irreversible state, plus the confirm requirement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three short sentences with no waste. The purpose is front-loaded, followed by safety impact and the confirmation requirement. It is appropriately sized for an at-a-glance description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive creation tool with a very rich schema and safety annotations, the description covers the minimum: it says what it creates, warns of destructive effects, and states the confirm requirement. However, it omits selection guidance against siblings and does little to help an agent choose this tool rather than another creation or update tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 17 parameters and 71% description coverage. The description mentions only confirm=true, which the schema already documents, and adds no meaning about content, payload, subscriber_filter, templates, or scheduling. It does not compensate for the remaining parameter gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource: 'Create a broadcast.' An agent can tell what the tool does. It does not differentiate from siblings such as create_sequence or update_broadcast, and the first sentence largely restates the title, so it is clear but not maximally informative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description notes effects and a confirm prerequisite, but it gives no guidance on when to choose this tool over alternatives, when not to use it, or what conditions select a different create tool. The requirement 'confirm=true' is a constraint rather than usage routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a custom field. Changes account configuration.
| Name | Required | Description | Default |
|---|---|---|---|
| label | No | ||
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| confirm | No | Must be true for audience/delivery changes, publishing, destructive operations and signing-secret changes. Use only for an action requested by the user. | |
| payload | No | Complete JSON body instead of individual body flags. Supports nullable fields and nested bulk structures. Cannot be combined with body flags or payload_file. | |
| payload_file | No | Local JSON request body file, at most 5 MB. Contents are validated before the API call and are never logged. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly=false, destructive=false, idempotent=false, and openWorld=true, so the safety profile is covered. The description adds one piece of context, 'Changes account configuration', which signals account-level mutation, but it says nothing about the confirm parameter, permission requirements, or side effects of creating a field.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, front-loaded sentences with no wasted words. It is efficient, though the first sentence largely restates the title rather than earning extra information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Annotations cover the safety profile and no output schema is needed, but for a create tool with a confirm gate and a nested payload object, the description should do more to explain what a custom field is and any required setup. It is minimally adequate rather than complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is high (80%), so the schema carries most of the parameter meaning, including the account, confirm, payload, and payload_file descriptions. The description adds no parameter-level detail beyond what the schema already provides, matching the baseline for well-documented schemas.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Create a custom field'), which is clear and actionable. However it does not distinguish this from siblings like bulk_create_custom_fields or update_custom_field, so an agent gets no help choosing between them from the text alone.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no indication of when to use this tool versus bulk_create_custom_fields, update_custom_field, or list_custom_fields, and no prerequisite or exclusion information. Usage must be inferred entirely from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a purchase. May affect delivery, audience membership, published data or irreversible state. Requires confirm=true. Requires OAuth; API keys are not supported for this endpoint.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| confirm | No | Must be true for audience/delivery changes, publishing, destructive operations and signing-secret changes. Use only for an action requested by the user. | |
| payload | No | Complete JSON body instead of individual body flags. Supports nullable fields and nested bulk structures. Cannot be combined with body flags or payload_file. | |
| purchase | No | ||
| payload_file | No | Local JSON request body file, at most 5 MB. Contents are validated before the API call and are never logged. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, readOnlyHint=false, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description earns credit for adding what annotations cannot express: the auth mechanism (OAuth only, no API keys) and the explicit confirm gate, plus a concrete list of affected surfaces (delivery, audience membership, published data, irreversible state). No contradiction with the destructive/irreversible annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the action and immediately followed by risk and prerequisites. No wasted clauses; the only weakness is that 'Create a purchase.' largely restates the title before the useful content arrives.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a five-parameter, nested-payload mutation with no output schema and no required fields, the description supplies the critical missing context: the confirm gate, OAuth-only auth, and the blast radius. The remaining ambiguity (payload vs. purchase vs. payload_file selection) is handled by the schema's own descriptions, so coverage is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 80%, so the schema already documents account, confirm, payload, purchase and payload_file semantics in detail. The description reinforces the confirm=true requirement but adds no syntax, format, or interaction rules beyond that. Baseline 3 is appropriate when the schema carries the load.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Create a purchase') and pairs it with a concrete scope note about what the operation may affect. It is clear, though it never names the sibling reads (get_purchase, list_purchases) that an agent might confuse it with, so differentiation rests on the verb alone.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives hard prerequisites ('Requires confirm=true', 'Requires OAuth; API keys are not supported'), which is actionable, but says nothing about when to choose this over list_purchases/get_purchase or what conditions make creation appropriate. Usage is implied by the confirm requirement rather than explained.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a sequence. May affect delivery, audience membership, published data or irreversible state. Requires confirm=true.
| Name | Required | Description | Default |
|---|---|---|---|
| hold | No | When `true`, subscribers added via Visual Automations stay in the sequence after receiving the last email. | |
| name | No | The name of the sequence. | |
| active | No | `true` to activate the sequence, `false` to deactivate it. | |
| repeat | No | When `true`, subscribers can restart the sequence multiple times. | |
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| confirm | No | Must be true for audience/delivery changes, publishing, destructive operations and signing-secret changes. Use only for an action requested by the user. | |
| payload | No | Complete JSON body instead of individual body flags. Supports nullable fields and nested bulk structures. Cannot be combined with body flags or payload_file. | |
| send_days | No | The days of the week to send the sequence on. Must be one of: `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, `sunday`. | |
| send_hour | No | The hour of the day to send the sequence at. Must be an integer between 0 and 23. | |
| time_zone | No | The timezone to use for the sequence. Must be a valid IANA timezone string. | |
| payload_file | No | Local JSON request body file, at most 5 MB. Contents are validated before the API call and are never logged. | |
| email_address | No | The sending email address to use. Uses the account's sending email address if not provided. | |
| email_template_id | No | Id of the email template to use. | |
| exclude_subscriber_sources | No | The subscriber sources to exclude from the sequence. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is known. The description adds useful specifics on the scope of impact ('delivery, audience membership, published data or irreversible state') and restates the confirm gate, though it remains vague about which of those actually occur and under what conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with zero filler, and the impact warning plus required flag are front-loaded where the agent will see them first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 14-parameter, nested-object creation tool with no output schema, the description is thin. The rich schema and the destructive/open-world annotations cover most of the burden, but there is no guidance on the payload/payload_file/flags interaction or on what a successful creation returns, which the description could have supplied.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 14 parameters, including the payload-vs-flags mutual exclusion. The description only surfaces confirm, adding no meaning beyond the schema. Baseline 3 applies when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Create a sequence.' It is unambiguous on its own, but it does nothing to distinguish itself from siblings like create_sequence_email or update_sequence, which an agent must disambiguate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The only usage instruction is 'Requires confirm=true.' There is no statement of when to create a sequence versus using an alternative like add_subscriber_to_sequence, and no preconditions beyond the confirmation flag.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a sequence email. May affect delivery, audience membership, published data or irreversible state. Requires confirm=true.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| confirm | No | Must be true for audience/delivery changes, publishing, destructive operations and signing-secret changes. Use only for an action requested by the user. | |
| content | No | HTML body content of the email | |
| payload | No | Complete JSON body instead of individual body flags. Supports nullable fields and nested bulk structures. Cannot be combined with body flags or payload_file. | |
| subject | No | Subject line of the email | |
| position | No | Zero-based position of the email in the sequence. Assigned automatically after the last email if omitted | |
| published | No | Whether the email is active and will be sent to subscribers. Defaults to `false` (draft) | |
| send_days | No | Days of the week this email may be sent. Defaults to all 7 days (inherits the sequence schedule). Pass a subset to restrict delivery, or `null` to reset to all days | |
| delay_unit | No | Unit for the send delay. Use `days` for schedule-aware delivery, `hours` for a fixed hourly delay | |
| delay_value | No | Number of days or hours to wait before sending this email after the previous one | |
| sequence_id | Yes | Positive sequence id. | |
| payload_file | No | Local JSON request body file, at most 5 MB. Contents are validated before the API call and are never logged. | |
| preview_text | No | Preview text shown in email clients before the email is opened | |
| email_template_id | No | ID of the email template to use for layout and styling |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds real value beyond that by naming what can be affected ('delivery, audience membership, published data or irreversible state') and stating the confirm=true requirement, which is not in the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the action, followed immediately by risk and prerequisite. No filler and nothing that could be trimmed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 14-parameter, nested-object mutation with no output schema, the description is adequate but thin: it never clarifies the relationship between the top-level body flags and the payload/payload_file alternatives, nor does it point to sibling tools. Annotations and the rich schema carry most of the load, making this minimally viable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all 14 parameters, including the nested payload fields, are already documented in the schema. The description adds only the confirm=true requirement, which the schema also states, so it does not meaningfully extend parameter meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Create a sequence email') that an agent can act on. It does not, however, distinguish this from close siblings such as create_sequence or update_sequence_email, so the purpose is clear but not differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no when-to-use guidance, no exclusions, and no alternatives despite the presence of update_sequence_email, get_sequence_email, and list_sequence_emails as siblings. The only operational hint is the confirm=true prerequisite, which is not framed as usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a snippet. May affect delivery, audience membership, published data or irreversible state. Requires confirm=true.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| confirm | No | Must be true for audience/delivery changes, publishing, destructive operations and signing-secret changes. Use only for an action requested by the user. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds genuine context beyond the annotations by naming the affected domains (delivery, audience membership, published data) and irreversible state, plus a confirm requirement. Annotations already flag destructiveHint=true, but the description specifies what is at risk, which is useful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short, front-loaded sentences with the verb+resource first and the constraint last. No filler, though the effect enumeration is slightly broad ('May affect...').
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-required-param mutation tool with no output schema and full annotation coverage, the description covers the key risk profile and the confirm gate. Nothing critical is missing for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both account and confirm are already documented in the schema. The description only restates the confirm requirement, adding little beyond the structured field.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Create) and resource (snippet), clearly distinct from the sibling update_snippet, list_snippets and get_snippet. It doesn't explicitly name which sibling to use instead, so it stops short of 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a conditional usage rule — confirm=true and only for user-requested actions — but no explicit when-to-use-vs-alternatives guidance relative to update_snippet. Usage is implied but not fully scoped.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a subscriber. May affect delivery, audience membership, published data or irreversible state. Requires confirm=true.
| Name | Required | Description | Default |
|---|---|---|---|
| state | No | Create subscriber in this state (`active`, `bounced`, `cancelled`, `complained` or `inactive`). Defaults to `active`. | |
| fields | No | Custom field values keyed by the custom field's `key` (e.g. `last_name`, not `Last Name`). Unknown keys are ignored and reported in the response `warnings` array. | |
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| confirm | No | Must be true for audience/delivery changes, publishing, destructive operations and signing-secret changes. Use only for an action requested by the user. | |
| payload | No | Complete JSON body instead of individual body flags. Supports nullable fields and nested bulk structures. Cannot be combined with body flags or payload_file. | |
| first_name | No | ||
| payload_file | No | Local JSON request body file, at most 5 MB. Contents are validated before the API call and are never logged. | |
| email_address | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, readOnlyHint=false and openWorldHint=true, so the mutation profile is covered. The description adds the confirm=true requirement and a vague impact warning ('delivery, audience membership, published data or irreversible state'), but does not say what specifically is destroyed or whether a re-created subscriber restores prior state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences with the action front-loaded and no filler. The impact sentence is a slightly generic laundry list that could be tightened, but nothing is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 8-parameter creation tool with nested objects, no output schema, and three competing body-supply mechanisms, the description should clarify which input style to use and what a successful create returns. It covers the confirm gate but leaves the biggest agent decision (payload vs. payload_file vs. flags) entirely to the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 75%, so most parameters (state enum, fields, account, payload, payload_file) are already documented in the schema. The description adds only the confirm prerequisite, and notably omits how the mutually exclusive payload/payload_file/individual-flag styles should be chosen, which is the highest-value missing guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Create a subscriber'), which is clear on its own and separable from siblings like update_subscriber and delete_subscriber. It does not, however, distinguish itself from bulk_create_subscribers or explain why one would pick this over the bulk variant.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The only usage guidance is the 'Requires confirm=true' prerequisite, restated from the schema. There is no indication of when to use this single-create tool versus bulk_create_subscribers, nor any prerequisites such as existing account/audience setup, though the sibling-heavy context makes that routing decision non-trivial.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a tag. Changes account configuration.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| confirm | No | Must be true for audience/delivery changes, publishing, destructive operations and signing-secret changes. Use only for an action requested by the user. | |
| payload | No | Complete JSON body instead of individual body flags. Supports nullable fields and nested bulk structures. Cannot be combined with body flags or payload_file. | |
| payload_file | No | Local JSON request body file, at most 5 MB. Contents are validated before the API call and are never logged. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description adds only 'Changes account configuration', which vaguely signals a state mutation but does not disclose the side effects, the confirm requirement for account-affecting actions, or any auth/rate-limit context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with the action front-loaded and no padding, which is structurally sound. The second sentence is of questionable value, since it repeats the implication of the non-read-only annotation without adding precision.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with five parameters, a nested payload object, and mutually exclusive input modes (payload vs. payload_file vs. body flags), the description is far too thin. With no output schema, it also does not tell the agent anything about the result, and it omits the single-vs-bulk routing that the sibling set makes necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 80%, so the schema already documents account, confirm, payload and payload_file well. The description adds nothing about parameters, leaving the baseline 3 appropriate; notably it never mentions the 'name' field even though it is the payload's required key.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Create a tag'), so an agent immediately knows the operation. However, it does nothing to distinguish this from the sibling 'bulk_create_tags', which shares the same resource and a similar action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance: nothing tells the agent to prefer this for a single tag versus 'bulk_create_tags' for many, and no prerequisites or conditions are stated. 'Changes account configuration' is not usage guidance, it is a vague side-effect note.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a webhook. May affect delivery, audience membership, published data or irreversible state. Requires confirm=true. Webhook response secrets are redacted; new signing secrets are saved only to a private local file.
| Name | Required | Description | Default |
|---|---|---|---|
| event | No | ||
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| confirm | No | Must be true for audience/delivery changes, publishing, destructive operations and signing-secret changes. Use only for an action requested by the user. | |
| payload | No | Complete JSON body instead of individual body flags. Supports nullable fields and nested bulk structures. Cannot be combined with body flags or payload_file. | |
| target_url | No | ||
| payload_file | No | Local JSON request body file, at most 5 MB. Contents are validated before the API call and are never logged. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true, openWorldHint=true and non-idempotency, so the safety profile is covered. The description adds real value beyond that: the confirmed scope of impact (delivery, audience membership, published data, irreversible state) and the secret-handling behavior (responses redacted, new signing secrets written only to a private local file), which an agent could not infer from annotations or schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the action and followed by impact and confirm prerequisite. The lead sentence restates the name/title almost verbatim, which is slightly redundant, but the remaining sentences are dense and waste-free.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 6-parameter nested-object tool with no output schema and no required params, the description covers the mutation risk and secret handling adequately. It still omits which webhook concept this creates relative to webhook_endpoint, and gives no hint of the success response or how the created webhook is identified afterward.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67%, with descriptions already attached to account, confirm, payload and payload_file. The description reinforces the confirm requirement but adds nothing about event, target_url, or the mutual-exclusion rules for payload vs payload_file vs body flags, so it does little beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Create a webhook'), so the operation is unambiguous. However, the sibling set contains both webhook and webhook_endpoint tools (create_webhook_endpoint, list_webhooks, list_webhook_endpoints), and the description never distinguishes this tool from those, leaving the agent to guess which of the two webhook concepts applies.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It does state a prerequisite ('Requires confirm=true'), which is genuine usage guidance. But it gives no context on when to choose create_webhook over create_webhook_endpoint or other creation tools, and no when-not guidance, so routing among siblings is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a webhook endpoint. May affect delivery, audience membership, published data or irreversible state. Requires confirm=true. Webhook response secrets are redacted; new signing secrets are saved only to a private local file.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | ||
| name | No | ||
| events | No | Event types this endpoint subscribes to (e.g. `subscriber.created`). On update, the list supplied here replaces the endpoint's full subscription list. | |
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| confirm | No | Must be true for audience/delivery changes, publishing, destructive operations and signing-secret changes. Use only for an action requested by the user. | |
| payload | No | Complete JSON body instead of individual body flags. Supports nullable fields and nested bulk structures. Cannot be combined with body flags or payload_file. | |
| description | No | ||
| secret_name | Yes | New private filename under KIT_PRIVATE_DIR. Required before creating/rotating a signing secret; never overwritten. | |
| payload_file | No | Local JSON request body file, at most 5 MB. Contents are validated before the API call and are never logged. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true, openWorldHint=true and idempotentHint=false, so the safety profile is partly covered. The description adds genuinely non-redundant behavior: webhook response secrets are redacted, new signing secrets are written only to a private local file, and confirm=true is mandatory. It stops short of explaining what 'irreversible state' actually means.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the action and its risk, with no filler. Slightly dense but every clause carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive, 9-parameter, nested-payload tool with no output schema, the description covers the confirmation gate and secret handling well. It omits return-shape expectations and the payload vs. body-flag exclusivity, though the latter is documented in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67%, so the schema documents most parameters (events, account, confirm, secret_name, payload_file). The description adds only a restated confirm requirement and secret-persistence context, contributing little beyond the structured fields. Baseline 3 is appropriate for a partially covered, 9-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Create a webhook endpoint'), so the operation is unambiguous. However, it does not distinguish this tool from sibling tools like create_webhook or update_webhook_endpoint, leaving the agent to infer the boundary.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description notes 'Requires confirm=true', which is a real usage precondition, and the schema adds 'Use only for an action requested by the user.' But it never states when to reach for this tool versus create_webhook or update_webhook_endpoint, so routing guidance is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a broadcast. May affect delivery, audience membership, published data or irreversible state. Requires confirm=true.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| confirm | No | Must be true for audience/delivery changes, publishing, destructive operations and signing-secret changes. Use only for an action requested by the user. | |
| broadcast_id | Yes | Positive broadcast id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, idempotentHint=false and readOnlyHint=false, so the safety profile is covered. The description adds concrete consequence detail beyond that: the operation may affect delivery, audience membership, published data, or leave irreversible state — valuable context for a destructive call.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with zero padding. The core action leads, the impact warning follows, and the confirm precondition is stated last — a well front-loaded structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a three-parameter destructive tool with no output schema, the description plus the rich annotations give the agent enough to call it safely. It stops just short of completeness by omitting any guidance on preconditions or how to recover from a mistaken deletion.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so account, confirm and broadcast_id are already documented in the schema, including the confirm=true requirement the description repeats. Baseline 3 applies; the description adds no format or constraint detail beyond the structured fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Delete a broadcast') so an agent can distinguish it from list_broadcasts, get_broadcast and update_broadcast. It does not explicitly name or contrast with the nearest sibling update_broadcast, but the destructive intent is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description supplies one operational precondition ('Requires confirm=true'), which is genuine invocation guidance, and the schema adds that confirm should be used only for a user-requested action. However, it never says when to delete a broadcast versus updating one, nor what the caller should verify first.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete custom field. May affect delivery, audience membership, published data or irreversible state. Requires confirm=true.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| confirm | No | Must be true for audience/delivery changes, publishing, destructive operations and signing-secret changes. Use only for an action requested by the user. | |
| custom_field_id | Yes | Positive custom field id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, readOnlyHint=false and idempotentHint=false, so the safety profile is partly covered. The description adds real value beyond that by naming the affected surfaces (delivery, audience membership, published data) and the irreversible state, plus the confirm=true gate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, zero filler, with the destructive impact and the confirm requirement front-loaded where an agent will read them first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive single-object delete with full annotations and complete schema coverage, the description supplies the impact warning and confirmation requirement an agent needs. A minor gap is what happens to existing subscriber values on the custom field, though 'irreversible state' gestures at it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so account, confirm, and custom_field_id are already documented in the schema, including the confirm semantics. The description restates the confirm=true requirement but adds no format or syntax detail beyond the schema, making the baseline 3 appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (delete) and resource (custom field), matching the sibling family of list/create/update_custom_field. It also hints at the blast radius (delivery, audience membership, published data). It does not explicitly contrast itself with update_custom_field or bulk_create_custom_fields, but the action is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a precondition ('Requires confirm=true') and a warning about side effects, which implies caution is needed, but never states when to use this versus alternatives such as update_custom_field for non-destructive edits. Usage context is implied rather than spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a sequence. May affect delivery, audience membership, published data or irreversible state. Requires confirm=true.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| confirm | No | Must be true for audience/delivery changes, publishing, destructive operations and signing-secret changes. Use only for an action requested by the user. | |
| sequence_id | Yes | Positive sequence id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description earns credit by going beyond that to disclose the blast radius ('may affect delivery, audience membership, published data or irreversible state'), which tells the agent what downstream state is at risk.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with zero waste; the core action is front-loaded and the risk note plus confirm requirement follow immediately. Nothing is padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive mutation with no output schema, the description supplies the necessary warning about irreversible effects and the confirmation requirement. It stops short of addressing scope (what gets deleted with the sequence) or permission requirements, but the essentials an agent needs are present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so account, confirm, and sequence_id are all already documented in the schema itself. The description restates the confirm=true requirement without adding format or constraint detail beyond what the schema provides, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Delete') and resource ('sequence'), so an agent can separate it from delete_broadcast, delete_custom_field, and delete_sequence_email. It does not explicitly differentiate itself from the closely related delete_sequence_email sibling, which is the main residual gap.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description notes that confirm=true is required, which is a usage condition, but gives no guidance on when to choose this tool over alternatives such as delete_sequence_email or how sequences relate to deletion scope. No when/when-not framing is present.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a sequence email. May affect delivery, audience membership, published data or irreversible state. Requires confirm=true.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| confirm | No | Must be true for audience/delivery changes, publishing, destructive operations and signing-secret changes. Use only for an action requested by the user. | |
| email_id | Yes | Positive email id. | |
| sequence_id | Yes | Positive sequence id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered structurally. The description adds genuinely useful consequence detail ('May affect delivery, audience membership, published data or irreversible state') plus the confirm precondition, which goes beyond what the annotations state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with the core action and the confirm requirement front-loaded and no filler. Every clause carries actionable information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive delete with no output schema, the description covers the key facts an agent needs: what it does, the impact surface, and the confirm guard. It stops short of noting cascading effects on subscribers or whether the operation is recoverable, but it is otherwise sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all four parameters (account, confirm, email_id, sequence_id) are already documented in the schema. The description only restates the confirm=true requirement, adding little syntax or semantic detail beyond the structured fields — baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource combination ('Delete a sequence email') that is unambiguous on its own. It does not, however, differentiate itself from closely related siblings such as delete_sequence or update_sequence_email, leaving the agent to infer the scope from the name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The requirement 'confirm=true' gives a concrete precondition for invocation, and the schema clarifies it should only be used for user-requested actions. However, there is no guidance on when to delete vs. update or unpublish a sequence email, nor any reference to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a subscriber's location. May affect delivery, audience membership, published data or irreversible state. Requires confirm=true.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| confirm | No | Must be true for audience/delivery changes, publishing, destructive operations and signing-secret changes. Use only for an action requested by the user. | |
| subscriber_id | Yes | Positive subscriber id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is partly covered. The description adds genuinely useful context beyond that: the downstream effects (delivery, audience membership, published data, irreversible state) and the confirm=true gate, which help the agent reason about consequences.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with the action front-loaded and the risk/guardrail stated second. Every clause earns its place; little room for improvement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with no output schema, the description supplies the consequence profile and the confirm gate, which is what an agent needs to call it safely. The absence of return expectations is acceptable since no output schema exists, though explicit sibling routing is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so account, confirm, and subscriber_id are already documented in the schema. The description only restates the confirm=true requirement, adding no format or semantic meaning beyond structured fields, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (Delete) and resource (a subscriber's location), which cleanly separates it from siblings like update_subscriber_location and pin_subscriber_location by the destructive verb. It doesn't explicitly name those siblings to route the agent, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It conveys the confirm=true prerequisite and warns of consequences, implying this is a high-stakes action. However, it never states when to choose this over update_subscriber_location or pin_subscriber_location, nor an explicit 'do not use' condition, leaving usage only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a webhook. May affect delivery, audience membership, published data or irreversible state. Requires confirm=true. Webhook response secrets are redacted; new signing secrets are saved only to a private local file.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| confirm | No | Must be true for audience/delivery changes, publishing, destructive operations and signing-secret changes. Use only for an action requested by the user. | |
| webhook_id | Yes | Positive webhook id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, idempotentHint=false and readOnlyHint=false, but the description adds real value beyond them: the confirm=true gate, the blast radius (delivery, audience membership, published data, irreversible state), and the non-obvious secret-handling behavior (response secrets redacted, new signing secrets written only to a private local file). The only gap is no statement about recoverability or required permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, each carrying distinct information: the action, the destructive scope plus the confirm gate, and the secret-handling side effect. The most decision-critical constraint (blast radius / confirm) is front-loaded after the action statement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with no output schema, the description covers preconditions, impact scope and side effects well. The one real omission is disambiguation from the near-named delete_webhook_endpoint sibling, which an agent needs before selecting this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so webhook_id, account and confirm are already documented, including the confirm semantics and the account resolution rules. The description's mention of 'Requires confirm=true' restates what the schema already says rather than adding syntax or format detail, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Delete a webhook'), so the action is unambiguous. However, the sibling list contains both delete_webhook_endpoint and delete_webhook, and the description never clarifies how a 'webhook' differs from a 'webhook endpoint', leaving an agent that must choose between the two without guidance.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a clear precondition ('Requires confirm=true') and a caution about scope of impact, but never says when to reach for this tool versus delete_webhook_endpoint or the secret-rotation siblings. Usage context is implied rather than stated, and no when-not guidance is offered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a webhook endpoint. May affect delivery, audience membership, published data or irreversible state. Requires confirm=true. Webhook response secrets are redacted; new signing secrets are saved only to a private local file.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| confirm | No | Must be true for audience/delivery changes, publishing, destructive operations and signing-secret changes. Use only for an action requested by the user. | |
| webhook_endpoint_id | Yes | Positive webhook endpoint id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=false, and the description adds real value beyond them: it names the affected domains (delivery, audience membership, published data, irreversible state), the confirm gate, and the signing-secret handling (secrets redacted, new secrets written to a private local file). That is exactly the kind of side-effect disclosure an agent needs for a destructive tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences with zero filler; the core action and the confirm requirement are front-loaded, and the impact/secret details follow in order of importance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a three-param destructive tool with full schema coverage and no output schema, the description covers purpose, prerequisite, and consequences adequately. It could go one step further by noting what the response returns or how this differs from the sibling delete_webhook tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the account, confirm, and webhook_endpoint_id parameters are already fully documented in the schema. The description reinforces the confirm=true requirement but adds no new syntax, format, or constraint detail beyond the schema, making the baseline 3 appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Delete) and resource (webhook endpoint) that matches the title, letting an agent distinguish it from CRUD siblings like update_webhook_endpoint or get_webhook_endpoint. However, it does not distinguish itself from the similarly named delete_webhook sibling, leaving the scope boundary implicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states the confirm=true prerequisite and warns that use should follow a user-requested action, which is genuine usage guidance. It gives no context on when to choose this over delete_webhook or other endpoint tools, so the guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Filter subscribers by engagement, sign-up date, state, and tags. Reads account data.
| Name | Required | Description | Default |
|---|---|---|---|
| all | No | Array of filter conditions where ALL must be met (AND logic) | |
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| include | No | Optional. 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). | |
| payload | No | Complete JSON body instead of individual body flags. Supports nullable fields and nested bulk structures. Cannot be combined with body flags or payload_file. | |
| sort_field | No | Field 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_order | No | Sort direction (default: desc). | |
| payload_file | No | Local JSON request body file, at most 5 MB. Contents are validated before the API call and are never logged. | |
| counting_mode | No | Controls 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. |
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.
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.
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.
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.
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.
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.
Get current account. Reads account data.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. |
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; 'Reads account data' merely restates the read-only nature. No additional behavioral context such as auth requirements, rate limits, or side effects is provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The first sentence is front-loaded and sufficient, but the second sentence ('Reads account data.') is redundant with the title, annotations, and first sentence. It does not earn its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with a fully documented optional parameter and rich annotations, the definition is mostly sufficient. However, with no output schema and no description of returned account fields, the agent lacks return-value context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single optional account parameter is fully documented with default fallback behavior. The description adds no parameter information beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource ('Get current account') and clarifies it is a read operation, so an agent can identify the basic action. It does not distinguish this tool from the sibling list_accounts or state scope beyond 'current'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use or when-not-to-use guidance appears; the description does not mention alternatives like list_accounts or any prerequisites. Usage is only implied by the tool name and parameter description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a broadcast. Reads account data.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| broadcast_id | Yes | Positive broadcast id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered structurally. The description adds nothing beyond that, and its "Reads account data" phrasing is confusing for a broadcast-reading tool rather than useful behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It is short and front-loaded, but the second sentence does not earn its place: it repeats the read nature already implied and introduces a misleading resource reference rather than adding information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description should convey what a broadcast read returns, but it only says "Reads account data." For a retrieval tool with no return-shape documentation, this leaves an important gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both the account and broadcast_id parameters are documented in the schema (positive id, account defaulting behavior). The description adds no syntax or format detail beyond that, which matches the baseline 3 when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence gives a clear verb+resource ("Get a broadcast"), but it does nothing to distinguish this tool from the many siblings reading the same broadcast resource (list_broadcasts, get_broadcast_stats, get_broadcast_clicks). The second sentence ("Reads account data") is vague and arguably misdescribes the resource the tool targets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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 versus list_broadcasts, get_broadcast_stats, or get_broadcast_clicks. No prerequisites or context for retrieval are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get link clicks for a broadcast. Reads account data.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| broadcast_id | Yes | Positive broadcast id. |
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 covered. The description adds only the vague 'Reads account data', which hints at account scoping but does not clarify pagination, result limits, or how click data is aggregated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two very short sentences with the core action front-loaded and no padding. The second sentence earns little, but there is no verbosity to penalize.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description should explain what a 'link click' result looks like (per-link counts, totals, date scoping), and it does not. For a data-retrieval tool with no output schema, the description leaves the return shape entirely opaque.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both the account and broadcast_id parameters are already documented in the schema. The description adds no additional meaning about parameter formats or constraints, which is the expected baseline when the schema carries the load.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Get link clicks for a broadcast'), which is clearly distinct from sibling stats tools like get_broadcast_stats. However, it makes no attempt to differentiate itself explicitly from those siblings, and the trailing phrase 'Reads account data' muddies rather than sharpens the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance at all: no indication of when to prefer this over get_broadcast_stats, list_broadcast_stats, or get_email_stats, and no prerequisites or exclusions. The agent must infer usage entirely from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get stats for a broadcast. Reads account data.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| broadcast_id | Yes | Positive broadcast id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint, covering the safety profile. 'Reads account data' restates the read-only nature with no additional value such as the stats returned, latency, rate limits, or auth/account-selection behavior beyond what the parameter already says.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the core action and no padding. 'Reads account data' is arguably redundant filler, but the description is not bloated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with rich annotations and a fully documented schema, the description is minimally adequate. Its main gap is not positioning itself against the several confusing sibling stats tools, which an agent needs to pick the right one.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both 'account' (naming KIT_ACCOUNTS default behavior) and 'broadcast_id' fully documented in the schema. The description adds nothing about parameter format or meaning, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Get stats for a broadcast'), so the agent knows it retrieves metrics for a single broadcast. However, it does nothing to distinguish itself from close siblings like list_broadcast_stats, get_broadcast_clicks, or get_email_stats, leaving the selection ambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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 versus list_broadcast_stats or get_broadcast_clicks, nor any prerequisites or exclusions. 'Reads account data' is a data-source note, not usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get Creator Profile. Reads account data.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds only 'Reads account data,' which is redundant with the readOnly annotation and does not disclose return shape, default-account resolution behavior beyond the schema, or any auth requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It is short and front-loaded, but the first sentence is pure name repetition and the second is thin, so it's terse rather than information-dense. Neither sentence earns much beyond the structured fields.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description should describe what a creator profile returns; it does not. For a tool with zero explanation of its return payload and no differentiation from get_account, this is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single 'account' parameter is fully documented in the schema (including the KIT_DEFAULT_ACCOUNT fallback). The description adds nothing further, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence merely restates the tool name and title ('Get Creator Profile'), and the second, 'Reads account data,' is vague and arguably misleading – it doesn't clarify what a creator profile is or how it differs from siblings like get_account or list_accounts. No specific resource detail is added beyond the name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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 alternatives. With get_account and list_accounts among the siblings, an agent has no way to know which to choose from the description alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get email stats. Reads account data.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. |
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. The only additional claim, "Reads account data," merely restates what readOnlyHint already conveys; it adds no scope, rate-limit, or result-shape context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
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.") is pure filler that duplicates the readOnlyHint annotation rather than earning its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description carries the burden of explaining what 'email stats' actually contains, and it fails to do so. No time range, no scope (account vs. broadcast), and no metric list are provided, leaving the agent unable to predict the response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single account parameter (with its KIT_ACCOUNTS default behavior) is fully documented in the schema. The description adds nothing further about the parameter, so the baseline 3 for high coverage is correct.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description "Get email stats" simply restates the tool name and title verbatim, offering no detail about which email metrics (opens, clicks, sends, per-broadcast vs. account-wide) are returned. It does not distinguish this tool from close siblings like get_growth_stats, get_broadcast_stats, or get_subscriber_stats.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no indication of when to use this tool versus the many other stats tools in the sibling list, nor any prerequisites or exclusions. The agent is left to infer usage entirely.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get growth stats. Reads account data.
| Name | Required | Description | Default |
|---|---|---|---|
| ending | No | ||
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| starting | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, fully covering the safety profile. The description's only behavioral claim, 'Reads account data,' is essentially a restatement of readOnlyHint and adds no rate-limit, auth, or aggregation context 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
Very short and not padded, but the first sentence merely repeats the title, so a full sentence is spent without earning its place. Front-loading is technically present but the content is empty.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with three loosely documented parameters, no output schema, and no annotation gaps to fill, the description is inadequate: it does not define the metric, the time-range parameters, or the return shape. An agent would have to guess at both scope and inputs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 33% (account documented, ending and starting undocumented), so the description must compensate but does not. It adds no meaning about what starting/ending represent (date ranges? periods?) or their format, leaving two of three parameters opaque.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description is essentially a tautology: 'Get growth stats' restates the name and title verbatim. 'Reads account data' is a vague domain hint but does not specify what 'growth stats' are (subscriber growth? revenue? email list growth?) or how it differs from siblings like get_email_stats and get_subscriber_stats.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use guidance, no prerequisites, and no routing to alternatives. An agent cannot tell from this text whether to call get_growth_stats, get_email_stats, or get_subscriber_stats. Usage is only implied by the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a post. Reads account data.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| post_id | Yes | Positive post id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds only 'Reads account data,' which is vague and does not disclose auth needs, rate limits, or return behavior beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, but the second sentence 'Reads account data' is vague and does not earn its place; it may even mislead. The first sentence is front-loaded but tautological.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with rich annotations and full schema coverage, the description is minimally adequate but lacks sibling differentiation and any note about what a post object contains (no output schema).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with both parameters fully described in the input schema. The description adds no parameter meaning, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get a post' is a tautological restatement of the tool name and title; it does not distinguish this tool from siblings like list_posts or get_account. The added 'Reads account data' is vague and could be confused with get_account.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as list_posts or get_account. No prerequisites or context are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a purchase. Reads account data. Requires OAuth; API keys are not supported for this endpoint.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| purchase_id | Yes | Positive purchase id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint. The description adds genuinely useful context beyond them: the endpoint requires OAuth and does not support API keys, which affects how an agent must authenticate. It stops short of describing return shape or failure behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the operation before the auth caveat, with little waste. 'Reads account data' is mildly vague filler but the rest earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-item getter with a 100%-documented schema, full safety annotations, and no output schema, the description covers what an agent needs to call it correctly, including the OAuth caveat. The missing piece is routing guidance against list_purchases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters (account, purchase_id) are already documented in the schema. The description adds no format, default, or constraint detail beyond that; baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('Get a purchase') that reads clearly as a single-item retrieval. It distinguishes itself implicitly from create_purchase and list_purchases via the verb, but never names them, so differentiation is left to inference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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 versus list_purchases or the other purchase siblings, and no stated prerequisites beyond auth. The 'Reads account data' sentence gestures at context but does not tell the agent when this tool is the right choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a sequence. Reads account data.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| include | No | ||
| sequence_id | Yes | Positive sequence id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, covering the safety profile. The description adds nothing beyond restating that it reads ('Reads account data'), providing no extra behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Very short and front-loaded, which is good. But the space is spent on a generic purpose statement plus a vague 'Reads account data' clause that does not earn its place by clarifying usage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter tool with an undocumented 'include' param and no output schema, the description should carry more load. It provides essentially no guidance on parameters or behavior, leaving the agent under-informed versus the sibling set.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67%, with the 'include' parameter having no description. The description mentions no parameters at all, so it cannot compensate for the undocumented 'include' field or clarify what should be included.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a generic verb+resource ('Get a sequence'), so an agent knows it retrieves a sequence. However, it does not differentiate from siblings like list_sequences or get_sequence_email, and the trailing 'Reads account data' is ambiguous for a sequence-fetching tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no indication of when to use this tool versus alternatives (e.g., list_sequences to enumerate, get_sequence_email to fetch a specific email). No prerequisites or context are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a sequence email. Reads account data.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| include | No | ||
| email_id | Yes | Positive email id. | |
| sequence_id | Yes | Positive sequence id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds only "Reads account data," which is redundant with readOnlyHint and unclear about what account data actually means here. No return shape, permission, or failure behavior is disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences that are front-loaded and free of padding, but the second sentence earns no place — it conveys neither behavior nor usage. The brevity here reflects under-specification rather than disciplined concision.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description should carry more burden, yet it never indicates what a returned sequence email contains or what `include` does. For a 4-parameter fetch tool with a hidden optional parameter, this leaves meaningful gaps an agent would have to guess at.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 75%, below the 80% baseline, so the description is expected to compensate — and it does not. The undocumented `include` parameter (likely controlling what related data is expanded) is never explained, despite being the one parameter whose semantics are not self-evident. email_id and sequence_id are already described adequately in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
"Get a sequence email" is a verbatim restatement of the title, adding no scope or specificity beyond the name. It does not distinguish this tool from adjacent siblings such as list_sequence_emails, get_sequence, or get_email_stats. The second sentence ("Reads account data") is ambiguous about whether it fetches account data or an email belonging to a sequence, muddying rather than clarifying the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use guidance is given, and no alternative is named even though list_sequence_emails (bulk) and get_sequence (parent) are obvious adjacent choices. An agent must infer that this is the single-item fetch from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a snippet. Reads account data.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| snippet_id | Yes | Positive snippet id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered structurally. The description's only added claim, "Reads account data," is vague and does not clarify what a snippet is, whether it is scoped to the given account, or any error/absence behavior — so it adds little beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded, which is appropriate for a simple read tool. However, the second sentence ("Reads account data") is vague filler that does not clearly earn its place, and the overall brevity here reflects under-specification rather than deliberate economy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter read-only tool with full schema coverage, annotations, and no output schema, the description is minimally sufficient to invoke correctly. It nonetheless omits what a snippet represents and any scoping/return context, leaving it adequate but bare.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters (account and snippet_id) are fully documented in the schema, including defaults and the positive-integer constraint. The description contributes nothing further about parameters, which is the expected baseline of 3 when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
"Get a snippet" simply restates the tool name and title, giving no differentiation from siblings like list_snippets, update_snippet, or create_snippet. While "get" and "snippet" identify a verb and resource, the sentence adds no information an agent couldn't infer from the name alone.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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_snippets, get_snippet-adjacent retrieval tools, or update_snippet. No preconditions, no alternatives, no exclusions are stated anywhere in the description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a subscriber. Reads account data.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| subscriber_id | Yes | Positive subscriber id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the read-only nature is fully covered by structured data. The description adds only the vague "Reads account data," which neither explains error/not-found behavior nor adds any behavioral detail beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The definition is very short and front-loads the purpose, but the second sentence "Reads account data" is filler that does not earn its place and is arguably ambiguous for a subscriber-fetching tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description should ideally indicate what fields a fetched subscriber returns; instead it offers only the ambiguous "account data." For a simple get-by-id tool with a fully documented schema and covering annotations, this is minimally adequate but leaves a visible gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both subscriber_id and account are already well documented in the schema (including the KIT_ACCOUNTS defaulting behavior). The description adds no parameter meaning beyond that, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a clear verb+resource ("Get a subscriber") and the singular form implicitly distinguishes it from list_subscribers/search_subscribers. However, the second sentence ("Reads account data") is vague and does not help differentiate it from siblings such as get_subscriber_stats or get_account.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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 alternatives like list_subscribers, search_subscribers, or get_subscriber_stats, nor any stated prerequisites such as whether the subscriber must exist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List stats for a subscriber. Reads account data.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| subscriber_id | Yes | Positive subscriber id. | |
| email_sent_after | No | ||
| email_sent_before | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description's 'Reads account data' adds no meaningful behavioral context beyond what the annotations already convey, and it omits details like pagination, rate limits, or return format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and front-loaded with the core action. The second sentence ('Reads account data') is somewhat redundant given the readOnly annotation, but it does not bloat the text significantly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 4-parameter tool with no output schema and only 50% schema description coverage, the description is too sparse. It does not explain the two undocumented date parameters, the account selection behavior, or what the stats contain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 50%; email_sent_after and email_sent_before lack schema descriptions. The description does not mention any parameters or compensate for those undocumented date filters, leaving their semantics unclear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('List') and resource ('stats for a subscriber'), making the purpose clear. However, it does not explicitly differentiate itself from sibling stats tools like get_email_stats or get_growth_stats, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as get_email_stats, get_growth_stats, or get_subscriber. There are no when-to-use or when-not-to-use conditions stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a webhook endpoint. Reads account data. Webhook response secrets are redacted; new signing secrets are saved only to a private local file.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| webhook_endpoint_id | Yes | Positive webhook endpoint id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavior beyond that: response secrets are redacted, and a new signing secret is written only to a private local file — a surprising side effect for a 'read' operation that the schema and annotations do not reveal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short clauses, no filler, and the most important behavioral detail (secret redaction/local file write) is placed where the agent will see it. Slightly weakened by the vague, low-value sentence 'Reads account data.'
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description should describe what is actually returned; instead it only says secrets are redacted and file-saved. The account-scoping and ID requirements are covered by the schema, and annotations carry the safety profile, so this is adequate but leaves the return shape unexplained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters (account and webhook_endpoint_id) are fully documented in the schema. The description adds nothing further about parameter meaning, which is acceptable here — baseline 3 applies when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description says 'Get a webhook endpoint,' which is a clear verb+resource but is nearly a verbatim restatement of the title. It also fails to distinguish this tool from the near-identical siblings list_webhook_endpoints and get_webhook, so an agent gets no disambiguation signal.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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_webhook_endpoints, get_webhook, or update_webhook_endpoint. 'Reads account data' is a vague statement of an effect, not a usage condition, and no prerequisites or exclusions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List private account labels and configured auth methods, without returning credentials or token-file paths. Does not contact Kit.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the bar is lower. The description still adds real value: it states credentials and token-file paths are withheld from the result and that no remote call is made, both of which are behavioral facts not derivable from the annotations alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, zero waste. The primary action is front-loaded and the two constraints (no secrets, no network) follow immediately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description does a good job sketching the return contents (labels, auth methods) and what is excluded. Safety is fully covered by annotations. Minor gap: no indication of result shape or ordering, though for a zero-parameter list tool this is not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is nothing to document and the schema is trivially complete. The baseline for a parameterless tool applies; no compensating detail is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names a specific verb and resource ('List private account labels and configured auth methods') and clarifies what it does not return. It does not, however, differentiate itself from the sibling get_account, which an agent may reasonably confuse with it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implicit usage: the phrase 'Does not contact Kit' hints this is a local/offline inspection tool, and 'list' implies enumeration vs get_account's single fetch. But there is no explicit when-to-use or when-not-to-use guidance relative to get_account.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List broadcasts. Reads account data.
| Name | Required | Description | Default |
|---|---|---|---|
| slim | No | ||
| after | No | ||
| before | No | ||
| status | No | ||
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| per_page | No | ||
| all_pages | No | Read successive cursor pages, bounded by max_items (default 1000). Default false returns one API page. | |
| max_items | No | Maximum records when all_pages=true. A capped result reports truncation and its continuation cursor. | |
| sent_after | No | ||
| sent_before | No | ||
| include_total_count | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description's only added claim, 'Reads account data,' is vague and adds no behavioral context about pagination, scoping, or result caps. It does not contradict the annotations, but it adds little.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It is short and front-loaded with the operation name, which is good. But the second sentence ('Reads account data') is redundant given the readOnlyHint annotation and does not earn its place in such a minimal description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 11-parameter listing tool with no output schema, the description omits filtering semantics, pagination behavior, and default account resolution. Only a few schema fields (account, all_pages, max_items) are self-documented, so an agent has an incomplete picture of how to call this correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 27% across 11 parameters, so the description carries the burden of explaining them. It mentions nothing: not the date range filters (after/before/sent_after/sent_before), the status enum, slim, per_page, or all_pages. The undocumented parameters are left entirely opaque.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List broadcasts'), which is enough to know the general operation. However, it gives no differentiation from siblings such as get_broadcast, list_broadcast_stats, or get_broadcast_stats, which all deal with the same domain. 'Reads account data' is filler that does not sharpen the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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 get_broadcast, list_broadcast_stats, or the other broadcast siblings. No prerequisites, filters, or exclusions are mentioned. The agent is left to infer everything from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get stats for a list of broadcasts. Reads account data.
| Name | Required | Description | Default |
|---|---|---|---|
| after | No | ||
| before | No | ||
| status | No | ||
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| per_page | No | ||
| all_pages | No | Read successive cursor pages, bounded by max_items (default 1000). Default false returns one API page. | |
| max_items | No | Maximum records when all_pages=true. A capped result reports truncation and its continuation cursor. | |
| sent_after | No | ||
| sent_before | No | ||
| include_total_count | No |
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 structurally. The description's only addition, 'Reads account data,' is vague and adds little scope information; it says nothing about pagination across the 10 parameters or what account-context behavior means.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded, with no padding or wasted phrases. However, this brevity comes from omission rather than efficiency; for a 10-parameter tool the size is inappropriate.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 10 parameters, no output schema, and 0 required fields, the description should at least sketch the filtering and paging model. It covers neither, and gives no indication of what stats are returned or how account selection interacts with the results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 30%, so the description is expected to compensate for the ~7 undocumented parameters (after, before, status, per_page, sent_after, sent_before, include_total_count). It mentions no parameters at all, leaving filtering and pagination semantics entirely unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb+resource combination: retrieving statistics for multiple broadcasts. This is distinguishable in principle from the singular get_broadcast_stats, but the description never names that sibling or explains the list-vs-single relationship, so an agent must infer it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as get_broadcast_stats or list_broadcasts, despite the sibling set containing several near-identical names. An agent gets zero routing help from the description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List colors. Reads account data.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. |
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 structurally. "Reads account data" merely restates readOnlyHint at account scope and adds no new behavioral detail such as return shape, pagination, or scope of visible colors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short fragments with zero filler and the action is front-loaded, but the brevity reflects under-specification rather than efficiency. Nothing is wasted, yet almost nothing is conveyed beyond the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-optional-parameter, read-only listing tool with full schema coverage and rich annotations, and no output schema to explain, the description is minimally adequate. It still leaves the domain meaning of "colors" and the relationship to `update_colors` unstated, so it is not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is one optional parameter and schema description coverage is 100%, so the `account` parameter, its default chain (KIT_DEFAULT_ACCOUNT / first configured account), and its source (KIT_ACCOUNTS) are already fully documented in the schema. The description contributes nothing about the parameter, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ("List") and resource ("colors"), so an agent knows exactly what operation is performed. It does not, however, distinguish this from the sibling `update_colors`, and gives no hint at what a "color" object represents in this system. Clear but undifferentiated from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Reads account data" hints at the context of use (account-scoped reads) but stops far short of guidance. There is no statement of when to call this tool, when not to, or how it relates to `update_colors` or `get_account`. An agent must infer usage entirely.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List custom fields. Reads account data.
| Name | Required | Description | Default |
|---|---|---|---|
| after | No | ||
| before | No | ||
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| per_page | No | ||
| all_pages | No | Read successive cursor pages, bounded by max_items (default 1000). Default false returns one API page. | |
| max_items | No | Maximum records when all_pages=true. A capped result reports truncation and its continuation cursor. | |
| include_total_count | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
'Reads account data' merely restates readOnlyHint=true that annotations already declare explicitly, adding no new behavioral context. Nothing is said about pagination behavior, result ordering, or account scoping, even though the tool is openWorld and the pagination semantics are non-trivial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, front-loaded sentences with no noise, but the second sentence ('Reads account data') is filler that duplicates the annotation rather than doing work. Concise, yet under-specified for a 7-parameter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a paginated 7-parameter list tool with no output schema and 43% schema coverage, the description is far too thin. It omits pagination/cursor behavior, account-scoping interactions, and result shape, leaving the agent without enough to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 43% (after, before, per_page, and include_total_count are undocumented), so the description carries real burden here. It provides zero parameter guidance, leaving half the parameters with no meaning documented anywhere.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('List custom fields'), which is clear and unambiguous. However, it does not differentiate from the CRUD siblings (create_custom_field, update_custom_field, delete_custom_field, bulk_create_custom_fields), so an agent gets no help distinguishing the read variant from the write variants.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance, no exclusions, and no reference to alternatives such as get/list siblings or the bulk/update counterparts. The agent must infer that this is the read-all path for custom fields entirely on its own.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List email templates. Reads account data.
| Name | Required | Description | Default |
|---|---|---|---|
| after | No | ||
| before | No | ||
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| per_page | No | ||
| all_pages | No | Read successive cursor pages, bounded by max_items (default 1000). Default false returns one API page. | |
| max_items | No | Maximum records when all_pages=true. A capped result reports truncation and its continuation cursor. | |
| include_total_count | No |
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. The description's only addition, 'Reads account data', is essentially a restatement of readOnlyHint and contributes no new behavioral context such as pagination semantics or result shape.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences are front-loaded and free of bloat, but the brevity comes at the cost of substance rather than through efficient expression. It is appropriately sized for what it says, nothing more.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
A 7-parameter list tool with pagination controls, no output schema, and 43% schema coverage demands more than two sentences. Cursor parameters and total-count behavior are unexplained, and the return shape is not described.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 43%: after, before, per_page, and include_total_count carry no descriptions, and the description provides no parameter semantics at all. With low coverage, the description is required to compensate, and it does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (List) and resource (email templates), so an agent knows exactly what is returned. It does not differentiate itself from related listing siblings such as list_snippets or list_sequences, and adds no scope qualifier, but the core purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No indication of when to use this tool versus alternatives, nor any prerequisites. 'Reads account data' is a vague statement about data access, not guidance on invocation context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List forms. Reads account data.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | ||
| after | No | ||
| before | No | ||
| status | No | ||
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| include | No | ||
| per_page | No | ||
| all_pages | No | Read successive cursor pages, bounded by max_items (default 1000). Default false returns one API page. | |
| max_items | No | Maximum records when all_pages=true. A capped result reports truncation and its continuation cursor. | |
| include_total_count | No |
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 without the description. The only added behavioral claim, 'Reads account data,' restates what readOnlyHint implies and says nothing about pagination (all_pages/max_items) or result shape.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no filler and the operation name front-loaded, so it is structurally sound. However, the brevity comes at the cost of under-specification rather than genuine conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 10-parameter listing tool with no output schema and low schema coverage, the description leaves out filtering semantics, pagination behavior, and result limits. Annotations cover the safety profile, but the definition is still too thin for an agent to invoke it confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only 3 of 10 parameters (account, all_pages, max_items) have schema descriptions, and the description adds nothing to clarify the remaining seven, including the status enum and the cursor params after/before. It does not compensate for the 30% coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a clear verb+resource (list forms) with the added scope note that it reads account data. This is unambiguous, though it does nothing to differentiate the tool from siblings like list_subscribers_for_form or bulk_add_subscribers_to_forms.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance, no prerequisites, and no mention of alternatives. 'Reads account data' is a scope remark, not a usage condition, so an agent gets no help choosing this over related form/subscriber tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List posts. Reads account data.
| Name | Required | Description | Default |
|---|---|---|---|
| after | No | ||
| before | No | ||
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| per_page | No | ||
| all_pages | No | Read successive cursor pages, bounded by max_items (default 1000). Default false returns one API page. | |
| max_items | No | Maximum records when all_pages=true. A capped result reports truncation and its continuation cursor. | |
| include_content | No | ||
| include_total_count | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered structurally. The description adds only 'Reads account data,' which is vague and partially redundant with the readOnly annotation, offering no additional behavioral context like pagination defaults, rate limits, or what 'account data' entails.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (two short sentences) with no wasted words. However, this brevity comes at the cost of usefulness, and the second sentence is vague rather than front-loading critical information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 8 parameters, 38% schema coverage, no output schema, and no annotations beyond standard hints, the description is insufficient. It fails to explain pagination behavior, filtering options, or return structure, leaving the agent without necessary context to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 38%, so the description must compensate for several undocumented parameters (after, before, per_page, include_content, include_total_count). The description adds no parameter detail at all, leaving over half the parameters without explanation in either schema or description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a verb+resource ('List posts') but this is essentially a restatement of the title and name. It does not distinguish from the sibling 'get_post' or explain what a 'post' is, leaving the agent to infer scope without additional specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use guidance is provided. The description does not mention alternatives like get_post for a single post, nor does it indicate context such as needing a specific account or filtering. Usage is left entirely to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List purchases. Reads account data. Requires OAuth; API keys are not supported for this endpoint.
| Name | Required | Description | Default |
|---|---|---|---|
| after | No | ||
| before | No | ||
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| per_page | No | ||
| all_pages | No | Read successive cursor pages, bounded by max_items (default 1000). Default false returns one API page. | |
| max_items | No | Maximum records when all_pages=true. A capped result reports truncation and its continuation cursor. | |
| include_total_count | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only/idempotent/open-world behavior, so the bar is lower, and the description adds a genuinely useful auth constraint: OAuth is required and API keys are rejected for this endpoint. That is operationally important context an agent cannot infer from the annotations or schema, though it omits rate limits and pagination behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short, front-loaded sentences with no padding and the auth constraint stated plainly. The first sentence is redundant with the title, costing it the top score, but overall structure is tight.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 7-parameter, cursor-paginated list tool with no output schema, the description is notably thin: it never explains the after/before cursors, per_page, or truncation behavior that the schema leaves undocumented. It covers auth but leaves the caller without enough to invoke the filtering/pagination surface correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 43%: after, before, per_page, and include_total_count have no schema descriptions at all. The description adds nothing about these parameters, offering no filter, cursor, or pagination semantics to compensate for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a clear verb+resource ('List purchases'), which maps cleanly against siblings like get_purchase and create_purchase, but the opening sentence is a verbatim restatement of the title. Beyond that tautology it adds only 'Reads account data' and auth notes, with no scope, filtering, or result-shape detail.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use guidance and no routing to alternatives (e.g., get_purchase for a single purchase). The 'Reads account data' clause hints at read access but does not tell the agent when this tool is the right choice over its siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List segments. Reads account data.
| Name | Required | Description | Default |
|---|---|---|---|
| after | No | ||
| before | No | ||
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| per_page | No | ||
| all_pages | No | Read successive cursor pages, bounded by max_items (default 1000). Default false returns one API page. | |
| max_items | No | Maximum records when all_pages=true. A capped result reports truncation and its continuation cursor. | |
| include_total_count | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is fully covered. 'Reads account data' merely echoes the read-only nature and adds nothing about pagination, rate limits, or account scoping that the annotations and schema do not already imply.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded, but the second sentence ('Reads account data.') contributes almost no information beyond the annotations. It is concise for the wrong reason: under-specification rather than disciplined editing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 7 parameters, no output schema, and only 43% schema description coverage, two terse sentences are insufficient. The description omits default page behavior, cursor semantics, and what a 'segment' contains, all of which an agent needs to call this list tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 43% (7 parameters, 4 undocumented: after, before, per_page, include_total_count), so the description should compensate for the gap. Instead it says nothing about any parameter, leaving the pagination and count parameters entirely opaque to the agent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a verb and a resource ('List segments'), so the basic operation is identifiable, but it is essentially a restatement of the tool name and adds no scope, filter, or sibling differentiation. An agent cannot tell from this text how list_segments relates to list_sequences, list_subscribers, or the other list_* tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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 rather than another list tool, nor any prerequisites or exclusions. 'Reads account data' describes a trait, not a selection condition, so the agent is left to infer usage entirely from the name and siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List sequence emails. Reads account data.
| Name | Required | Description | Default |
|---|---|---|---|
| after | No | ||
| before | No | ||
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| include | No | ||
| per_page | No | ||
| all_pages | No | Read successive cursor pages, bounded by max_items (default 1000). Default false returns one API page. | |
| max_items | No | Maximum records when all_pages=true. A capped result reports truncation and its continuation cursor. | |
| sequence_id | Yes | Positive sequence id. | |
| include_content | No | ||
| include_total_count | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds only 'Reads account data,' which is vague and adds little beyond what annotations already provide. With annotations carrying the burden, a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences are front-loaded and efficient, though the second sentence is vague and borderline filler. No wasted length, but the content is thin.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 10 parameters, 40% schema coverage, and no output schema, the description is far too sparse. It fails to explain pagination behavior, what 'sequence emails' actually returns, or how this differs from sibling sequence tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 40%, so six parameters (after, before, include, per_page, include_content, include_total_count) lack descriptions anywhere. The description adds no parameter meaning, leaving a significant gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a verb and resource ('List sequence emails'), giving clear basic purpose. However, it doesn't distinguish this tool from siblings like 'get_sequence_email' or 'list_sequences', leaving scope ambiguous within the sequence family.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use context, no exclusions, and no alternatives named. The agent must infer from the name alone whether this returns emails in a sequence, sends them, or something else.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List sequences. Reads account data.
| Name | Required | Description | Default |
|---|---|---|---|
| after | No | ||
| before | No | ||
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| include | No | ||
| per_page | No | ||
| all_pages | No | Read successive cursor pages, bounded by max_items (default 1000). Default false returns one API page. | |
| max_items | No | Maximum records when all_pages=true. A capped result reports truncation and its continuation cursor. | |
| include_total_count | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description's only addition, 'Reads account data,' adds no real behavioral value and hints at scoping that is not explained, so it does not clear the lowered bar for annotated tools.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences are not bloated, but this is under-specification presented as brevity rather than genuine conciseness. The text is too thin to earn its place as a tool definition for an eight-parameter listing endpoint.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an eight-parameter paginated list tool with no output schema and a partially documented schema, the description leaves critical gaps: what a sequence is, cursor semantics, and the relationship between all_pages, per_page, and max_items. It is not sufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Eight parameters with only 38% schema description coverage (after, before, include, per_page, include_total_count are undocumented in the schema), and the description supplies no parameter meaning at all. With coverage well below the 50% threshold, the description needed to compensate and does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence gives a clear verb+resource ('List sequences'), but it does nothing to distinguish this tool from the many other list_* siblings such as list_sequence_emails, list_segments, or list_broadcasts. The second sentence, 'Reads account data,' is vague and even mildly confusing since it suggests account-level data rather than sequences.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use guidance, no mention of alternatives, and no exclusions. An agent cannot tell from the description when to reach for list_sequences versus list_sequence_emails or get_sequence; it must infer everything from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List snippets. Reads account data.
| Name | Required | Description | Default |
|---|---|---|---|
| after | No | ||
| before | No | ||
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| archived | No | ||
| per_page | No | ||
| all_pages | No | Read successive cursor pages, bounded by max_items (default 1000). Default false returns one API page. | |
| max_items | No | Maximum records when all_pages=true. A capped result reports truncation and its continuation cursor. | |
| snippet_type | No | ||
| include_content | No | ||
| include_total_count | No |
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 safety behavior is covered structurally. "Reads account data" adds nothing beyond the readOnlyHint annotation and omits pagination behavior, multi-account resolution, and truncation semantics, which are the genuinely useful unknowns here.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The two sentences are short but the problem is under-specification rather than conciseness. Nothing is front-loaded or prioritized, and both sentences are too thin to orient the caller on a 10-parameter listing tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 10 optional parameters, 30% schema coverage, no output schema, and no sibling differentiation, the description is nowhere near complete enough to invoke this tool correctly. Field names like snippet_type and include_content are left entirely to inference.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only 30% of the 10 parameters carry schema descriptions, so the burden falls on the description to compensate for the rest. It explains none of them — after, before, archived, per_page, snippet_type, include_content, and include_total_count are undocumented in both places, leaving seven parameters with zero semantic guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
"List snippets" merely restates the tool name and title without adding a specific verb-plus-scope framing. It never distinguishes this from siblings like get_snippet, create_snippet, or update_snippet, so the agent gets no help disambiguating the read-many operation from the read-one or write operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The second sentence, "Reads account data," gives no when-to-use context, no prerequisites, and no alternatives. An agent cannot tell from this whether list_snippets is preferred over get_snippet or how it relates to archived or filtered retrieval.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List subscribers. Reads account data.
| Name | Required | Description | Default |
|---|---|---|---|
| slim | No | ||
| after | No | ||
| before | No | ||
| status | No | ||
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| include | No | ||
| per_page | No | ||
| all_pages | No | Read successive cursor pages, bounded by max_items (default 1000). Default false returns one API page. | |
| max_items | No | Maximum records when all_pages=true. A capped result reports truncation and its continuation cursor. | |
| sort_field | No | ||
| sort_order | No | ||
| created_after | No | ||
| email_address | No | ||
| updated_after | No | ||
| created_before | No | ||
| updated_before | No | ||
| include_total_count | No |
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 by structured fields. The description adds nothing beyond that — it doesn't mention pagination behavior, page-size handling, sorting, or result truncation, which are the real behavioral traits an agent would need for a 17-parameter list tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It is short, but the second sentence earns no place and the whole is under-specified rather than concise. Nothing meaningful is front-loaded beyond the tool name being restated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 17-parameter tool with 18% schema coverage and no output schema, the description should carry substantial weight on filtering, pagination, and return shape. Instead it provides two sentences of content, none of which helps an agent call the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 18%, so the description must compensate — and it does not mention a single parameter. Key semantics like the 'slim' flag, 'include' expansions, date-range filters, sort fields, and the all_pages/max_items truncation contract are left entirely to the thin schema, which documents only three of seventeen parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence states a clear verb+resource ('List subscribers'), but the second sentence 'Reads account data' is vague filler that does not describe the resource being listed and borders on misleading, since subscribers are not account data. There is no differentiation from the many sibling listing tools (search_subscribers, filter_subscribers, list_subscribers_for_form, list_subscribers_for_tag) despite them being obvious alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use guidance is given. Nothing tells the agent how this differs from filter_subscribers or search_subscribers, or when each filtering parameter family applies. 'Reads account data' is not usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List subscribers for a form. Reads account data.
| Name | Required | Description | Default |
|---|---|---|---|
| slim | No | ||
| after | No | ||
| before | No | ||
| status | No | ||
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| form_id | Yes | Positive form id. | |
| per_page | No | ||
| all_pages | No | Read successive cursor pages, bounded by max_items (default 1000). Default false returns one API page. | |
| max_items | No | Maximum records when all_pages=true. A capped result reports truncation and its continuation cursor. | |
| added_after | No | ||
| added_before | No | ||
| created_after | No | ||
| created_before | No | ||
| include_total_count | No |
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. 'Reads account data' merely restates readOnlyHint and adds essentially no new behavioral context (no pagination defaults, no result-count behavior).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, front-loaded sentences with no filler. It is efficient, though the brevity reflects under-specification rather than disciplined conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 14-parameter listing tool with low schema coverage and no output schema, the description omits any discussion of pagination, filtering, or return shape. It leaves the agent to reconstruct usage entirely from the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 29% across 14 parameters; several (slim, after, before, status, per_page, added_*/created_* date filters, include_total_count) have no documentation in the schema. The description adds no parameter meaning whatsoever to compensate for that gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (List), resource (subscribers), and scope (for a form), which cleanly separates it from list_subscribers (all subscribers) and list_subscribers_for_sequence/tag. However, it does not explicitly name or contrast with those siblings, so an agent must infer the distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as filter_subscribers or search_subscribers. 'Reads account data' is a note about behavior, not a condition for selecting this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List subscribers for a sequence. Reads account data.
| Name | Required | Description | Default |
|---|---|---|---|
| after | No | ||
| before | No | ||
| status | No | ||
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| per_page | No | ||
| all_pages | No | Read successive cursor pages, bounded by max_items (default 1000). Default false returns one API page. | |
| max_items | No | Maximum records when all_pages=true. A capped result reports truncation and its continuation cursor. | |
| added_after | No | ||
| sequence_id | Yes | Positive sequence id. | |
| added_before | No | ||
| created_after | No | ||
| created_before | No | ||
| include_total_count | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered elsewhere. The description's only addition, 'Reads account data,' is vague and does not explain the account scoping, pagination behavior, or that results may be truncated by max_items.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no filler, so it is not bloated. But brevity comes at the cost of substance; the second sentence adds little, and nothing about the tool's many options is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 13-parameter list tool with pagination controls, date filters, a status enum, and no output schema, the description should explain filtering and paging expectations. As written it leaves the agent to discover all of that from the schema and annotations alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 13 parameters and only 31% schema description coverage, the description carries a real burden here and supplies essentially nothing about filtering semantics (status enum, added_/created_ date windows, include_total_count, cursor handling). The phrase 'for a sequence' restates the required sequence_id at most.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource (list subscribers) scoped to a sequence, which is clearer than a bare 'list'. However, it offers no differentiation from the several close siblings that do the same thing for other containers (list_subscribers_for_form, list_subscribers_for_tag, list_subscribers), leaving the agent to infer the distinction from names alone.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no when-to-use guidance, no prerequisites, and does not name any alternative such as filter_subscribers or list_subscribers for cases where the agent wants unsegmented or cross-sequence results. The only steer is the tool name itself.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List subscribers for a tag. Reads account data.
| Name | Required | Description | Default |
|---|---|---|---|
| slim | No | ||
| after | No | ||
| before | No | ||
| status | No | ||
| tag_id | Yes | Positive tag id. | |
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| per_page | No | ||
| all_pages | No | Read successive cursor pages, bounded by max_items (default 1000). Default false returns one API page. | |
| max_items | No | Maximum records when all_pages=true. A capped result reports truncation and its continuation cursor. | |
| tagged_after | No | ||
| created_after | No | ||
| tagged_before | No | ||
| created_before | No | ||
| include_total_count | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered without the description. 'Reads account data' hints at account scoping but is vague and adds little beyond what the account parameter and annotations already convey; nothing is said about pagination behavior or result truncation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no padding and the purpose front-loaded. The brevity is not the problem here — the omission of any substantive details is, so it lands at minimum viable rather than efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
A 14-parameter, filter-heavy list tool with 29% schema coverage, no output schema, and no annotations explaining return shape. The description supplies none of the missing filtering, pagination, or account-selection context an agent needs to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 29% across 14 parameters, so the description carries a heavy compensation burden — and it explains none of them. The status enum filter, the all_pages/max_items pagination pair, the four date-range parameters, and include_total_count are all left undocumented in prose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource (list subscribers scoped to a tag), which is clear on its own. However, it does nothing to distinguish itself from near-identical siblings such as list_subscribers_for_form and list_subscribers_for_sequence, so the agent must infer the distinction from the names alone.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use guidance, no mention of alternatives, and no prerequisites beyond the required tag_id. The agent gets no help deciding this tool versus list_subscribers, filter_subscribers, or search_subscribers.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List tags for a subscriber. Reads account data.
| Name | Required | Description | Default |
|---|---|---|---|
| after | No | ||
| before | No | ||
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| per_page | No | ||
| all_pages | No | Read successive cursor pages, bounded by max_items (default 1000). Default false returns one API page. | |
| max_items | No | Maximum records when all_pages=true. A capped result reports truncation and its continuation cursor. | |
| subscriber_id | Yes | Positive subscriber id. | |
| include_total_count | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is fully covered elsewhere. The added sentence 'Reads account data' is close to a restatement of readOnlyHint and says nothing about pagination, scoping, or the account-selection behavior that the tool actually exposes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Very short and front-loaded with no filler sentences, which is good. But the second sentence adds almost no information, so the brevity comes from under-specification rather than efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read tool with 8 parameters, half of them undocumented, and no output schema, the description leaves too much unsaid. Pagination semantics and account selection are handled only inside the schema and are never surfaced to the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 50% across 8 parameters, and the description supplies no parameter detail at all. Nothing explains cursor parameters (after/before), all_pages/max_items pagination, or the include_total_count flag, so the description fails to compensate for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List tags for a subscriber'), so the agent knows exactly what it returns. It does not, however, distinguish itself from nearby siblings such as list_tags or list_subscribers_for_tag, leaving the direction of the relationship implicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use guidance, no prerequisites, and no mention of alternatives. With siblings like list_tags and list_subscribers_for_tag in the same family, the agent must guess which direction of lookup applies.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List tags. Reads account data.
| Name | Required | Description | Default |
|---|---|---|---|
| after | No | ||
| before | No | ||
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| include | No | ||
| per_page | No | ||
| all_pages | No | Read successive cursor pages, bounded by max_items (default 1000). Default false returns one API page. | |
| max_items | No | Maximum records when all_pages=true. A capped result reports truncation and its continuation cursor. | |
| include_total_count | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered elsewhere. 'Reads account data' adds only marginal scoping context and omits pagination behavior, truncation semantics, or rate limits that matter for an 8-param listing tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two very short sentences are front-loaded but this is under-specification rather than conciseness. Nothing is wasted, but almost nothing is supplied either.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 8 parameters, 38% schema coverage, no output schema, and many sibling tag tools, this description is far too thin. It neither explains pagination/cursor semantics nor routes among alternative tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 38%, so the description is expected to compensate for undocumented parameters such as 'after', 'before', 'include', 'per_page', and 'include_total_count'. It provides none of that; only account/all_pages/max_items carry schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a verb and resource ('List tags'), so the basic operation is inferable. However, it does nothing to distinguish itself from close siblings like list_subscriber_tags and list_subscribers_for_tag, nor does it explain what a 'tag' resource represents here.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use, when-not-to-use, or alternative-tool guidance is given. The agent must guess whether this is the right tag-listing tool versus list_subscriber_tags or list_subscribers_for_tag.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List webhook endpoints. Reads account data. Webhook response secrets are redacted; new signing secrets are saved only to a private local file.
| Name | Required | Description | Default |
|---|---|---|---|
| after | No | ||
| before | No | ||
| status | No | ||
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| per_page | No | ||
| all_pages | No | Read successive cursor pages, bounded by max_items (default 1000). Default false returns one API page. | |
| max_items | No | Maximum records when all_pages=true. A capped result reports truncation and its continuation cursor. | |
| include_total_count | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered structurally. The description earns credit by disclosing non-obvious behavior beyond the annotations: webhook response secrets are redacted and new signing secrets are written only to a private local file — a critical surprise an agent would otherwise miss.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the core purpose, then the scope, then the security caveat. Nothing is padded, though the middle sentence ('Reads account data') is close to filler next to the annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 8-parameter list tool with no output schema and partial schema coverage, the description covers the distinctive secret-handling behavior but omits filtering, pagination, and default behavior (e.g., all_pages/max_items semantics). It is adequate but leaves real gaps for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Eight parameters with only 38% schema description coverage, and the description supplies no parameter meaning at all. Undocumented parameters such as after, before, per_page, and include_total_count receive no explanation in either place, so the description fails to compensate for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('List webhook endpoints') and adds a useful scope note ('Reads account data'), so an agent knows this is a read operation over webhook endpoint records. It doesn't distinguish itself from the sibling list_webhooks, but the verb+resource pairing is clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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 versus list_webhooks, get_webhook_endpoint, or list_webhooks, nor any stated prerequisites or conditions. 'Reads account data' describes what the tool touches rather than when to pick it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List webhooks. Reads account data. Webhook response secrets are redacted; new signing secrets are saved only to a private local file.
| Name | Required | Description | Default |
|---|---|---|---|
| after | No | ||
| before | No | ||
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| per_page | No | ||
| all_pages | No | Read successive cursor pages, bounded by max_items (default 1000). Default false returns one API page. | |
| max_items | No | Maximum records when all_pages=true. A capped result reports truncation and its continuation cursor. | |
| include_total_count | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower. The description still adds genuinely useful, non-obvious behavior: response secrets are redacted, and new signing secrets are written only to a private local file rather than returned. The signing-secret sentence reads as possible boilerplate for a pure list operation, which keeps this from a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences with the purpose front-loaded and no padding. The final clause about signing secrets is arguably off-topic for a read-only list, but the overall structure is tight and readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-required-parameter read-only list tool with full annotations, the description is serviceable, and the redaction note is valuable. However, it leaves the 43%-covered pagination parameters unexplained and gives no routing guidance against 'list_webhook_endpoints', both of which an agent needs for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 43%: 'after', 'before', 'per_page', and 'include_total_count' are undocumented in the schema. The description supplies no compensating meaning for any parameter, so pagination and cursor behavior remain opaque. Low coverage demanded compensation that is entirely absent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence 'List webhooks' states a verb and resource, but it is essentially a restatement of the tool name/title rather than an elaboration. Crucially, it never distinguishes this from the adjacent sibling 'list_webhook_endpoints', so an agent cannot tell the two apart from the description alone. Purpose is legible but thin.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use, when-not-to-use, or alternative-tool guidance. With 'list_webhook_endpoints' in the sibling set, some routing hint was warranted. The description states no context for selection at all.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Pin a subscriber's location. May affect delivery, audience membership, published data or irreversible state. Requires confirm=true.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| confirm | No | Must be true for audience/delivery changes, publishing, destructive operations and signing-secret changes. Use only for an action requested by the user. | |
| payload | No | Complete JSON body instead of individual body flags. Supports nullable fields and nested bulk structures. Cannot be combined with body flags or payload_file. | |
| location | No | ||
| payload_file | No | Local JSON request body file, at most 5 MB. Contents are validated before the API call and are never logged. | |
| subscriber_id | Yes | Positive subscriber id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description usefully enumerates the blast radius (delivery, audience membership, published data, irreversible state) and the confirm requirement, but this reads as generic destructive-op boilerplate that partly duplicates the confirm parameter's own schema description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with the action front-loaded and the risk warning immediately after; nothing is padded. It is efficient, though the terseness leaves the usage gaps noted above.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 6-parameter destructive tool with nested objects and no output schema, the description covers the risk profile and confirm requirement but omits what pinning means versus updating, when to choose it, and how the three body-input options relate. Minimum viable but with clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 83%, so the schema already documents the parameters well. The description only echoes the confirm=true requirement and adds no syntax, format, or relationship detail (e.g., payload vs location vs payload_file mutual exclusion) beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
"Pin a subscriber's location" states a verb and resource, but it is essentially a restatement of the title and adds no detail. It does not distinguish pinning from the sibling tools update_subscriber_location or delete_subscriber_location, so an agent cannot tell why it would pick this over those without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no when-to-use or when-not-to-use guidance and names no alternatives, despite three closely related location tools existing. The only guidance is the confirm=true prerequisite, which is a rule rather than a routing hint.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Revoke the previous webhook endpoint secret. May affect delivery, audience membership, published data or irreversible state. Requires confirm=true. Webhook response secrets are redacted; new signing secrets are saved only to a private local file.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| confirm | No | Must be true for audience/delivery changes, publishing, destructive operations and signing-secret changes. Use only for an action requested by the user. | |
| webhook_endpoint_id | Yes | Positive webhook endpoint id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare destructiveHint=true, idempotentHint=false, and openWorldHint=true. The description adds valuable behavioral details beyond annotations: the warning that it 'May affect delivery, audience membership, published data or irreversible state,' the confirm=true requirement, and the crucial note that 'webhook response secrets are redacted; new signing secrets are saved only to a private local file.' This tells the agent how to handle secret retrieval, which annotations do not cover.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the action and followed by critical warnings. It is efficient and every sentence earns its place, though it could be slightly tighter by combining the confirm requirement with the earlier warning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive, non-idempotent secret-revocation tool with no output schema, the description covers the key risks (irreversible state, affected delivery) and the confirm requirement. It also explains where new secrets go, which is important for correct agent behavior. It does not explain the return value (none), but that is acceptable without an output schema. The main gap is the lack of explicit when-to-use guidance relative to rotate_webhook_secret.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all three parameters, including the id, account, and confirm fields. The description adds the semantic that confirm=true is required specifically for this signing-secret change, reinforcing the schema's general rule, but it does not add new parameter formatting or usage details beyond what the schema provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource: 'Revoke the previous webhook endpoint secret.' It is distinguishable from sibling rotate_webhook_secret because it targets the 'previous' secret rather than rotating to a new one. It doesn't explicitly differentiate from delete_webhook_endpoint or update_webhook_endpoint, but the operation is clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says 'Requires confirm=true' and implies this is a signing-secret change, which provides some context. However, it never states when an agent should choose this tool over rotate_webhook_secret or why one would revoke a previous secret (e.g., after rotation). It offers no explicit alternatives or when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rotate a webhook endpoint secret. May affect delivery, audience membership, published data or irreversible state. Requires confirm=true. Webhook response secrets are redacted; new signing secrets are saved only to a private local file.
| Name | Required | Description | Default |
|---|---|---|---|
| force | No | Rotating again while a previous rotation's overlap window is still open returns `409` (see the responses below). Pass `true` to rotate anyway, immediately expiring the older secret. | |
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| confirm | No | Must be true for audience/delivery changes, publishing, destructive operations and signing-secret changes. Use only for an action requested by the user. | |
| payload | No | Complete JSON body instead of individual body flags. Supports nullable fields and nested bulk structures. Cannot be combined with body flags or payload_file. | |
| secret_name | Yes | New private filename under KIT_PRIVATE_DIR. Required before creating/rotating a signing secret; never overwritten. | |
| payload_file | No | Local JSON request body file, at most 5 MB. Contents are validated before the API call and are never logged. | |
| webhook_endpoint_id | Yes | Positive webhook endpoint id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=false, so the description goes beyond them by warning that rotation 'may affect delivery, audience membership, published data or irreversible state', that confirm is required, and that webhook responses are redacted while new secrets are written to a private local file. These are genuinely useful behavioral facts not derivable from 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four short sentences, front-loaded with the action and consequences, with no filler. The confirm sentence lightly duplicates the schema but earns its place as a safety callout.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive mutation tool with rich annotations, 100% schema coverage, and no output schema, the description covers the important agent-facing concerns: consequences, the confirm gate, and where the new secret is stored. Little relevant information is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters like force, secret_name, and payload are already fully documented in the schema. The description largely restates the confirm requirement and adds no syntax or format detail beyond it, so a baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Rotate a webhook endpoint secret') matching the title, and adds the key consequence that new signing secrets land in a private local file. It does not, however, distinguish this from the very close sibling 'revoke_previous_webhook_secret', which an agent must disambiguate on its own.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Requires confirm=true' gives a concrete precondition for invoking the tool. But there is no explicit when-to-use versus the near-identical 'revoke_previous_webhook_secret' sibling or guidance on overlap-window/force usage, so the usage context is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compatibility alias for list_subscribers with a required exact email_address filter.
| Name | Required | Description | Default |
|---|---|---|---|
| slim | No | ||
| after | No | ||
| before | No | ||
| status | No | ||
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| include | No | ||
| per_page | No | ||
| all_pages | No | Read successive cursor pages, bounded by max_items (default 1000). Default false returns one API page. | |
| max_items | No | Maximum records when all_pages=true. A capped result reports truncation and its continuation cursor. | |
| sort_field | No | ||
| sort_order | No | ||
| created_after | No | ||
| email_address | Yes | ||
| updated_after | No | ||
| created_before | No | ||
| updated_before | No | ||
| include_total_count | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the meaningful behavioral fact that this is a compatibility alias rather than a primary tool. It does not describe pagination behavior, though the schema covers all_pages/max_items.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with no filler; the required filter is stated up front and nothing is redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 17-parameter tool with 18% schema description coverage and no output schema, a one-line description is inadequate. Annotations cover the safety profile, but an agent still lacks guidance on the many filter, sort, and pagination parameters. The definition is under-specified relative to the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 18% (3 of 17 params documented), so the description carries a heavy burden it does not meet. It adds one useful semantic detail — that email_address is an 'exact' match — but leaves the other 14 parameters, including the status/sort enums and pagination controls, unexplained. It compensates only marginally for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb (search/find), resource (subscribers), and scope (required exact email_address filter), and explicitly identifies the sibling it aliases (list_subscribers). An agent can tell what it does and how it differs from list_subscribers. The 'compatibility alias' framing slightly muddies whether it is a distinct capability or a legacy shim, keeping it from a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Calling it a 'compatibility alias for list_subscribers' implies it exists for backward compatibility and that list_subscribers is the preferred tool, but this is left implicit. There is no explicit when-to-use/when-not guidance or statement of which alternative to prefer for new work.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tag a subscriber by email address. May affect delivery, audience membership, published data or irreversible state. Requires confirm=true.
| Name | Required | Description | Default |
|---|---|---|---|
| tag_id | Yes | Positive tag id. | |
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| confirm | No | Must be true for audience/delivery changes, publishing, destructive operations and signing-secret changes. Use only for an action requested by the user. | |
| payload | No | Complete JSON body instead of individual body flags. Supports nullable fields and nested bulk structures. Cannot be combined with body flags or payload_file. | |
| payload_file | No | Local JSON request body file, at most 5 MB. Contents are validated before the API call and are never logged. | |
| email_address | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds concrete consequences (delivery, audience membership, published data, irreversible state) that go beyond the boolean hints, plus the confirm gate. It stops short of noting that repeat calls are not idempotent, which the annotations only hint at.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences with the purpose front-loaded and the confirm requirement last. No filler, though the risk list is somewhat boilerplate and could be tightened.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the mutating nature and the confirm gate for a 6-parameter tool with no output schema. The identifier and body-input alternatives (payload vs payload_file vs body flags) are left entirely to the schema, so an agent gets only a partial picture of how to invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 83%, so the schema carries most parameter meaning; the baseline applies. The description only reinforces the email-address selector and the confirm requirement, adding little about payload, payload_file, or account over what the schema already documents.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names a specific verb (tag) and resource (subscriber) with the identifying key (email address), which implicitly separates it from the sibling tag_subscriber_by_id. It does not explicitly name that sibling, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
States the prerequisite that confirm=true is required, which is actionable. However, it gives no guidance on when to prefer this over tag_subscriber_by_id, bulk_tag_subscribers, or untag_subscriber, so usage selection is implied rather than directed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tag a subscriber. May affect delivery, audience membership, published data or irreversible state. Requires confirm=true.
| Name | Required | Description | Default |
|---|---|---|---|
| tag_id | Yes | Positive tag id. | |
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| confirm | No | Must be true for audience/delivery changes, publishing, destructive operations and signing-secret changes. Use only for an action requested by the user. | |
| subscriber_id | Yes | Positive subscriber id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, and the description largely restates that risk rather than going beyond it. It does add the confirm=true requirement and a list of consequence categories (delivery, audience membership, published data, irreversible state), which gives real context for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with the core action front-loaded and no filler. The second sentence is somewhat hedgy ("may affect ... or") rather than precise, which keeps it from a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive, non-idempotent mutation with no output schema, the description omits what an agent most needs: what happens on a repeat call (non-idempotent), whether an existing tag is added to or replaces prior tags, and whether the tag must already exist. Risk and confirm are covered, but the operational behavior is not.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so subscriber_id, tag_id, account and confirm are all already documented in the schema, including the confirm semantics. The description adds no parameter meaning beyond repeating the confirm requirement, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb+resource ("Tag a subscriber"), so the operation is immediately identifiable. However, it does not distinguish itself from the sibling tag_subscriber (email-based variant) or bulk_tag_subscribers, even though the "_by_id" suffix and subscriber_id parameter are the only differentiators.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
States the hard prerequisite "Requires confirm=true", which is genuinely useful usage information. But there is no guidance on when to choose this over tag_subscriber, bulk_tag_subscribers, or untag_subscriber, nor any warning about repeated calls.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Unsubscribe subscriber. May affect delivery, audience membership, published data or irreversible state. Requires confirm=true.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| confirm | No | Must be true for audience/delivery changes, publishing, destructive operations and signing-secret changes. Use only for an action requested by the user. | |
| subscriber_id | Yes | Positive subscriber id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true. The description adds value beyond them by warning that the operation 'may affect delivery, audience membership, published data or irreversible state' – concrete downstream consequences an agent needs before acting – plus the confirm precondition.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences with the action, impact warning, and precondition front-loaded in that order. No filler and nothing that could be trimmed without losing meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a three-parameter mutation with no output schema, the description covers the action, its side effects, and the confirm gate, and the schema covers parameter detail. It stops short of stating reversibility or the expected result, but nothing critical to a correct call is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents account, confirm, and subscriber_id thoroughly, including the confirm semantics. The description's only parameter note ('Requires confirm=true') restates what the schema's confirm field says, adding no new format or constraint detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Unsubscribe) and resource (subscriber) in the first two words, so the core action is unambiguous. It does not, however, distinguish itself from nearby siblings like delete_subscriber, update_subscriber, or untag_subscriber, which an agent must infer.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives one hard precondition ('Requires confirm=true'), which is real usage guidance, but says nothing about when to choose unsubscribe over delete_subscriber or other subscriber-mutating siblings. Usage is implied by the name rather than explained.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove tag from subscriber. May affect delivery, audience membership, published data or irreversible state. Requires confirm=true.
| Name | Required | Description | Default |
|---|---|---|---|
| tag_id | Yes | Positive tag id. | |
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| confirm | No | Must be true for audience/delivery changes, publishing, destructive operations and signing-secret changes. Use only for an action requested by the user. | |
| subscriber_id | Yes | Positive subscriber id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered structurally. The description's second sentence restates a generic destructive-action warning ("delivery, audience membership, published data or irreversible state") that is boilerplate rather than specific to untagging, and the confirm requirement it highlights is already documented in the schema's confirm property.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no filler, and the action plus its precondition are front-loaded. The second sentence is somewhat generic but does not bloat the definition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-required-parameter mutation with full schema coverage and annotations carrying the destructive/idempotency profile, the description is nearly complete. It lacks sibling disambiguation (by-id vs by-email) but needs no return-value explanation since there is no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so subscriber_id, tag_id, account and confirm are all documented in the schema itself. The description adds only the confirm=true requirement, which duplicates the confirm parameter's own description, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ("Remove tag from subscriber") that an agent can map directly to an action. However, it does not distinguish itself from the near-identical sibling untag_subscriber_by_email or bulk_remove_tags_from_subscribers, leaving the agent to infer the by-id scope from the name alone.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Requires confirm=true" is a useful precondition, but there is no explicit when-to-use guidance and no mention of the obvious alternatives (untag_subscriber_by_email for email addressing, bulk_remove_tags_from_subscribers for multi-target removals). Usage must be inferred from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove tag from subscriber by email address. May affect delivery, audience membership, published data or irreversible state. Requires confirm=true.
| Name | Required | Description | Default |
|---|---|---|---|
| tag_id | Yes | Positive tag id. | |
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| confirm | No | Must be true for audience/delivery changes, publishing, destructive operations and signing-secret changes. Use only for an action requested by the user. | |
| email_address | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the agent knows this is a write operation. The description adds valuable context beyond annotations: it explicitly warns that the action 'May affect delivery, audience membership, published data or irreversible state' and states 'Requires confirm=true.' This clarifies downstream effects and a required parameter not obvious from annotations alone. The description stops short of naming what exactly is irreversible or the scope of the audience impact, hence not a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the action and resource, followed by critical behavioral warnings and a required parameter. Every clause earns its place; no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's destructive nature, the description adequately warns of the impact and the confirm requirement. However, it does not specify the return value (no output schema exists) or the exact scenarios where the irreversible state occurs. It is nearly complete for a destructive action tool but leaves minor gaps in outcome description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 75%, with descriptions for tag_id, account, and confirm. The description adds explicit meaning for the confirm parameter ('Requires confirm=true') and reinforces that removal affects delivery and audience membership, which ties to the tag_id's role. The account parameter remains undocumented in the description, but the schema already covers it. The description adds moderate value over the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Remove') and resource ('tag from subscriber'), and scopes the lookup key as 'by email address'. This distinguishes it from the sibling 'untag_subscriber', which evidently uses a different identifier. An agent can tell exactly which tool performs this operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description names the required key (email address) and notes the confirm requirement, which is implicit usage guidance. However, it does not clarify when to use this tool versus 'untag_subscriber' or 'bulk_remove_tags_from_subscribers'. The sibling set includes several untagging tools, and the description provides no explicit routing guidance between them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a broadcast. May affect delivery, audience membership, published data or irreversible state. Requires confirm=true.
| Name | Required | Description | Default |
|---|---|---|---|
| public | No | `true` to publish this broadcast to the web. The broadcast will appear in a newsletter feed on your Creator Profile and Landing Pages. | |
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| confirm | No | Must be true for audience/delivery changes, publishing, destructive operations and signing-secret changes. Use only for an action requested by the user. | |
| content | No | The HTML content of the email. On a `Classic` template this is the body, and the template adds the design around it when the broadcast is sent. On a `Starting point` template the design lives in the body, so this is the complete email: keep the wrappers, images, inline styles and Liquid tags, including `{{ unsubscribe_url }}` and `{{ address }}`. Without an unsubscribe link the broadcast can't be sent. A read returns the string that was written, so `GET`, `PUT`, `GET` round-trips, apart from Kit's own "Built with Kit" badge, which a `Starting point` write takes out of the body and re-applies when the email renders. A broadcast built in Kit's editor reads back as Kit's rendered HTML instead, and writing that back replaces its individually-editable blocks with one HTML block. Sending `content` in the same request as a `Starting point` `email_template_id` also needs `allow_starting_point: true`. | |
| payload | No | Complete JSON body instead of individual body flags. Supports nullable fields and nested bulk structures. Cannot be combined with body flags or payload_file. | |
| send_at | No | The scheduled send time for this broadcast in ISO8601 format. If no timezone is provided, UTC is assumed. | |
| subject | No | ||
| description | No | ||
| broadcast_id | Yes | Positive broadcast id. | |
| payload_file | No | Local JSON request body file, at most 5 MB. Contents are validated before the API call and are never logged. | |
| preview_text | No | ||
| published_at | No | The published timestamp to display in ISO8601 format. If no timezone is provided, UTC is assumed. | |
| email_address | No | The sending email address to use. Uses the account's sending email address if not provided. | |
| thumbnail_alt | No | ||
| thumbnail_url | No | ||
| email_template_id | No | Id of the email template to use. Uses the account's default template if not provided. 'Starting point' template is not supported. | |
| subscriber_filter | No | Filters your subscribers. At this time, we only support using only one filter group type via the API (e.g. `all`, `any`, or `none` but no combinations). If nothing is provided, will default to all of your subscribers. | |
| allow_starting_point | No | Explicitly allow replacing a Starting point template body, as described in Kit’s current content-field documentation. Review the complete rendered HTML first. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is partly carried structurally. The description goes beyond them by disclosing specific consequences (affecting delivery, audience membership, published data, irreversible state) and the confirm=true gate, which is real added context an agent needs before invoking.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences, no filler. The high-impact warning and the confirm requirement are front-loaded, and every clause carries weight.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 18-parameter destructive tool with nested objects and no output schema, the description covers the essential safety gate but says nothing about the payload vs. body-flag exclusivity, allow_starting_point coupling, or content round-trip caveats that live only in the schema. It is adequate but leaves meaningful complexity unaddressed above the schema level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 72%, so the schema does most of the heavy lifting and documents confirm in detail. The description's only parameter-level contribution is reiterating "Requires confirm=true," which is already stated in the schema. With high-ish coverage and nested structures this is baseline-appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a clear verb+resource ("Update a broadcast") and usefully enumerates the domains the change can touch (delivery, audience membership, published data, irreversible state). It does not explicitly differentiate from siblings like create_broadcast or delete_broadcast, but the scope clause helps disambiguate this as a mutation of an existing broadcast.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when the tool is appropriate by flagging the high-blast-radius nature and the confirm=true requirement, but it never names an alternative sibling or states explicit when-not conditions. Usage is inferable rather than spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update colors. Changes account configuration.
| Name | Required | Description | Default |
|---|---|---|---|
| colors | No | An array of up to 10 color hex codes | |
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| confirm | No | Must be true for audience/delivery changes, publishing, destructive operations and signing-secret changes. Use only for an action requested by the user. | |
| payload | No | Complete JSON body instead of individual body flags. Supports nullable fields and nested bulk structures. Cannot be combined with body flags or payload_file. | |
| payload_file | No | Local JSON request body file, at most 5 MB. Contents are validated before the API call and are never logged. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=true, so the write semantics are covered. The description adds only "Changes account configuration," which is marginal and omits the account-wide blast radius, reversibility, and the confirm requirement for delivery/audience changes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It is short and front-loaded, but the second sentence ("Changes account configuration") is low-value filler that consumes the space where a scope or confirmation note should be.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with nested payload support and a confirmation gate, two vague sentences are not enough. It omits that changes are account-level, that confirm may be required, and how payload/payload_file interact with the body flags.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents colors, account, confirm, payload and payload_file thoroughly. The description adds nothing about parameters, but the baseline of 3 applies when the schema carries the semantic load.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
"Update colors" simply restates the tool name and title; the only added content is "Changes account configuration," which is broad and vague. It does not distinguish this from the sibling list_colors or explain what scope of configuration is affected.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use, when-not-to-use, or alternative guidance. An agent gets no signal on why it would call update_colors instead of list_colors or update_broadcast, and no prerequisites or confirmation workflow are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a custom field. Changes account configuration.
| Name | Required | Description | Default |
|---|---|---|---|
| label | No | ||
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| confirm | No | Must be true for audience/delivery changes, publishing, destructive operations and signing-secret changes. Use only for an action requested by the user. | |
| payload | No | Complete JSON body instead of individual body flags. Supports nullable fields and nested bulk structures. Cannot be combined with body flags or payload_file. | |
| payload_file | No | Local JSON request body file, at most 5 MB. Contents are validated before the API call and are never logged. | |
| custom_field_id | Yes | Positive custom field id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true. The description adds only the vague 'Changes account configuration' and omits that confirm=true may be required for certain changes (as the schema hints) and that non-idempotent updates are not safely retryable — context that matters for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Very short and front-loaded, which is good, but the second sentence ('Changes account configuration') is vague filler that does not earn its place — it neither specifies the resource affected nor the effect.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Six parameters including a nested payload object, no output schema, and a mutation that can require confirmation. The description says nothing about the confirm requirement, the payload-vs-body-flags exclusivity, or effect scope, leaving substantial gaps for a non-trivial mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 83%, above the 80% threshold, so the schema already documents account, confirm, payload, payload_file, and custom_field_id. The description adds nothing about parameters, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a clear verb+resource ('Update a custom field'), which cleanly separates it from create_custom_field, delete_custom_field, and bulk_create_custom_fields in the sibling list. The second sentence, 'Changes account configuration,' is vague and adds no real specificity about what updating entails.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No indication of when to use this versus create_custom_field, bulk_update_subscriber_custom_field_values, or the payload/payload_file alternatives. No prerequisites or preconditions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a sequence. May affect delivery, audience membership, published data or irreversible state. Requires confirm=true.
| Name | Required | Description | Default |
|---|---|---|---|
| hold | No | When `true`, subscribers added via Visual Automations stay in the sequence after receiving the last email. | |
| name | No | The name of the sequence. | |
| active | No | `true` to activate the sequence, `false` to deactivate it. | |
| repeat | No | When `true`, subscribers can restart the sequence multiple times. | |
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| confirm | No | Must be true for audience/delivery changes, publishing, destructive operations and signing-secret changes. Use only for an action requested by the user. | |
| payload | No | Complete JSON body instead of individual body flags. Supports nullable fields and nested bulk structures. Cannot be combined with body flags or payload_file. | |
| send_days | No | The days of the week to send the sequence on. Must be one of: `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, `sunday`. | |
| send_hour | No | The hour of the day to send the sequence at. Must be an integer between 0 and 23. | |
| time_zone | No | The timezone to use for the sequence. Must be a valid IANA timezone string. | |
| sequence_id | Yes | Positive sequence id. | |
| payload_file | No | Local JSON request body file, at most 5 MB. Contents are validated before the API call and are never logged. | |
| email_address | No | The sending email address to use. Uses the account's sending email address if not provided. | |
| email_template_id | No | Id of the email template to use. | |
| exclude_subscriber_sources | No | The subscriber sources to exclude from the sequence. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds genuinely new context: the blast radius ('delivery, audience membership, published data or irreversible state') and the hard requirement for confirm=true. This helps the agent understand the consequences beyond the safety flags, though it stops short of describing reversibility details or failure modes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with the purpose front-loaded and the impact plus the confirm requirement following. No filler and every clause carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 15-parameter, destructive mutation tool with no output schema, the description covers purpose, impact scope and the confirm gate, and annotations plus the richly documented schema fill in the rest. It is largely complete, though it does not mention the payload vs. body-flags mutual exclusivity or note that the call is non-idempotent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all 15 parameters are already documented in the schema, making the baseline 3. The description adds only the confirm=true requirement, which is already present in the schema's confirm parameter description, so there is little net semantic gain.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
'Update a sequence' states a specific verb and resource, immediately distinguishing it from siblings like get_sequence, create_sequence, delete_sequence and list_sequences. It does not however explicitly name an alternative or clarify scope of what 'update' covers beyond the impact note.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description supplies a precondition ('Requires confirm=true.') that frames how to invoke it, and the impact list signals caution. But it gives no explicit when-to-use versus alternatives and no statement of who should call it, leaving usage largely implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a sequence email. May affect delivery, audience membership, published data or irreversible state. Requires confirm=true.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| confirm | No | Must be true for audience/delivery changes, publishing, destructive operations and signing-secret changes. Use only for an action requested by the user. | |
| content | No | New HTML body content of the email | |
| payload | No | Complete JSON body instead of individual body flags. Supports nullable fields and nested bulk structures. Cannot be combined with body flags or payload_file. | |
| subject | No | New subject line for the email | |
| email_id | Yes | Positive email id. | |
| position | No | New zero-based position of the email in the sequence | |
| published | No | Pass `true` to publish a draft email or `false` to unpublish it | |
| send_days | No | Days of the week this email may be sent. Pass a subset to restrict delivery, or `null` to reset to all days (inherits the sequence schedule) | |
| delay_unit | No | New delay unit. Use `days` for schedule-aware delivery, `hours` for a fixed hourly delay | |
| delay_value | No | New delay value | |
| sequence_id | Yes | Positive sequence id. | |
| payload_file | No | Local JSON request body file, at most 5 MB. Contents are validated before the API call and are never logged. | |
| preview_text | No | New preview text shown in email clients before the email is opened | |
| email_template_id | No | New email template ID for layout and styling. Pass `null` to clear |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true. The description adds real value on top: it names the affected domains (delivery, audience membership, published data) and flags irreversible state, plus the confirm gate. This is meaningful context the annotations alone do not convey, though the phrasing 'may affect' stays somewhat vague.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the action and immediately followed by the risk/gate information. Every clause is useful; the only minor cost is the list-like enumeration of affected areas, which is slightly generic.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 15-parameter destructive mutation with a nested payload object and no output schema, the description covers the risk profile and the confirm gate but says nothing about the mutually exclusive input forms (payload vs individual body flags vs payload_file) or account selection. The schema covers these, so the gap is not fatal, but a routing sentence would have completed the picture.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 15 parameters, including the nested payload object and payload_file exclusivity. The description only restates the confirm requirement and adds no syntax or interaction detail beyond the schema, which is the correct baseline when the schema carries the load.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource (update a sequence email), which cleanly separates it from sibling tools like update_sequence or update_broadcast. It is clear but does not explicitly call out what distinguishes it from those near-neighbours beyond the resource name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Requires confirm=true' gives a concrete precondition for invocation, and the risk sentence implies caution before mutating. However, there is no guidance on when this tool is preferable to alternatives (e.g. update_sequence for schedule changes), nor any statement of what must be true before calling it for a given field.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a snippet. May affect delivery, audience membership, published data or irreversible state. Requires confirm=true.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| confirm | No | Must be true for audience/delivery changes, publishing, destructive operations and signing-secret changes. Use only for an action requested by the user. | |
| snippet_id | Yes | Positive snippet id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, idempotentHint=false and readOnlyHint=false, so the safety profile is partly covered. The description still adds real value beyond them by spelling out the blast radius: delivery, audience membership, published data, or irreversible state, plus the confirm gate. It stops short of saying what specifically gets altered or whether the change is reversible.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences that are front-loaded with the action, then risk, then the gating requirement. Every sentence carries a distinct piece of information and there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive, non-idempotent mutation with no output schema or body-field parameters, the description covers risk and the confirm requirement, which is the essential part. It leaves a real gap, though: with only snippet_id/account/confirm in the schema, it is never explained what state change is actually applied to the snippet.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents account, confirm, and snippet_id, and the description's mention of confirm=true merely repeats the schema. It adds no syntax, format, or defaulting detail beyond what the structured fields provide, which is the expected baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("Update a snippet") that any agent can map to a concrete operation, and the sibling set contains obvious counterparts (get_snippet, create_snippet, list_snippets). However, it does not differentiate itself from those siblings or say what aspect of a snippet is being updated, so the agent must infer this is the mutation counterpart of get_snippet.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a conditional requirement ("Requires confirm=true") tied to risky effects, which is useful usage information. But it offers no when-to-use framing versus alternatives, no prerequisites, and no indication of which changes are safe versus which need confirmation beyond a general warning.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a subscriber. May affect delivery, audience membership, published data or irreversible state. Requires confirm=true.
| Name | Required | Description | Default |
|---|---|---|---|
| fields | No | Custom field values keyed by the custom field's `key` (e.g. `last_name`, not `Last Name`). Unknown keys are ignored and reported in the response `warnings` array. | |
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| confirm | No | Must be true for audience/delivery changes, publishing, destructive operations and signing-secret changes. Use only for an action requested by the user. | |
| payload | No | Complete JSON body instead of individual body flags. Supports nullable fields and nested bulk structures. Cannot be combined with body flags or payload_file. | |
| first_name | No | ||
| payload_file | No | Local JSON request body file, at most 5 MB. Contents are validated before the API call and are never logged. | |
| email_address | No | ||
| subscriber_id | Yes | Positive subscriber id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare destructiveHint=true and idempotentHint=false, and the description adds value beyond that: it warns that delivery, audience membership, published data, and irreversible state may be affected. That's a meaningful behavioral disclosure. It stops short of naming what exactly is irreversible or how failures are handled.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, followed immediately by impact and requirement. No waste, very high signal density.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex mutation tool with nested objects and no output schema, it gives the essential impact and confirmation requirements. It omits the mutually exclusive relationship between payload and body flags, and doesn't reference warnings handling, but is otherwise sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 75%, so the schema already carries most parameter meaning. The description adds the crucial semantics that confirm=true is required and must be user-requested, which the schema also states but the description reinforces. It doesn't explain the interaction between payload, payload_file, and body flags, which is a notable gap for 8 params.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a clear verb+resource ('Update a subscriber'), enough to distinguish from get_subscriber, create_subscriber, delete_broadcast, etc. But it doesn't distinguish from sibling update tools like bulk_update_subscriber_custom_field_values or update_subscriber_location, which is a real ambiguity given many subscriber-related updaters exist.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Clearly states that confirm=true is required, which is when-to-use guidance. It implies this is a mutating tool. But it doesn't say when to prefer bulk_update_subscriber_custom_field_values or other subscriber-update siblings, so context is clear but alternatives aren't named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a subscriber's pinned location. May affect delivery, audience membership, published data or irreversible state. Requires confirm=true.
| Name | Required | Description | Default |
|---|---|---|---|
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| confirm | No | Must be true for audience/delivery changes, publishing, destructive operations and signing-secret changes. Use only for an action requested by the user. | |
| payload | No | Complete JSON body instead of individual body flags. Supports nullable fields and nested bulk structures. Cannot be combined with body flags or payload_file. | |
| location | No | ||
| payload_file | No | Local JSON request body file, at most 5 MB. Contents are validated before the API call and are never logged. | |
| subscriber_id | Yes | Positive subscriber id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already carry destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is largely covered. The description still adds real value by naming the blast radius ('may affect delivery, audience membership, published data or irreversible state') and the confirm gate, going beyond what the structured fields say.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences, zero filler, with the impactful mutation-risk and confirm-requirement information placed immediately after the purpose statement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive, 6-parameter mutation tool with no output schema, the description covers purpose, risk, and the confirm gate, which is most of what an agent needs. It stops short of explaining how the nested location parameters or payload/payload_file alternatives interact, though the schema handles that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 83%, so the schema already documents confirm, payload, payload_file, and subscriber_id. The description reinforces the confirm requirement but adds no syntax, format, or exclusivity detail beyond the schema (e.g. payload vs body flags).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Update a subscriber's pinned location'), which is clearly distinct from siblings like get_subscriber or update_subscriber. However, it does not differentiate itself from the close sibling pin_subscriber_location, leaving the agent to infer the boundary between the two.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description supplies a trigger condition ('Requires confirm=true') but never states when to choose this over pin_subscriber_location or delete_subscriber_location. Usage is implied rather than explicit, and no prerequisites beyond confirm are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update tag name. Changes account configuration.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| tag_id | Yes | Positive tag id. | |
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| confirm | No | Must be true for audience/delivery changes, publishing, destructive operations and signing-secret changes. Use only for an action requested by the user. | |
| payload | No | Complete JSON body instead of individual body flags. Supports nullable fields and nested bulk structures. Cannot be combined with body flags or payload_file. | |
| payload_file | No | Local JSON request body file, at most 5 MB. Contents are validated before the API call and are never logged. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false. The description adds no behavioral context beyond a vague 'Changes account configuration' statement. It does not explain side effects, permissions, or what the confirmation flag does, leaving significant gaps for an agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short—two brief sentences. While it is front-loaded with the core action, the second sentence is a vague generalization that does not clearly earn its place and may confuse rather than clarify.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with six parameters, no output schema, and nested objects like payload, the description is far too sparse. It fails to explain the purpose of confirmation flags, the meaning of 'account configuration', or the relationship between the name parameter and payload. An agent would struggle to invoke this correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 83%, so the schema largely documents parameters like tag_id, account, confirm, payload, and payload_file. The description adds no parameter semantics beyond what the schema provides, but the high coverage establishes a baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Update tag name', which is a clear verb+resource matching the tool name. However, it offers no differentiation from sibling tag tools like create_tag or bulk_create_tags, and the vague addendum 'Changes account configuration' arguably contradicts the narrow purpose of renaming a tag.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, no differentiation from sibling tools, and no information about when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a webhook endpoint. May affect delivery, audience membership, published data or irreversible state. Requires confirm=true. Webhook response secrets are redacted; new signing secrets are saved only to a private local file.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | ||
| name | No | ||
| events | No | Event types this endpoint subscribes to (e.g. `subscriber.created`). On update, the list supplied here replaces the endpoint's full subscription list. | |
| status | No | Endpoint status. One of: `active`, `disabled`. | |
| account | No | Named private account from KIT_ACCOUNTS. Defaults to KIT_DEFAULT_ACCOUNT or the first configured account. | |
| confirm | No | Must be true for audience/delivery changes, publishing, destructive operations and signing-secret changes. Use only for an action requested by the user. | |
| payload | No | Complete JSON body instead of individual body flags. Supports nullable fields and nested bulk structures. Cannot be combined with body flags or payload_file. | |
| description | No | ||
| payload_file | No | Local JSON request body file, at most 5 MB. Contents are validated before the API call and are never logged. | |
| webhook_endpoint_id | Yes | Positive webhook endpoint id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is partly covered. The description adds real value beyond that: the confirm=true gate, the scope of possible impact (delivery, audience membership, published data, irreversible state), and the secret-handling behavior (responses redacted, new signing secrets written only to a private local file).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the verb+resource and immediately followed by the highest-risk consequences and the confirm requirement. No filler or repetition, though the secret sentences could be tightened slightly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive, non-idempotent mutation with annotations and no output schema, the description covers the required confirm flag, the blast radius of the change, and secret handling. It is nearly complete, with the only gap being explicit routing against the secret-rotation siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 70%, so the schema already documents the notable parameters (events replacement semantics, status enum, confirm, payload_file). The description reinforces the confirm requirement but adds little syntactic or format meaning beyond what the schema provides, making the 3 baseline appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Update') and resource ('a webhook endpoint'), so the agent knows exactly what operation this performs. It does not, however, distinguish itself from closely related siblings like rotate_webhook_secret or revoke_previous_webhook_secret, which also mutate the signing-secret side of an endpoint.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description supplies an actionable precondition ('Requires confirm=true') and warns that the operation may affect delivery, audience membership, and published data. It stops short of saying when to choose this tool versus rotate_webhook_secret or create_webhook_endpoint, leaving usage largely implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v2.0.1add_subscriber_to_formadd_subscriber_to_form_by_idadd_subscriber_to_sequenceadd_subscriber_to_sequence_by_idbulk_add_subscribers_to_formsbulk_create_custom_fieldsbulk_create_subscribersbulk_create_tagsbulk_delete_tagsbulk_remove_tags_from_subscribersbulk_tag_subscribersbulk_update_subscriber_custom_field_valuescreate_broadcastcreate_custom_fieldcreate_purchasecreate_sequencecreate_sequence_emailcreate_snippetcreate_subscribercreate_tagcreate_webhookcreate_webhook_endpointdelete_broadcastdelete_custom_fielddelete_sequencedelete_sequence_emaildelete_subscriber_locationdelete_webhookdelete_webhook_endpointfilter_subscribersget_accountget_broadcastget_broadcast_clicksget_broadcast_statsget_creator_profileget_email_statsget_growth_statsget_postget_purchaseget_sequenceget_sequence_emailget_snippetget_subscriberget_subscriber_statsget_webhook_endpointlist_accountslist_broadcast_statslist_broadcastslist_colorslist_custom_fieldslist_email_templateslist_formslist_postslist_purchaseslist_segmentslist_sequence_emailslist_sequenceslist_snippetslist_subscriber_tagslist_subscriberslist_subscribers_for_formlist_subscribers_for_sequencelist_subscribers_for_taglist_tagslist_webhook_endpointslist_webhookspin_subscriber_locationrevoke_previous_webhook_secretrotate_webhook_secretsearch_subscriberstag_subscribertag_subscriber_by_idunsubscribeuntag_subscriberuntag_subscriber_by_emailupdate_broadcastupdate_colorsupdate_custom_fieldupdate_sequenceupdate_sequence_emailupdate_snippetupdate_subscriberupdate_subscriber_locationupdate_tag_nameupdate_webhook_endpointScored across 85 tools
Many tools exist in near-duplicate pairs that an agent will struggle to distinguish: list_webhooks vs list_webhook_endpoints, create_webhook vs create_webhook_endpoint, tag_subscriber vs tag_subscriber_by_id, untag_subscriber vs untag_subscriber_by_email, add_subscriber_to_form vs add_subscriber_to_form_by_id, and add_subscriber_to_sequence vs add_subscriber_to_sequence_by_id. search_subscribers is explicitly a compatibility alias for list_subscribers, further muddying selection.
The set overwhelmingly follows a predictable snake_case verb_noun convention (list_, get_, create_, update_, delete_, bulk_). Minor deviations exist (bare 'unsubscribe', odd 'update_tag_name'), and the _by_id/_by_email variants add noise, but the pattern is largely readable and consistent.
85 tools is far beyond what the domain needs and well into extreme-mismatch territory. The count is inflated by redundant webhook/webhook_endpoint pairs and name-vs-ID duplicates that could be consolidated, making the surface overwhelming and hard to navigate.
Coverage is broad and mostly full-lifecycle across broadcasts, subscribers, tags, sequences, snippets, forms, custom fields, purchases, and webhooks, with bulk and stats operations included. Some resources are read-only (segments, posts) and lack update/delete, which are minor gaps given the core workflows are covered.
Read audiences, members, campaigns and reports; add, update, tag and archive subscribers.
Read subscribers, groups, campaigns, fields, segments, automations, webhooks; safe additive writes.
Manage MailSenpai email marketing: lists, subscribers, templates and campaigns (EU, OAuth).
Manage a Mailcheer email workspace: subscribers, segments, campaigns, transactional sends and stats.
