anima

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds real value beyond them: a single round-trip replaces multiple calls, and 'no real send needed to find out' tells the agent it can probe send-capability without side effects. It stops short of discussing auth preconditions or rate limits.

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

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

Dense and front-loaded — the snapshot contents and the routing question lead, and every clause carries information. It is a single long sentence that leans on parenthetical enumerations, which is efficient but slightly heavy for one line.

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

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

With an output schema present, the description needn't re-explain return shapes, and it still names the key fields an agent will rely on. For a zero-parameter, read-only overview, 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?

The tool takes zero parameters, so the baseline is 4. There are no argument semantics to clarify, and the description correctly spends no words on inputs.

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

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

States a specific resource (account overview) and enumerates exactly what it returns: org context, credential identity, send-capability flags, inventory counts, active blockers, and deploy identity. It explicitly positions itself as a 'strict superset of the legacy whoami + workspace_health pair', distinguishing it from the sibling usage_overview without opening either schema.

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

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

Gives an explicit trigger ('Use before any non-trivial workflow') plus the exact question it answers ('who am I, can I do X right now, and which deploy is serving me?'), and names the alternative it supersedes. Nothing about when-to-use is left to inference.

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

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

The description thoroughly explains the idempotency behavior: 'Pass idempotencyKey to make retries safe — same key + same body returns the original response, same key + different body returns IDEMPOTENCY_BODY_MISMATCH 409.' It also discloses a subtle caveat about partial failure with address attachment, going beyond the basic idempotentHint annotation.

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

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

The description is four sentences, each serving a clear purpose: purpose, use case, alternative guidance, and idempotency note. It is succinct, front-loaded with the primary action, and contains no redundant or filler text.

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

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

The description covers all essential contexts: what the tool does, when to invoke it, how it differs from related tools (agent_update for adding addresses later), and important behavioral nuances (idempotency and partial-failure caveat). Since an output schema exists separately, the lack of return-value details is acceptable.

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

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

The schema already provides detailed descriptions for every parameter (100% coverage), and the overall description adds high-level context (e.g., 'sending identity or automation actor') that is not in the schema. However, it does not individually elaborate on each parameter beyond what the schema states, so a score slightly above the schema-heavy baseline is warranted.

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 clearly states the tool's purpose: 'Create a new agent with optional metadata, and optionally attach an initial address.' It also identifies the intended use case ('provisioning a new sending identity or automation actor'), making the action and scope 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?

The description explicitly says when to use this tool and when not: 'Use this when provisioning a new sending identity or automation actor' and 'To add more addresses later, use agent_update.' This provides direct guidance for tool selection among siblings.

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

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

The description explicitly discloses the destructive side effect: 'Cascades to attached addresses, email identities, and phone identities.' This, combined with the destructiveHint annotation, fully informs the agent of the operation's impact.

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

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

The description is two sentences, direct, and free of fluff. It front-loads the main action and then adds necessary context about cascade effects. Every word serves a purpose.

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

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

For a delete operation, the description covers the essential context: what is deleted, why you would use it, and what else is affected. The lack of an output schema is acceptable since delete operations typically return a confirmation or empty response. No critical information is missing.

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

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

The only parameter 'id' is described as 'Agent ID', which is sufficient given the tool's singular purpose. While terse, it is unambiguous and matches the schema. A bit more detail about the ID format (e.g., UUID) could add value, but it is not necessary for correct invocation.

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 clearly states that the tool deletes an agent by ID, which is a specific action on a specific resource. It distinguishes itself from sibling tools like agent_create, agent_get, agent_list, and agent_update by the verb and intent.

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

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

The description provides guidance on when to use the tool ('to remove deprecated or compromised agents that should no longer send messages'), which helps the agent decide when this operation is appropriate. It stops short of explicit warnings or conditions, but the usage context is clear.

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

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

Annotations already declare this as read-only, idempotent, and non-destructive. The description adds meaningful behavioral context by enumerating the returned data categories: settings, metadata, status, addresses, emailIdentities, and phoneIdentities. This is useful beyond the structured 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 concise sentences with no filler. The primary capability is front-loaded, and the sibling routing is placed at the end, making the description easy to parse.

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 operation with full schema coverage, annotations, and an output schema, the description is sufficient. It explains what the tool returns and when to use an alternative, leaving no critical gap for an agent to call it correctly.

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

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

The schema has 100% description coverage for the single 'id' parameter, and the parameter description already explains that it returns full agent detail. The tool description reinforces this but does not add significant new semantic meaning beyond the schema.

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

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

The description uses a specific verb ('Fetch full detail for a single agent by ID') and clearly identifies the resource and the data returned. It also distinguishes this tool from agent_list, which is for browsing multiple agents.

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 explicitly says to use agent_list for browsing multiple agents, which helps an agent decide between the two similar tools. It implies agent_get is the correct choice when a single agent ID is known and full detail is needed.

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 indicate read-only, idempotent, and non-destructive behavior. The description adds behavioral details about cursor pagination and the exclusion of addresses for performance, going beyond the annotations without contradicting them.

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

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

The description is three sentences, direct and free of fluff. It efficiently states the action, the response characteristics, and the alternative tool, with no redundant 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 list tool with optional pagination, the description covers the core purpose, pagination behavior, response shape (lightweight, excluding addresses), and when to use a different tool. With an output schema present, the context is complete without over-explaining.

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?

Both parameters (limit and cursor) have clear descriptions in the schema, giving 100% coverage. The tool description does not add extra semantics beyond the schema, but it does reinforce the pagination concept, 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 clearly states the tool lists agents in the current account context with cursor pagination, and distinguishes itself from agent_get by noting it returns lightweight records without addresses. This gives a precise, unambiguous purpose.

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

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

Explicitly directs users to agent_get for full single-agent detail, indicating when not to use this tool. It also explains the lightweight response is intentional to avoid N+1 round-trips, providing context for when this listing is appropriate.

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

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

The description explicitly discloses a destructive operation ('deleteAddressId to remove one'), while the annotations declare destructiveHint=false. This is an annotation contradiction: an agent relying on the hint would underestimate the tool's destructive potential. The description does add a useful combinability note, but the contradiction forces a low score.

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

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

The description is two sentences and every clause carries information; the first sentence gives the general purpose and the second routes to the correct parameter names. It is slightly dense with comma-separated operations, but not 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 tool with six parameters and nested objects, the description covers the address operation modes and combinability. However, it leaves important invocation semantics implicit: whether metadata overwrites wholesale or merges, what happens when an addressId is invalid, and whether all changes apply atomically. The existence of an output schema and full parameter descriptions helps, but an agent still lacks enough guidance for a safe complex update.

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 descriptions already cover all six parameters (100%), so the baseline is 3. The description adds meaningful relationship semantics: add/update/delete are distinct operations and multiple can be combined in one call, which the schema alone does not convey. It does not clarify metadata replacement versus merge, but that gap is not the description's core burden.

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

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

The description names a specific verb ('Update') and resource ('agent'), and enumerates the exact modifiable surfaces: name, metadata, and addresses. This clearly distinguishes agent_update from siblings like agent_create, agent_get, and agent_delete without needing to inspect the schema.

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

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

