Emailit

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

The annotations already establish that this is a non-read-only, non-destructive, non-idempotent write. The description adds useful behavior beyond that by saying it creates the contact if it does not exist, but it does not explain what happens when the email already exists as a subscriber, nor does it describe subscription status or double opt-in effects beyond what the schema already 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?

The description is two short sentences with the core action front-loaded and no wasted wording. It is appropriately sized for a concise tool summary.

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 a nested custom_fields object and no output schema, the description is too sparse. It omits optional parameter behavior, existing-subscriber handling, and double opt-in requirements, leaving the agent with significant gaps.

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

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

With 7 parameters and only 43% schema description coverage, the description should compensate but does not. It mentions only the audience and email in passing and says nothing about first_name, last_name, custom_fields, double_opt_in, or send_confirmation_email semantics.

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

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

The description gives a specific verb and resource: adding an email address to an audience, and notes that a missing contact is created. It does not distinguish this operation from close siblings such as bulk-add-contacts-to-audience or update-audience-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?

The description implies when the tool is relevant by naming the action, but gives no explicit guidance on when to use it versus create-contact, update-audience-subscriber, or bulk-add-contacts-to-audience. No prerequisites or exclusions are 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?

The description goes beyond the annotations by disclosing a real side effect: it starts 'tag added' automations and resumes automations waiting on the tag. That is exactly the kind of consequence not encoded in idempotentHint/destructiveHint. It still omits whether existing tags are preserved (additive vs replace), which matters for a mutation.

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

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

Two short sentences, front-loaded with the action and followed by the side effect. Nothing redundant.

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

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

With only two fully documented parameters and no output schema, the description covers what an agent needs to call it safely, including the automation side effect. The one gap is not stating whether tags are merged with existing ones.

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% – the id format, lowercase storage, and 1-50 tag limit are all already documented in the schema. The description adds no parameter meaning beyond that, 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 tags to a contact'), clearly distinguishable from remove-contact-tags and bulk-add-contacts-to-audience by the singular contact scope. It stops short of naming which sibling to use for bulk or removal cases.

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

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

No guidance on when to use this versus remove-contact-tags for replacing tags, update-contact, or the bulk audience tools. The usage is only implied by the verb 'Add'.

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=true, destructiveHint=false, and openWorldHint=false, so the safety and repeat-call profile is covered structurally. The description adds only the 'subscribe' framing, and says nothing about what happens to contacts already subscribed, whether unsubscribed contacts are resubscribed, or any per-call error 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 with no filler, and the batch limit is stated up front. Nothing is wasted, even if more could have been said.

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 full schema coverage and four annotations, the description is technically callable as written. But for a bulk mutation whose sibling bulk-resubscribe-contacts implies distinct resubscribe semantics, an agent cannot tell whether this tool handles previously unsubscribed contacts or errors on duplicates — a real gap 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%: ids documents the con_xxx format and 100-item cap, and audience_id documents the aud_xxx format. The description's 'up to 100 contacts' simply restates maxItems, adding no new meaning; 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 (subscribe) and resource (contacts to an audience) plus the batch cap of 100, which distinguishes it from the single-contact add-audience-subscriber sibling. It does not name any sibling explicitly, so the differentiation is inferred 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?

There is no guidance on when to use this over add-audience-subscriber, bulk-update-audience-subscribers, or bulk-resubscribe-contacts. The only hint is the '100 contacts' cap, which is already in the schema's maxItems, so the description provides no routing logic.

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, so the safety profile is covered. The description earns credit for going beyond that by stating the deletion is permanent and, importantly, that audience memberships are removed as a cascade effect — a non-obvious consequence an agent could not read off 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?

One sentence, zero filler, with the destructive nature and the cascade effect front-loaded. Nothing could be trimmed without losing 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 one-parameter, annotation-backed destructive tool with no output schema, this covers what an agent needs: permanence, item limit, and the membership side effect. Failure/partial-success behavior is the only gap, and it is minor 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 single ids parameter has 100% schema coverage, including the con_xxx format and the 1–100 bounds, so the schema does the heavy lifting. The description's 'up to 100 contacts' merely restates maxItems without adding format or validation detail beyond it.

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 (permanently delete) plus resource (contacts) plus scope (up to 100) and a stated side effect (audience memberships). It implicitly distinguishes itself from the singular delete-contact by the 'bulk' framing and the 100-item bound, though it never names that sibling 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?

The word 'Permanently' signals this is an irreversible operation, so the agent can infer caution is warranted, but there is no explicit guidance on when to pick this over delete-contact or bulk-remove-contacts-from-audience, and no stated prerequisite like confirming the contact IDs first.

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, so the safety profile is covered. The description adds one genuinely useful behavioral fact — "Contacts are kept" — clarifying the removal is from the audience only. However, it says nothing about how ids and filter parameters combine, whether all_matching is required for filter mode, or what happens when both are supplied.

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

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

Two short sentences, front-loaded with the core action and immediately followed by the clarifying constraint. 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 6-parameter destructive mutation with no output schema and low schema coverage, the description should explain the filter parameters and the role of all_matching. It leaves four of six parameters unexplained and doesn't resolve how ids and filters interact.

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 33%: id and ids are documented in the schema, but search, engagement, subscribed, and all_matching carry no descriptions anywhere. The description gestures at "a filter" without naming which parameters form it or explaining all_matching, which is a significant gap for a destructive bulk operation.

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 ("Remove many subscribers from an audience") and reveals the two operating modes (explicit ids vs. filter-matched). It does not differentiate itself from the very similar sibling bulk-remove-contacts-from-audience, which leaves a real ambiguity for selection.

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 two modes imply when each applies (targeted removal by id vs. bulk removal by filter), which is more than nothing. But there is no explicit guidance on choosing between this tool and bulk-remove-contacts-from-audience or remove-audience-subscriber, and no stated prerequisites or 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 already declare destructive=true, idempotent=true, readOnly=false, so the safety profile is covered. The description adds only the 100-item ceiling, which merely restates the schema's maxItems and says nothing about whether removal is reversible, whether it affects subscription status, or how it differs from deleting the contact outright.

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 with no filler — the scope and limit land first. It is efficient, though efficiency tips into under-specification for a destructive operation.

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

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

This is a destructive, non-annotated-for-reversibility mutation with a confusingly similar sibling set, no output schema, and no explanation of the resulting state after removal. For that complexity level, one sentence is not sufficient to invoke it confidently.

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

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

Schema coverage is 100%, including the `con_xxx`/`aud_xxx` ID formats and the maxItems constraint, so the description need not carry parameter detail. The single added fact ("up to 100") is already in the schema, so the description contributes nothing 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?

Specific verb plus resource ("Remove ... contacts from an audience") and a stated batch ceiling, so the operation is immediately graspable. However, it never distinguishes itself from the near-identical sibling `bulk-remove-audience-subscribers`, leaving the agent unable to tell which of the two to 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?

No when-to-use, when-not-to-use, or alternative is named. With siblings like `bulk-remove-audience-subscribers`, `remove-audience-subscriber`, and `bulk-delete-contacts` in the list, the absence of routing guidance is a real cost.

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 the safety profile (not read-only, non-destructive, idempotent), so the description's main addition is the consent precondition, which is genuinely useful for a compliance-sensitive write. The 100-item cap is repeated from the schema's maxItems, and nothing is said about partial failures or what happens to IDs that weren't unsubscribed.

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

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

Two short sentences with zero filler; the what (resubscribe, cap) is front-loaded and the consent rule follows as the gating condition.

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 bulk mutation with full schema coverage and annotations covering safety, the description supplies purpose, limit, and precondition. The only residual gap is outcome behavior (partial success, unknown IDs), which is minor given there's no output schema.

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

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

Schema coverage is 100% and the single 'ids' parameter is documented as 'Contact IDs (con_xxx), up to 100.' The description's 'up to 100 contacts' restates the schema constraint without adding syntax or format guidance, so this sits at the baseline.

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

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

States a specific verb and resource ('Resubscribe ... contacts') plus the bulk cap of 100, which is enough to separate it from bulk-unsubscribe-contacts and the audience-subscriber siblings. It doesn't explicitly name a sibling to steer away from, but the operation 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?

Adds an explicit precondition — 'Only do this when they asked to receive email again' — which tells the agent when this tool is appropriate. It stops short of naming when-not conditions or alternatives (e.g., for contacts who never unsubscribed), so it's clear context rather than 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 declare destructiveHint=true and idempotentHint=false, so the safety profile is covered by structured data. The description adds useful effect scope ('stop receiving campaigns and automations'), but omits key behavioral facts for a destructive bulk op: whether it is reversible (a bulk-resubscribe-contacts sibling exists), whether partial failures are possible, and whether transactional mail is unaffected.

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

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

