SpacePost

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false. The description adds valuable auth context by requiring a `full_access` API key, though it does not describe the exact effect, reversibility, or 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?

The description is short, front-loaded with the action, and includes the auth requirement without unnecessary prose. The API metadata is compact and does not obscure the core instruction.

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 tool with rich annotations, the description covers purpose, auth, and endpoint. It could additionally state what happens on success or failure, but it is largely complete for correct invocation.

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

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

Schema description coverage is 100%, and the single `id` parameter is documented as 'The email id.' The endpoint path reinforces that the id identifies the email to cancel, but the description adds no further parameter 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 states a precise verb and resource: cancel a scheduled email. This clearly distinguishes it from siblings such as send_email, update_email, get_email, and list_emails.

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 states the required `full_access` API key, which is useful prerequisite context. However, it does not explain when to use this instead of alternatives like update_email or how to handle already-sent emails.

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

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

Annotations declare readOnlyHint=false and idempotentHint=false, so mutation and non-idempotency are already covered. The description adds context beyond that: the `token` is returned only in this response, which tells the agent the value cannot be retrieved later; and it notes the caller must hold a full_access key, which is an auth requirement not visible in the schema or annotations.

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

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

Three short, front-loaded sentences. The single-use token warning comes early where an agent will see it. The trailing API/operationId metadata is boilerplate but not disruptive.

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

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

There is no output schema, and the description covers the most important return-value fact (the token is shown once and never again), plus the auth prerequisite. It is nearly complete for a three-parameter creation tool on a public API; only the permission/name parameter semantics are absent.

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

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

Schema description coverage is only 33% (only domain_id is documented, including the full_access incompatibility), so the description should compensate for `name` and `permission`, but it says nothing about them. Its mention of full_access describes the caller's own credential, not the `permission` parameter's accepted values or default, so the gap remains.

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 uses a specific verb and resource ('Create an API key'), which is clearly distinct from list_api_keys and delete_api_key in the sibling set. It does not explicitly name those siblings, so it falls short of a 5, but an agent can identify the operation 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?

It states a prerequisite ('Requires a full_access API key'), which is genuinely useful for gating the call, but gives no guidance on when to choose this over alternatives or when not to create a key. Usage is implied rather than directed.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely new context: a `full_access` API key is required and the call maps to POST /audiences (operationId createAudience). It could still note duplicate-name behavior implied by idempotentHint=false.

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

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

Two short sentences, front-loaded with the action, with the endpoint metadata compactly appended. Nothing is padded, though the operationId/parenthetical is closer to internal bookkeeping than agent-facing guidance.

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 create tool with full annotation coverage and no output schema, the definition is close to sufficient. It still omits what an audience is in this system, whether names must be unique, and whether anything is returned on 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?

There is exactly one parameter (`name`) with 0% schema description coverage, and the description never mentions it or its constraints (1-100 chars). It should at least state that `name` is the audience label and whether uniqueness is enforced, since the schema supplies only type and length.

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'), which cleanly separates it from get_audience, list_audiences, delete_audience and update_* siblings. It does not explicitly contrast itself with any sibling, but the CRUD naming makes the role 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 guidance on when to create versus using an existing audience, no prerequisites beyond the API key tier, and no mention of how it relates to create_contact/create_broadcast workflows. 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 cover the safety profile (readOnly=false, destructive=false, idempotent=false), and the description adds value beyond them: the result is a draft rather than a sent broadcast, the required auth tier is `full_access`, and two preconditions on inputs must hold. It omits what happens on invalid domain/audience or what the created draft contains.

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?

Compact and front-loaded: purpose, then output state, then constraints, then auth/endpoint. The opening sentence only restates the tool name and title, which is the one wasted line in an otherwise tight description.

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

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

For an 8-parameter mutation with 25% schema coverage and no output schema, the description covers auth and two key input constraints but says nothing about the remaining optional body fields or what a successful response returns (e.g., a broadcast id for later send_broadcast). 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 only 25%, so the description must compensate. It adds real semantics for two of eight params — `from` must belong to a verified domain and `audience_id` must be an existing audience — but leaves `html`, `text`, `preview_text`, `subject`, and `name` unexplained beyond the schema's own types and 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 and resource ('Create a broadcast') and immediately clarifies the output state ('Creates a draft'), which separates it from send_broadcast and update_broadcast in the sibling list. It does not explicitly name those siblings, 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?

Gives concrete preconditions that determine when this call will succeed: a `from` address on a verified team domain, an `audience_id` from the caller's audiences, and a `full_access` API key. The 'creates a draft' framing implies sending is a separate step, but no alternative tool is named and no 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?

Annotations already cover the safety profile (non-readonly, non-destructive, non-idempotent), and the description adds real value beyond them: emails are lower-cased, addresses must be unique per audience, and a `full_access` API key is required. These are exactly the preconditions an agent needs before calling a mutating write.

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

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

Three short, front-loaded sentences with no filler: the action first, then constraints, then auth/endpoint metadata. The endpoint and operationId are slightly internal but cheap and useful for an API-backed tool.

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

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

For a five-parameter mutation with zero schema description coverage and no output schema, the description omits what the optional fields mean, what is returned (e.g. the created contact or an ID), and what happens on the duplicate-email collision beyond that it 'can only appear once'. That is a meaningful 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 0%, so the description carries the full burden for all five parameters, but it only touches email normalization and says nothing about first_name, last_name, unsubscribed, or the audience_id UUID format. The agent gets types and maxLength from the schema but no semantic guidance from the description.

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

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

The opening sentence states a specific verb and resource ('Create a contact'), and the API endpoint plus operationId make the operation unambiguous. It doesn't explicitly name a sibling like update_contact, but 'create' vs 'update'/'delete' is clear enough from the name and verb.

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 agent must infer that this is for adding a new contact rather than updating an existing one. The uniqueness rule ('An address can only appear once per audience') hints at failure conditions, not at when to prefer create_contact over update_contact, and no exclusions or alternatives are named.

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?

Adds substantial context beyond the annotations: auth requirement (full_access key), global name uniqueness, plan-based quotas, the exact contents of the returned DNS records (three DKIM CNAMEs, MAIL FROM MX and SPF TXT), and propagation timing (minutes to hours). None of that is derivable from readOnlyHint=false / idempotentHint=false.

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

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

Front-loads the operation and the returned records, with constraints and next steps following in a sensible order. The DNS record list is stated twice (paragraphs one and three), which is minor redundancy that could be trimmed.

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

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

No output schema exists, so the description carries the burden of describing the return value — and it does, enumerating the DNS records and warning about propagation delay. Prerequisites, quota limits, and the verify/get follow-up chain close the loop for a mutation tool.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns one above by explaining that the MAIL FROM subdomain is what receives the MX/SPF records (illuminating custom_return_path) and that a domain is attributed to a tenant. It does not address the region parameter, which is left entirely 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+resource ('Create a domain', 'Registers a domain and returns the DNS records') and immediately distinguishes it from get_domain/list_domains/update_domain by describing the write and its return payload. An agent can tell exactly what this does without opening the schema.

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

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

