Enginemailer MCP by usefulapi

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

Annotations already flag non-read-only, non-idempotent, non-destructive; the description adds substantive context beyond them: consent requirement, per-day insert quotas for free vs paid accounts, and the underlying endpoint. It omits duplicate-email behavior, which matters given idempotentHint=false.

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 WRITE marker and core action, then constraints, then endpoint. No filler; 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?

No output schema, so the description ideally would say what is returned (e.g. new subscriber id) or how duplicates are handled. Everything else an agent needs to call it correctly — consent rule, quotas, optional fields, mutation semantics — is 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% and each parameter is documented with formats and cross-references (customfield_key, subcategory ids from sibling list tools). The description only echoes the schema's framing ("optionally into subcategories, with custom field values"), adding no syntax or constraint detail, 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 ("add a subscriber to the account") with the optional axes (subcategories, custom field values), and the WRITE prefix plus API endpoint make it trivially distinguishable from get_subscriber, update_subscriber, and unsubscribe_subscriber.

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 clear usage precondition ("Only add people who consented to marketing email") and states rate limits so the agent knows when calls will fail. It does not explicitly route to update_subscriber for existing contacts or say what happens if the email already exists, so no explicit alternatives/exclusions.

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 cover the safety profile (destructiveHint=true, idempotentHint=true, openWorldHint=true), so the bar is lower. The description adds things annotations can't express: no email is sent, a paid account is required, and 'set who a campaign will go to' signals replacement of the existing recipient list, which explains the destructiveHint. It doesn't spell out what happens to a previously assigned list explicitly.

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?

One compressed paragraph, front-loaded with 'WRITE:' as a signal token, then scope, then behavioral caveats. Every clause carries information; nothing is padded.

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 no output schema, the description supplies the essentials: write nature, audience options, no-send guarantee, paid-account prerequisite. Minor gaps remain around campaign-state prerequisites and how an existing recipient list is treated on re-assignment.

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% and the schema already documents match_type's OR/AND semantics and the subcategory_ids conditional requirement. The description's restatement of match_type ('any = OR, all = AND') duplicates schema content and it says nothing about campaign_id, so it adds little 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?

Opens with a specific verb and resource ('WRITE: set who a campaign will go to') and immediately scopes the two audience modes. It explicitly distinguishes itself from the send path with 'Does not send anything', separating it from sibling enginemailer_send_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?

'Does not send anything' implicitly routes the agent to send_campaign for the actual send and positions this as the configuration step. It doesn't state ordering or prerequisites beyond the paid-account requirement (e.g., whether the campaign must exist first), so a 4 rather than a 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=true and destructiveHint=false, so the safety profile is covered. The description still adds value by disclosing the two possible states and what the response contains when finished, which annotations cannot express. It stops short of noting whether the download URL expires or how long processing typically takes.

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?

One front-loaded sentence carrying the status semantics and return payload, followed by a short endpoint note. No filler, though the endpoint path adds little for an agent that only needs to call the 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 one-parameter polling tool with no output schema, the description covers the state model and the key return field, which is what an agent needs to decide whether to re-check. Missing is any guidance on retry timing or URL lifetime.

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 parameter is documented as an integer ExportID tied to the start-export tool. The description adds nothing beyond that, 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 ('Status of a report export') and immediately names the return payload ('CSV download URL'), which pins down what the tool does. The reference to export_id coming from enginemailer_start_transactional_report_export makes the distinction from that sibling explicit.

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 pairing with start_transactional_report_export and the Processing/Complete states imply the tool should be polled after starting an export, but the description never says so explicitly or states any polling cadence. 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?

Beyond the annotations (readOnlyHint=false, destructiveHint=false), it discloses that nothing is sent at this stage, that the sender domain must be verified, that a paid account is required, and that there is a 200-campaign account cap. Those are exactly the prerequisites and limits an agent needs before attempting a write.

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?

Every sentence earns its place: write intent first, non-sending guarantee second, workflow third, prerequisites fourth, endpoint last as reference. No filler or repetition of the 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?

