Sarbacane MCP by usefulapi

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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false; the description adds that the effect is permanent within these tools and that it suppresses future campaign sends, which the annotations do not convey. The additive-blacklist semantics are consistent with destructiveHint=false rather than contradicting it.

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: the operation type is front-loaded in a 'WRITE:' prefix, followed by effect, durability warning, and endpoint. 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 3-parameter mutation with annotations but no output schema, the description covers what it does, permanence, and side effects on campaigns. It leaves unspecified what happens if both email and phone are omitted and what the response contains, minor gaps given the tool's simplicity.

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% (only blacklist_id is documented), but the description compensates by explaining that 'email and/or phone' are the identifying values — implying at least one is required while neither is schema-required. That is real meaning beyond the schema, though it does not specify precedence when both are supplied.

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 ('record an email and/or phone as unsubscribed in a blacklist'), names the downstream effect ('campaigns using that blacklist skip it'), and gives the endpoint. It is clearly distinguishable from siblings like sarbacane_list_blacklist_entries and sarbacane_upsert_contact.

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 leading 'WRITE:' tag plus the unsubscribe framing gives a clear condition for use, and 'Cannot be undone with these tools' signals the caution needed before calling. It does not explicitly name an alternative (e.g. listing existing entries first) or state when not to use it, so it stops short of 5.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, so the safety/write profile is covered. The description reinforces this with "WRITE" and "Adds a new record" and adds the sibling routing. However, it never says whether adding a duplicate email fails, creates a second record, or is silently merged — the single most important behavioral question for a non-idempotent create.

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 WRITE marker, then the input requirement, then the sibling routing, then the endpoint. Nothing is redundant with the title and no sentence 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?

There is no output schema, so the description is the only place a caller could learn what a successful add returns (new contact id? echo of fields?), and it is silent on that. For a 4-parameter write with a nested fields object, the input side is adequately covered but the outcome side 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 coverage is only 50%, and the description fills the critical gap by stating that email, phone, or both may be supplied — this explains why neither is required in the schema. It also flags fields as optional custom values and points to sarbacane_list_list_fields for ids. It does not restate email/phone formats, but the patterns already cover those.

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 ("add a contact to a contact list") and even the underlying endpoint POST /v1/lists/{listId}/contacts. It explicitly distinguishes itself from sarbacane_upsert_contact, so an agent can pick between the two without opening a schema.

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

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

Names the alternative explicitly ("use sarbacane_upsert_contact to update an existing contact"), which is the main routing decision here. It also states the minimum input requirement (email, phone, or both). It stops short of saying what happens when the contact already exists, which is the remaining ambiguity in when-to-use.

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

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

Annotations already declare write/non-destructive/open-world, but the description adds substantive context beyond them: the object is created as an unsent draft, nothing in this toolset will dispatch it, and the underlying endpoint is POST /v1/campaigns/email. It stops short of covering duplicate-creation risk on retry or what happens if a referenced sender is not allowed on the account.

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, no filler, with the WRITE marker and draft status front-loaded before the workflow chain. Every clause carries information an agent needs.

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 with annotations but no output schema, the description covers the create-and-populate workflow well. The one gap is that the return value is never characterized, yet the follow-up tools presumably need the new campaign's identifier — an agent is left to infer that it receives an ID back.

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 every field (name, subject, preheader, from/reply aliases and addresses) is documented inline in the schema. The description adds no parameter-level detail such as sender verification requirements or default handling of the optional preheader, 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?

Opens with a specific verb+resource+mode: "WRITE: create a new email campaign as a DRAFT." This clearly separates it from siblings that mutate an existing campaign (sarbacane_set_campaign_content, sarbacane_set_campaign_list) and from read tools like sarbacane_get_campaign.

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?

Explicitly states the lifecycle constraint ("It is never sent by these tools") and names the exact follow-up tools needed to make the draft usable, plus the escape hatch (send it from Sarbacane). An agent knows both when to call this and what to do next.

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

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