Explicitly prescribes the follow-up sequence ('afterwards call verify_domain and then get_domain') and states the prerequisites (full_access API key, plan ceilings Free 3 / Pro 10 / Scale 1,000). It lacks an explicit exclusion against update_domain for existing domains, but the create-only framing plus downstream routing is strong 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?

Beyond the annotations, the description discloses the auth tier (`full_access` key), the fixed reason value applied, the endpoint/operationId, and the dedupe behavior of re-adding an existing address. One nuance worth noting: annotations declare `idempotentHint: false`, yet the stated 'returns the existing entry' behavior implies repeated calls have no additional effect — an agent doing retry logic could be misled, but this is a hint-level tension rather than a direct safety contradiction.

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

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

Three short, front-loaded lines with no filler; the only redundancy is restating 'Add a suppression' from the title before the substantive detail.

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 create tool with no output schema, this covers the essentials: auth requirement, side-effect semantics, and idempotent-ish re-add behavior. Minor omissions are what 'reason `manual`' implies (other reasons exist but are not settable here) and the downstream effect of suppressing an address.

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

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

The schema is present but has 0% description coverage for the single `email` parameter. The description only refers to "the address", adding no normalization rules, case handling, or validation detail beyond the schema's `format: email`.

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

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

The description states a specific verb and resource ("Add a suppression") and clarifies what it actually writes (the address with reason `manual`). It is distinguishable from delete_suppression and list_suppressions by name alone, though it never explicitly names those siblings.

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

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

It gives the prerequisite (a `full_access` API key) and the re-add behavior, which helps an agent decide to call it safely, but it never states when to use this versus delete_suppression/list_suppressions or what business situation warrants suppressing an address.

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

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

Beyond the annotations (which only declare non-readonly, non-idempotent, non-destructive), the description adds a concrete auth requirement (full_access API key) and a uniqueness constraint on external_id that an agent cannot get from annotations. It does not say what happens on a duplicate external_id or whether the tenant is immediately active.

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?

Short and front-loaded: purpose first, then domain clarification, then the key constraint, then auth, then the endpoint. The opening line 'Create a tenant.' merely restates the title and could be folded into the next sentence, but the rest is dense with no waste.

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 never indicates what a successful creation returns (an id? an object?). Nor does it describe duplicate-external_id failure behavior. The auth and endpoint details are genuinely useful, but a non-idempotent create tool leaves an agent guessing about the response shape.

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% (name undocumented), and the description compensates by documenting the external_id uniqueness rule within the account, which is a server-side constraint rather than a type detail. daily_limit is left to the schema, which already explains it adequately.

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 and goes further by explaining the domain object: a tenant is a customer with its own isolated SES reputation. That distinguishes it well from list_tenants/get_tenant. It does not explicitly contrast with the other create_* siblings, but the verb+resource pair 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 framing ('creates one of your customers, with its own SES tenant (isolated reputation)') implies when you'd reach for it rather than create_domain or create_contact, but there is no explicit when-to-use / when-not statement or named alternative. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so the mutation profile is known. The description adds meaningful context beyond that: an authentication requirement (full_access key) and a production-only constraint that the endpoint must be https and resolve to a public address. It stops short of noting whether a signing secret is returned or what happens on validation failure.

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

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

Four short lines, each earning its place: purpose, production constraint, auth requirement, and API mapping. The scoping constraint is front-loaded and nothing is padded.

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

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

With annotations covering the safety profile and no output schema, the description is close to sufficient, but for a webhook-creation tool it omits important expectations — notably whether a signing secret or webhook ID is returned and what verification steps follow. Coverage of the auth and endpoint constraints is good, but the post-creation contract is left implicit.

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

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

Schema coverage is 50%, with endpoint and the events item enum documented in-schema. The description reinforces the https-in-production rule and adds the public-address resolution requirement, which the schema does not state, but it says nothing about the events array semantics (e.g., subscribing to multiple events) beyond what the schema provides. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Create a webhook') and includes the underlying API operation (POST /webhooks, createWebhook), so an agent can identify it unambiguously against create_* siblings. It does not explicitly contrast with update_webhook or delete_webhook, but the verb makes the distinction apparent.

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

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

The description gives a real prerequisite ('Requires a full_access API key') and a production constraint, which helps decide feasibility. However, it offers no explicit when-to-use guidance versus alternatives like create_api_key or update_webhook, leaving usage context implied by 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?

Goes well beyond annotations by disclosing that the key stops working immediately, that the response body is an empty object, and that a full_access key is required. These are real behavioral facts an agent cannot infer from destructiveHint/idempotentHint alone.

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

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

Three short lines, front-loaded with the action and the immediate effect, then the auth requirement, then the API mapping. No sentence is filler.

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

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

Covers effect, return value, and auth requirement for a one-parameter destructive tool with no output schema. It leaves out what happens to existing requests in flight or whether the id must belong to the caller's tenant, but the essentials are present.

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

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

Schema description coverage is 0% and the single required `id` is documented only through the `DELETE /api-keys/{id}` path template. That maps the parameter to its role, but the description never says it's the API key's UUID identifier distinct from tenant/domain ids.

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 ('Delete an API key') and is unmistakable against siblings like list_api_keys and create_api_key. The added endpoint and operationId confirm the exact resource being destroyed.

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 makes the prerequisite explicit ('Requires a full_access API key'), which is the key gating condition for calling it. It does not name alternatives (e.g., rotate vs. delete, or create_api_key for replacement), so it stops short of full when/when-not guidance.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, so the bar is lower, yet the description adds the crucial non-obvious consequence that contacts are destroyed too, plus the auth tier needed. That is exactly the extra context 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?

Very short and front-loaded: purpose first, then the cascade warning, then prerequisites and endpoint. The `operationId`/`Audiences` provenance tag is extra detail but costs little.

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

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

For a single-parameter destructive tool with no output schema and rich annotations, the description covers purpose, cascade side effect, and auth requirement—enough to call it safely. Only error/not-found behavior is 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?

There is one required `id` parameter with 0% schema description coverage, and the description only implies its meaning via the `DELETE /audiences/{id}` path template. It doesn't state the expected UUID format or what an invalid id yields.

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 audience') and immediately names the cascading effect. The resource name itself distinguishes it from delete_contact/delete_domain and other delete siblings, though no explicit sibling comparison is made.

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

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

Gives a concrete prerequisite ('Requires a `full_access` API key') and the underlying endpoint, which tells an agent when the call will succeed. It does not, however, state when to prefer an alternative such as removing contacts individually.

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 structurally. The description adds real value beyond that: the eligibility window (drafts/future-scheduled only) and the `full_access` API key requirement, both of which the annotations cannot express. It stops short of 5 because it does not say whether deletion is permanent or recoverable.

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

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

Three tight sentences with the operation named first, the precondition second, and auth/endpoint metadata last. No filler, and nothing important 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?

For a destructive single-parameter tool with full annotation coverage and no output schema, the definition covers the essentials: what is deleted, which objects are eligible, and the required key scope. The remaining gap is outcome semantics — whether the deletion is reversible and whether recipients or analytics are affected.

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% for the single `id` parameter, so the description must compensate. It does so only indirectly via the endpoint template `DELETE /broadcasts/{id}`, which implies the id is a broadcast identifier matching the uuid format, but it adds no further constraints such as whether a draft vs. scheduled id behaves differently.

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

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