Workflow, prerequisites, limits and the underlying endpoint are all covered for a schema-only tool with no output schema. The one minor gap is that it never says the call returns a campaign identifier, which the agent needs in order to pass it to assign_campaign_recipients.

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%, so the schema already explains name, reply_to, content_html and sender_email. The description reinforces the verified-domain constraint on sender_email but adds nothing about the two undocumented fields (subject, sender_name), so it neither compensates for nor extends the schema meaningfully.

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 campaign DRAFT") plus an explicit scope qualifier ("Nothing is sent") that separates it from enginemailer_send_campaign. An agent can distinguish it from every sibling 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?

Gives the exact ordering: create draft here, assign recipients with enginemailer_assign_campaign_recipients, then send with enginemailer_send_campaign. It names both alternatives and the condition that selects each, leaving nothing 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 and destructiveHint=false, so the description focuses on what annotations cannot convey: the paid-account requirement, the delivered-only precondition, and the raw endpoint. It doesn't explain behavior on invalid/undelivered campaigns or stats freshness, which is the remaining gap.

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?

Front-loaded with the outcome and the precondition, then the metric list, then the endpoint. The long metric enumeration earns its place because there is no output schema; the raw REST path is marginal but small overhead.

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 usefully stands in for the return shape by naming every metric. Preconditions and the paid-account gate are covered; only error/freshness behavior is missing, which is minor for a single-parameter read 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?

Only one parameter, and the schema documents it fully at 100% coverage as 'Campaign id.' with a positive-integer bound. The description adds no extra meaning about where the campaign_id comes from (e.g., from list_campaigns), 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 ('Delivery results of a DELIVERED campaign') and enumerates the exact metrics returned, which distinguishes it from campaign-management siblings like list_campaigns or send_campaign. An agent immediately knows this is a read-only post-send reporting call.

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 clear preconditions: the campaign must be in DELIVERED status and a paid account is required. It does not name alternatives or exclusions (e.g., what to call for an un-sent campaign), but the context for use is unambiguous.

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 cover safety (readOnlyHint true, destructiveHint false), so the description only needs to add context. It does add the return payload (id, status, custom field values), but says nothing about what happens when the email is not found or whether the lookup spans all subscriber categories in this open-world API.

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?

One short, front-loaded sentence naming the key and the returned fields. The trailing raw endpoint path adds little for an agent but is not costly.

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-only, single-parameter lookup with no output schema, the description usefully enumerates the returned fields. Only the not-found / error behavior 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 coverage is 100% with a single email parameter already fully documented (format, pattern, max length). The description restates 'by email' without adding semantics beyond the schema, 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 plus the lookup key: fetch "One subscriber by email" returning id, status and custom field values. That clearly separates it from add_subscriber, update_subscriber and list_* siblings, though it never names an alternative 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 verb 'get by email' – there is no statement of when to prefer this over list_subscriber_categories or update_subscriber. For a trivial single-record lookup that is serviceable but not explicit 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, openWorldHint=true, so the safety profile is covered. The description adds genuinely new operational context — the paid-account requirement and the underlying endpoint — which is the kind of beyond-schema detail annotations don't 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?

A single tight sentence plus the plan requirement and endpoint path — no filler. The raw REST path is arguably low-value for an agent but is compact and doesn't crowd out the main 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 parameterless, read-only list call with annotations covering safety, the description says what the resource is, what fields come back, and the account prerequisite. Absent an output schema, a note on result ordering or volume would be a nice addition but is not essential here.

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 for the description to disambiguate; baseline is 4. The parenthetical field list usefully previews the shape of each returned category even though no inputs exist.

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 the specific resource (campaign categories that recipients can be filtered by) and the fields returned (id, name, description), which lets an agent recognize this as a lookup/list operation. It is clear but does not explicitly distinguish itself from the nearby sibling enginemailer_list_campaign_subcategories.

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 useful prerequisite ("Needs a paid account") that tells the agent when the call is viable, but it gives no guidance on choosing between this and enginemailer_list_campaign_subcategories or when categories are needed versus subcategories. Usage 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.

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