Two short sentences, front-loaded with the action and its scope; nothing extraneous. The second sentence partly restates the first but adds clarifying detail about campaigns and automations, so it earns its place without being essential.

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 tool with full schema coverage, full annotations, and no output schema, the definition is close to sufficient. The remaining material gap is the reversibility/irreversibility story and any note on bulk partial-failure behavior for a destructive operation.

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 schema already documents the con_xxx ID format and the maxItems=100 limit. The description's 'up to 100 contacts' merely restates the maxItems constraint rather than adding new meaning such as behavior on invalid or unknown IDs, 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 a specific verb (unsubscribe) and resource (contacts) plus scope (up to 100, all marketing email), so the agent knows exactly what the tool does. It does not explicitly name the counterpart sibling tool (bulk-resubscribe-contacts) or differentiate from adjacent tools like bulk-remove-audience-subscribers, which keeps it below 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?

'Unsubscribe from all marketing email' implies the scenario, but there is no explicit when-to-use statement, no exclusion (e.g., versus removing a contact from a single audience), and no reference to alternatives. Usage is inferable but not guided.

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 is a non-read-only, idempotent, non-destructive operation. The description adds useful context that it can affect either explicit subscriber ids or every subscriber matching a filter, but it omits the 10,000-subscriber cap and does not elaborate on the effects of bulk unsubscription.

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 efficient sentence that front-loads the core operation and then gives the two targeting modes. Every clause contributes to understanding the tool, with no repetition or noise.

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 bulk write tool with no output schema, the description is adequate but thin. It captures the main targeting modes but leaves the agent to rely on the schema for limits, filter fields, and the exact meaning of all_matching.

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 moderate (57%), and the description explains the central ids-versus-filter targeting distinction plus an example tied to engagement. It still does not clarify the search, subscribed, or all_matching semantics beyond what the schema already provides, and the required action parameter is only implied by 'subscribe or unsubscribe'.

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 pair (subscribe/unsubscribe), the resource (many subscribers of an audience), and the two targeting modes (subscriber ids or a matching filter). It is clear enough to distinguish from single-subscriber tools, but it does not explicitly differentiate itself from nearby bulk-removal or bulk-unsubscribe siblings.

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

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

It implies the tool is for bulk audience subscription changes and gives the two targeting modes, including an example of filtering unengaged subscribers. However, it does not say when to prefer this over siblings like bulk-remove-audience-subscribers or bulk-unsubscribe-contacts, nor does it state exclusions or prerequisites.

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=false, so the bar is lower, but the description still adds real value by explaining what specifically is destroyed (waiting steps) and that nothing further executes. It does not say what happens when the run has already finished or errored, which is the remaining behavioral 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?

Two short sentences, zero filler, with the effect front-loaded and the irreversibility warning second. Nothing could be removed without losing information.

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

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

For a destructive one-shot mutation with no output schema, the definition covers the essential outcome and irreversibility, and annotations carry the safety profile. It falls short only on edge-case behavior (already-completed runs, error responses) and on the purpose of the 'reason' field.

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%: id and run_id are documented in the schema, but 'reason' has no description anywhere. The tool description adds no parameter meaning at all, so the undocumented third parameter is left entirely to inference — acceptable but not compensating for the gap.

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

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

States a specific verb and resource ('Cancel one running run') and defines the effect precisely: waiting steps canceled, no further steps run. It is clearly distinct from cancel-campaign and cancel-email by scope, though it never explicitly contrasts with the automation-level siblings like stop-automation or pause-automation.

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 choose this over stop-automation, pause-automation, or remove-contact-from-automation, all of which sit in the same sibling set. 'Can't be undone' is a hazard warning, not a usage rule, and no precondition (e.g., the run must still be active) is 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 destructiveHint=true and idempotentHint=false, and the description adds genuinely new behavior: cancellation is not retroactive ('Emails already delivered are not recalled') and is state-restricted. It stops short of saying what the campaign's resulting status is or how a second call behaves, so it is strong but not 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?

Three short sentences, front-loaded with the action and its valid states, then the exclusion, then the irreversibility caveat. Nothing is redundant with the title or 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?

For a one-parameter destructive tool with full schema coverage and annotations, the description covers eligibility, the alternative, and non-reversibility. The only real gap is the post-call state of the campaign (and there is no output schema to cover it), which is minor but would help an agent confirm success.

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 'id' parameter already documents that it accepts a cmp_xxx ID or a name. The description adds no syntax, resolution, or ambiguity-handling 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 a specific verb (cancel) and resource (campaign) plus the eligible states (draft or sending), which immediately separates it from delete-campaign and send-campaign in the sibling list. An agent can pick this tool 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?

Explicitly names the excluded state ('Scheduled campaigns cannot be canceled') and routes the agent to the correct alternative ('delete them to stop the send'). That is a concrete when-not plus a named fallback, not just implied usage.

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; the description adds genuinely new context by characterizing the operation as 'best-effort' and explaining the mechanism ('pulls it from the send queue') and its failure mode ('not guaranteed if delivery already started'). That is exactly the kind of caveat annotations can't express. It doesn't say what the caller sees when the cancel fails to land.

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

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

Two short sentences, zero filler, and the core action is front-loaded ahead of the caveat. Every clause carries information the 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 single-parameter mutation with a full annotation set and no output schema, the description covers what is being acted on, the best-effort semantics, and the failure condition. The only gap is what a successful or failed cancel returns to the caller, which is minor 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?

Only one parameter and schema coverage is 100%, with the 'id' field already documented as 'Email ID (em_xxx)'. The description adds no format or lookup guidance beyond that, 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+resource ('cancel ... email') plus the eligible states (scheduled, accepted, attempted), which clearly separates it from siblings like cancel-campaign, cancel-automation-run, and retry-email. It doesn't explicitly name those siblings, but the resource noun alone disambiguates well.

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 condition for use (email is scheduled, accepted, or attempted) and a clear boundary (not guaranteed once delivery has started), which is the key decision factor for an agent. It stops short of naming alternatives such as retry-email for already-failed sends, so it lacks explicit 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 cover the safety profile (not read-only, not idempotent, not destructive), and the description adds a genuinely non-derivable behavior: the secret is returned only once and cannot be retrieved again. The instruction to tell the user to store it securely is actionable operational context. It does not mention rate limits or whether creating a key revokes prior keys, but for a short tool this is strong disclosure.

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

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

Two short sentences, zero filler, with the one-time secret caveat placed second where it is most likely to be acted on. Nothing is repeated from the schema or title.

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 the important job of explaining what the caller receives (a one-time secret). The remaining gap is the parameter relationship between scope and sending_domain_id, which the description leaves to the schema.

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

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

Schema coverage is 67% -- 'scope' and 'sending_domain_id' are documented in the schema with enums and constraints, but 'name' has no description anywhere. The description adds nothing about the required name field or how scope interacts with sending_domain_id (e.g., that a domain lock only makes sense for a sending key). Mid-range baseline 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 ('Create an API key') that unambiguously separates it from get-api-key, list-api-keys, regenerate-api-key and update-api-key in the sibling set. It does not explicitly name those alternatives, so it stops just short of full sibling differentiation.

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 create a fresh key versus regenerating or updating an existing one, and no mention of prerequisites such as workspace permissions or scope choice. The agent must infer usage entirely from the name.

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

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

Annotations already disclose that this is a non-destructive mutation (readOnlyHint=false, destructiveHint=false) and that it is not idempotent. The description adds that settings are optional, which is useful, but it does not mention permissions, duplicate-name behavior, or what the call returns. The description adds some value but not rich behavioral context beyond annotations.

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

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

A single, front-loaded sentence that states the action, the resource, the domain of use, and the optional settings. There is no redundant or filler text.

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

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

Given seven parameters with nested objects, no output schema, and a create mutation, the description is somewhat thin. It does not address duplicate audience names, required verified-domain constraints for confirmation emails, or what the call returns. The schema and annotations compensate partially, making it adequate but with clear gaps.

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

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

Schema description coverage is 71%, so the schema already carries most parameter meaning, including visibility, public_name, double_opt_in, and confirmation_email. The phrase 'optionally with its settings' correctly signals that only the name is required and the remaining seven parameters are optional settings, but it does not explain the individual settings beyond what the schema already documents.

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

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

States a specific verb and resource ('Create an audience') and clarifies the resource as a mailing list, which distinguishes it from update-audience, delete-audience, and list-audiences. The added purpose ('for campaigns and automations') makes the tool's role immediately clear.

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

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