States a specific verb and resource ('Delete a broadcast') that is unambiguously distinct from send_broadcast, update_broadcast, and cancel_email. It does not name a sibling or contrast with one, so it stops short of the top tier, but an agent can identify the operation 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?

Gives a concrete applicability constraint: only drafts and broadcasts scheduled in the future may be deleted, which implicitly excludes already-sent or in-flight broadcasts. It does not, however, point to an alternative (e.g. cancel_email for stopping a scheduled send), so the routing guidance is incomplete.

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 description doesn't need to restate destruction. It does add genuinely new context: the `full_access` API key requirement, which the agent cannot infer from annotations. It still omits whether the deletion is permanent, whether the contact can be restored, and whether related sends/history 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?

The destructive action is front-loaded in the first sentence, and the auth and endpoint facts follow compactly. The `operationId` and parenthetical group name are of marginal value to an agent selecting a tool, but cost little.

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

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

For a 2-parameter, no-output-schema tool with rich annotations, the definition covers the action, the auth gate, and the target endpoint. Only the outcome of deletion (permanence, side effects on related data) is missing, which is a modest gap 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 only 50% – `audience_id` has no description in the schema. The endpoint template clarifies that `id_or_email` is a path segment scoped by audience, which reinforces the email-encoding note, but the description adds no explicit meaning for `audience_id` beyond its position in the URL.

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

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

Names a specific destructive verb and resource ('Delete a contact'), which is unambiguous against siblings like delete_audience or delete_suppression. However, it offers no explicit differentiation from those siblings beyond the resource noun in the name.

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

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

The description never says when to delete versus when to use update_contact, or how this interacts with suppression lists or cancel_email. No when-not or prerequisites are given beyond the auth requirement.

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 structurally. The description adds genuinely useful context by naming the `full_access` API key requirement and the underlying `DELETE /domains/{id}` operation, but it says nothing about what happens to associated resources (domains, senders, DNS records) or whether deletion is recoverable.

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

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

Three short lines with the action front-loaded and zero filler; the auth and endpoint facts are stated compactly with no repetition of the schema 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 destructive, non-reversible operation with no output schema and an undocumented parameter, the description covers auth and the underlying API call but omits consequences (cascading deletions, effect on in-flight sends, error conditions). An agent could invoke it correctly but cannot judge risk from the text alone.

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

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

Schema description coverage is 0% and the single `id` parameter is undocumented in the schema, so the description carries the burden. It partially compensates by exposing the endpoint `DELETE /domains/{id}`, which implies the id is the domain identifier used in the path, but it never states that explicitly or notes format expectations beyond the uuid type.

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 ("Delete a domain") that maps directly to the tool name and title. It is unambiguous about what the tool does, though it offers no explicit differentiation from sibling mutators such as update_domain or verify_domain.

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 alternatives like update_domain or verify_domain, and no warning that deletion is irreversible or when it should be avoided. The only usage-relevant statement is the authentication prerequisite, which is a constraint rather than a use-case 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 destructiveHint=true, idempotentHint=true and readOnlyHint=false, and the description usefully adds a prerequisite the annotations don't carry: a `full_access` API key is required. It stops short of stating the consequence (that mail to the address will resume sending) or whether the deletion is reversible.

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

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

Front-loaded with the action in a single short sentence, with the auth requirement immediately after. The trailing API route and operationId are low-value metadata for an agent but do no real harm.

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 safety profile is fully covered by annotations and whose parameter is fully documented in the schema, the description says enough to invoke it correctly. The main omission is the downstream effect of removing a suppression.

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

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

Schema description coverage is 100% and the single parameter is already documented in the schema, including that the email must be URL-encoded. The description adds no syntax, format, or lookup guidance beyond that, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Remove a suppression') that is unambiguous and clearly the inverse of the sibling create_suppression. It doesn't explicitly contrast with list_suppressions or explain what a suppression is, but the operation itself is unmistakable.

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

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

Usage is implied by the verb and resource — an agent would call this to delete an entry from the suppression list. There is no explicit when-to-use/when-not-to-use guidance and no mention of the related validate/unsuppress workflow, leaving routing to inference.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral facts: a specific failure mode (422 with existing domains) and an auth requirement (`full_access` key). It does not spell out permanence/irreversibility of the deletion, so it isn't fully exhaustive.

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

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

The core statement, the 422 precondition, and the auth requirement are all front-loaded and short. The trailing API/operationId line is useful for API parity but is boilerplate that doesn't help an agent decide or invoke.

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, the definition covers purpose, prerequisite ordering, and auth, and annotations cover the safety semantics. No output schema exists, and for a delete the only missing detail is whether anything is returned or whether deletion is immediate vs. scheduled — a minor 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% — the single `ref` parameter is already documented in the schema as 'the tenant id or your own external_id', with examples and length bounds. The description adds nothing about `ref` and doesn't need to; baseline 3 applies since the schema does the work.

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

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

States a specific verb and resource ('Delete a tenant') and pins it to the concrete API operation `DELETE /tenants/{ref}` (operationId `deleteTenant`). The verb+resource pair is unambiguous against siblings like delete_domain, delete_api_key, or pause_tenant, though it never explicitly says how it differs from those.

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

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

Gives a concrete precondition: it fails with `422` while the tenant still has domains, and instructs to delete those first — effectively telling the agent a prerequisite call to make before this one. It also states the `full_access` API key requirement. No explicit alternative (e.g. pause_tenant vs delete_tenant) is offered, so it stops short of a 5.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuinely new behavioral context the annotations do not: the required permission level (`full_access` API key) and the underlying endpoint/method. It stops short of saying the deletion is permanent or what happens to in-flight deliveries.

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

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

Two short sentences with the action front-loaded and the access prerequisite immediately after. The parenthetical operationId and service name are marginally useful for debugging but add little for tool selection.

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 deletion tool with full annotation coverage, the description covers what an agent needs: what it destroys, what credentials are required, and the backing endpoint. Lack of return-value information is acceptable since there is no output schema and the operation is a simple delete.

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 burden is on the description. The endpoint form `DELETE /webhooks/{id}` does implicitly identify `id` as the path identifier of the webhook to remove, but no format, sourcing, or error behavior is explained beyond that.

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

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

States a specific verb and resource ('Delete a webhook'), which unambiguously separates it from the many sibling delete_* tools (delete_contact, delete_domain, etc.) by resource. It is essentially the title restated, so it earns clarity through noun precision rather than added detail.

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

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