Annotations already declare readOnlyHint=true, non-destructive, open-world, so safety is covered. The description adds real value beyond that by naming the endpoint (GET /v1/campaigns/{campaignId}) and listing the returned fields, which matters because no output schema exists.

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 returned-field summary front-loaded. The telegraphic fragment style is efficient but slightly sacrifices readability (e.g., 'send ids' is unexplained).

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 one-parameter read tool with annotations and no output schema, the description covers what is fetched and roughly what comes back. Only minor gaps remain, such as error/not-found behavior and any permission requirements.

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 one parameter and schema coverage is 100%, so the schema already documents campaign_id with type, pattern, and length bounds. The description conveys nothing extra about the id format or source (path parameter in the endpoint string is the sole addition).

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 resource (one campaign) and enumerates what it returns: state, kind, blacklists, send ids, sent date. 'One campaign' implicitly distinguishes it from list_campaigns and get_campaign_report, though no sibling is named.

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?

Usage is only implied — retrieve a single campaign by id. The note 'The send id is needed to see content' is a useful downstream dependency hint pointing at content-related siblings, but there is no explicit when-to-use / when-not guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds the REST endpoint (GET /v1/reports/{campaignId}) and the returned metric set, but says nothing about behavior for unsent campaigns, empty results, or rate limits.

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 compact sentence front-loads the resource and then enumerates the payload metrics, with the endpoint appended as a trailing reference. No filler or repetition.

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 present, the description carries the burden of describing return values, and it does so by listing the metric categories per send. What is missing is only secondary: result shape granularity (e.g., per-send breakdown structure) and error/empty-case behavior.

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 only one parameter and schema description coverage is 100%, so the schema fully documents campaign_id including its pattern and length bounds. The description adds a small amount of meaning via 'per send', implying the id must reference a campaign that has already been sent, but no additional syntax or sourcing 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?

Names a specific verb+resource ('statistics of a campaign') and enumerates the exact metrics returned (delivered, opens, openers, clicks, clickers, unsubscribers, devices, OS), which clearly separates it from sarbacane_get_campaign (campaign metadata) and sarbacane_list_campaign_recipients. It stops short of explicitly naming those siblings, so differentiation relies on the agent inferring 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?

The 'per send' phrasing implies this is for post-send performance analysis, but there is no explicit statement of when to use this versus sarbacane_get_campaign or the recipient-list tools, and no note about the campaign needing to have been sent. Usage is inferable but not stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description goes further by disclosing what the response contains (per-type credit amounts, expiry date, subscription type), which matters because there is no output schema. Auth scope or rate-limit behavior is not mentioned, keeping it just short of 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, zero padding: the return contents come first and the underlying endpoint path is a compact trailing detail. Every clause carries information an agent can use.

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-parameter read with no output schema and full annotation coverage, the description supplies exactly the missing piece: what fields come back (per-type credits, expiry, subscription type). Nothing needed to invoke it correctly is absent.

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 the baseline is 4; the schema has nothing for the description to clarify. The description appropriately spends its words on the return shape instead of inventing parameter 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?