Annotations already cover safety (readOnlyHint=true, destructiveHint=false), so the bar is lower; the description still adds real value by disclosing an API limitation (delivered campaigns are simply unavailable here), a plan/account requirement, and the underlying endpoint. It stops short of describing pagination or result-size behavior, which is the only remaining gap.

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 scope constraint, then the alternative, then the precondition and endpoint. Nothing is repeated from the title and no sentence 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, the description compensates by naming the returned fields, and it warns that delivered campaigns are unreachable before the agent wastes a call. For a zero-parameter read tool with annotations covering safety, nothing material 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate — baseline 4 applies. The description correctly spends no space on phantom arguments and instead documents the output fields it will return.

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?

Specific verb (list) plus resource (campaigns) plus a hard scope qualifier: campaigns NOT yet delivered, explicitly defined as drafts and scheduled ones. It also enumerates the fields returned (id, name, subject, sender, schedule), so an agent knows exactly what this returns versus get_campaign_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?

States the boundary condition outright: delivered campaigns are not listed by the API, and names the alternative (enginemailer_get_campaign_stats with a known id) for that case. It also adds a precondition ('Needs a paid account'), which is exactly the kind of when-to-use detail agents need.

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 beyond that with the paid-account prerequisite, the underlying endpoint GET /restapi/campaign/emcampaign/GetSubCategoryList, and the shape of what comes back. It stops short of mentioning rate limits or failure behavior, keeping it at 4 rather than 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?

One compact sentence plus two short clauses; the returned fields and downstream consumer are front-loaded, and nothing is padded. Every element — scope, output fields, prerequisite, endpoint — 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-parameter read-only list tool with no output schema, the description compensates well by naming the returned fields and the paid-account requirement. Only minor gaps remain (ordering, pagination/empty-result behavior), so it is nearly 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?

The schema already documents category_id at 100% coverage, including its provenance ('from enginemailer_list_campaign_categories'). The description reinforces the single-category scope but adds no format or constraint detail beyond the schema, 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 the exact resource (subcategories of one campaign category) and even enumerates the returned fields (id, name, description), which distinguishes it from the sibling enginemailer_list_campaign_categories. It is phrased as a noun phrase rather than a verb, but the operation (list) is unmistakable.

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 clear routing statement: the returned ids feed enginemailer_assign_campaign_recipients, and it discloses the prerequisite 'Needs a paid account.' There is no explicit when-not guidance, but the companion-tool linkage makes the usage context unambiguous.

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 the returned field set, which is useful, but says nothing about pagination, result ordering, empty-list behavior, or auth requirements expected of an external API 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?

Two sentences plus the endpoint path; the purpose is front-loaded and the downstream usage hint follows. The raw REST path is slightly redundant for an agent but is short and harmless.

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 compensates by enumerating the returned fields (key, name, type), which is the key thing an agent needs to plan a follow-up add/update call. Minor gap: no indication of response envelope or field ordering.

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 for the description to disambiguate; the baseline of 4 applies. Schema coverage is 100% and the description correctly signals a no-argument call by mentioning nothing optional.

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: subscriber custom field definitions, and names the returned fields (key, name, type). It is clearly separable from siblings like list_subscriber_categories or list_campaign_categories, though it doesn't explicitly say 'all fields, no filtering.'

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 keys when adding or updating subscribers" gives concrete downstream context that ties this tool to enginemailer_add_subscriber and enginemailer_update_subscriber. No explicit when-not or exclusion, so it stops short of a 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=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real value by describing the returned structure (a category tree with ids and names), which matters because there is no output schema. It omits ordering/pagination details and the conditional nature of active-count data, which the schema covers instead.

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 what is returned and then why it matters. The trailing raw endpoint path (GET /restapi/subscriber/emsubscriber/getSubCategory) is the only line that earns little for an agent.

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 one optional parameter, full schema coverage and no output schema, the description supplies what is otherwise missing: the shape of the returned category tree and the intended use of its ids. Nothing critical for correct invocation 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% for the single optional parameter include_active_subscriber_count, so the schema carries its meaning fully. The description adds nothing about that flag, making the documented baseline of 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?