The 'Requires a `full_access` API key' line functions as a precondition, which is useful usage guidance, but there is no explicit when-to-use/when-not or mention of alternatives such as update_webhook or cancel/pause flows. 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds genuinely useful context: the required `full_access` API key scope and the underlying endpoint/operationId, which helps with auth planning and error interpretation.

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, with the permission and endpoint detail trailing. Nothing is wasted, though the API metadata is somewhat incidental to selection.

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 single-parameter read tool with rich annotations and no output schema, the description covers what an agent needs to call it correctly: the action, the access requirement, and the endpoint. Only minor gaps remain (e.g., behavior on a missing/invalid ID).

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% and the single `id` parameter is only typed as a UUID with no explanation. The endpoint reference `GET /audiences/{id}` implicitly tells the agent this is an audience identifier, but no format, source, or examples are given beyond the type.

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 (an audience), which cleanly separates it from list_audiences, create_audience, and delete_audience without needing the schema. It does not explicitly mention the siblings, but the action/resource pair 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 gives no guidance on when to use this versus list_audiences or get_broadcast, nor does it describe prerequisites beyond the API key requirement. The agent must infer that this is for fetching a single audience by 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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds a genuinely useful constraint not in annotations — it requires a `full_access` API key — plus the underlying endpoint, but says nothing about behavior on missing records or the shape of the result.

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?

Extremely compact and front-loaded: the action comes first, then the auth prerequisite, then the endpoint reference. No wasted wording, though the operationId and product-name tail add little for an agent.

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

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

For a single-parameter read tool with annotations covering safety and no output schema, the core facts an agent needs (what it fetches, auth requirement, endpoint) are present. It could go further by describing the returned broadcast or error behavior, but nothing essential is missing.

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

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

Schema description coverage is 0% for the single `id` parameter, so the description must carry the burden. It only hints at the parameter via the `{id}` path template; it never states that the id identifies the broadcast, nor any format or validation expectations.

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 broadcast"), which is unambiguous. However, it does not distinguish itself from nearby siblings such as get_broadcast_readiness or list_broadcasts, so the agent must infer the difference from the names alone.

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

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

There is no guidance on when to use this versus list_broadcasts or get_broadcast_readiness, and no note on when it fails (e.g., unknown id). The only contextual statement is the API key requirement, which is a prerequisite rather than usage 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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial context beyond that: the full checklist scope, the blocking rule for `error` vs `warning` levels, the `full_access` API key requirement, and that it is not part of the Resend core API.

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

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

Front-loaded with purpose, then the return shape, then the blocking rule and auth requirement. The long checklist enumeration is dense but each item adds real value. Minor tightening possible around the parenthetical asides.

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 describing return values — and it does: the checklist categories and the `ready` boolean semantics with error/warning levels. Auth requirements and failure behavior are also covered. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 0% and the single `id` parameter is undocumented in both schema and description text directly, but the endpoint reference `GET /broadcasts/{id}/readiness` makes it inferable that `id` is a broadcast identifier. That indirect hint is enough to avoid a lower score, but explicit 'UUID of the broadcast' wording is missing.

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 ('Check a broadcast before sending') and immediately clarifies it is a SpacePost extension returning a deliverability checklist. This distinguishes it clearly from get_broadcast (fetch data) and send_broadcast (perform the send).

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 frames the tool as a pre-send gate: 'ready is false when any check has level error; POST /broadcasts/{id}/send is then refused'. That tells the agent when to call it and what happens otherwise. It stops short of naming send_broadcast as the follow-up tool or saying when-not to bother running it.

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 genuinely new context: a `full_access` API key is required and the exact REST endpoint and operationId are given, which helps an agent diagnose auth failures and reason about the call surface.

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

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

Very short and front-loaded with the action, then the prerequisite and endpoint. The operationId/"Contacts" tag metadata is arguably noise for tool selection, but overall there is little waste.

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

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

With no output schema and annotations covering safety, the description is close to sufficient, but for a lookup tool it omits what is returned and what happens when the contact does not exist (404 vs. empty), which an agent needs to plan error handling.

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%: id_or_email is well documented in the schema, but audience_id has no description at all. The endpoint template `GET /audiences/{audienceId}/contacts/{idOrEmail}` partially compensates by showing both parameters' roles, but the meaning/constraints of audience_id remain unstated.

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?

"Retrieve a contact" is a verb+resource but is essentially a restatement of the tool name and title, and the added endpoint path does most of the disambiguating work. It never distinguishes this single-record fetch from siblings like list_contacts, update_contact, or the audience-scoped variants.

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

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

No guidance on when to use this vs. list_contacts (bulk) or get_audience. There is a hard prerequisite (a `full_access` API key), but that is an auth constraint rather than a when-to-use rule, and no exclusions or lookup-fallback behavior 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?

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is fully covered without prose. The description adds the non-obvious authorization requirement (`full_access` API key) and the canonical endpoint/operationId, which is real context beyond the structured fields. It omits behavior when the id does not exist (e.g., a 404), keeping it out of the top band.

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 identity of the operation first and the prerequisite second. No filler, no restatement of the title beyond what is needed.

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 complete annotations, the description covers the call mechanics and auth. However, there is no output schema and the description never says what a domain record contains or how failures are signaled, so the return contract is undocumented anywhere in the definition.

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 0%, so the schema alone only says `id: string (uuid)` with no meaning attached. The description partially compensates by showing the path template `GET /domains/{id}`, making clear the id identifies a domain, but adds no format hints, sourcing guidance, or note on whether the id is the domain's UUID or a name.

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+resource ("Retrieve a domain") and pins it to the exact endpoint `GET /domains/{id}` (operationId `getDomain`), which unambiguously separates it from list_domains or get_audience. It never explicitly names a sibling to contrast with, 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?

There is no statement of when to use this versus list_domains, get_domain's update/delete/verify siblings, or how the caller should already know the id. The only conditional content is an API-key prerequisite, which is a gating requirement rather than usage guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely new context that annotations cannot express: the `full_access` API key requirement, plus the concrete endpoint and operationId for tracing. It does not describe error behavior (e.g. 404 on missing id), which keeps it below 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 short sentences, zero filler, and the purpose is front-loaded before the auth and endpoint details. 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 read tool with full annotation coverage and no output schema, the definition gives everything needed to call it: purpose, required credential, and endpoint. The residual gap is the return shape and missing-id behavior, which an agent must guess, but this is minor for a trivial fetch.

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 a uuid, so the schema carries the load. The description's `GET /emails/{id}` adds the useful detail that the id is a path parameter, but nothing about form or lookup semantics beyond that — baseline 3 applies.

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

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

States a specific verb ('Retrieve') and resource ('an email'), so the operation is unambiguous, and the endpoint `GET /emails/{id}` confirms it is a single-record fetch. It never distinguishes itself from the closest sibling `list_emails`, leaving the agent to infer that this one requires an id and returns one email.

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 required `id` parameter and the `/emails/{id}` path — the agent can reason that this is for fetching a known email rather than enumerating. There is no explicit statement of when to prefer this over `list_emails`, nor any note about what happens if the id is unknown or belongs to a different tenant.

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 information the annotations do not: the required `full_access` API key scope and the underlying endpoint. It omits error behavior (e.g., unknown ref) but that is a minor gap for a simple read.

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: purpose first, then the auth and endpoint facts. Every clause carries usable information and nothing is padded.

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

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