The description implies usage by saying the audience is 'for campaigns and automations', but it does not state when to use this tool versus update-audience or merge-audiences, nor does it mention any prerequisites such as unique naming. It gives context but no explicit exclusions or alternatives.

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 only declare it is a non-read-only, non-destructive, non-idempotent write. The description adds real behavioral context beyond that: saving is inert until a start/trigger call, plan gating surfaces as 403 plan_required, and exit_conditions cancel a run when an event or condition matches. It does not mention what happens on duplicate names or whether repeating the call creates a second draft, which is the one gap 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?

It is front-loaded with the definition and the inert-until-started constraint before the long action mapping, so the critical facts come first. The action-to-tool enumeration and the multi-paragraph 'webinar' example are dense but each earns its place as concrete guidance; the example could be trimmed without much loss.

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

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

For a 6-parameter, deeply nested create tool with no output schema, the description covers what an agent needs: the draft-only semantics, the execution model, supported versus unsupported step types, plan gating, exit conditions, and a worked end-to-end example. Missing return-shape detail is minor because the tool's product is a saved draft and the description leaves no ambiguity about the call's 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?

Top-level schema description coverage is only 17%, so the description must compensate, and it does: it maps each action value to the equivalent sibling tool (send_email = send-email, update_subscription = bulk-unsubscribe/resubscribe, etc.), explains the flow-step semantics of wait, wait_until modes and branches, condition, goal (runs jump to it), experiment, run_automation and end/end_run, and clarifies that settings.exit_conditions takes an event or a condition. It leaves 'context' and 'connections.branch' largely to the schema, but the added meaning is substantial.

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

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

The first sentence states a specific verb and resource ('Save a new automation as a draft') and enumerates the shape it takes (trigger step, action steps, connections between step keys). It immediately separates itself from the sibling tools that launch automations by stating that saving runs nothing and that start-automation/trigger-automation are what execute 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?

It names the alternatives explicitly (start-automation for each matching event, trigger-automation for a single run) and gives exclusions: webhook steps can only be added via dashboard or REST API, and goal steps / custom events require Pro or Business with contact.on_event needing Business (403 plan_required). That is a genuine when-to-use / when-not / prerequisite set rather than vague 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 readOnly=false, destructive=false, idempotent=false and openWorld=false. The description adds the useful fact that the result is an unsent draft with no recipients. It does not warn that retries create duplicate drafts despite idempotentHint=false, nor mention any domain/verification requirement for from_email.

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

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

Two sentences, front-loaded with the action and then the sequencers. Every clause carries routing information; nothing is wasted.

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

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

For a 16-parameter creation tool with no output schema, the description is adequate on workflow but silent on what comes back (presumably a campaign id needed for update-campaign) and on the draft's default settings. An agent can act, but with avoidable guesswork.

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 69%, a mid-range case where the schema documents the nontrivial fields (ab_test, utm_params, tracking overrides) while the plain fields are self-explanatory. The description adds no parameter meaning at all, so it neither compensates for the gap nor detracts; 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?

"Create a draft campaign" gives a specific verb plus the key state qualifier (draft, not sent), which meaningfully separates it from send-campaign and the other create-* tools. It does not explicitly contrast with adjacent creation tools like create-template, 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 description spells out the workflow: add recipients via update-campaign, then send via send-campaign. That tells an agent the campaign is empty on creation and which sibling to call next. It stops short of stating when a campaign is the wrong choice (e.g. vs. automation) or any prerequisites.

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=false, idempotentHint=false and openWorldHint=false, so safety is covered. The description usefully discloses that ancillary fields are optional, but it omits the critical behavior for a non-idempotent create: what happens when the email already exists, and what identifier is returned. That is a meaningful gap beyond the annotation baseline.

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

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

A single front-loaded sentence with the core action first and the optional extras after; no filler and every clause carries information.

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

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

For a create tool with a nested custom_fields object, no output schema and a non-idempotent annotation, the description should say what a successful call returns and how existing-email collisions are handled. It covers the field surface adequately but leaves the agent guessing on outcomes.

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

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

Schema description coverage is only 38%, so the description must compensate; it names four of eight parameters (audiences, custom_fields, tags, score) and clarifies they are optional. It says nothing about email being required, nor about first_name/last_name/unsubscribed, so partial compensation only.

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 contact') and clarifies that audience subscription, custom fields, tags and lead score are bundled optional capabilities. That distinguishes it from narrower siblings like add-contact-tags or add-audience-subscriber, though it never names those alternatives.

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

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

The phrase 'optionally subscribing it to audiences and setting custom fields, tags and a lead score' implies this is the one-shot creation path versus follow-up calls to the tag/audience tools. However there is no explicit when-to-use guidance, no mention of update-contact for existing records, and no stated precondition.

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 is a non-destructive, non-idempotent write and no output schema exists, so the description earns real credit for disclosing the return payload (SPF, DKIM, return-path, DMARC records) and the fact that verification cannot succeed until those records are published. It omits failure modes such as duplicate-domain errors.

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 filler, with the core action front-loaded and the consequential return value stated immediately after. Nothing here could be cut without losing 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?

With no output schema, the description usefully covers what comes back and the DNS prerequisite, which is the key thing an agent must relay. It leaves the undocumented use_for_any flag and post-creation verification steps unexplained, so it is strong but not exhaustive for a 7-parameter write 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 coverage is 86%, so the schema already explains name, incoming, outgoing, and all tracking flags; the description adds no parameter-level meaning. It notably never mentions the inbound-email option, which sits slightly at odds with calling it a "sending domain."

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?

"Add a sending domain" gives a specific verb+resource, distinguishing it from list-domains/get-domain/delete-domain. It doesn't explicitly contrast with update-domain or verify-domain, though "before verifying" gestures at the verify flow, so it stops just short of full sibling differentiation.

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 "to publish before verifying" implies a workflow ordering (create → publish DNS → verify-domain), but there is no explicit statement of when to use this versus update-domain, or what to do if the domain already exists. 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 declare non-readOnly, non-idempotent, non-destructive, closed-world; the description's addition of 'draft' tells the agent the created resource is not immediately live and needs a publish step — a meaningful detail beyond annotations. It still omits what happens if a form with the same name exists (non-idempotent consequence) and what is returned.

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

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

A single front-loaded sentence with no filler. The parenthetical enum list is the only slightly redundant part since the schema already enumerates those values.

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 4 params including two nested free-form objects and no output schema, the description should at least hint at the create-to-draft-to-publish lifecycle and whether a default template is used. The schema mentions the default template, so the description is not required to, but its coverage of behavior for a mutating tool is thin.

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 roughly 50%: 'settings' and 'definition' carry descriptions, while 'name' and 'type' do not. The description simply restates the type enum values already in the schema and adds no syntax or constraint meaning for the required 'name' parameter. Baseline 3 applies since the schema does the heavy lifting.

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

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

Specific verb+resource ('Create a draft signup form') and it names the form types supported, so the agent knows this is the create counterpart to update-form/publish-form/delete-form. It doesn't explicitly differentiate itself from those siblings, but the intent is unambiguous.

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

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

The word 'draft' implies the form is not live until publish-form is called, which is a useful implicit cue. However, there is no explicit statement of when to use this versus update-form, nor any prerequisites (workspace context, permission needs) 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 disclose that this is a non-read-only, non-destructive, non-idempotent mutation. The description adds useful context about how global values are consumed, including a date-wait example. It does not disclose collision behavior when the key already exists, permission requirements, or whether creation fails on duplicate keys, which matters 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?

The description is two tight sentences that front-load the core purpose and then add the most relevant usage context. Every sentence contributes something an agent would not get from the tool name alone.

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 and only 40% schema description coverage, the description leaves several gaps. It communicates purpose and downstream usage well, but an agent still lacks guidance on duplicate keys, failure modes, and how type and value interact.

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 low at 40%, so the description should compensate more. It adds operational meaning for the key reference syntax and date-value behavior, but does not explain the name, description, or how the value parameter must align with the selected type. The added semantics are useful but incomplete against the coverage gap.

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

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

The description names a specific verb and resource: create a global value. It also explains how the created value is referenced as {{global.<key>}}, which helps an agent understand the tool's output context. It does not explicitly differentiate this from update-global-value or delete-global-value, but the create action is unambiguous.

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

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

The description implies usage by explaining that global values are referenced in templates and can be used in automation date waits. However, it does not state when to use this tool instead of update-global-value, or what to do if a value with the same key already exists. The guidance is contextual but not prescriptive.

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=false, openWorldHint=false and idempotentHint=false, so the safety profile is covered. The description adds the delivery-blocking consequence, but says nothing about what happens on a duplicate address — which matters given idempotentHint=false — nor about required scopes/permissions or the returned record.

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

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