The description names the specific resource (the account's remaining credits) and enumerates the credit types returned (email campaigns, SMS, eye tracking, Sendkit emails). No sibling tool deals with credits, so an agent can distinguish this from the campaign/contact tools without opening a schema.

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

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

There is no explicit 'use when...' statement or mention of alternatives; usage is implied by the resource name (checking quota/balance). Because no sibling tool competes for this purpose, the implied guidance is enough to avoid mis-selection, but nothing actively routes the agent.

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

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

Annotations already flag destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description does add that existing content is replaced and supplies the underlying endpoint, which is useful, but it stays silent on constraints such as whether the campaign must already be a draft and whether the overwrite is recoverable.

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 clauses, front-loaded with the 'WRITE:' signal so an agent sees the mutation risk immediately. Nothing here is 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?

With no output schema and only two well-documented parameters, the description covers the essentials: mutation type, effect on existing content, and endpoint. The remaining gap is the precondition that the target campaign must be a draft, which is only hinted at in the title.

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 both required parameters (campaign_id, template_id) are fully documented in the schema, including id format constraints. The description adds no meaning beyond that, which is the expected baseline when the schema does 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?

States a specific verb and resource: load a saved template's content into a campaign, replacing existing content. It implicitly differentiates from sarbacane_set_campaign_content by framing the action as a template import, but it never names that sibling, so the distinction is left for the agent to 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 title mentions 'draft campaign' and the description implies this is the template-based route to setting content, but there is no explicit when-to-use/when-not guidance and no mention of the directly competing sibling sarbacane_set_campaign_content.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuine value by defining what each kind contains and flagging that unsubscriber/complaint entries carry personal data (email, phone), but says nothing about pagination behavior 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?

Three short, front-loaded sentences with no filler; the kind enumeration comes first and the raw endpoint path is appended for API traceability. Slight duplication between 'by kind' and the endpoint template, but nothing wasteful.

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, and the description never says what a result looks like or that the response is paginated (offset/next_offset, limit default 50). For an 8-parameter paginated list tool, that leaves an agent to infer return shape from the schema 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?

Schema coverage is 100%, so every parameter including limit, offset and the modified_after/before bounds is already documented in the schema. The description only echoes the filterable fields (email, phone, modification date) and omits limit/offset entirely, adding little beyond the structured data.

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 ('Entries of a blacklist') and enumerates the three kinds with short glosses, which distinguishes it from sarbacane_list_blacklists (which lists the blacklists themselves). It never names that sibling explicitly, so the differentiation is inferential 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 description implies retrieval and filtering ('Filter by email, phone or modification date') but gives no explicit when-to-use guidance or exclusions. The prerequisite that a blacklist_id must come from sarbacane_list_blacklists appears only in the schema parameter description, not here.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false plus openWorldHint=true, so safety and reach are covered. The description adds little beyond that — it doesn't mention that results are paginated or that the list may be empty, though it does indicate ids are included in the response.

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; the resource and payload come first and the endpoint is appended as a compact reference. Nothing redundant beyond the REST path, which is arguably useful for debugging.

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 carries more burden than it does — it names 'ids' but not the other fields returned (name, type, counts) or the pagination envelope shape, which matters for a list endpoint an agent will page through. Adequate but thin for a paginated listing 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%: both limit and offset are fully documented, including the next_offset instruction. The description contributes no additional parameter guidance, which is acceptable at this coverage level.

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 resource ('All blacklists (suppression lists) of the account') and what is returned ('with their ids'). The parenthetical clarifies the synonym, and the contrast with sibling sarbacane_list_blacklist_entries is inferable from 'blacklists' vs. entries, though not stated explicitly.

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?

Usage is only implied by the resource name; there is no statement of when to prefer this over sarbacane_list_blacklist_entries (to inspect the members of a blacklist) or any prerequisites. An agent must infer the routing from the sibling names alone.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description contributes one piece of added context — that the payload contains personal data (email, phone) — which is useful for handling sensitivity. It says nothing about volume, pagination behavior, or whether the list is exhaustive beyond what the schema states.

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 compact fragments with no filler; the core resource statement comes first and the endpoint path and data-sensitivity note follow. It is short without becoming a tautology, though the raw path adds little for an agent already given the 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?

With no output schema, the description carries more burden; it hints at the returned fields (email, phone) but does not describe the shape of the response or the pagination envelope that the offset/next_offset parameters imply. Adequate for a simple read, but an agent cannot fully anticipate the result.

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%: limit, offset and campaign_id are each documented, including constraints and the next_offset idiom. The description adds no parameter detail 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?

The description names a specific resource relationship: recipients attached to a campaign, backed by the endpoint GET /v1/campaigns/{campaignId}/recipients. An agent can tell it retrieves campaign recipients rather than campaign metadata or reports. It stops short of explicitly differentiating from siblings like sarbacane_get_campaign_report or sarbacane_list_contacts, but the resource 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 phrase 'attached to a campaign' implies you need a campaign id and that this is a per-campaign read, but there is no explicit when-to-use guidance or comparison to alternatives such as get_campaign_report for performance data or list_contacts for the full audience. Usage is inferable but not stated.

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

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

Annotations already declare readOnlyHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds substantive value by disclosing the shape of the result (which fields come back) in the absence of an output schema, plus the endpoint path. It doesn't mention pagination behavior or result ordering, which are typically documented in the 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 compact sentences: resource, filters, endpoint. Front-loaded and free of filler. Slightly terse – the endpoint fragment at the end carries little value for an agent that already knows 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?

No output schema exists, and the description compensates by naming the returned fields; pagination and ranges live in the schema, and safety lives in annotations. Complete enough to call correctly, with only ordering/pagination semantics left implicit.

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%: limit, state, offset and search are all documented with defaults, ranges, enums and even the next_offset guidance. The description only restates the two filter concepts without adding syntax or semantics, 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?

Opens with a specific resource ('Campaigns of the account') and enumerates the fields returned (id, name, kind, created/edited, recipient count), so the agent knows exactly what a call yields. It doesn't explicitly contrast with siblings like sarbacane_get_campaign or sarbacane_list_campaign_recipients, which keeps 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?

'Filter by state or a text in the name or subject' implies when the filters are useful, but there is no statement of when to prefer this over sarbacane_get_campaign (single campaign detail) or other list siblings. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description adds value by disclosing that results are personal data (email, phone, custom fields) and that the call maps to a GET endpoint, confirming a non-mutating server-side filter. It says nothing about pagination behavior or result volume limits, which the schema only hints at via next_offset.

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 with zero padding: resource and returned fields first, then the filter options, then the endpoint. Nothing is repeated from the schema and every sentence 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 an eight-parameter read with no output schema, the description usefully characterises the returned record shape and the available filters. The remaining gap is pagination and default result size, which the agent must infer from the offset/limit descriptions rather than from the tool 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 100%, so every one of the eight parameters is documented in the schema itself. The description only summarises the filter axes (email, phone, search, modified dates) without adding syntax, precedence, or combination rules, 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?

States a specific resource (contacts of one list) and what comes back (email, phone, custom fields), plus the underlying GET path, so it is clearly a filtered read of list membership rather than a write like sarbacane_create_contact. It does not explicitly distinguish itself from near-neighbours such as sarbacane_list_campaign_recipients or sarbacane_list_blacklist_entries, so sibling differentiation is left 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 filter dimensions (email, phone, text search, modification date) imply the lookup use cases, but there is no explicit when-to-use or when-not-to-use statement. Nothing tells the agent to call sarbacane_list_lists first to obtain list_id, or which sibling to prefer for recipient/blacklist lookups.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds real value beyond them: it discloses the exact return shape (id, caption, type with allowed values) despite no output schema existing, and cites the underlying endpoint GET /v1/lists/{listId}/fields. It stops short of mentioning pagination or empty-list 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?

A single front-loaded sentence plus endpoint reference, with every clause carrying information (return fields, type domain, write-key role). The telegraphic fragment style with no leading verb is efficient but marginally less readable than a full 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 single-parameter read tool the description covers the resource, the returned fields with their type domain, and the practical purpose of the ids, which compensates for the absent output schema. Missing only error/empty-state behavior and explicit sibling routing.

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 one parameter and 100% schema description coverage, the schema already documents list_id, its pattern, length bounds and even cross-references sarbacane_list_lists. The description adds nothing specific about list_id, 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 names the specific resource (custom fields/columns of a contact list) and enumerates the returned attributes (id, caption, type plus the type enum values), so an agent can tell it apart from sarbacane_list_lists or sarbacane_list_contacts at a glance. It lacks an explicit contrast sentence with those siblings, keeping it just 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?

'Field ids are the keys used when writing contacts' implicitly tells the agent to call this before create_contact/upsert_contact, which is genuine usage context. However, it never explicitly states when to use this versus alternatives (e.g. sarbacane_list_lists to obtain a list_id first) or any exclusions, so guidance remains inferred.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds only that results come with ids and the GET /v1/lists endpoint; it says nothing about pagination behavior despite default limit=50, which is the one behavioral trait an agent could trip over.

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. It is slightly terse: the word 'All' sits awkwardly beside a paginated endpoint that defaults to 50 items, so a qualifier would have earned 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?

No output schema exists, and the description does indicate the key return element (list ids), plus the endpoint for orientation. For a two-parameter, zero-required list tool with full annotation coverage, this is nearly sufficient; only pagination expectations are left unaddressed.

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% – both limit and offset are fully documented, including the useful 'Pass the previous reply's next_offset' hint. The description adds no parameter meaning beyond the schema, so baseline 3 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?

States a specific verb+resource ('All contact lists of the account, with their ids') and the underlying endpoint, which is enough to distinguish it from siblings like sarbacane_list_campaigns or sarbacane_list_contacts. It stops short of explicitly contrasting with those siblings, so it lands at 4 rather than 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?

'Use the ids for contacts, fields and campaigns' implies the follow-on workflow (fetch lists first, then drill into fields/contacts/campaigns), which is genuine usage guidance. But it never states when NOT to use this tool or names a specific alternative sibling, leaving routing to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds one genuinely useful behavioral detail: pending invitations are included alongside active users. It says nothing about result size, default of 50, or pagination flow, which are left to the 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?

Two short, front-loaded clauses with the resource and returned fields up front. The trailing 'GET /v1/users' is redundant implementation trivia but costs little.

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 tool with no output schema, the description supplies the most important missing piece — what each returned record contains and that invitations are mixed in. Pagination and filtering behavior are covered by the schema, so nothing essential is absent.

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 limit, offset and search are fully documented in the schema, including the next_offset pagination hint. The description contributes no additional parameter meaning, which is acceptable but adds no value beyond 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?

The description names the concrete resource — account users plus pending invitations — and lists the fields returned (name, email, role, team), which is more specific than the title alone. It is distinguishable from siblings like sarbacane_list_contacts or sarbacane_list_webhooks, though that separation comes from the resource name rather than any explicit contrast.

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 call this versus the many other list_* siblings, and no mention of prerequisites such as admin permissions needed to see account users. The endpoint string 'GET /v1/users' adds no usage context.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered without help from the description. The description adds only the underlying endpoint (GET /v1/webhooks), which hints at scope but says nothing about authentication, pagination, or volume of results — none of which is disclosed elsewhere since there is no output 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?

Two short clauses with no filler; the returned-field list is front-loaded before the endpoint reference. The tradeoff for that compactness is that the phrasing is a noun fragment rather than an explicit statement of the action.

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-parameter, read-only listing tool with annotations covering the safety profile, the description supplies enough: what the resource is and the shape of what comes back. Pagination and result-count behavior are the only meaningful omissions, and with no output schema those would have been worth one more sentence.

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 per the baseline this scores a 4; there is no parameter semantics to explain. The schema is an empty object with 100% description coverage, leaving nothing for the description to compensate for.

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 resource (webhook subscriptions of the account) and the fields returned (url, display name, subscribed event kinds), which distinguishes it cleanly from every sibling list_* tool (lists, users, contacts, campaigns, blacklists). The verb is only implied by the title rather than stated in the description, so it falls just short of a self-contained verb+resource statement.

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?

Usage is implied rather than stated: the agent can infer this is the read path for inspecting webhook configuration, and there is no sibling webhook tool that would create ambiguity. There is no explicit when-to-use framing, no prerequisites, and no mention of alternatives such as the campaign or list tools that might also be relevant to an integration task.

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

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

'replacing what was there' explicitly confirms the destructive overwrite that the destructiveHint annotation only implies, and the send-resolution rule (single send vs. multiple A/B sends) is real behavioral context not present in the annotations. It stops short of saying what happens on a non-draft campaign or whether prior content is recoverable.

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 with the write/mutation warning front-loaded, then the parameter rule, then the endpoint as trailing reference. 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 4-param destructive write with full schema coverage, rich annotations, and no output schema, this covers the essentials: mutability, overwrite semantics, and send targeting. The remaining gap is the draft-only precondition, which lives in the title rather than the 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 100%, so the baseline is 3; the description earns an extra point by explaining the semantics of send_id beyond the schema's terse 'Optional when the campaign has one send' — namely that A/B campaigns have several sends and you must pick one. html/text are left to their 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?

Opens with a specific verb+resource ('set the HTML (and optional plain-text) content of an email campaign's send') and adds the critical qualifier that it replaces existing content. It also distinguishes itself from read-side siblings like sarbacane_get_campaign by prefixing 'WRITE:' and giving the underlying POST path.

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 concrete condition for the tricky parameter: omit send_id when the campaign has one send, but pass one for A/B test campaigns. It does not cover when to prefer this over the sibling sarbacane_import_campaign_template, nor does it state the campaign must be a draft (only the title hints at that).

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=true and openWorldHint=true. The description earns credit beyond that by explaining the mechanism that makes it destructive ('import contacts as the recipients'), which implies existing recipient data is replaced, and by clarifying the no-send semantics. It stops short of stating outright that prior recipients are overwritten or what happens when the campaign is not in draft 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, front-loaded with the 'WRITE:' mutability marker, then the action, then the negative boundary, then the endpoint. 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 two-parameter mutation with full annotations and full schema coverage, this is nearly sufficient: mutability, destructive effect, idempotency and the endpoint are all conveyed. The remaining gap is the precondition (campaign must be a draft) and whether existing recipients are replaced or appended.

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 parameters documented and list_id pointing at sarbacane_list_lists, so the baseline is 3. The description names the two roles (contact list, campaign) but adds no syntax, sourcing, or constraint detail 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 ('import a contact list's contacts as the recipients of a campaign') plus the underlying endpoint, and explicitly separates itself from the send operation and from content-setting siblings. An agent can tell exactly what this does 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 line 'It does not send the campaign' usefully bounds the operation and prevents an agent from treating it as a dispatch step. However, no alternatives are named (e.g., use sarbacane_set_campaign_content for content, sarbacane_create_email_campaign for creation), and the requirement that the campaign be a draft appears only in the title, not the description.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, and the description adds valuable context beyond them: it marks the operation as WRITE, identifies the matching key, and warns that custom field values are overwritten. It still omits details such as auth requirements or all mutation side effects, so it is not fully exhaustive.

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 a single front-loaded sentence that begins with 'WRITE' and includes the key behavior, overwrite warning, and endpoint. Every element 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?

The definition covers the core upsert semantics and destructive overwrite behavior, which is important for a mutation tool with rich annotations. However, it leaves a significant gap: the schema requires only list_id, and the description does not state that at least one of email or phone is needed to identify or create the contact.

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 50%, and the description adds meaning for the least-documented parameters: email/phone act as the existence-matching pair, and custom field values are overwritten. It does not fully clarify whether at least one identifier is required, but it meaningfully supplements 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 states a specific verb/resource pair ('add or update a contact') and scope ('to a list'), plus the upsert condition. It is clear operationally, but it does not explicitly distinguish this from the sibling sarbacane_create_contact 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?

It explains the upsert condition: update when the same email/phone pair already exists. However, it gives no explicit guidance on when to choose this over sarbacane_create_contact or other contact tools, and no exclusions or prerequisites are stated.

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