For a one-parameter read with full schema coverage and a complete annotation set, the definition covers purpose, auth, and endpoint. It lacks only failure-mode behavior (what happens when the ref doesn't resolve), which is a modest omission rather than a blocking one.

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

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

Schema description coverage is 100%, and the `ref` schema already documents "The tenant id or your own `external_id`". The description adds nothing about ref format or resolution order, so the baseline 3 applies when the schema does the explanatory work.

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

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

States a specific verb plus resource ("Retrieve a tenant") and includes the exact endpoint and operationId, making the single-resource read unambiguous. It doesn't explicitly contrast with list_tenants or get_audience, but the singular resource name carries most of that 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 description gives a hard prerequisite ("Requires a `full_access` API key"), which is real usage guidance. However, it never says when to prefer this over list_tenants or how it relates to update_tenant/delete_tenant, so the when-to-use reasoning is only implied by the tool name.

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

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 contributes the `full_access` auth requirement, which is genuine added context, but omits error behavior (e.g., not-found handling) and whether the full webhook object is returned for a tool with 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, no padding, with the auth and endpoint facts front-loaded after the purpose statement. The first sentence largely restates the tool name/title, so it does not fully earn its place, but the total length is appropriate.

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 single-resource read tool with one parameter and no output schema, the definition covers identity, auth, and endpoint. It still leaves an agent without the id format/derivation and without any expectation of the payload or failure mode, which are relevant given the absent output schema.

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

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

Schema description coverage is 0% and the single `id` parameter has no description in the schema, so the description must carry the burden. The path template `GET /webhooks/{id}` indirectly indicates that `id` identifies the webhook, but it never says the value is the webhook's UUID or how to obtain it, leaving the gap only partially closed.

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 a webhook') and reinforces it with the concrete API path `GET /webhooks/{id}` and operationId, making the scope (single webhook fetched by id, versus list_webhooks or delete_webhook) unambiguous. It does not explicitly name a sibling to route away from, which caps it below 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 required `full_access` API key is a useful precondition, but the description never states when to prefer this over list_webhooks or get_* alternatives, nor what happens when the id is unknown. Usage is implied by the singular resource + id pattern rather than explained.

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 genuinely new context: the required credential scope (`full_access`) and the underlying endpoint/operationId, which helps with tracing and permission failures. Pagination behavior is left entirely to the schema.

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

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

Three short lines, front-loaded with the purpose, then the auth requirement, then the endpoint mapping. No filler, though the endpoint/operationId parenthetical is more useful to a developer than to an invoking agent.

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

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

For a zero-required-param, read-only list tool with a fully documented schema and complete annotations, nothing an agent needs in order to call it correctly is missing; the one non-obvious gating fact, the API key tier, is stated.

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% – after/before/limit are each documented including the mutual exclusion of the cursors. The description adds nothing about parameters, 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 ('List API keys') that is unambiguously distinct from the create_api_key and delete_api_key siblings. It does not explicitly name those siblings, so it stops short of active 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 prerequisite 'Requires a `full_access` API key' is a real usage constraint that tells an agent whether it can call this at all. However, there is no guidance on when to use this versus the create/delete API key tools or how pagination is expected to be driven.

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 structurally. The description adds genuine context beyond that with the `full_access` key prerequisite, but says nothing about the paginated response shape, ordering, or result-set size — meaningful gaps for a list operation.

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

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

Two short sentences, front-loaded with the resource and followed by the operational prerequisite and endpoint. Zero padding; the only miss is that it omits useful pagination behavior rather than being overlong.

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

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

There is no output schema, so the description should hint at what a list call returns (items array, has-more/cursor semantics), and it does not. The auth note is helpful, but for a cursor-paginated list tool the definition is only minimally 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% and each of the three pagination params is documented in the schema, including the mutual-exclusion rule between `after` and `before`. The description adds no parameter semantics at all, 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 says "List audiences" plus the API endpoint and operationId, which is a specific verb+resource but largely restates the tool name and title. It does nothing to distinguish this from siblings like get_audience or list_contacts, so an agent must infer the collection-vs-single difference from names alone.

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

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

The only guidance is the auth requirement ("Requires a `full_access` API key"). It never states when to use this versus get_audience, nor does it mention pagination navigation as a use case, so there is essentially no when-to-use framing.

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 covered. The description adds the auth requirement (`full_access` key) and the underlying HTTP endpoint, which are useful beyond the annotations, but says nothing about pagination behavior, result ordering, or volume beyond what the schema implies.

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

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

Two short sentences with no filler, and the auth constraint is stated up front. The trailing parenthetical '(operationId `listBroadcasts`, Broadcasts)' adds little for an agent and is slightly noisy, but the overall size is appropriate.

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 100% schema coverage and annotations carrying the safety profile, and no output schema required, the essentials are present. However, for a paginated list tool the description never mentions that results are paginated or how the page tokens work, leaving the agent to infer this from parameter names alone.

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

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

Schema description coverage is 100%, and all three parameters (after, limit, before) are fully documented in the schema including the mutual-exclusion rule between after and before. The description contributes nothing on parameters, so baseline 3 applies.

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

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

The description restates the tool name almost verbatim ('List broadcasts') rather than adding a distinct verb+resource framing, and does not differentiate this from sibling list_* tools or from get_broadcast. It does add the concrete endpoint and operationId, which confirms the resource being listed, but the semantic content is largely tautological.

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

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

The only guidance is the prerequisite that a `full_access` API key is required, which is genuinely useful. There is no indication of when to choose this tool over get_broadcast for a single record, or over the other list_* siblings, and no exclusions or context are given.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=false, so the safety profile is covered. The description adds useful non-schema context by disclosing that a 'full_access' API key is required and naming the underlying API endpoint/operation.

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

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

The description is two short sentences, front-loaded with the tool purpose and followed by operational requirements. There is no filler or redundant restatement.

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 list tool with rich annotations and 75% schema coverage, the description supplies the key missing operational context: required auth level and endpoint. It does not describe the response shape, but the core invocation requirements are sufficiently covered.

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

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

Schema description coverage is 75%, with after/limit/before documented but audience_id left without a schema description. The description only indirectly clarifies audience scoping through the API path and does not add paging semantics beyond what the schema already provides.

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

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

The description states a specific verb and resource: 'List contacts.' It is immediately clear what the tool does, though it does not distinguish itself from siblings such as get_contact or list_audiences.

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 API path '/audiences/{audienceId}/contacts' implies listing contacts within a specific audience. The description gives no explicit guidance on when to use this tool versus get_contact or other list_* tools, and no 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 annotations already establish that this is a safe, read-only, idempotent, non-destructive operation. The description adds practical behavioral context beyond the annotations by disclosing the `full_access` API key requirement and the underlying `GET /domains` endpoint. It does not mention rate limits or pagination behavior, so a 4 rather than 5.

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

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

The description is two short sentences and front-loads the core purpose before the auth and endpoint details. Every sentence provides useful information, with no padding or repetition.

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

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

For a simple read-only list tool with full parameter documentation and complete annotations, the description supplies the key missing context: auth requirements and the API endpoint. It is nearly complete, though it could mention pagination behavior for extra clarity.

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 three pagination parameters (`after`, `limit`, `before`) are fully documented in the schema. The description adds no parameter-specific meaning beyond what the schema already provides, so 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 uses a clear verb+resource phrase, "List domains," and provides the backing endpoint `GET /domains`, so the operation is unambiguous. It does not explicitly distinguish itself from sibling tools such as `get_domain` or other `list_*` tools, 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?

The description states the prerequisite "Requires a `full_access` API key," which is useful usage context. However, it does not say when to choose this tool versus alternatives like `get_domain` or explain pagination behavior, so usage is only implied by the name and endpoint.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed world), yet the description still adds real value: authentication scope (full_access key), result ordering (newest first), and payload shape (bodies omitted). Rate limits or a total-count/next-page-flag note would be the only remaining gaps.

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

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