A single front-loaded sentence with zero filler, which is the right shape for a simple create tool. It is arguably too terse given the undocumented parameters, but nothing in it 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?

With four parameters at 25% coverage, no output schema, and a non-idempotent mutation, the description would need to explain the type values, duplicate behavior, and what gets created. None of that is present, so a caller cannot be confident it will invoke the tool correctly.

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

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

Schema description coverage is only 25%: keep_until is documented in the schema, while email, reason and the type enum (recipient/bounce/complaint/unsubscribe) carry no explanation anywhere. The description compensates for none of this, so an agent must guess what each suppression type means and what reason is used 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?

States a specific verb (add) and resource (suppression list) plus the concrete effect: Emailit will never send to that address. That is clear enough to distinguish it from get-suppression or delete-suppression by name alone, but the description never names those siblings explicitly, leaving the routing to inference.

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

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

There is no guidance on when to call this versus update-suppression (e.g. changing an existing suppression's expiry) or the bulk unsubscribe/contact tools. The only usage signal is the implied 'add an address that should never be mailed', which is context rather than a decision rule.

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 it is a non-destructive, non-idempotent write. The description adds one meaningful behavioral trait beyond that – the draft/publish lifecycle gate ('publish it before use') – but says nothing about duplicate-alias handling or what is returned for referencing later, which matters 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?

Two short sentences, front-loaded with the action and followed by the essential lifecycle constraint. 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 non-idempotent create with 8 parameters and no output schema, an agent still lacks duplicate-alias behavior, editor-mode semantics, and the response handle. The publish-before-use note is valuable but partial.

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% with 8 parameters. The description clarifies that alias (and ID) are the handle used by send-email, but leaves text, editor (four-value enum), reply_to and name entirely unexplained, and does not note the {{variables}} templating contract for html/subject.

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 ('Create an email template'), which cleanly separates it from update-template, delete-template and publish-template in the sibling list. It does not explicitly name those alternatives, so differentiation is implied rather than spelled out.

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 downstream context: the template is consumed by send-email via ID or alias, and must be published before use. That is real when-to-use guidance, but there are no exclusions or direct pointers to publish-template as the required next step.

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 only say it is a non-destructive, non-idempotent write; the description adds genuinely new traits: asynchronous background execution, per-address credit consumption, and the polling follow-up. It does not say whether duplicate list names are allowed or what a credit shortfall does mid-run, so not a 5.

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

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

Two sentences, no filler, with the capability and limit front-loaded and the operational follow-up second. Nothing is redundant beyond the harmless restatement of the batch cap.

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 async behavior, cost, and the polling path, but for a write tool with no output schema it omits what the call returns — critically, whether an ID is returned that get-verification-list needs. An agent knows the workflow shape but not how to thread the result into the next call.

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 0%, so the description must carry parameter meaning. It explains 'emails' only implicitly as 'addresses' and repeats the 10,000 cap already enforced by maxItems; the required 'name' parameter (label? unique key? used for lookup later?) is never addressed.

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 (verify) and resource scope (up to 10,000 addresses, background, full mailbox check), which cleanly separates it from the single-address verify-email sibling. The follow-up polling tool is named, so the agent can see the whole workflow immediately.

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?

Makes clear this is the bulk/background path and tells the agent to poll get-verification-list rather than wait. It does not explicitly contrast with verify-email for small batches or note prerequisites (e.g. credit balance required), which keeps it 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 the mutation profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false, openWorldHint=true), so the bar is lower. The description adds genuinely non-obvious behavior: the response returns the signing secret, which matters for later signature verification and is not implied by any annotation or schema field. It does not mention that the endpoint may need verification or that the secret is only returned at creation time.

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; the action and its effect come first, and the return-value fact is second. Every clause carries information an agent would not get from the schema alone.

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

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

A six-parameter mutation tool with no output schema benefits from the explicit note about the signing secret in the response. However, defaults are unaddressed (what happens if events and all_events are both omitted), and there is no guidance on endpoint validation or idempotency, leaving real gaps for a creation tool with a nested filter parameter.

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?

At 67% schema coverage, the schema already documents url, events, filter, and all_events in detail. The description reinforces which event families exist but adds nothing about the events-vs-all_events interaction, the filter rule object, or the undocumented name/enabled parameters. Baseline 3 is appropriate.

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

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

States a specific verb+resource ("Create a webhook") and immediately explains the effect: Emailit POSTs email, domain, contact, and campaign events to the URL. That is clearly more than a restatement of the name. It stops short of distinguishing itself from update-webhook or test-webhook, which are the nearest ambiguous siblings.

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

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

No explicit guidance on when to create a new webhook versus updating an existing one, nor any pointer to test-webhook or list-webhooks for verification. The only implicit cue is the event categories listed, which hints at the subscription use case but never states prerequisites or 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 already declare non-read-only, non-destructive, non-idempotent, closed-world, so the mutation profile is covered. The description adds genuinely new context: the plan gating and the w:<name> dispatch convention. It stops short of disclosing what happens when a name collides with an existing event, which is the main behavioral risk 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 action and resource, followed by the follow-up workflow and the plan constraint. No filler. The telegraphic "Send it afterwards as w:<name>" is terse to the point of being slightly cryptic, which keeps it off a 5.

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

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

For a 4-parameter create mutation with no output schema, the description covers purpose, the follow-up send step, and plan eligibility, but omits duplicate-name behavior, whether the created event identifier is needed downstream, and whether properties can be amended later. Adequate, with real gaps.

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

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

Schema description coverage is only 25%, so the description needs to compensate and partially does: it enumerates the four property types (string, number, date, boolean) that constrain the nested `properties` array. The `title` and `description` parameters are undocumented in both schema and description, leaving half the surface unexplained.

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

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

States a specific verb+resource ("Define a workspace event and its typed properties") and enumerates the property types allowed, so the agent knows exactly what is being created. It does not name the sibling it is distinct from (update-workspace-event, delete-workspace-event), but the "send it afterwards" clause implicitly routes to send-event.

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 "send it afterwards as w:<name>" line gives a real usage sequence: define here, then dispatch through send-event. "Pro and Business plans" states an eligibility constraint. However there is no explicit when-not guidance (e.g. what to do if the event already exists, or how this differs from update-workspace-event).

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, so the safety profile is covered. The description adds genuinely useful blast-radius context that annotations cannot convey: apps using the key stop working immediately, making the operational consequence concrete.

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, the permanence warning front-loaded and the consequence second. 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 single-parameter destructive tool with rich annotations and no output schema, the description covers what an agent must know before calling: it is permanent and immediately impactful. Only the alternative-action routing (regenerate vs delete) is left unstated.

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% for the single 'id' parameter, so the schema already carries the semantics and the description rightly does not restate it. Baseline 3 applies; no added value is offered, but none is needed.

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

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

States a specific verb ('revoke') and resource ('API key') plus the permanence modifier, which distinguishes it from the reversible sibling operations like update-api-key or regenerate-api-key. An agent can immediately tell what this does.

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

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

No guidance on when to choose this over the closely related alternatives. The most important distinction — revoke permanently versus regenerate-api-key or update-api-key — is never named, even though those siblings exist.

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, so the description is not carrying the safety burden alone. It still adds genuinely useful behavior context by naming exactly what is destroyed (subscriber records) and what survives (contacts), which annotations cannot express.

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

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

Two short sentences with zero waste; the destruction scope is front-loaded and the retention caveat follows immediately.

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

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

For a single-parameter destructive delete with full annotation coverage and no output schema, this covers what an agent must know: it is permanent and contacts are not affected. Only the absence of any rollback/irreversibility confirmation or prerequisite note keeps it from a 5.

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 (id) with 100% schema description coverage, so the schema fully documents it. The description adds no format, sourcing, or lookup guidance for the audience ID, leaving it at the baseline.

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

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

States a specific verb (permanently delete) and resource (audience) plus a precise scope note: subscriber records go, contacts stay. That distinguishes it from bulk-remove-audience-subscribers and bulk-delete-contacts by implication, though no sibling is named 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: the 'permanently' and 'contacts are kept' framing tells an agent this is an irreversible container removal, not a contact purge. There is no explicit when-to-use/when-not statement and no named alternative such as update-audience for reversible changes.

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, so the safety profile is covered. The description adds genuinely new behavioral detail the annotations cannot express: new events stop starting runs, but in-flight runs are allowed to complete. It stops short of saying whether the automation record itself is recoverable or whether dependent resources are affected.

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

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