It clearly establishes the use case: updating an existing agent and its addresses. It also explains the three address operations and that they can be combined. However, it does not explicitly state when-not-to-use or name alternatives such as agent_create for new agents, 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 disclose that the operation is non-read-only, non-destructive, and idempotent. The description adds that the domain is 'registered' and that it is a precursor to DNS setup, implying it does not perform DNS configuration or verification itself. This is consistent with annotations but does not provide additional behavioral insight beyond what the annotations convey, such as whether an existing domain is overwritten or how idempotency manifests. Given annotations cover the core traits, a 3 is appropriate.

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

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

The description is two concise sentences with no superfluous information. The primary purpose is front-loaded, and the usage guidance is neatly appended. Every word adds value, making it efficiently scannable 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?

Given the tool's low complexity (one parameter, output schema present), the description provides sufficient context: what it does, when to use it, and its place in the workflow. The presence of an output schema means return details are already structured, and the description covers the essential purpose and sequencing. Nothing crucial is missing for an agent to call it correctly.

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

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

The schema provides 100% coverage for the single 'domain' parameter with a clear description ('Domain name to add, such as mail.example.com or example.com.'). The description does not add any supplementary semantics beyond the schema, though it aligns with the generic domain usage. Since the schema fully documents the parameter, the baseline of 3 is maintained; no extra meaning is contributed by 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 description uses the specific verb 'Register' with the resource 'custom sending domain', clearly indicating the action and object. It states the domain is registered 'in the workspace' and 'so it can be configured for email traffic', which distinguishes it from related siblings like domain_verify (verification) and domain_zone_file (DNS file) by emphasizing the creation step. The sequencing clue 'before DNS setup and verification' further clarifies its unique role.

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 explicitly states when to use the tool ('Use this before DNS setup and verification'), giving clear timing for invocation. It implies that this is the initial registration step and that subsequent tools handle DNS and verification, but it does not name those alternatives explicitly. The guidance is clear enough for an agent to sequence it correctly, but it lacks an explicit 'when not to use' or mention of sibling tools.

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

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

The description clearly indicates destructive intent with 'Delete' and 'remove', and the annotations already provide destructiveHint and idempotentHint. It adds the workspace scope, but does not mention irreversibility or side effects on associated records; annotations cover the core destructive 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 two concise sentences with no redundant wording, directly stating the action and common use cases.

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

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

The tool is simple, destructive annotations are present, and an output schema is indicated, so return values do not need to be described. The description sufficiently covers the main scenario, though it could mention idempotency behavior more explicitly, but the annotation already handles that.

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

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

The only parameter 'id' is documented in the schema as 'Unique domain ID.' with 100% schema coverage. The description adds no additional meaning beyond the schema, which is acceptable for a single simple parameter.

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

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

The description states a specific verb ('Delete') and resource ('domain from the workspace'), clearly distinguishing it from sibling domain tools like domain_get, domain_update, and domain_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?

It provides a clear trigger ('when it is no longer needed') and examples ('old or incorrect domain configurations'), but it does not explicitly contrast with domain_update for fixing incorrect configurations, leaving some ambiguity about when deletion is preferable to update.

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, covering safety behavior. The description adds no additional behavioral details beyond those annotations, though it does mention the response content (verification and configuration state).

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

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

The description is two concise sentences with no wasted words, effectively communicating purpose and usage guidance in a clear structure.

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

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

For a simple read operation with one parameter, the description provides all necessary context: what is fetched (full detail including verification/configuration) and how to get an overview (domain_list). No critical information is missing.

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

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