Front-loaded one-sentence summary followed by a tight behavior line and a prerequisite line; nothing is buried. The trailing 'API: GET /emails (operationId listEmails, Emails)' line is reference metadata that adds little for an agent choosing a tool.

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

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

For a read-only list tool with no output schema and a fully documented schema, the description covers ordering, payload exclusions, and auth. Only pagination mechanics (how to obtain the cursor ids in practice) are left implicit.

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

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

Schema coverage is 100% and the schema already documents before/after mutual exclusion and the 1–100 limit range, so the description can legitimately defer. It adds nothing parameter-specific (e.g., that cursors are opaque ids from a prior response), 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 ('List emails') and immediately narrows scope: sent and scheduled emails, newest first, bodies excluded. That scope detail separates it implicitly from get_email, though the sibling is never named.

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

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

The prerequisite ('Requires a `full_access` API key') is useful routing context, and the 'no bodies' note hints at when to reach for get_email instead. But no alternative is named and no exclusion or when-not condition is given.

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 structurally. The description earns credit for disclosing a hard behavioral constraint annotations cannot express: a full_access API key is required, which materially affects whether an agent can call this 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, front-loaded with the operation and followed by the access constraint. The trailing API metadata (operationId, endpoint, group name) is mildly noisy but compact and does not bury the key information.

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

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

For a simple read-only list tool with full schema coverage and no output schema, the essentials (operation, auth) are present. However, it gives no indication of what a suppression record contains or what ordering the list follows, leaving the agent to infer return shape entirely.

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

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

Schema coverage is 100%, so all three parameters (after, limit, before) including the mutual-exclusion rule are documented in the schema itself. The description adds no additional parameter meaning, which is the expected baseline given 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?

The description is essentially the name restated: 'List suppressions' names a verb and a specific resource, so an agent knows the object domain, but there is no differentiation from siblings like create_suppression, delete_suppression, or the list_* family. It is minimum viable rather than informative.

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

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

The only guidance is the authentication prerequisite ('Requires a `full_access` API key'). Nothing says when to use this versus get/list alternatives or what problem it solves, and there are no exclusions or preconditions about pagination or filtering strategy.

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, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context — the required `full_access` API key and the underlying `GET /tenants` operation — which an agent needs before calling and cannot get from the annotations.

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

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

Two short, front-loaded sentences with no filler; the auth and endpoint facts come before anything else. The opening sentence "List tenants." merely restates the tool name and title, so it is not perfectly waste-free, but sizing is appropriate for a simple list tool.

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

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

There is no output schema, so the description could have explained what a tenant record contains or what the response envelope looks like, and it does not. It says nothing about pagination defaults or result cap either, though the schema covers those. Adequate to invoke correctly, but thin on what comes back.

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

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

Schema description coverage is 100%, with `after`, `before` and `limit` each documented including the mutual exclusion of after/before, so the schema carries the parameter burden fully. The description adds no parameter meaning beyond that, 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?

The description names a specific verb and resource ("List tenants"), making the operation unambiguous against mutation siblings like create_tenant or delete_tenant. It does not, however, explicitly differentiate itself from get_tenant or from the many other list_* tools, so the agent must infer the distinction from the name alone.

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

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

Usage is only implied: it is the enumeration form of the tenant resource, with get_tenant presumably for a single record. No explicit when-to-use, when-not-to-use, or comparison to alternatives is given. The prerequisite (`full_access` API key) is stated, which is useful but is a gate, not 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 readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context beyond that: the full_access key requirement and the underlying endpoint/operationId, which matters for an agent reasoning about permissions.

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

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

Two short sentences with the purpose front-loaded and the auth constraint immediately after. The API/operationId metadata is somewhat redundant but compact enough to earn its place as a disambiguation aid.

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, fully-annotated read-only list tool with complete schema descriptions and no output schema, the definition covers purpose, permissions and endpoint. Only a note on pagination behavior or expected return shape would improve it.

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

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

Schema description coverage is 100%, and the schema itself explains the cursor semantics of `after`/`before` and the limit bounds. The description adds nothing about parameters, so the baseline 3 applies.

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

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

States a specific verb and resource ("List webhooks") that an agent can immediately understand. It does not, however, distinguish itself from sibling tools like get_webhook or create_webhook beyond the implicit list-vs-get 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?

The description supplies a prerequisite ("Requires a `full_access` API key"), which tells the agent when the call will succeed. It gives no explicit guidance on when to prefer this over get_webhook for a single record or how to page through results, so usage is only implied.

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

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

Goes well beyond the annotations: it discloses the concrete failure mode (sends return `403 sending_paused`), that already-queued emails are lost, that the request body is optional, and that a `full_access` API key is required. That is exactly the operational context the destructiveHint/idempotentHint flags cannot convey.

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

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

Four short sentences, front-loaded with the action and its consequence, then auth, then endpoint reference. 'The body is optional' is mildly redundant with `required: [ref]`, but overall there is no padding.

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

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

For a two-parameter mutation with no output schema, the description covers effect, error behavior, lost work, auth requirement, and the underlying endpoint/operationId. Nothing an agent needs in order to call it safely is missing.

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

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

Schema description coverage is 100%, so both `ref` (tenant id or external_id) and `reason` (stored as `paused_reason`, has a default) are already fully documented in the schema. The description adds little parameter-level meaning beyond noting the body is optional, so the baseline 3 applies.

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

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

States a specific verb and resource ('Pause a tenant') and immediately defines the effect ('Stops all sending for the tenant'), which clearly separates it from update_tenant, delete_tenant, and unpause_tenant. It never names a sibling explicitly, so differentiation is implicit rather than signposted.

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 ('Stops all sending... emails already queued fail'), so an agent can infer when pausing is appropriate versus updating. There is no explicit 'use this when / use unpause_tenant to resume' routing, and no stated prerequisite beyond the 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?

Goes well beyond the annotations by disclosing atomicity ("All-or-nothing, if any email is invalid none are sent"), the whole-batch blast radius of paused-tenant and tenant-cap errors, and the required key scopes (`sending_access` or `full_access`). These are exactly the failure-mode facts an agent needs before committing a 100-message call.

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

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

Four short, front-loaded statements: capability and limit, atomicity/error scope, supported features, then alternative and auth. No sentence is filler.

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

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

With no output schema, the description still doesn't say what comes back (e.g., per-email ids or a partial-failure report), which matters for a tool whose all-or-nothing contract is its selling point. Everything else an agent needs to call 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?