Two short sentences with zero filler, and the core action is front-loaded before the side-effect clarification. Every clause carries information an agent can act on.

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 destructive tool with no output schema and annotations that already flag destructiveness, this is nearly sufficient: the side effect on running executions is the main thing an agent needs. What is missing is whether deletion is permanent or retrievable, and whether verification via get-automation is advisable first.

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 with the expected format ('Automation ID (aut_xxx)') at 100% coverage. The description adds nothing about the identifier, 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 verb and resource ('Delete an automation') and immediately defines what deletion means operationally. It does not explicitly contrast with the very close siblings pause-automation, stop-automation, or cancel-automation-run, so an agent must infer the distinction.

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

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

Usage is only implied: 'runs already in progress finish' hints that this differs from stopping or cancelling a run, but the description never says when to choose delete vs stop-automation vs pause-automation. No prerequisites or warnings about permanence are given, leaving the agent to infer them from the sibling list.

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, so the safety profile is covered. The description adds value beyond that by stating permanence and an eligibility precondition (campaign must be unsent), though it does not explain failure behavior when the precondition is violated.

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 sentence with the destructive nature and the precondition front-loaded; every word earns its place 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?

For a single-parameter destructive tool with full annotations and full schema coverage, the description covers what is destroyed and the precondition. The only meaningful gap is not routing the agent to cancel-campaign for campaigns that have already been sent.

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 'id' parameter is documented as accepting a camp_xxx ID or a name, so the schema carries the full burden. The description adds nothing about the identifier beyond what the schema already states.

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

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

States a specific verb and resource ('delete a campaign') plus a scoping precondition ('that has not been sent'), which clearly signals it is for unsent campaigns only. It does not name the sibling to use for sent campaigns (cancel-campaign), so differentiation is implicit rather than 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 phrase 'has not been sent' implies when the tool is applicable, but it never states what to do otherwise (e.g., use cancel-campaign for sent campaigns) and gives no prerequisites or confirmation guidance for a destructive operation.

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?

The annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered structurally. The description still earns credit by adding what actually gets destroyed — the contact's audience memberships — and reinforcing irreversibility with "Permanently," context the annotations cannot express. It doesn't cover auth requirements or behavior when the contact is missing, which keeps it from a 5.

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

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

One sentence with no filler, and the most consequential fact (permanence plus cascade) is front-loaded. Nothing here is redundant with the title or annotations.

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

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

For a one-parameter mutation with full schema coverage and rich annotations, the description supplies the missing piece — scope of deletion. Minor gaps remain around what happens on a nonexistent ID and whether the contact is also removed from automations, but no output schema is needed to be explained.

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 `id` parameter already documents the con_xxx-or-email format, so the schema does the heavy lifting. The description adds no additional meaning about identifier handling, making the baseline 3 appropriate.

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

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

The description names a specific verb and resource ("Permanently delete a contact") and adds the side effect on audience memberships, which goes beyond a bare restatement of the name. It doesn't distinguish itself from the sibling bulk-delete-contacts or remove-audience-subscriber, so an agent must infer the single-vs-many boundary.

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

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

No explicit when-to-use or when-not-to-use guidance is given. The description never points to bulk-delete-contacts for multi-record deletion or to remove-audience-subscriber when only membership removal is wanted, leaving the choice to inference from the name alone.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=false, so the safety profile is covered. The description adds a concrete consequence beyond the annotations: outbound sending from the domain stops immediately, which tells the agent what blast radius to expect. It still omits whether deletion fails when the domain is attached to campaigns or whether related records cascade.

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, no filler, with the destructive scope front-loaded and the operational consequence second. Every sentence 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 one-parameter destructive tool whose annotations already carry the safety flags, the description covers what is destroyed and the immediate side effect. It leaves out dependency/cascade behavior and any undone-state warning, which an agent confirming a destructive action would still want.

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 a single required 'id' parameter with 100% schema description coverage, so the schema already identifies it. The description contributes nothing about the identifier (format, source, whether it accepts the domain name instead of the ID), which is the correct baseline for full schema 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 and resource: 'Permanently delete a domain', which unambiguously separates it from update-domain and verify-domain. It doesn't explicitly contrast with 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?

No guidance on when to use this instead of update-domain or verify-domain, nor any prerequisite note (e.g. whether a domain in active use can be deleted). The word 'Permanently' hints at caution but gives no explicit when/when-not rule.

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=true, so the bar is lower, yet the description adds real value by disclosing the downstream consequence that embedded copies stop working. It stops short of noting permission requirements or whether the form must be unpublished first.

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

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

Two short sentences with zero padding; the destructive nature is front-loaded and the consequence follows immediately.

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

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

Placeholder.

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?

Single required parameter with 100% schema description coverage ("Form ID (frm_xxx)"), so the schema fully carries the load. The description adds no further meaning about the id, which is the expected baseline here.

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 ("Permanently delete a form"), which is unambiguous. It does not explicitly distinguish itself from siblings like unpublish-form or bulk operations, but the delete semantics are clear.

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

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

No guidance on when to prefer this over the non-destructive unpublish-form alternative, or any prerequisites (ownership, published state). The agent must infer that deletion is the last resort.

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, so the safety profile is covered structurally. The description adds genuinely new context: templates referencing the value render it empty, which tells the agent about downstream blast radius on live emails/templates. It still omits whether deletion is recoverable and whether in-use values can be deleted at all.

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

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

Two short sentences, zero filler, with the action first and the consequence second. Nothing could be removed without losing 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 one-parameter destructive tool with rich annotations and no output schema, the description covers what it does and one non-obvious side effect. It is nearly complete, though a note on irreversibility would close the remaining gap.

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

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

Schema coverage is 100% and the single 'id' parameter is documented as accepting a gv_xxx ID or key. The description adds nothing about 'id' 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?

States a specific verb ('Delete') and resource ('a global value'), which cleanly separates it from update-global-value, get-global-value, and create-global-value in the sibling list. It does not explicitly name those alternatives, so it stops short of a 5.

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

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

The description never says when to use this versus update-global-value (which could clear a value non-destructively) or bulk cleanup paths. The only contextual hint is the rendering consequence, which is impact information rather than selection 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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is clear. The description adds useful behavioral context beyond annotations by explaining the consequence: the address becomes eligible to receive email again. It does not mention irreversibility or confirmation, but the annotations carry that burden.

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 sentence with no wasted words, and the core action and effect are front-loaded.

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

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

For a simple one-parameter deletion tool with rich annotations and fully documented schema, the description is nearly complete enough. It covers the business effect, though it omits explicit usage alternatives or confirmation expectations that could help in a destructive operation.

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

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

Schema description coverage is 100%, so the parameter is fully documented in the schema. The description does not add details about the id parameter and even says "an address" while the schema allows either a suppression ID or email address. Baseline 3 is appropriate because the schema does the heavy lifting.

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

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

The description states a specific verb (remove) and resource (suppression list), and adds the outcome that the address can receive email again. It does not explicitly name siblings like update-suppression or list-suppressions, but the operation is clearly distinguishable from those tools.

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

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

The phrase "so it can receive email again" implies when to use the tool, but there is no explicit guidance on alternatives, exclusions, or prerequisites. An agent can infer its purpose, but the description does not route the agent among related 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 declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is mostly carried by structured data. The word 'Permanently' adds a small amount of value by signaling irreversibility, but the description says nothing about what is destroyed beyond the template record, whether deletion fails if the template is in use, or any auth/scope requirement.

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

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

One short sentence with the action front-loaded and no filler. It is efficiently sized, though the terseness leaves room that could have been used for a caveat about irreversibility or in-use templates.

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

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

For a destructive single-parameter mutation, the annotations already carry the risk profile and the schema fully documents the input, so nothing critical is missing for a correct call. However, no output schema exists and the description gives no hint of the response or failure modes, leaving it only minimally viable.

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

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

Schema coverage is 100% and the single parameter 'id' is documented in the schema as 'Template ID (tem_xxx)', so the description has no gap to fill. The baseline of 3 applies: the schema does the work, and the description adds nothing about the identifier.

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

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

States a specific verb (delete) and resource (template), clearly distinct from sibling delete-* tools that target other resources. It does not explicitly distinguish from unpublish-template or update-template, but the action is unambiguous.

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

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

There is no guidance on when to use this versus alternatives such as unpublish-template (which likely removes a template from availability without destroying it) or update-template. No preconditions, no mention of what happens when a template is still referenced by emails or campaigns.

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, so the core safety profile is structured data. The description adds genuine domain context beyond that – 'Permanently' and 'Pending deliveries are dropped' – which tells the agent about in-flight data loss that annotations cannot express. It stops short of stating error behavior for a nonexistent ID or that the webhook stops firing immediately.

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

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

Two short sentences with the destructive action front-loaded and the consequence tucked behind it; nothing is wasted. It is arguably a touch terse for a destructive operation, but efficient.

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

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

