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

The description explicitly details a critical behavioral trait: the draft will never be sent automatically and requires human review. This highly valuable context is not provided by the annotations or schema and prevents dangerous misinvocation.

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 definition is extremely concise, using a single sentence to explain the tool's function and constraints without any wasted language or extraneous detail.

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

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

For a low-complexity tool (2 required parameters), the description provides sufficient information regarding its function, state, and operational constraints to allow an agent to select and invoke it safely. Minor details like input string length or ID format are not addressed, but are not critical for initial usage.

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?

Given that schema description coverage is 0%, the description adds significant value by defining the semantic context of the input: the `body` is a 'reply to the customer' and the `case_id` ties it to a customer case. This helps the AI understand the functional meaning of the required 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 clearly identifies the specific action (Save a DRAFT reply) and the resource involved (customer). This distinguishes it from sibling tools that merely retrieve case data or update existing records.

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

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

It implies clear usage guidance by stating that the tool is for drafting purposes, effectively guiding the agent to use this tool when immediate sending is not appropriate. It serves as a clear instruction on the tool's intended use 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 declare readOnlyHint, idempotentHint, destructiveHint=false, and closed-world, so the safety profile is covered. The description adds the returned field list and id format, which is genuinely useful, but says nothing about error behavior for unknown ids or whether a missing case returns empty vs. throws.

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

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

Two short sentences with zero waste: the verb and resource are front-loaded, and the id-format hint is placed at the end where it is most useful. Nothing is redundant.

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

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

For a single-parameter read tool with full annotation coverage and no output schema, the description covers purpose, returned fields, and id format adequately. The only gap is not describing behavior on invalid or unknown case ids.

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 case_id schema already supplies the 'e.g. CS-1001' example, which the description simply repeats. No additional syntax, validation, or constraint detail is added beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Fetch a support case') and enumerates the returned fields (subject, customer description, status, account_id, order_id, reason), making it clearly distinguishable from siblings like get_customer_profile and get_order by resource.

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

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

Usage is implied — retrieve a case by id — but there is no explicit when-to-use/when-not guidance or reference to alternatives such as update_case for modifications or get_order for order data. The agent must infer the boundary itself.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so the safety profile needs no repetition. The description adds the concrete contents of the profile (fraud_flag, lifetime value, open cases, refunds), which is genuinely useful context about what the read surfaces, but it says nothing about lookup failure behavior or freshness of the aggregates.

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

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

Two short sentences, the field inventory front-loaded and the id format second, with no filler. The tradeoff is that the terseness comes partly from omitting a verb and any routing guidance rather than from tight editing.

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

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

For a simple one-parameter read tool with full annotation coverage and no output schema, the description does the important remaining work by listing the returned fields and the id format. Missing only not-found behavior and sibling routing, which are minor at this complexity.

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

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

Schema coverage is 0% for the single account_id parameter, so the description carries the burden. It partially compensates with the format hint 'Account ids look like A-100', which is real value beyond the bare string type, but it does not state whether the id is case-sensitive, whether an alternate id form is accepted, or what happens on a malformed id.

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

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

The description names the resource (a unified customer profile) and enumerates the fields it exposes, so the agent knows roughly what comes back. However, it is a bare noun phrase with no verb and no differentiation from siblings like get_case or get_order, leaving the agent to infer that this is a read of an account record keyed by account_id.

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

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

There is no when-to-use guidance at all: no mention of when to pick this over get_case, get_order, or draft_customer_email, and no prerequisites or exclusion conditions. The only inferable cue is that an account id is required.

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 readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds value beyond them by disclosing the shape of the returned record and the required id convention (O-5001), which is real behavioral context an agent needs before calling.

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

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

Two short sentences, front-loaded with the action and return shape, then the id hint. Nothing is redundant or 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 simple one-parameter read with rich annotations and no output schema, the description covers the essential: what comes back and how to form the argument. The only real gap is not-found behavior, which is minor for a lookup of this size.

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 documents nothing (0% coverage) and the single parameter is a bare string, so the description carries the burden. The "Order ids look like O-5001" example gives the format and prefix needed to construct a valid value, which is meaningful beyond the schema — though it doesn't state whether the prefix is case-sensitive or whether ids can be passed without 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?

States a specific verb and resource ("Fetch an order") and parenthesizes the fields it returns (item, amount, delivered_on, refunded). That is enough to distinguish it from siblings like get_case and get_customer_profile, though it never names those siblings explicitly.

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

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

Usage is only implied by the verb and the id-format hint — fetch a single order when you have its id. There is no explicit guidance on when to prefer this over get_case or get_customer_profile, and no statement about what happens when the order doesn't exist.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and non-idempotent, so the safety profile is established structurally. The description adds value beyond that: it flags a financial action, defines the $250 approval threshold, and clarifies that approved_by is populated by the harness rather than the model — a behavioral detail no annotation conveys. It omits remaining behavior such as reversibility of an issued refund or what happens on retry, which keeps it from a 5.

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

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

Three short sentences, front-loaded with the action and immediately followed by the risk warning and the approval constraint. The parenthetical about approved_by prevents a likely misuse and earns its space; nothing is filler.

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

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

For a destructive, non-idempotent financial mutation with no output schema and 20% parameter coverage, the description covers the most important risk (approval gating) but leaves gaps: whether partial refunds are supported, what reason should contain, whether the call is retryable, and what confirmation is returned. Adequate as a guardrail, incomplete as a full specification.

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

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

Schema coverage is only 20%, with approved_by the sole documented parameter, so the description must carry weight — and it does partially, explaining both the amount threshold and the provenance of approved_by. However, reason, case_id, and order_id receive no semantic elaboration (accepted values, format, or relationship to the order/case), leaving half the required surface undocumented.

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?

"Issue a refund for an order" gives a specific verb plus resource, and no sibling (get_case, get_order, update_case, draft_customer_email) competes for this action, so differentiation is implicit. It stops short of stating scope details such as partial vs full refunds, but the core action is unmistakable.

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

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

The description supplies one concrete usage rule — amounts above $250 require a human approver — which is genuinely actionable gating information. It does not say when to prefer this over alternatives (e.g., escalation paths, or when a refund should instead be declined or drafted as an email to the customer), leaving the broader invocation context to inference.

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

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

Annotations already disclose non-read-only, non-destructive, non-idempotent, closed-world behavior, so the safety profile is covered. The description adds one genuinely useful fact beyond them: the note is 'internal', i.e. not customer-visible. However, it does not explain why the call is non-idempotent, whether status changes notify the customer, or whether the update is reversible — notable gaps for a mutation 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?

A single tight sentence with the action and both effects front-loaded; nothing is redundant. It is arguably too terse, but that gap is better attributed to completeness than to wordiness.

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 three-required-parameter mutation with zero schema descriptions and no output schema, the definition should state whether the note is appended or replaces an existing one, whether status transitions are constrained, and what the caller gets back. None of that is present, so an agent can invoke it but cannot predict its effect.

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

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

Schema coverage is 0%, and the schema itself only names the fields; the enum values for status are self-documenting. The description does add real meaning for two parameters ('internal note' implies internal-only visibility; 'set case status' implies overwrite rather than append), but leaves case_id and note length/append-vs-replace semantics unexplained.

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

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

Names a specific verb ('Set') and two concrete resources (case status, internal note), which is enough for an agent to distinguish it from the read-only siblings like get_case. It stops short of explicitly contrasting itself with any sibling by name.

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

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

There is no guidance on when to use this versus alternatives, no prerequisites (required permissions, whether the case must be open), and no statement of what happens downstream when a status is set. The agent must infer usage entirely from the name.

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