Schema coverage is 100%, so the baseline is 3; the description adds real value by telling the agent to put the emails in `body` as an array and that attachments, `scheduled_at`, and a per-email `tenant_id` are supported at the item level. It doesn't mention `idempotency_key`, the one top-level parameter whose retry semantics matter most.

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

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

States a specific verb and resource ("Send batch emails") and immediately bounds the scope with "Sends up to 100 emails in one call." The final guidance to prefer send_email for a single message cleanly separates it from the nearest sibling.

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 routes single-message use to send_email and implies this tool is for bulk fan-out. It doesn't spell out when a broadcast (create_broadcast/send_broadcast) would be the better choice, which is the one remaining sibling ambiguity.

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?

Adds substantial context beyond annotations: blast radius (every subscribed contact in the audience), status lifecycle (queued → sending → sent), and the auth requirement (full_access API key). Annotations already flag openWorld and non-idempotent; the description adds the irreversible audience-wide reach and the human-in-the-loop expectation. It does not say whether a bad send can be recalled or what the response contains, which keeps it below 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?

Front-loaded with the action, then prerequisites, then the API endpoint reference — each sentence carries weight. The 'needs html or text' line is the one piece that doesn't map onto this tool's parameters and slightly muddies an otherwise tight spec.

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 fills that gap by describing the resulting status progression; it also covers the readiness prerequisite and the permission level. For a high-consequence, non-idempotent send operation, an agent has everything needed to call it safely.

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

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

Schema coverage is 50%, and the description compensates usefully: it explains what omitting scheduled_at does and that the target is a draft broadcast. However, the mention that 'The broadcast needs html or text' refers to fields not present in this tool's schema and it never clarifies that id is the broadcast UUID, so some ambiguity remains.

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 ('Send or schedule a broadcast') and immediately clarifies the effect: queues a draft for delivery to every subscribed contact of its audience. This distinguishes it from create_broadcast and update_broadcast in the sibling list, since those prepare the draft rather than deliver 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?

Explicitly names the prerequisite sibling ('Run get_broadcast_readiness first') and adds a user-confirmation gate, plus the key branch condition: without scheduled_at it sends immediately. An agent knows both the call order and the two modes without opening any 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?

Beyond the annotations, it discloses quota accounting per recipient, the 30-day scheduling ceiling, three named failure modes (422 tenant conflict, 403 sending_paused, 429 daily_quota_exceeded), required API key scopes, and the irreversibility of delivered mail. That is exactly the operational context the 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?

Front-loaded with the core action, then organized into constraints, testing, and safety. Dense but nearly every clause earns its place; only the trailing 'API: POST /emails (operationId sendEmail, Emails)' line is filler for an agent.

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

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

For a 14-parameter mutation tool with no output schema and thin schema descriptions, the description covers auth, quota, scheduling, error handling, and the irreversibility warning. Gaps remain around attachment/header/tag usage and what the call returns (email id? queue status?), but nothing essential to invoking it correctly is missing.

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

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

With only 29% schema coverage across 14 parameters, the description compensates well: it explains the html/text either-or requirement, the tenant_id conflict semantics, the replyTo/scheduledAt aliases, and the natural-language scheduling format. Secondary parameters such as headers, tags, and cc/bcc still get no mention in the description, so it does not fully close the coverage gap.

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

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

The description states a specific verb and resource and adds the crucial scope qualifier 'queues one email', which separates it from send_batch_emails and send_broadcast. It also names the underlying operation (POST /emails) so the agent knows exactly which API is wrapped.

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

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

It gives concrete routing guidance: call list_domains to find a verified `from` domain, use the delivered@/bounced@ test addresses to avoid real mail, and pass `idempotency_key` when retrying. It lacks an explicit 'use send_batch_emails instead when sending many', so the alternative-selection rule is only implied by 'one email'.

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 non-read-only, idempotent, non-destructive, and closed-world; the description adds the auth requirement (full_access API key), the role restriction with the exact error ('403 invalid_access'), and the reason a tenant might be paused. This is exactly the behavioral context annotations can't convey.

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

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

Front-loaded with the action and its effect, then the permission gate, then the auth requirement and endpoint. Every sentence carries information an agent needs; no filler or restatement of the 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?

For a one-parameter mutation with no output schema, the description covers the effect, auth level, role-based failure mode, and endpoint. Nothing material an agent would need before calling it is missing.

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

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

There is a single required parameter and schema coverage is 100% — the schema already explains that `ref` is a tenant id or your own external_id. The description adds nothing about the parameter, so the baseline 3 applies.

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

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

States a specific verb and resource ('Unpause a tenant') plus the functional effect ('Resumes sending'), so an agent knows exactly what changes. It doesn't explicitly name pause_tenant as the inverse operation, but the verb is unique enough among siblings that confusion is unlikely.

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

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

Gives a concrete precondition: tenants paused by the reputation guard can only be unpaused by trusted/internal teams, and everyone else gets a 403 and should contact support. It doesn't say when to use pause_tenant vs. update_tenant or whether unpausing is safe to retry, but the key usage gate is spelled out.

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

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

Annotations already declare the write/idempotency/destructive profile, and the description adds two things they cannot: a draft-only mutation constraint and a `full_access` API key requirement. It omits whether the update is partial or a full replacement of omitted fields, which matters for a PATCH on a mutable draft.

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?

Short and front-loaded with the core action, but "only drafts can be updated" appears twice in consecutive sentences, which is pure waste. The trailing API/operationId metadata is defensible for traceability but consumes a third of the 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 9-parameter mutation with no output schema and near-zero schema coverage, the description supplies auth and lifecycle constraints but leaves the field-level contract largely unstated. It is enough to avoid calling it on a sent broadcast, not enough to fill the body 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 only 11% — just `from` and `reply_to` carry descriptions — across 9 parameters. The phrase "any field of the create request" defers entirely to a sibling tool's schema and explains nothing about `id`, `audience_id`, `subject`, `html`, `text`, `name`, or `preview_text`, leaving most parameters undocumented in both places.

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 ("Update a broadcast") with an added scope qualifier that only drafts are mutable. It does not explicitly contrast itself with create_broadcast, delete_broadcast, or send_broadcast, so the agent must infer the boundary from the sibling list.

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?

"Only drafts can be updated" is a concrete precondition/exclusion that tells the agent when this tool will fail, which is more than most definitions provide. It stops short of naming an alternative path for already-sent broadcasts, so the agent gets a constraint but no routing guidance.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false. The description adds useful context by naming the required API key and the PATCH endpoint, but it does not disclose partial-update semantics, whether omitted fields are cleared, or any side effects of updating a contact.

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

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

The description is short and front-loaded, with the API key requirement stated before endpoint details. The first sentence repeats the title and the operationId metadata is of limited use, but overall there is no padding or wasted prose.

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 only 20% schema description coverage and no output schema, the description is too thin. It notes authentication but omits the semantics of the mutable body fields and the update behavior, leaving the agent with significant gaps before invocation.

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

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