For a single-parameter destructive tool with full annotation coverage, the description supplies the one fact annotations omit: pending deliveries are lost. Combined with the 100%-covered schema and destructive/idempotent hints, an agent has enough to call it correctly, though a note on failure mode for an unknown ID would round it out.

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 'id' documented as 'Webhook ID (wh_xxx).' including the expected format. The description adds no parameter-level detail, so the baseline 3 applies.

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

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

States a specific verb+resource ('Permanently delete a webhook') that clearly distinguishes it from get-webhook, update-webhook, and the many other delete-* siblings by naming the resource. It does not, however, contrast it against a sibling such as update-webhook for reversible disabling, so differentiation is by noun rather than explicit text.

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

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

There is no guidance on when to use this versus update-webhook (disable) or the retry-webhook-request siblings, and no mention of prerequisites or irreversibility checks. The agent must infer that this is the terminal teardown option.

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, so the safety profile is covered. The description adds genuinely non-redundant behavior: stored events are retained while new events of the type are rejected — this is the key operational fact beyond what annotations say. It stops short of stating what happens to in-flight or referenced events, or error behavior for an unknown ID.

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

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

Two short sentences, zero filler, with the action front-loaded and the non-obvious side effect immediately after. Nothing could be cut without losing 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 single-parameter delete with full annotation coverage and no output schema, this is nearly complete: the agent knows the action, the identifier, and that stored data survives. A brief note on whether deletion is reversible or fails on unknown IDs would close the remaining gap.

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

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

Only one parameter and schema coverage is 100%, with the schema itself documenting the accepted 'etp_xxx / name / w:name' forms. The description adds no parameter-level meaning, so the baseline 3 applies.

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

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

States a specific verb ('Delete') plus a precisely scoped resource ('a workspace event definition'), and the second sentence disambiguates it from deleting the stored events themselves — a distinction an agent could otherwise get wrong given the sibling 'get-event'/'list-events' family.

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

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

Usage is implied by the consequence stated ('new events of this type are rejected'), so an agent can infer this is for stopping future event ingestion. But it never names an alternative or exclusion — e.g. when to use update-workspace-event to disable instead, or whether this affects existing automations that reference the event.

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 readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered; the description usefully adds the return format and column set. However, it leaves a real ambiguity: it accepts page/limit (max 100), so it is unclear whether the CSV covers all matching contacts or only one page, and no note on result size or rate limits is given.

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 that names the action, the filter scoping, the output format, and the columns. Nothing is wasted and no sentence is buried.

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 12 parameters, 92% schema coverage, and full annotations, the definition is serviceable but thin: the pagination behavior of an export, and how it differs from list-contacts, are left unstated. Since there is no output schema, a short note on the CSV's shape/paging would have closed the gap.

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

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

Schema description coverage is 92%, so the baseline is 3; the description does add a bit by framing the parameters as filters that shape the exported column set (email, names, subscription, audiences, custom fields). It does not add syntax or semantics for individual parameters, which the schema already handles well.

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 ("Export contacts") plus the output form (",CSV text") and the columns produced, which is more informative than the title alone. It stops short of naming the closest sibling (list-contacts) to make the export-vs-list distinction explicit, so it is clear but not fully differentiated.

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

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

"matching the filters" and "as CSV text" imply the use case (get a CSV of a filtered contact set), but there is no explicit when-to-use, when-not-to-use, or alternative such as list-contacts. Guidance is inferred from format 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 destructiveHint=true, openWorldHint=true and idempotentHint=false, so the description adds the valuable rate-limit constraint (3 forwards per hour per workspace) and the default-vs-headers behavior. It does not explain what makes the operation destructive (e.g., new delivery created, original untouched), which is a real gap for a destructive mutation.

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: purpose first, then the mode toggle, then the rate limit. Every sentence carries information an agent needs, with no redundancy against 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?

For a destructive, non-idempotent 9-parameter tool with no output schema, the description covers the key mode toggle and rate limit but leaves several parameters and the destructive semantics (attachment handling, whether the original is modified, response shape) 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 coverage is 56%, so roughly half the parameters are undocumented anywhere. The description adds meaning for include_headers and comment (including the body alias only indirectly), but 'from', 'subject', 'html', and 'text' go unexplained, and 'to'/'id' are left to 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 ('Forward an outgoing email to a new recipient') and clarifies the default mode versus the include_headers variant. It doesn't explicitly distinguish itself from send-email or retry-email, so sibling differentiation is only implied.

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?

Explains the default behavior (plain resend) and when to use include_headers, which is useful conditional guidance. However, it never names alternatives such as send-email, retry-email, or update-email, nor does it state when not to forward.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the meaningful behavioral detail that the secret is omitted, but it does not describe authentication requirements or the returned fields.

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

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

The description is a single compact sentence with no wasted words. It front-loads the action and immediately clarifies the secret-omission scope.

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 getter with rich safety annotations, the description covers the main behavioral nuance: the secret is not returned. Because there is no output schema, it could say more about what metadata is returned, but the essential context for calling it correctly 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?

The single parameter is fully documented in the schema as 'API key ID.' with 100% schema description coverage. The tool description does not add format examples or constraints beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description states a specific verb and resource: retrieve an API key. The parenthetical '(without its secret)' adds an important scope detail and distinguishes it from operations that expose secrets, though it does not explicitly name sibling tools like list-api-keys.

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 use case is implied: fetch a single API key when the key metadata is needed without revealing the secret. However, there is no explicit guidance on when to use this versus list-api-keys, update-api-key, or regenerate-api-key.

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, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered elsewhere. The description's contribution is disclosing the returned data shape (settings plus three count types), which is genuinely useful since no output schema exists, but it says nothing about permissions, not-found behavior, or whether counts are live.

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 well-formed sentence that front-loads the verb and resource and spends its remainder on return-value detail rather than filler. Nothing extraneous.

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-only getter with rich annotations, this covers purpose and return contents adequately. The remaining gaps—not-found/error behavior and whether the counts are real-time—are modest for this tool class.

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 100% schema description coverage and a single 'id' parameter documented as 'Audience ID.', the schema carries the parameter semantics. The description adds no format, ID-source, or lookup guidance beyond what the schema already says.

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 (Retrieve) and resource (audience) and enumerates what the response contains (settings, subscriber/unengaged/pending double opt-in counts). It is clearly distinguishable from mutation siblings like update-audience or delete-audience, though it doesn't explicitly contrast with list-audiences or get-audience-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?

Usage is only implied by the singular 'get' + required id, i.e. fetch one known audience by ID. There is no explicit statement of when to prefer this over list-audiences or get-audience-subscriber, and no prerequisites or exclusion notes.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds nothing beyond that – no note on permissions, error behavior for an unknown subscriber, or whether membership must exist – so it contributes no behavioral context of its own.

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 short sentence with zero waste and the resource stated up front. It is efficient, though the brevity reflects under-specification rather than disciplined compression.

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

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

For a simple two-parameter read with full schema coverage and complete annotations, the definition is minimally sufficient. Still missing is any hint of the return payload (subscriber fields) or the failure mode when the subscriber is not in the audience, which would matter to an agent deciding whether to call this or list.

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 'id' (Audience ID) and 'subscriber_id' (Subscriber ID) documented inline, so the baseline is 3. The description's phrase 'subscriber of an audience' loosely maps to the two-parameter scoping but adds no format, validation, or lookup 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?

The description names a specific verb ('Retrieve') and resource ('one subscriber of an audience'), and 'one' distinguishes it from the list-audience-subscribers sibling. However, it does not distinguish this from other single-resource getters such as get-contact, nor does it name the sibling it is not, so the agent must infer the boundary.

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

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

There is no statement of when to use this tool versus list-audience-subscribers, get-contact, or update-audience-subscriber. The agent must infer usage entirely from the name and the presence of an 'id' + 'subscriber_id' pair.

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, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds one genuinely useful behavioral fact — that the response is a composite of steps and connections — but says nothing about depth, pagination, or whether missing IDs error.

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

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

A single front-loaded sentence with no filler; the payload hint ('steps and connections') is packed into the same clause rather than added as a separate line.

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

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

For a simple read-by-ID tool with full annotation coverage and a fully documented single parameter, the definition is essentially sufficient. The mention of steps and connections partially compensates for the absence of an output schema, though error behavior for an unknown ID is left unstated.

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 'id' parameter is documented as an automation ID with the 'aut_xxx' format, so the schema carries the meaning. The description adds no parameter-level detail, which is acceptable for a one-param tool at full 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 and resource ('Retrieve an automation') and clarifies the payload includes steps and connections, which distinguishes it from list-automations and from the narrower get-automation-run/get-automation-stats siblings. It doesn't explicitly name any sibling, but the scope is unambiguous.

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

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