The schema fully describes the single parameter 'id' as 'Unique domain ID,' providing clear semantics. The description does not add extra meaning beyond this already sufficient 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 clearly states the tool fetches full detail for a single domain by ID, including verification and configuration state, and explicitly contrasts with domain_list for browsing all domains.

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 explicitly tells the agent when to use this tool (for a specific domain's full details) versus when to use domain_list (to browse all domains), making the selection unambiguous.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, covering the safety profile. The description adds the workspace scoping ('connected to the current workspace') and the intended use case, but does not describe return format or pagination behavior. With annotations present, this is acceptable but not rich.

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

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

The description is two sentences with no fluff. The core action ('List all domains connected to the current workspace') is front-loaded, followed by a purposeful usage hint. Every word earns its place.

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

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

For a simple list tool with an output schema, annotations covering safety, and zero parameters, the description is fully adequate. It states the scope (current workspace) and the use case, which are the only missing behavioral details. Nothing an agent needs to call this tool correctly is omitted.

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

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

The tool has zero parameters, so schema coverage is trivially 100%. Per the baseline for 0 params, a score of 4 is appropriate. The description adds no parameter semantics because none are needed; it correctly describes the list behavior without redundant parameter information.

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: 'List all domains', and adds scope with 'connected to the current workspace'. It also hints at a use case (audit and choose), making it clearly distinct from sibling operations like domain_get or domain_create. The purpose is unambiguous.

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

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

The description provides a clear context for when to use the tool: 'Use this to audit configured sender domains and choose one for follow-up actions.' It implies the tool is for listing and selection, but does not explicitly mention when not to use it or name alternatives. This gives clear usage context without exclusions.

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

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

Annotations already indicate this is a non-read-only, non-destructive, idempotent write. The description adds valuable context beyond annotations by clarifying that the update is limited to mutable configuration and does not require or trigger re-verification. No contradiction with the annotations exists.

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

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

The description is a single, front-loaded sentence with no filler. It states the action, the sole updatable field, and the notable side-effect avoidance of re-verification in a compact and easily parseable format.

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 update tool with rich annotations and an output schema, the description covers what changes, what cannot change, and a key behavioral guarantee. It does not explicitly state preconditions like the domain already existing or being verified, but the sibling tool set and context make this 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?

The schema already documents both parameters fully, but the description adds extra meaning by stating that `feedbackEnabled` is currently the only updatable field. This clarifies that `id` serves purely as an identifier and that other domain properties cannot be changed through this tool, which is beyond what the schema alone conveys.

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 action and resource: 'Update mutable configuration on a domain.' It narrows the scope to the single updatable field `feedbackEnabled` and explains its effect as toggling SES bounce and complaint feedback processing. This clearly distinguishes it from sibling domain tools like create, delete, get, list, and verify.

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 intended use is clear: update an existing domain's feedback processing without re-verifying the domain. The description does not explicitly name alternative tools or list when-not-to-use conditions, but the 'currently the only updatable field' wording and sibling tool set make the boundary reasonably obvious.

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 indicate readOnlyHint=false and idempotentHint=true. The description adds that it 'update[s] verification status', implying state change. Since annotations cover the main behavioral aspects, the description adds minimal new transparency.

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 concise sentences that fully convey the purpose and usage. No fluff or redundant 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?

The tool is simple with one parameter. The description provides enough context for correct invocation. It doesn't describe the response format, but that's not required for such a simple operation and no output schema is expected.

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 covers 100% of the parameter (id) with 'Unique domain ID.' The description doesn't add further meaning beyond the schema, so it stays at the baseline for high 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 uses a specific verb ('trigger'), identifies the resource ('domain'), and specifies the context ('after DNS records are configured'). It clearly differentiates from sibling tools like domain_get or domain_update by focusing on verification.

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 provides clear when-to-use guidance: 'after DNS records are configured' and for 're-run DNS validation'. It doesn't explicitly mention when not to use it, but the context is sufficient for correct selection.

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 (readOnlyHint, idempotentHint, destructiveHint) already disclose the read-only, non-destructive nature. The description is consistent but adds no extra behavioral context beyond what the annotations provide.

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 concise, containing only two sentences with no redundant information. It effectively communicates the tool's purpose and uses.

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

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

The description is complete for a simple read operation with a single parameter. It explains what the tool returns (full DNS zone file) and why it would be used, without needing to detail the 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?

The single parameter 'id' has a description in the schema ('Unique domain ID') covering 100% of parameters. The description adds no additional detail, so a baseline score 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 clearly states the tool's function: 'Get the full DNS zone file for a domain.' It also specifies two concrete use cases (export and verification), making it distinct from sibling tools like domain_get or domain_verify.

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

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

The description provides explicit guidance on when to use the tool ('Use for complete DNS export or to verify all records are correctly configured'), but does not explicitly contrast it with alternative sibling tools.

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

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

Annotations already indicate read-only, non-destructive, idempotent behavior. The description adds that the URL is temporary, which is useful and consistent with the annotations; no 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?

One concise sentence that states the purpose and usage context without superfluous detail. Well-structured and easy to parse.

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 operation, describing the return as a temporary URL is sufficient. The output schema is flagged as present, and no critical details like authentication or expiration are necessary given the tool's simplicity and annotations.

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 parameter description ('Attachment ID') is clear. The additional 'Returns a temporary download URL' is output-related, not parameter-specific, so it adds limited semantic value beyond the schema.

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

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

Clearly states the tool gets a temporary download URL for an email attachment, with a specific resource and action. It is distinguishable from email_get and other email tools by mentioning direct file access for preview/download.

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

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

Explicitly states when to use it ('when you need direct file access for preview or download'), giving clear context. It does not mention when not to use it, but the guidance is sufficient for this simple tool.

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 indicate non-read-only, non-destructive, and non-idempotent behavior. The description adds useful context about draft incompleteness and the lifecycle (send/delete later), which enhances transparency beyond the annotations.

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

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

The description is two sentences, concise and to the point, with no fluff or redundant information. It efficiently communicates the essential purpose and lifecycle.

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

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

Given an output schema exists (per signal) and the description clearly explains the tool's role and relationship to sending/deleting drafts, nothing more is needed for an agent to invoke it correctly.

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

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

The schema has 100% coverage with descriptions for all parameters, and the description text does not add extra parameter-level meaning. Baseline of 3 is appropriate since the schema already does the heavy lifting.

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

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

The description clearly states the verb 'Create', the resource 'email draft', and the important distinction that it is 'composed but not sent'. It also explicitly differentiates from sibling tools by mentioning later send/delete actions.

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 explicitly says 'Use email_draft_send later to actually deliver, or email_draft_delete to discard', giving clear guidance on when to use this tool versus the alternatives.

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

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

Description clearly indicates the destructive nature by using 'Discard' and 'remove'. Annotations support this with destructiveHint=true and readOnlyHint=false. No contradiction or hidden 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?

Description is concise, using two short sentences with no unnecessary words or repetition. It is well-structured and easy to parse.

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 delete operation, the description and annotations provide all necessary context: what it does, when to use it, and how it differs from the send alternative. No critical information is missing.

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

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

The only parameter id is fully covered by the schema description 'Draft ID.' The tool description does not add extra meaning beyond the schema, but with 100% schema coverage this is sufficient.

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?

Description clearly states the tool discards/removes a draft, with the specific resource being email drafts. It also distinguishes itself from email_draft_send, which is the sibling for delivering drafts.

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 tells when to use this tool: to remove drafts no longer needed. It also explicitly tells when not to use it and which alternative to use (email_draft_send for delivering).

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the useful notion that this returns 'full detail' rather than summary info, but it does not go beyond that. With annotations carrying the main burden, a 3 is appropriate.

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

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

Two short sentences with no filler: the first states the primary action and target, and the second points to the relevant sibling for an alternative use case. It is front-loaded and earns its place.

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

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

For a straightforward single-ID fetch tool with a rich output schema and comprehensive annotations, the description is complete. No pagination, filtering, or mutation concerns apply, and the routing to email_draft_list covers the main open decision.

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 in the schema itself. The description adds no additional parameter semantics, but none are needed for such a simple, fully self-describing parameter.

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 ('Fetch'), resource ('full detail for a single draft'), and the required identifier ('by ID'). It also explicitly differentiates from the sibling tool by routing browse behavior to email_draft_list, so an agent can select this tool correctly.

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 clearly signals when to use this tool: when you already have a draft ID and need full details. It also tells the agent to use email_draft_list for browsing, which explicitly addresses the most likely alternative.

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 readOnly, idempotent, and non-destructive behavior. The description adds the note about returning 'lightweight draft records', which is minor extra context but does not introduce rate limits, pagination defaults, or other behavioral details.

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

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

The description is two sentences, concise, and well-structured. It front-loads the core action and immediately provides a helpful pointer to the detail-oriented sibling without any 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 a defined output schema and fully documented parameters, the description gives enough context for a simple list operation. It could mention pagination behavior or default limits, but these are not essential given the schema and the pointer to email_draft_get for details.

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

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

Schema coverage is 100% with all three parameters (limit, cursor, agentId) fully described. The description's mention of 'optional filters' aligns with the schema but adds no additional semantic detail, so baseline 3 applies.

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

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

The description clearly states the verb 'List' and the resource 'email drafts', and explicitly distinguishes from email_draft_get by mentioning the lightweight record format and pointing to the sibling for full 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?

It explicitly mentions using email_draft_get when full detail is needed, providing a clear alternative. However, it does not explicitly state when to avoid this tool (e.g., for creating, sending, or deleting drafts), though the sibling list implies those cases.

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?

Annotation Contradiction: the description states it 'deletes the draft row,' which conflicts with the destructiveHint=false annotation. The description otherwise adds useful behavioral detail (atomic conversion, delivery, return of new Message), but the contradiction with the annotation is serious and warrants a score of 1.

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 no filler: action, mechanics, preconditions, return value. Every sentence adds necessary information and the core action is front-loaded.

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

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

With one parameter, an output schema present, and annotations provided, the description covers all necessary operational details: what happens atomically, the deletion side effect, required draft fields, and the returned Message. The agent has enough 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?

The input schema already documents the single 'id' parameter as 'Draft ID' with 100% coverage. The description does not add semantic detail about the parameter beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states a specific verb ('Send') and resource ('draft'), then explains the atomic transformation of the draft into a delivered Message and the deletion of the draft row. This distinguishes it from siblings like email_send and email_draft_* operations without needing to open schemas.

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

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

The description communicates the intended use by referencing an existing draft and states the preconditions (recipient, subject, body). It does not explicitly cite alternatives or when-not-to-use scenarios, but the draft-focused language makes the appropriate case clear.

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 indicate readOnlyHint=false and openWorldHint=true, covering mutation and external effects. The description adds the 'loading the original content first' step, which is useful behavioral context. It does not contradict annotations, but adds only minimal extra transparency beyond that.

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 concise sentences with no wasted words. The main action is front-loaded, and the use case is stated in the second sentence. Efficient and well-structured.

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

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

The description is adequate for a straightforward forward operation. It explains the purpose and process, while the schema covers parameter details and the output schema handles return values. It does not explicitly address attachment behavior, but that is documented in the schema, so nothing critical 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%, with all five parameters documented in detail. The description does not add any parameter-specific meaning beyond what the schema provides, so it meets the baseline for fully covered schemas.

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

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

The description states a specific verb and resource: 'Forward an existing email to another recipient'. It clearly conveys the action and object. However, it does not explicitly distinguish itself from siblings like email_reply or email_send, so it misses the top score for sibling differentiation.

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

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

The phrase 'Use this to share a prior message while preserving context' gives a clear use case, but there is no explicit guidance on when not to use it or alternatives to consider. This is implied usage rather than explicit routing.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety and side-effect profile. The description adds the return content (metadata and body), which is useful but not beyond what annotations already imply. No additional behavioral context like error handling or rate limits is provided, but this is a simple read operation where the annotations do most of the work.

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

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

The description is two sentences with zero waste. The primary function is front-loaded, and the alternative usage is stated in a separate clause. Every word earns its place, making it efficient and clear.

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

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

Given the output schema exists, the description does not need to explain return values. The tool is simple with one parameter, and the description covers purpose and guidance. It does not mention potential error scenarios or how to obtain the ID, but these are minor for a straightforward getter. Overall, it is sufficient for an agent to call 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?

The schema description for the 'id' parameter already states 'Email ID. Returns full metadata and body.', which fully covers the semantics. The tool description repeats this but adds no new information. Given 100% schema coverage, the baseline of 3 is appropriate; the description does not enhance parameter understanding.

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 clearly states the verb 'Fetch' and the resource 'full detail for a single email by ID', specifying the content (metadata and body). It also differentiates itself from email_list by naming it as the browsing tool, which is a sibling. This makes the purpose unambiguous and distinguishes it from related tools.

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

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

The description explicitly directs the agent to 'Use email_list to browse emails in a folder', which is a clear alternative for a related task. However, it does not cover other potential alternatives like email_search or email_thread_get, but for its specific role (fetching a single email by ID) the guidance is sufficient.

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 adds valuable behavioral context: labeling is the 'agent's workflow state,' read/unread are mutually exclusive states, and there is no batch form. It does not contradict the readOnlyHint=false or idempotentHint=true annotations.

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

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

The description is concise and front-loaded: it opens with the action, then provides usage context and constraints. Every sentence earns its place—no filler or redundant restating of the tool name.

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

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

Given the rich schema descriptions, annotations, and presence of an output schema, the description covers all essential operational constraints: required labels, one-message limit, and integration with email_list. There are no critical gaps for an agent to call the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds extra meaning by explaining the archive label (`archived`), supporting custom tags, and restating the at-least-one constraint. This helps agents understand valid label values beyond parameter names.

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 and/or remove labels on one message.' It also clarifies the intended use cases—read/unread, archive, custom tags—and distinguishes the tool from related operations by pointing to email_list's labels.

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 clear usage context: mark read/unread, archive, apply tags, and filter via email_list. It also states key constraints: supply at least one of addLabels/removeLabels and one message per call. It does not explicitly name alternative sibling tools, but the guidance is clear enough for an agent to know when to invoke 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 readOnly, openWorld, idempotent, and non-destructive behavior. The description adds useful behavioral detail by noting it returns lightweight per-email records plus a pagination object and does not return full bodies, which supplements the annotations without contradicting them.

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 are tight and highly informative, covering return shape, pagination flow, and pointers to sibling tools without any fluff or redundancy.

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

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

The description is complete for a paginated list tool: it explains the return style, pagination continuation, and how to get full content or search, which is exactly the context an agent needs. The output schema exists, so the description does not need to enumerate the record fields.

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

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

Schema description coverage is 100%, so all five parameters are already well documented. The description does not need to add much; it only reinforces the cursor pagination semantics, which are already in the schema.

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

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

States a specific verb and resource ('List emails') and clearly distinguishes itself from email_get and email_search by noting what it returns (lightweight records with pagination) versus what those siblings do. An agent can immediately tell this apart from related email tools.

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

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

Explicitly tells the agent when to use alternatives: use email_get for the full body and email_search to find specific messages. It also gives the pagination workflow by instructing to pass pagination.nextCursor back as cursor.

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

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

The description discloses that it loads the original message and sets threading headers, which are meaningful side effects. It does not mention idempotency, delivery outcomes, or potential failures, but annotations already indicate non-read-only, non-idempotent 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 concise, using two sentences with no redundant or irrelevant content. It communicates the core purpose and key behavior efficiently.

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

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

The description is sufficient to invoke the tool given the schema and sibling context. It could mention the return value or error scenarios, but the presence of an output schema and required parameters makes the current description adequately complete.

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

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

The schema provides full parameter descriptions, so the tool description adds little beyond referencing the reply context. The schema's per-field descriptions are thorough, including attachment semantics, which covers the parameter understanding.

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 clearly states the tool replies to an existing email thread, and distinguishes it by noting it loads the original message and sets threading headers. This differentiates it from related tools like email_send or email_forward.

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 explicitly says 'Use this when you need a proper in-thread response,' which gives a clear usage condition. It does not explicitly contrast alternatives, but the guidance is sufficient for the common case.

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 indicate readOnly, openWorld, idempotent, and non-destructive behavior, and the description aligns with these by describing a pure search operation. It adds important behavioral context such as the output shape, pagination differences, and the fact that semantic mode can return non-email results. No contradictions exist between the description and annotations.

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

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

The description is concise—two sentences—and front-loads the core purpose ('Search messages by content') before explaining mode-specific details. It is well-structured, covering fulltext mode's substring matching and cursor pagination, then semantic mode's similarity ranking and multi-channel scope, without any redundant or vague phrasing.

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

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

Given the tool's complexity (dual modes, 8 parameters, divergent return shapes), the description is sufficiently complete. It explains both modes, their outputs, and parameter nuances (like includeSpam and labels), and even mentions follow-up actions. Combined with the thorough schema, an agent has all necessary information to call the tool correctly.

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

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

The schema provides 100% coverage for all 8 parameters with detailed descriptions, including mode-specific behavior (e.g., limit defaults, threshold relevance, labels system). The main description adds a high-level overview of mode differences and return structures, but most parameter semantics are already well-documented in the schema. The description does reinforce key points like default mode and pagination, which adds slight value beyond the schema.

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

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

The description clearly states the tool 'searches messages by content' and distinguishes between fulltext and semantic modes, which differentiates it from sibling tools like email_list (which likely lists without content search) and email_get (which retrieves a specific message). The verb 'search' is specific and the resource 'messages' is explicit, leaving no ambiguity about the tool's primary function.

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

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

The description provides explicit guidance on when to use each mode: fulltext for substring matching on emails, semantic for similarity across all channels. It also directs users to 'check the channel field' for semantic results and suggests follow-up via email_get or email_thread_get, giving clear context on tool selection. Parameter behaviors like cursor pagination (fulltext only) and threshold (semantic only) are explained, so an agent knows exactly when to use this tool versus alternatives.

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

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

Annotations already indicate a mutating, non-idempotent, open-world operation, so the description is not burdened with that. It adds the useful 'agent mailbox' context and positions this as compose-and-deliver, but does not disclose traits such as immediate external delivery, irreversibility, or sending limits.

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

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

Two front-loaded sentences with no fluff. The core action and sender scope come first, and the usage cue is placed in the second sentence.

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

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

For a complex 12-parameter tool with a rich schema, an output schema, and useful annotations, the description is adequate. It would be more complete if it pointed to email_reply, email_forward, or email_draft_send for non-new-message cases, but the schema fills in the invocation details.

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

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

Schema description coverage is 100%, so the schema already documents every parameter in detail. The description only mentions optional CC and threading headers, which adds slight emphasis but no meaning beyond the schema.

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

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

The description clearly states the verb ('Send'), the resource ('a new outbound email'), and the scope ('from the agent mailbox'). Saying 'new' differentiates it from reply/forward/draft-send siblings, though it does not explicitly name those alternatives.

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

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

'Use this when you need to compose and deliver a message' gives a clear context for when the tool applies. It does not mention when not to use it (e.g., when replying, forwarding, or sending an existing draft), so it stops short of full alternative routing.

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the base behavior is covered. The description adds useful context about returning messages ordered within each thread, but does not disclose additional side effects, rate limits, or authorization requirements beyond what annotations provide.

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

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

The description is compact and well-structured: it states what the tool does, how to specify thread selection, and what the response ordering will be. No unnecessary words or redundant content are present.

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 an output schema present and all input parameters fully described in the schema, the description provides enough context for correct invocation. It also clarifies the single-vs-multiple thread usage and ordering behavior, so no critical operational details are missing.

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

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

The input schema covers all four parameters with descriptions, and schema coverage is 100%. The main description mostly reiterates the id/ids distinction without adding deeper meaning for limit or agentId, so it does not exceed the baseline set by the schema.

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

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

The description clearly states the tool fetches all email messages in one or more threads, using a specific verb and resource. It is distinct from siblings like email_get or email_list based on the thread-scoped behavior.

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 clear parameter usage (id vs ids, ordering) but does not explicitly compare this tool to alternatives such as email_search or email_list. The use case is implied rather than stated with explicit when-to-use or when-not-to-use guidance.

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

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

Clearly describes the creation side effect, the returned URL, the handshake deadline, and notes that the response carries no token or secret. It aligns with the readOnly=false annotation; slightly less detail is given about what happens after the handshake completes, but the core behavior is transparent.

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

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

The description is compact, front-loaded with the core action and result, and every sentence adds meaningful usage or behavioral detail. No redundant or filler content.

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

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

Given the two-parameter schema and available annotations, the description fully covers what the tool does, how to authenticate, what the response contains, and the expiry constraint. Nothing essential is missing for correct invocation.

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

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

Both parameters are fully described in the schema and reinforced in the description. The agentId authentication nuance and ttl enum/rejection behavior are explicit, making the semantics unambiguous.

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

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

States a specific verb ('Create') and the exact resource (short-lived, single-use connect URL) for linking a browser extension or Puppeteer worker to an Anima agent. The returned `connectUrl` purpose and handshake context clearly distinguish it from other tools.

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

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

Provides explicit usage conditions: agentId MUST be passed with a master key and OMITTED with an agent key, ttl is optional, and values above the org maximum are rejected. This gives clear when-to-use and how-to-use 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?

Describes the immediate receive capability and the ability to choose or auto-generate username/domain. Includes a permission requirement (master key access), but does not mention idempotency 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?

Two concise sentences with no redundant 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?

Provides enough for a simple creation operation, but does not mention the return value or error scenarios. Output schema likely covers this, but description alone is slightly incomplete.

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

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

All four parameters are described with constraints, and the description reinforces the domain verification requirement. Schema coverage is 100%.

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 clearly it creates a new email inbox that can receive mail immediately. Distinguishes from other inbox operations by specifying creation.

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

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

Does not explicitly compare to sibling tools like inbox_get or inbox_update, but the action of creating is unambiguous. No guidance on when to use vs alternatives, so moderate.

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 (destructiveHint, readOnlyHint false, idempotentHint, openWorldHint), the description discloses important behavioral details: the deletion is permanent, the mailbox is removed along with the inbox, mail bounces after deletion, and master key access is required. This substantially adds context for safe invocation.

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?

Each sentence earns its place: the first states the action, the second adds an important side effect, the third emphasizes irreversibility, and the fourth states the auth requirement. The most important safety-relevant information is front-loaded and there is no fluff.

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

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

This is a high-risk destructive operation with only one parameter, and the description covers what is destroyed, irreversibility, post-deletion behavior, and the auth prerequisite. The output schema exists and the parameter schema is fully documented, so nothing critical is left implicit 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?

There is only one parameter, `id`, and the schema describes it as 'Unique inbox ID.' The description does not add extra parameter-level semantics, but because schema coverage is 100%, the missing description-level parameter detail is not a deficiency beyond the established baseline.

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

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

The description states a specific action ('permanently delete') on a specific resource ('inbox and its mailbox'), which clearly differentiates it from sibling tools like inbox_get, inbox_update, and inbox_create. It also adds concrete behavioral scope, so an agent knows exactly what resource is affected.

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

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

The description gives clear contextual guidance by stating that the operation is permanent, affects the mailbox, and requires master key access. It does not explicitly name when-not-to-use or alternatives, but deletion is a distinct action with no close functional substitute among the siblings, so the implied usage is clear and adequately supported.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the description adds no new behavioral transparency. The description is consistent with the annotations, but does not go beyond them.

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 concise (two sentences), front-loaded with the action and resource, and includes a helpful pointer to the list alternative. No unnecessary words.

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

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

Given that the tool is a simple get and there is no output schema, the description provides a reasonable indication of what the response will contain. It could be slightly more explicit about error behavior or exact response structure, but it is sufficient for typical use.

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 only parameter 'id' is described as 'Unique inbox ID.' Schema coverage is 100%, so the baseline is 3. The description does not add extra semantics beyond the field name and short definition.

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 ('Fetch full detail') and a specific resource ('a single inbox by ID'), clearly distinguishing it from inbox_list. The inclusion of expected fields ('email address, display name, associated agent') further clarifies the purpose.

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

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

Explicitly differentiates from the sibling tool inbox_list by saying 'Use inbox_list to browse all inboxes.' This gives the agent clear guidance on when to use this tool versus the alternative.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the bar is lower. The description adds useful behavioral context beyond the annotations by mentioning cursor-based pagination, optional search, and the specific attributes returned, without contradicting any annotation.

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

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

A single sentence with no filler. It front-loads the core action ('List inboxes'), then adds pagination/search behavior, then states the return fields. Every part earns its place.

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

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

For a simple, read-only list tool with an output schema and 100% schema coverage, nothing critical is missing. Safety is covered by annotations, parameter semantics by the schema, and return shape by the output schema; the description completes the picture with pagination and search behavior.

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

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

Schema description coverage is 100%, and each parameter already has a clear description. The tool description adds only that search is 'free-text' and that pagination is cursor-based, which mirrors the schema. This meets the baseline but does not go beyond what the schema already communicates.

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 — 'List inboxes in the workspace' — and adds distinguishing details: cursor pagination, optional free-text search, and the returned fields. This clearly separates it from siblings like inbox_get, whose single-resource purpose is different, even without an explicit comparison.

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 clearly implies when this tool is appropriate: when a caller needs to enumerate inboxes, especially with search or pagination. It does not explicitly name alternatives or exclusion conditions, but the 'cursor pagination' and 'optional free-text search' phrasing gives enough context for an agent to choose it over inbox_get or email_list.

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

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

Annotations already indicate a mutating operation, but the description adds meaningful behavioral detail: partial update semantics (omitted fields unchanged), clearing behavior via null, unlink semantics, immutability of the email address, and the master key requirement. This is exactly the kind of context an agent needs beyond the raw 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 filler. The first sentence front-loads the operation and target fields; the second compactly conveys clear/omit semantics, the immutability constraint, and the access requirement. Every sentence earns its place.

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

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

For a simple three-parameter update tool with a complete schema, a clear output schema, and annotations covering mutation/idempotency, the description provides the essential additional context: partial update behavior, clearing behavior, email immutability, and required access level. Nothing critical is missing.

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

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

Schema description coverage is 100%, and the schema already documents each parameter with null vs. omit semantics. The description restates these semantics rather than adding new parameter-level meaning. It does clarify the overall purpose of the update and the unlink/remove behavior, but that is more purpose-level than parameter-level.

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

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

The description names the resource ('inbox') and specific verb ('update'), and immediately scopes what can be changed ('display name or agent association'). It also states what cannot be changed ('The email address itself cannot be changed'), disambiguating from other inbox operations like inbox_create, inbox_delete, inbox_get, and inbox_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?

The description clearly conveys when to use the tool: to modify an existing inbox's display name or agent association. It provides usage details about null vs. omitted fields and notes the master key access requirement. It does not explicitly name alternative tools for creation or deletion, so it falls 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?

The description discloses that the call stays open, that the tool returns the full transcript, and that it errors out if elicitation is unsupported. It adds meaningful behavioral detail beyond the readOnly/destructive/idempotent annotations, though it does not mention potential costs or billing implications of placing an outbound 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?

The description is long but well-structured and information-dense; every sentence adds useful detail. It could be slightly more concise, but the complexity of the tool justifies the length.

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

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

The description covers the tool's purpose, live behavior, parameter nuances, error conditions, and return value (full transcript). It is complete enough for an agent to use the tool safely and effectively without additional external documentation.

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?

All 8 parameters are fully documented, including defaults, max lengths, valid formats, and conditional behavior. The agentId and agentConfig parameters receive especially thorough explanations that go well beyond the raw schema.

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

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

The description clearly states the tool places a live phone call and manages a real conversation, which is a specific verb and resource. It distinguishes itself from sibling tools like phone_call_get, phone_call_list, and phone_call_recording_get by focusing on call creation and live interaction.

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 explains when to use the server-side agentConfig loop versus when to rely on client elicitation, and explicitly references agent_list and voice_list for valid IDs. It also notes the requirement for the MCP client to support elicitation, giving clear operational 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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the description's additional disclosure about summary generation ('generated once on first read after post-call processing and cached') adds valuable behavioral nuance about timing and caching. This goes beyond the annotations without contradicting them.

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

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

Two sentences with no filler. The first sentence front-loads the core return fields; the second adds the behavioral nuance about summary caching. Could potentially split the field list for scannability, but overall it uses every word efficiently.

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

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

The tool has an output schema and annotations cover safety and idempotency, reducing the description's burden. The description covers the key fields and the summary behavior. It doesn't mention how to obtain the call ID or pagination, but neither is necessary for a single-get tool with one parameter.

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

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

The input schema provides 100% coverage and unambiguously documents the only parameter (id: 'The call ID.'). The description adds no new parameter-specific details beyond the obvious, so a baseline score 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 states a specific verb ('Get'), resource ('phone call'), scope ('single'), and enumerates the exact fields returned (status, duration, participants, AI summary components, quality score). This clearly distinguishes it from sibling tools like phone_call_list, phone_call_recording_get, and phone_call_transcript_get.

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

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

The description implies when to use this tool — when a caller needs the full detail of a single call, especially the AI summary and quality score. However, it does not explicitly name alternatives or state when not to use it (e.g., phone_call_list for browsing calls), leaving a small inference step.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by stating it returns 'lightweight call records' and points to phone_call_get for more complete data, which goes beyond the annotations without contradicting them.

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

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

The description is two sentences with no wasted words. The core purpose is front-loaded, and the pointer to phone_call_get is placed as a natural follow-up, making the structure efficient and easy to scan.

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 listing tool with an output schema present, extensive annotations, and a clear sibling pointer, the description is complete. An agent has enough information to decide when to call this tool, what it returns, and when to choose phone_call_get instead.

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 each of the five parameters already described in the input schema. The description only says 'optional filters' and does not add parameter-level meaning, so the schema carries the heavy lifting and 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 specific verb and resource: 'List phone calls with optional filters.' It also distinguishes itself from phone_call_get by noting it returns lightweight call records rather than full detail, so an agent can tell the two apart without opening the schema.

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

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

The description clearly states that phone_call_get should be used when full call detail including summary and score is needed. It does not explicitly cover all sibling tools or exclusion cases, but the core alternative and the decision factor are provided clearly.

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 indicate read-only, idempotent, and non-destructive behavior, and the description does not contradict this. It adds useful behavioral details about the URL expiring after 1 hour and the recording-enabled prerequisite, which go beyond the annotations and help the caller understand side effects and limitations.

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 concise and well-structured, with three short sentences that each convey essential information: the action and format, the expiration, and the prerequisite. There is no redundant or extraneous content.

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

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

Given the simplicity of the tool (one parameter, no output schema displayed), the description sufficiently covers the key context: what is returned (a time-limited URL), the format, and a key condition for success. It does not describe error cases or response structure, but those are not essential for a straightforward get operation and would not significantly hinder 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?

The only parameter, id, is described in the schema as 'The call ID,' and the tool description does not add further semantic detail beyond that. Since schema coverage is 100% for the parameter, the baseline score of 3 is appropriate; the description does not need to elaborate further but also does not add extra 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 description clearly states the action (get a download URL), the resource (call recording), and the format (WAV), making the tool's purpose unambiguous. It also distinguishes the tool from related ones like phone_call_transcript_get by focusing on the recording URL rather than transcript content.

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

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

The description provides a prerequisite for use ('Recording must have been enabled during the call') and notes the URL is time-limited, which helps set expectations. However, it does not explicitly mention alternative tools or when to prefer this one over siblings like phone_call_get or phone_call_transcript_get, leaving some usage guidance implicit.

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 read-only, idempotent, and non-destructive behavior, so the description's added availability timing and transcript content are useful extras. There is no contradiction with annotations, and the description appropriately clarifies that this tool is not usable during an active call.

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

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

Two sentences, no filler, with the core purpose front-loaded. The availability condition is a valuable addition and is placed second without bloating the description.

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

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

For a one-parameter, read-only tool with an output schema and strong annotations, the description covers everything needed: what the tool returns and when it can be called. Nothing critical is missing.

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

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

The input schema fully describes the only parameter ('id' as the call ID) with 100% coverage. The description adds no parameter-specific detail, but none is really needed for a single, clearly documented field.

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

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

The description clearly states a specific verb ('Get') and resource ('full transcript of a phone call'), with details on content (speaker labels, timestamps, confidence scores). This sets it apart from sibling tools like phone_call_get and phone_call_recording_get, which serve different retrieval needs.

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

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

It gives a clear temporal constraint: 'Available after the call ends and transcription completes.' This tells an agent when it is appropriate to call this tool. It does not explicitly name alternatives, but the scope is clear enough to route the agent away from recording or call metadata tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds that results include status and capability flags, which is useful but does not go beyond what an output schema would supply. No additional behavioral context such as pagination or filtering is provided, so a mid-range score is appropriate.

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

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

The description is two short sentences with no filler. The primary action and scope are front-loaded, and the second sentence adds meaningful output context. Every word earns its place.

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

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

For a simple, read-only list operation with one well-documented parameter, an output schema, and strong annotations, the description is sufficiently complete. Nothing critical is missing for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, with agentId clearly documented as 'Agent whose phone numbers to list.' The description essentially repeats the same agent scoping, adding no new meaning beyond the schema. Baseline 3 is correct when the schema already documents the parameter well.

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

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

The description states a specific verb and resource: 'List phone numbers assigned to an agent.' It also adds output detail (status and capability flags), making the tool's purpose unmistakable. It clearly distinguishes from siblings like phone_number_provision and phone_number_release.

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 context clear: this lists phone numbers for a specific agent, so an agent can infer when to call it. However, it does not explicitly contrast with alternatives such as phone_number_provision, phone_number_release, or phone_call_list, nor does it state when not to use it.

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

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

Annotations indicate this is a write operation (readOnlyHint=false), non-idempotent. Description adds the crucial behavioral detail that provisioning incurs a monetary cost, which is not in annotations. This is significant context for an agent to avoid wasteful calls.

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

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

Two sentences, front-loaded with the purpose, followed by the cost warning and selection guidance. No fluff, each sentence earns its place.

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

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

With an output schema present, return values are covered. The description covers purpose, cost, and selection constraints. It does not explicitly mention prerequisites like agent existence, but that is implied by the required agentId. It is sufficiently complete for an agent to use 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 parameters are well-described in schema. Description mentions the constraint parameters but adds little beyond the schema's descriptions, which already cover them. 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?

Clearly states a specific verb (provision) and resource (phone number), and explains it assigns to an agent. Distinguishes from siblings like phone_number_list and phone_number_release by indicating it creates a new number.

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

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

Provides explicit guidance on when not to call (do not call speculatively) and how to constrain selection (use countryCode / areaCode / capabilities). Does not explicitly mention alternatives, but the context of cost and constraints implies appropriate usage.

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

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

Annotations already mark this as destructive, but the description adds critical behavioral context: released numbers cannot be recovered. It also clarifies that only previously provisioned numbers are affected, which goes beyond the annotation hints.

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

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

The description is three short sentences, front-loaded with the main action, then usage guidance, then a critical consequence. Every sentence earns its place with no redundancy or fluff.

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

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

For a simple two-parameter destructive operation, the description covers what the tool does, when to use it, and the most important post-condition (unrecoverable). Since an output schema exists, return values do not need to be explained here.

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

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

Schema description coverage is 100%, so the input schema already fully documents agentId and phoneNumber. The description does not add parameter-level detail beyond what the schema provides, which meets the baseline but does not exceed it.

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

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

The description names a specific verb ('Release') and resource ('previously provisioned phone number'), and states the destination ('back to the carrier pool'). This clearly distinguishes the operation from provisioning or listing phone numbers.

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

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

The description provides actionable usage context: 'Use this when cleaning up unused numbers.' It does not name alternative tools or explicit when-not-to-use conditions, but the stated use case is sufficiently clear for an agent to select 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=true and destructiveHint=false, covering the safety profile. The description adds meaningful context by specifying that the response includes threadId for joining the conversation, which helps the agent understand expected output. No contradictions or hidden behaviors are suggested.

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 concise sentences with no fluff. The first sentence front-loads the key action and a valuable output detail, and the second sentence cleanly points to the sibling tool for the broader use case.

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

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

The definition is complete for a simple single-fetch tool: one parameter is fully documented in the schema, an output schema exists to describe returns, annotations cover safety, and the sibling tool distinction is clear. Nothing necessary for correct invocation is missing.

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

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

Schema description coverage is 100%, so the parameter 'id' is already documented as 'SMS message ID.' The description does not add format or source details beyond the schema, so it meets but does not exceed the baseline.

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

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

The description states the specific verb 'Fetch' and resource 'full detail for a single SMS by ID', and distinguishes it from sms_list by noting that sms_list is for browsing multiple messages. Including the threadId detail further sharpens the purpose.

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

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

The description explicitly tells the agent when to use this tool versus sms_list: 'Use sms_list to browse multiple SMS messages.' This directly routes to the appropriate sibling for the alternative use case, leaving no ambiguity about scope.

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

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

The annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds minimal behavioral context beyond that, mentioning the inclusion of threadId but not expanding on side effects or edge cases. It does not contradict the annotations, so a neutral score is appropriate.

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

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

The description is two sentences with no redundant words. It starts with the core purpose ('List SMS messages') and immediately provides the most important context, making it highly efficient.

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

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

For a list operation with a simple schema, the description covers all essential information: the action, the resource, the optional filters, the presence of threadId, and a pointer to the related sms_get tool. No critical details are missing.

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

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

The schema provides full descriptions for all parameters, so the baseline is 3. The description adds the phrase 'optional filters', which hints that the parameters are filter-like and optional, but does not provide additional detail beyond the schema. This is a slight enhancement but not significant.

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 clearly states the tool lists SMS messages and includes the key attribute threadId. It also distinguishes itself from sms_get by mentioning that tool for full message detail, making its scope 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 explicitly says 'Use sms_get for full single-message detail', providing an alternative when needed. It implies when to use this tool for listing, though it does not detail specific use cases or prerequisites, but the list vs. get distinction is clear.

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 indicate this is a mutating, non-idempotent operation (readOnlyHint=false, idempotentHint=false). The description adds the prerequisite that the agent must have a provisioned phone number, which is useful beyond the annotations. It doesn't disclose failure modes or costs, but given the annotations cover the basic behavioral profile, a 3 is appropriate.

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

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

The description is three concise sentences with no fluff. The action is front-loaded, followed by a key requirement and usage context. Every sentence earns its place.

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

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

Given the tool's complexity (4 params, output schema present, annotations available), the description covers purpose, usage, and a prerequisite. It doesn't explain return values, but the output schema handles that. It could mention rate limits or costs, but those are not essential for a correct call. The description is adequate and slightly above minimum.

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 parameters are already well-documented in the schema. The description mentions mediaUrls for MMS, but this is already in the schema. The description adds no new parameter-specific information, so the baseline of 3 applies.

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

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

The description uses a specific verb ('Send') and resource ('SMS' or 'MMS'), and distinguishes from sibling tools like sms_get, email_send, and phone_call_create by explicitly mentioning SMS/MMS and mediaUrls. It clearly states the action and the optional MMS variant.

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

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

The description provides explicit usage context: 'Use this for transactional texts or conversational messaging.' It doesn't explicitly mention when not to use it or name alternatives, but the context is clear enough to guide selection among the sibling tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds valuable behavioral context: messages are returned oldest first, and when the conversation exceeds the limit, only the most recent messages are returned, with deeper history accessible via sms_list. This goes beyond the annotations without contradicting them.

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

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

The description is three sentences, each carrying essential information: purpose, ID discovery, and pagination behavior. It is front-loaded with the primary action and avoids any fluff, making it efficient and easy to parse.

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 an output schema defining the return format, annotations covering safety, and the description explaining ordering, pagination, and ID retrieval, nothing essential is missing. The tool is simple (2 parameters, no nested objects) and the description fully equips an agent to use it correctly.

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

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

Schema coverage is 100%, with both parameters described in the schema. The description adds extra semantic value by explaining the behavior of the limit parameter (returns most recent messages when exceeded), which is not in the schema. This enhances understanding of how the limit affects results, though it is a modest addition.

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

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

The description clearly states the verb 'Get' and the resource 'one SMS/MMS conversation with its message history, oldest first.' It distinguishes itself from sms_thread_list (which lists threads) and sms_list (which pages messages) by explicitly mentioning pagination and ordering. This makes the tool's purpose 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?

It provides explicit guidance on how to obtain the required thread ID via sms_thread_list or from any SMS, and explains when to use sms_list for deeper history when the conversation exceeds the limit. This gives clear context for when to use this tool versus its siblings, leaving no 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: result ordering, conversation grouping logic, and the exact summary fields returned. It doesn't discuss pagination behavior, but that is a minor gap for a read-only list tool.

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

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

Two dense sentences with no wasted words. The purpose and sort order are front-loaded, the conversation definition is concise, and the alternative tool is named explicitly. Every sentence earns its place.

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

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

Given the rich annotations, fully documented parameters, output schema presence, and clear sibling differentiation, nothing essential is missing. The description covers what the tool returns, how threads are defined, and when to use the complementary tool.

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

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

Schema description coverage is 100%, so all three parameters are already documented. The description adds marginal value by restating the agentId filter and clarifying that omitting it shows all accessible agents, but it does not provide additional semantics beyond the schema.

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

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

The description states a specific verb and resource ('List SMS/MMS conversations'), defines the unit of conversation, and specifies sorting ('most recently active first'). It also clearly differentiates itself from sms_thread_get by noting it returns summaries rather than full history.

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 explicitly directs the agent to sms_thread_get for full history, establishing when this summary-level tool is appropriate. It also explains the optional agentId filter and its scope, giving clear context for when to use it versus alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds meaningful context: it is callable by any authenticated credential, scoped to the caller's org, and defaults to the current calendar month in UTC when period is omitted. It doesn't discuss rate limits or pagination, but for a read-only rollup with an output schema, this is close to complete.

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

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

Four tight sentences, front-loaded with what the tool returns, then default behavior, then access model, then the routing hint. Every sentence earns its place with no filler.

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

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

With an output schema present, return-value explanation is not required, yet the description still names the counter keys an agent will see. Combined with the access and default-period context, 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 100% and the single parameter already documents the YYYY-MM format and UTC default. The description restates the default but adds no syntax or behavior beyond the schema, so the baseline 3 is appropriate.

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

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

States a specific verb+resource ('Usage rollup for a billing period') and enumerates what is returned ('counters keyed by usage type... plus the latest update timestamp'). An agent can immediately distinguish this aggregate rollup from per-event detail 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?

Explicitly names the use case ('answer where am I against my tier limits?') and the alternative it displaces ('without paying for per-event detail (UsageEvent is operator-tier)'). Nothing is left to inference about when to pick this tool.

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 signal that this is a mutating, non-idempotent operation; the description adds value by disclosing a key behavioral nuance: using `generatePassword` keeps the secret out of the conversation and returns only the credential reference. It also hints at post-creation constraints by telling users to set `allowedHosts` for broker-usable credentials, complementing the annotations without contradicting them.

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

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

Three sentences with no filler: the first states the core operation, the second gives the most security-relevant creation pattern, and the third covers the broker-access prerequisite. Each sentence earns its place and the most important guidance is front-loaded.

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

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

Given the tool's complexity — 14 parameters, nested payload objects, multiple credential types, and an output schema — the description covers the essential decision paths: choosing the type, providing the matching payload, generating passwords securely, and setting allowedHosts for brokerable credentials. It does not enumerate every payload field, but the schema and output schema carry that burden; the description is complete enough 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 coverage is 100%, so the baseline is 3. The description adds meaningful cross-cutting semantics beyond the schema: it explains the relationship between `type` and the payload blocks, recommends `generatePassword` over `login.password`, and ties `allowedHosts` to downstream exercise via vault_credential_use. This provides selection guidance that the flat property descriptions do not convey.

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

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

The description opens with a specific verb and resource: "Create a new credential in an agent vault." It clearly distinguishes this creation tool from its update, get, list, search, and use siblings, and the rest of the description reinforces scope by naming the credential types and payload blocks involved.

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 actionable usage guidance: pass `type` plus the matching payload block, prefer `generatePassword` for login credentials, and set `allowedHosts` for api_key/oauth_token credentials so they can be exercised via vault_credential_use. It does not explicitly state when not to use this tool versus an alternative, but the creation context and cross-reference to vault_credential_use provide clear directional context.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the destructive nature is clear. The description adds the rationale (removing obsolete or compromised secrets) but does not disclose additional behavioral details such as irreversibility, cascading effects on dependent resources, or permission requirements. With annotations covering the core safety profile, the description contributes modestly but does not contradict.

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

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

The description is a single, front-loaded sentence that states the action, resource, and key parameter (ID) immediately, followed by a brief usage note. There is no unnecessary verbiage or repetition of schema details. It is optimally concise.

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

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

The tool has an output schema, so return values do not need to be described. With two parameters (one required) and clear annotations (destructive, idempotent), the description covers the purpose and usage adequately. It does not mention prerequisites or post-conditions, but for a simple delete operation with full schema and annotations, this is nearly complete. The only minor gap is not explicitly stating permanence, though destructiveHint implies 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%: both 'id' and 'agentId' have descriptions in the schema. The tool description does not add any parameter-specific meaning beyond what the schema already provides. Baseline of 3 is appropriate since the schema fully documents the parameters.

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

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

The description states the exact operation: delete a credential from vault storage by ID. It clearly distinguishes from sibling tools like vault_credential_create, vault_credential_update, and vault_credential_get by specifying the deletion action and the target resource. No ambiguity about what the tool does.

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

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

The description provides a clear use case: 'Use to remove obsolete or compromised secrets.' This gives the agent context on when to invoke it. However, it does not explicitly state when not to use it or mention alternatives (e.g., vault_credential_update for changing a credential), but the purpose is specific enough that this is a minor gap.

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, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering safety and idempotency. The description adds valuable behavioral context beyond annotations by disclosing that sensitive fields are masked and that the LLM never sees the secret directly, which is critical for the agent's decision-making. No contradiction exists.

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

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

The description is two sentences long, with the core purpose in the first sentence and critical behavioral guidance in the second. It is front-loaded and contains no filler. Every sentence earns its place, making it efficient and easy to parse.

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

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

The tool is a simple get-by-ID operation. With an output schema present, the return format is documented. Annotations cover safety and idempotency. The description adds the crucial masking behavior and the alternative for plaintext, which fully equips an agent to decide when to call this tool and what to expect. Nothing essential is missing for correct invocation.

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

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

The input schema provides full 100% coverage with descriptions for both 'id' and 'agentId'. The description does not add additional meaning beyond the schema—it merely restates that the tool fetches by ID. Given the high schema coverage, the baseline of 3 is appropriate, and the description does not compensate for any gaps because none exist.

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

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

The description clearly states a specific verb ('Get'), a specific resource ('vault credential'), and the retrieval method ('by ID'). It differentiates from siblings like vault_credential_list and vault_credential_search by focusing on a single credential lookup. The purpose is immediately unambiguous.

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