The description names a specific resource (the subscriber category tree) and states its contents (categories with subcategories, ids and names), which separates it from the sibling campaign-category tools. The verb is only implied by the tool name rather than stated outright, keeping it just 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?

"Use the subcategory ids when adding or updating subscribers and when assigning campaign recipients" tells the agent exactly what downstream calls depend on this tool's output, implicitly pointing at enginemailer_add_subscriber, enginemailer_update_subscriber and enginemailer_assign_campaign_recipients. There is no explicit when-not guidance or mention of the campaign-category sibling, so it is clear context without full routing.

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=false, and openWorldHint=true, so the safety bar is lowered. The description adds the POST endpoint and length limits, but crucially does not say what an update destroys — whether omitted fields are cleared or whether the subcategories array replaces existing subcategories. For a destructive write, that gap matters.

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 dense sentence front-loads the WRITE semantics and the create-vs-update rule, then appends the endpoint. Nearly every clause earns its place; the raw endpoint path is the only marginal addition.

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 destructive, non-idempotent write, the description should state what happens to existing data on update and what response comes back. Those are absent, leaving an agent able to call it but unsure of the side effects.

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 40%, and the description mostly restates schema content: the 0-sentinel for category_id/subcategory_id and the 128-character limits, both of which already appear in the schema. It leaves is_visible and the subcategories maxItems=200 unexplained, adding little beyond 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?

The description opens with an explicit 'WRITE' marker plus a specific resource ('subscriber category') and clearly states the dual create/update mode keyed off category_id. It is easy to distinguish from the read-side sibling enginemailer_list_subscriber_categories, though it doesn't name any sibling outright.

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 concrete mode-selection rules: category_id 0 means create, an id means update, and subcategory_id 0 creates a new subcategory. What's missing is any note on preconditions (e.g., needing an existing category before adding subcategories) or an explicit statement of when to prefer this over listing tools.

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 and idempotentHint=false, and the description adds substantive context beyond them: irreversibility ('cannot be undone'), the recipient/scheduling preconditions, and the paid-account requirement. It also names the underlying endpoint, which helps with debugging and traceability.

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 compact and front-loads the destructive nature of the call, which is the right priority. The shouty capitalized opening ('WRITE, SENDS EMAIL TO CUSTOMERS NOW') is slightly awkward and mildly redundant with the following clause, costing a point.

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 only two parameters, full schema coverage, and no output schema to explain, the description covers everything an agent needs: what it does, when it may be called, what approval is required, and that it is irreversible. Nothing material 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%, and both parameters are documented in the schema itself, so baseline is 3. The description reinforces confirm's meaning as user approval but adds no syntax, format, or edge-case detail beyond what the schema already provides.

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 pair ('sends / delivers the campaign to its assigned recipients immediately') and pins the timing with 'NOW', which clearly separates it from create_campaign, get_campaign_stats, and send_transactional_email. An agent can identify the operation without reading 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?

It lays out explicit preconditions: at least one recipient, not already scheduled or delivered, a paid account, and prior user approval with confirm set to true only after that approval. It also states the sequencing rule (show the campaign and audience, get go-ahead, then send), leaving nothing 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?

Goes well beyond the destructiveHint/idempotentHint annotations by stating the send is immediate and cannot be undone, that the sender must be on a verified domain, the 5 MB total size ceiling, and that a template supplies subject and sender name. These are operational constraints the annotations alone do not convey.

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?

Front-loads the highest-stakes fact (irreversible send), then the content-shape choice, then size limit, then the confirm protocol, and closes with the endpoint. Every sentence carries an actionable constraint with 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?

Covers the branching, prerequisites, limits, and safety protocol for an 11-parameter mutation tool with no output schema. The one omission is what a successful call returns (e.g., a message/submission id), which matters for follow-up verbs like enginemailer_check_transactional_report_export.

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?