No indication of when to use this versus list-automations (to discover IDs) or get-automation-run/step-stats (for execution data). The agent must infer the fetch-by-ID context entirely from the name and schema.

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, idempotentHint, and destructiveHint=false, so safety is covered. The description adds one genuinely new behavioral fact — the response embeds step history rather than just run metadata — but says nothing about pagination, size limits, or error behavior for a missing run.

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

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

A single front-loaded sentence with the resource named before the payload detail; zero redundant or filler text.

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

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

For a simple read tool with full annotation coverage and complete param docs, this is close to adequate, but with no output schema the description is the only source of return-shape information and provides just one clause (step history). Minimum viable rather than complete.

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

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

Schema description coverage is 100%, with both required params (id, run_id) documented including the aut_xxx format hint. The description adds no parameter-level meaning 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?

The description pairs a specific verb ("Retrieve") with a specific resource ("one automation run") and adds scope ("with its step history"). This clearly distinguishes it from list-automation-runs, though it doesn't explicitly name the sibling or clarify versus get-automation/get-automation-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?

"Retrieve one" hints at single-record lookup versus a list, but there is no explicit when-to-use statement, no prerequisite (e.g., requiring run_id from list-automation-runs), and no routing to alternatives like get-automation or get-automation-step-stats.

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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds that the result is aggregated counts rather than individual runs, which is useful context, but it says nothing about default time windowing, aggregation granularity, or timezone handling.

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

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

A single front-loaded sentence with no filler. It is efficient, though the extreme brevity leaves nothing to orient the caller beyond the core purpose.

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

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

For a simple read-only aggregation with fully described params and no output schema, the description conveys the return shape at a high level. It omits default date-range behavior and the fact that output is aggregate counts rather than a list, which an agent deciding between this and list-automation-runs would want.

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 id, since and until are already documented, including the aut_xxx format and ISO 8601 formats. The description adds no further semantics such as whether the range is inclusive, what happens when since/until are omitted, or which timezone 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?

Specific verb-plus-resource: returns aggregated run totals broken down by status and outcome for one automation. It is distinguishable from get-automation (entity detail) and list-automation-runs (raw runs), though it does not explicitly name the near-sibling get-automation-step-stats.

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

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

There is no statement of when to use this versus get-automation-step-stats or list-automation-runs, and no prerequisites or exclusions. The agent must infer the choice from the name alone.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description's only added behavioral value is disclosing that send_email steps return a delivery funnel, which is useful but thin; it says nothing about the shape of 'totals', time-window behavior, or what happens for steps in other 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?

A single, front-loaded sentence with zero filler. It is efficient but correspondingly sparse; no clause is wasted, though there is little structure to speak of.

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

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

There is no output schema, so the description carries the burden of describing returns; it names 'totals' and the send_email funnel but does not say what totals are included or what non-email steps return. Combined with a fully documented input schema and strong annotations, this is adequate but leaves a real gap for a stats 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% — id, step_key, since and until are all documented in the schema itself. The description adds no further semantics for any parameter (e.g., whether since/until are required for funnel data, or expected format for step_key), 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-plus-resource ('Return totals for one step') and adds scope detail about the delivery funnel for send_email steps. It implicitly contrasts with get-automation-stats (whole automation) via 'one step', but never names that sibling, so distinguishing requires 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?

Usage is only implied: 'one step' hints at per-step granularity versus automation-level stats, and the send_email funnel mention hints at when the extra data appears. There is no explicit when-to-use, when-not-to-use, or named alternative (e.g., get-automation-stats).

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, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds useful return-payload context (content, recipients, stats), but says nothing about behavior when the ID is unknown or ambiguous, and its "stats" claim overlaps confusingly with the dedicated get-campaign-stats sibling.

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 sentence, zero filler, and the most decision-relevant information (what comes back) is front-loaded immediately after the verb.

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's enumeration of returned data is the key contribution and it is present. For a read tool it is adequate, but it leaves the agent guessing about not-found behavior and about how name lookup resolves against ID lookup.

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 parameter already documents the cmp_xxx format and name alternative, so the schema carries the load. The description adds no syntax, resolution-order, or error semantics beyond it; 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 ("Retrieve a campaign") and even enumerates the payload (content, recipients, stats), which is more than a restatement of the title. It does not distinguish itself from nearby siblings like get-campaign-stats or list-campaigns, so an agent must infer the boundary.

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

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

There is no statement of when to use this versus get-campaign-stats (stats-only) or list-campaigns (enumeration), nor any note that the id accepts either an ID or a name at this level. Usage is only implied by the verb.

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, idempotentHint, destructiveHint: false and openWorldHint: false, so the safety profile is covered. The description adds genuine context beyond that by enumerating the metric families returned, including A/B variant results with leader and significance — content the agent otherwise could not anticipate 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?

One sentence, front-loaded with the resource and then the returned fields, with no filler. It is a noun phrase rather than a verb-led statement, which is slightly less directive, but nothing is wasted.

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

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

For a one-parameter read tool with no output schema, the description covers the main thing the agent needs — what data comes back. It stops short of noting edge cases such as stats being unavailable before a send or whether figures are live versus final.

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 'id' parameter already documents that it accepts a campaign ID (cmp_xxx) or name. The description adds nothing about the identifier, but with full schema coverage the baseline of 3 is appropriate.

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

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

The description names the resource (a sent campaign) and enumerates exactly what is returned — delivery, opens, clicks, bounces, unsubscribes, mailbox providers, and A/B results. That makes the purpose unmistakable, though it never explicitly contrasts with get-campaign (configuration) or get-automation-stats, which are the nearest siblings.

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

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

There is no statement of when to call this versus get-campaign, list-campaigns, or get-automation-stats, and no prerequisites such as 'the campaign must have been sent'. The agent must infer the usage context entirely from the tool name.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds no extra context such as what happens when the ID/email doesn't match (error vs empty), or that email lookup may be case-insensitive or 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?

One short, front-loaded sentence with no wasted words. It is sized appropriately for a trivial lookup, though it wastes its only sentence on information already in 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?

For a one-parameter read with full annotations and full schema coverage, the essential information is present. But with no output schema, the description could briefly say a contact object is returned and what a miss looks like, which it omits.

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 already documents 'Contact ID (con_xxx) or email address.' The description merely repeats that same fact, adding no new meaning such as precedence when both forms could match or whether email must be verified.

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 (retrieve) and resource (contact), and the get- prefix plus the description distinguish it from list-contacts and update-contact. However, it doesn't explicitly name the sibling boundaries the way a top score would.

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 name and the single-contact scope: look up one contact when you have an identifier. No explicit statement of when to use this versus list-contacts or the bulk/export alternatives, and no prerequisites.

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, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered elsewhere. The description contributes beyond that by stating this is the *default* workspace for the connection and that role and granted scope are returned, which is essential because 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 sentences with no waste; the returned content is stated first and the usage cue second. Every clause 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?

With no input parameters, full annotation coverage and no output schema, the description carries the burden of describing return values — which it does at field level (workspace, role, scope). It stops short of saying what happens if no default workspace exists or how the data is shaped, a minor gap for a simple identity tool.

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

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

The tool takes no parameters (parameter count 0, empty properties object), so there is nothing for the description to disambiguate. Baseline 4 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?

Uses a specific verb ('Return') with a specific resource ('the Emailit workspace this connection acts on by default') and enumerates what comes back: workspace, role, granted scope. It is clearly distinct from the many get-*/list-* siblings that target concrete resources like get-workspace-event or get-domain, though it never names an alternative.

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?

'Call it to confirm which account changes apply to' gives a concrete decision context for invoking it before mutating operations. There are no exclusions or named alternatives, but for a zero-parameter identity probe there is little ambiguity to resolve.

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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered without the description. The description adds nothing on top of that: no note about whether reports expire, how long forensic data is retained, or what happens if the report ID is unknown. With annotations carrying the entire behavioral burden, this is a minimal contribution.

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

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

A single front-loaded sentence with zero filler; nothing is redundant. It is efficient, though the brevity reflects under-specification rather than disciplined editing.

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

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

There is no output schema, so the description is the only place an agent could learn what a forensic report record contains, and it says nothing about the return shape. For a tool requiring both a domain ID and a report ID, the absence of any hint about the two-key lookup leaves a real gap.

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

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

Schema description coverage is 100% and both parameters (id as Domain ID, report_id as Forensic report ID) are documented in the schema. The description adds no meaning beyond that, so the baseline 3 applies. It notably does not explain the coupling between the domain ID and report ID, which is the one non-obvious aspect of the call.

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

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