Schema description coverage is only 20%, with just id_or_email documented in the schema. The description maps audience_id and id_or_email to the URL path, but adds no meaning for first_name, last_name, or unsubscribed, and does not explain whether the update is partial or full replacement.

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, "Update a contact," largely restates the tool name and title. The endpoint and operationId clarify that it is a PATCH to a specific contact resource, but the description never states which contact fields can be changed or how it differs from siblings such as create_contact, delete_contact, or update_broadcast.

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

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

The description gives an authentication prerequisite (`full_access` API key) but no guidance on when to use this tool versus create_contact, delete_contact, or other update_* siblings. There are no exclusions, alternatives, or usage conditions beyond the key requirement.

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 that this is a non-readonly, non-destructive, non-idempotent mutation. The description adds useful context by naming the required API key and the PATCH endpoint, but it does not clarify partial-update behavior, what happens to unspecified fields, or any side effects of changing tracking/TLS settings.

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

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

The description is short and front-loaded with the action, then adds tracking, auth, and endpoint details. It is efficient overall, though the tracking-only sentence is slightly misleading about the full update 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 4-parameter mutation with no output schema, the description covers auth and endpoint but leaves key gaps: TLS update semantics and id handling are not explained. The schema exposes required fields and enum values, but not enough descriptive context to make the definition fully complete.

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

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

Schema description coverage is 0%, so the description must compensate. It mentions open and click tracking, which maps to two parameters, but it omits the required id semantics and does not explain the TLS enum values (opportunistic vs enforced), leaving important parameter meaning to be inferred.

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

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

The description states a specific verb and resource ("Update a domain") and is distinguishable from create/get/delete/verify domain siblings by name. However, "Toggles open and click tracking" under-describes the actual update scope because the schema also allows changing TLS, and no sibling differentiation is explicit beyond the verb.

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

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

The only guidance is a prerequisite ("Requires a `full_access` API key"), not when to use this tool versus get_domain, verify_domain, create_domain, or delete_domain. There are no exclusions or alternative-selection cues.

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-readonly, non-destructive, non-idempotent mutation, so the bar is lower. The description adds real value beyond them: the auth requirement (`full_access` key) and the state precondition that the email must still be scheduled, which implies a failure mode for already-sent emails. It does not describe what happens on failure or what the response contains.

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 lines, front-loaded with the purpose, then the constraint, then the auth/API detail. Every sentence carries distinct information with no 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?

No output schema exists, so the description would ideally hint at the return value, and it does not. Otherwise it covers purpose, precondition, and auth for a simple two-parameter PATCH, which is sufficient to invoke correctly.

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

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

Schema coverage is 100%, so both `id` and `scheduled_at` are fully documented including format, examples, and the 30-day limit. The description adds no parameter-level detail beyond mapping the operation to `scheduled_at`, 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 (reschedule) and resource (email), then immediately narrows the scope to changing `scheduled_at` on an email that is still `scheduled`. That precondition plus the verb makes it clearly distinguishable from cancel_email, send_email, and get_email without opening any schema.

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

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

Gives the key usage gate: the email must still be in `scheduled` state, and a `full_access` API key is required. It does not explicitly name the alternative tool (e.g. use cancel_email to stop it entirely), which keeps it below 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 non-read-only, non-destructive, non-idempotent, so the description's contribution is the auth requirement ('Requires a full_access API key') and the null-removes-the-cap rule for daily_limit, both genuinely useful. It stops short of saying what happens on a missing ref or whether unspecified fields are left untouched, 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?

Three short lines: purpose first, then the changed fields, then the auth and endpoint constraints. No filler and nothing 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?

For a four-parameter mutation with no output schema, the definition supplies the permission requirement and the null-removal rule, which are the non-obvious behaviors. It omits error behavior (unknown ref, external_id collision) and partial-update confirmation, which keeps it just short of 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 coverage is 50% (ref and daily_limit are documented in-schema), so the baseline is 3. The description restates the null semantics already present in the schema and names the three writable fields, but adds no format, validation, or behavior detail for the undocumented name and external_id parameters.

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

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

Specific verb plus resource ('Update a tenant') immediately followed by the exact set of mutable fields (name, external_id, daily_limit). The tenant resource is unambiguous against siblings like update_contact, update_domain, and update_webhook, and the endpoint/operationId removes any doubt about which underlying operation is called.

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 enumeration of mutable fields implies a partial update, but the description never says so explicitly, nor does it route the agent away from related siblings such as create_tenant, pause_tenant/unpause_tenant, or delete_tenant. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely new context: the required `full_access` API key scope and the underlying `PATCH /webhooks/{id}` operation. The remaining gap is that it doesn't state the partial-vs-replace semantics of a PATCH for omitted 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?

Two short, front-loaded sentences with the operation first and the auth/endpoint metadata second. Nothing is padded.

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

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

Annotations cover the mutation safety profile and there is no output schema to explain, so the baseline need is modest. However, for a mutation tool with 4 undocumented parameters and an enum-bearing `events` array, an agent still lacks guidance on what a valid update payload looks like and what a successful response returns.

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% and the description gives no parameter guidance at all — nothing about `events`, `status`, or `endpoint`, and nothing about `id` needing to reference an existing webhook. With four params and no schema documentation, the description should compensate and does not.

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

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

The description says 'Update a webhook,' which is a specific verb+resource but is a near-verbatim restatement of the tool name and title, adding no scope detail (which fields can be updated, what the operation affects). It does not differentiate from siblings like get_webhook, create_webhook, or delete_webhook beyond the verb itself.

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 'Requires a `full_access` API key' line is a real precondition that helps an agent decide whether it can call at all, and the verb implies use on an existing webhook. But there is no guidance on when to use this versus create_webhook or delete_webhook, and no note on whether omitted fields are preserved or reset.

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

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

Beyond the annotations (which already flag a non-readonly, idempotent, non-destructive operation), the description discloses the privilege requirement ('full_access' API key) and the fact that state changes are observable only via a later read. That privilege gate is genuinely additive context an agent cannot get from the annotations.

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

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

Four short lines, front-loaded with the intent, then behavior, then follow-up, then auth. The opening 'Verify a domain.' duplicates the title and the trailing 'Domains' category tag adds nothing, but no sentence is otherwise wasteful.

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

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

With no output schema, the description correctly tells the agent that the result must be read via a subsequent domain fetch rather than returned here. Auth requirement and endpoint are covered; what remains thin is the parameter itself, which is the one gap for a one-param 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 0% for the single `id` parameter, so the description would need to compensate. It does so only indirectly through the endpoint path 'POST /domains/{id}/verify', which implies `id` is the domain identifier, but it never states the format or where to obtain the value.

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 title line is a restatement, but 'Re-checks DNS now' supplies the actual semantics: this triggers a live DNS re-verification of an existing domain. That distinguishes it meaningfully from get_domain (read-only) and update_domain (configuration), even without naming those siblings.

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

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

It gives an explicit follow-up workflow ('Retrieve the domain afterwards to read the new status and per-record statuses') which routes the agent to get_domain after the call. What's missing is any exclusion: when not to call it, e.g. before records are set, or whether it is safe to call repeatedly during pending verification.

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