Adds real meaning for the trickiest parameters: the template_id vs subject/content_html tradeoff, sender_email's verified-domain requirement, and the attachment size limit. The remaining gap is that cc/bcc, campaign_name, sender_name, and substitution_tags get no treatment in the description, though the schema documents most of them (64% coverage).

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 (submits/sends) and resource (a single transactional email to one recipient), and the emphasis on ONE email distinguishes it from the campaign-oriented siblings. An agent can tell immediately this is the single-message path rather than enginemailer_send_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 defines the pre-send protocol: confirm recipient and text with the user first, set confirm to true only after approval. It also gives the content branch (subject + content_html OR template_id) and the prerequisite of a verified sender domain, so the agent knows the conditions for a valid call.

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 declare readOnlyHint=false, destructiveHint=false and openWorldHint=true; the description usefully clarifies that the side effect is only a report file and no email is dispatched, and that it returns an export id. It stops short of stating idempotency behavior (whether repeat calls spawn duplicate exports) or any rate limits, which the idempotentHint=false annotation alone leaves ambiguous.

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, front-loaded with the action, then the return/poll path, then the safety caveat, ending with the endpoint. Nothing is redundant and the 60-day limit is embedded where it belongs.

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 full schema coverage and no output schema, the description supplies the missing pieces: what is returned (an export id), how to retrieve the result, and the 60-day window. An agent has everything needed to call it and follow up 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 coverage is 100%, so baseline would be 3, but the description adds a constraint not present in the schema: the start date can be at most 60 days back. The two optional filters aren't discussed, but the schema documents both thoroughly, so the added value is real if partial.

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 ("Start a CSV export of the transactional email delivery report") with the exact scope (a period). It also names the sibling it hands off to (enginemailer_check_transactional_report_export), so an agent can separate the two without opening schemas.

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 explicit when-to-use context (a start date at most 60 days back), names the follow-up tool to poll with, and pre-empts the common misunderstanding with "Creates a report file only; nothing is sent." The exclusions and the alternative are both spelled out.

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, idempotentHint=true, and readOnlyHint=false. The description adds useful behavioral context by stating this is a WRITE operation and that reversal requires the subscriber to opt in again.

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?

Front-loaded with 'WRITE' and the core effect, then adds the reversal caveat and endpoint. It is brief and every sentence provides useful 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 simple one-parameter unsubscribe tool, the description plus annotations cover the key behavior. It does not describe response or error behavior, but no output schema exists and the core action is clear.

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 required email parameter is fully documented in the schema. The description does not add further meaning about parameter usage, 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 specific verb and resource: unsubscribe a subscriber from campaigns. It clearly distinguishes from siblings like add_subscriber, update_subscriber, and get_subscriber.

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 indicates the action is for unsubscribing a subscriber so they stop receiving campaigns. It notes reversal requires the subscriber to opt in again, but does not explicitly contrast with alternatives such as update_subscriber.

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 this as a destructive write, but the description adds crucial details beyond them: the default custom_fields_mode is replace_all and fields not given are cleared, and subcategories_mode replace makes the provided list the full list. These specifics tell the agent exactly what can be destroyed.

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, front-loaded with 'WRITE', and every sentence explains mode behavior or the endpoint. There is no wasted text, and the mode semantics are grouped efficiently.

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 mutation tool with no output schema, the description covers the destructive mode behavior and defaults that an agent most needs. Required email validation and parameter types are documented in the schema, and annotations cover safety hints.

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 nonetheless adds meaningful semantics beyond the schema, especially explaining 'remove' and 'replace' for subcategories and spelling out the destructive effect of the default replace_all mode for custom 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?

The description states a specific verb and resource — changing an existing subscriber's subcategories and/or custom fields — and the word 'existing' distinguishes it from enginemailer_add_subscriber and get_subscriber. An agent can identify the operation 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 context is clear: this is the update path for an existing subscriber, not creation or retrieval. However, it does not explicitly mention when to prefer this over siblings such as add_subscriber or unsubscribe_subscriber, so it falls short of full alternative routing guidance.

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