The description states a verb ("Retrieve") and a resource ("one DMARC forensic report"), which is enough to know it fetches a single record. But it is essentially a restatement of the title and never distinguishes it from close siblings like get-dmarc-report or list-dmarc-forensic-reports. The word "one" is the only clue that this is a single-item fetch rather than a listing.

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

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

There is no guidance on when to use this instead of list-dmarc-forensic-reports or get-dmarc-report, and no stated prerequisites. The agent must infer usage purely from the tool name and its position among siblings.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful context that the report's records are returned inline, but says nothing about whether records are paginated or truncated for large reports, nor about error behavior when the report is not yet processed.

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

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

A single front-loaded sentence with zero filler. It is arguably too terse for a tool that returns a nested report body, but nothing in it 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?

With two fully documented required params and rich annotations, an agent can invoke this correctly, and there is no output schema to explain. Still, the description omits the return shape (report metadata plus the records array) and any retrieval caveats, leaving a modest gap for a report-fetching 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%, with both required parameters (domain 'id' and 'report_id') documented in the schema itself. The description adds nothing about the ID formats or the relationship between the two, 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?

Specific verb (retrieve) plus resource (one DMARC aggregate report) and it notes that the embedded records come back with it. The word 'aggregate' subtly distinguishes it from get-dmarc-forensic-report and from list-dmarc-reports, though no sibling is named 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?

There is no explicit statement of when to use this versus list-dmarc-reports or get-dmarc-forensic-report, nor any prerequisite about where id/report_id come from. The only signal is the word 'one', which implies single-item retrieval rather than listing.

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, idempotentHint, non-destructive and closed-world, so the safety profile is fully covered by structured fields. The description adds only that results are aggregated over a range; it says nothing about whether missing dates default to a window, whether the call is expensive, or the shape of returned counters.

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 eighteen-word sentence with the resource and the returned metrics front-loaded; nothing is padded or repeated. It is arguably too terse rather than too verbose, which costs less than padding.

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

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

With no output schema, the description carries the burden of describing the return value, and it does so only at a high level (pass/fail totals, alignment rates) without indicating structure or units. The optional from/to parameters and any default window are left unexplained, which is a real gap for a stats 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%: id, from, and to are each documented in the schema, so the baseline of 3 applies. The description adds no extra semantics such as whether from/to are inclusive, what happens if only id is supplied, or maximum range limits.

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 (implied retrieval) and resource: DMARC pass/fail totals and alignment rates for a domain over a date range. That is clear enough to act on, but it never distinguishes itself from close siblings like get-dmarc-report, get-dmarc-forensic-report, or list-dmarc-reports, which an agent must choose between.

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 'over a date range' hints at aggregated analysis rather than raw report retrieval, but there is no explicit when-to-use, no mention of prerequisites (e.g., DMARC reporting must be enabled, a report uploaded), and no routing to get-dmarc-report for individual reports. Usage must be fully inferred from the name.

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, idempotentHint, destructiveHint=false and a closed-world scope, so the safety profile is fully covered structurally. The description contributes some payload context by disclosing that DNS records and per-record verification status come back, but says nothing about lookup failures (unknown ID), pagination, or freshness of verification data.

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

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

A single front-loaded sentence with no filler, and the most decision-relevant detail (the returned DNS records and verification status) is placed before any alternative tooling would need to be considered.

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 read tool with full annotation coverage, the description is nearly sufficient, and it usefully previews the return contents despite there being no output schema. It falls just short on error behavior and on whether verification status is live or cached, which an agent acting on that field would want to know.

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?

One required parameter with 100% schema description coverage ('Domain ID.'), so the schema already carries the semantics and baseline 3 applies. The description adds nothing about the ID's format (UUID, hostname, or slug) or where an agent obtains a valid ID.

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 ('Retrieve') and resource ('a domain'), and additionally scopes the payload to DNS records and per-record verification status, which separates it from list-domains and from update-domain/verify-domain. It doesn't explicitly name a sibling, but the read-one-domain scope is unambiguous from the name-plus-description pair.

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: an agent can infer this is the single-domain fetch keyed by ID, with list-domains as the bulk alternative. There is no statement of when to prefer it, no mention of what to do if the domain is missing or unverified, and no pointer to verify-domain for acting on the verification status it returns.

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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is fully covered. The description adds only that the result includes status and delivery details — useful but thin, and it says nothing about what happens when the ID doesn't exist.

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 with no wasted words. It is sized appropriately, though its brevity is partly the source of the missing differentiation rather than pure efficiency.

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

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

There is no output schema, so the description must convey the return shape; 'status and delivery details' gestures at it but doesn't enumerate fields. For a simple single-record read with full annotation coverage this is close to adequate, but a bit more on the returned object would close the gap.

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

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

Single parameter with 100% schema description coverage ('Email ID (em_xxx)'), so the schema already carries the semantics. The description adds no extra meaning about the ID's format or source; 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 ('Retrieve') and resource ('a single email') and hints at the returned content ('status and delivery details'), which partially differentiates it from siblings like get-email-body and get-email-raw. However, it never explicitly says it is the email record/metadata view, so the boundary with get-email-meta remains blurry.

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

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

No when-to-use guidance and no mention of alternatives, despite five closely related siblings (get-email-body, get-email-meta, get-email-raw, get-email-attachments, get-email). The agent must infer that this is the general record fetch while the others retrieve specific parts.

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, idempotentHint, non-destructive, and closed-world behavior, so the description adds nothing new. It does not say what happens when an email has no attachments, whether attachment content is included or only metadata, or whether results are paginated.

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

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

A single front-loaded sentence with no waste. It is concise but borders on under-specified rather than tightly constructed.

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

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

No output schema exists, so the description carries the burden of explaining what is returned (attachment list, filenames, sizes, content, URLs). It does not, leaving the return shape entirely unknown to the agent.

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

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

There is a single parameter with 100% schema description coverage ('Email ID (em_xxx)'), so the schema does the work. The description adds no extra meaning about the ID format or lookup behavior, which is the baseline 3 case.

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

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

Clear verb+resource: 'Return the attachments of an email.' It implicitly distinguishes itself from siblings such as get-email-body and get-email-raw by naming the attachments specifically, but it never states that distinction 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?

There is no when-to-use guidance, no mention of alternatives like get-email or get-email-body, and no prerequisites. The agent must infer that this tool is for fetching attachment metadata/content for an already-known email ID.

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, idempotentHint, and non-destructive, so the safety profile is fully covered. The description adds the useful distinction that the body is parsed (text and HTML) rather than raw, but says nothing about behavior when a body is absent or in a non-text format.

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

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

One front-loaded sentence with no filler and no redundancy. It is appropriately sized for a simple single-parameter read, though it leaves room for a short disambiguating clause.

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 the burden of explaining the return value, and it does so only loosely ('text and HTML body'). It does not say whether both parts are always present or how they are keyed in the response, which matters for a tool whose whole purpose is returning two body formats.

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 'id' parameter is documented as an email ID with the em_xxx format. The description adds no semantics 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?

Uses a specific verb ('Return') and states exactly what resource is returned: the parsed text and HTML body of an email. However, it makes no attempt to distinguish itself from the numerous email-related siblings (get-email, get-email-raw, get-email-meta, get-email-attachments), which an agent must disambiguate by name alone.

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

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

There is no statement of when to use this instead of get-email-raw or get-email, which is the critical decision for an agent facing four sibling readers of the same email resource. Usage must be inferred entirely from the word 'parsed' versus sibling names.

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, idempotentHint=true, destructiveHint=false and openWorldHint=false, so safety and idempotency are covered. The description adds only the scoping fact that attachment content is excluded; it says nothing about authentication, size limits, or what happens with a missing/invalid email ID.

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 short sentence, front-loaded with the resource and carrying one useful qualifier. There is no filler or redundancy to trim.

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 must convey what 'metadata and headers' actually contains, and that term is left vague. Given the density of sibling email getters, a brief note on what fields are returned would make the definition complete.

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

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

There is a single required parameter with 100% schema description coverage ('Email ID (em_xxx)'), so the schema fully documents it. The description adds no additional meaning about the ID beyond the schema, which is the baseline-3 case.

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 ('Return email metadata and headers') and adds a scope limiter ('without attachment content') that separates it from get-email-attachments. It does not differentiate itself from close siblings get-email, get-email-body, or get-email-raw, so an agent still has to infer which getter to pick.

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

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

The phrase 'without attachment content' implies you should use this when attachments aren't needed, but there is no explicit when-to-use or when-not-to-use guidance and no named alternative. Against four sibling email-reading tools, the routing guidance is only implied.

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