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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false. The description adds real context beyond those flags: the audience/visibility model ('Only staff see notes, never the customer') and the practical non-idempotency consequence ('Each call adds a new note'), warning the agent that repeat calls create duplicates. It does not detail auth/permissions or return 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?

Three short sentences, front-loaded with the core action, and each adds a distinct fact (action, visibility, non-idempotency). No filler or repetition, though it is minimal rather than richly 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?

An output schema exists, so return values need not be explained, and annotations carry the safety/mutation profile. For a simple two-parameter write tool the description is nearly sufficient, with the notable gap being parameter semantics given 0% schema coverage.

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

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

Schema description coverage is 0%, so the description must compensate, but it only implicitly suggests a ticket reference and note body without naming or explaining ticket_id or body. No format guidance (e.g., ticket_id is numeric-only) is provided, leaving the schema to carry parameters it does not document.

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: 'Add an internal note to a ticket.' This is clearly distinct from siblings like search_tickets, get_ticket, export_tickets, and issue_refund, which an agent can tell apart without opening schemas. It stops short of explicitly naming siblings, so 4 rather than 5.

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

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

The line 'Only staff see notes, never the customer' implies this is the channel for staff-only communication, which hints at when to use it. However, no explicit when/when-not conditions or alternatives (e.g., a customer-visible reply tool) are named, so guidance remains implied.

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

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

With readOnlyHint=true and openWorldHint=false already declared, the description still adds real value: it warns that large exports are slow, notes progress reporting, and discloses the asynchronous-ish 'export id' return. That is meaningful operational context the annotations do not carry. It stops short of saying how long 'slow' is or whether the id must be polled elsewhere.

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

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

Three tight sentences, front-loaded with purpose, then performance, then return. No filler or repetition of the name/title.

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

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

The output schema presumably covers the return shape, so the description needn't explain it further. The performance warning and export-id mention round out the key behavioral facts. The main gap is routing: nothing tells the agent why to pick this over search_tickets for non-file use cases.

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

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

Schema description coverage is 100% for the single 'status' parameter (with an enum), so the schema already fully documents it. The description adds nothing about the parameter, which is acceptable at this coverage level but earns only 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 names a specific verb and resource plus the output format: 'Export tickets to a CSV file.' That is far more precise than the tautological title. It does not, however, distinguish itself from siblings like search_tickets, which an agent might reasonably reach for when it just wants ticket data.

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 a useful performance caveat ('Slow for large exports'), which is the closest thing to guidance, but no statement of when to use this over search_tickets, nor any exclusions or prerequisites. The agent is left to infer that export is for bulk file retrieval rather than interactive querying.

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 openWorldHint=false, so the safety profile is covered by structured data. The description adds useful context about the record's composition and the id convention, but does not mention auth requirements, error behavior, or whether the fetch fails hard on a bad id.

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

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

Two short sentences, front-loaded with the action and return contents, followed by the id convention. No filler and nothing repeated that the schema covers more precisely.

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

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

A single-parameter read tool with full schema coverage, annotations carrying the safety profile, and an output schema that owns return-value documentation. Nothing an agent needs to invoke 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% with a single parameter that already documents the pattern and example, so the description merely restates the cus_ convention. With the schema doing all the work, baseline 3 is correct; the description adds no syntax or edge-case detail beyond it.

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

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

States a specific verb (Fetch) and resource (one customer account) and clarifies the domain entity (a gym or yoga studio) plus what the record carries (plan, contact email, recent charges). There is no competing customer tool among the siblings, but the scope is unambiguous enough that an agent knows exactly what it gets.

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

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

Usage is implied by the tool name and the 'fetch one' framing, but there is no explicit when-to-use guidance, no statement of prerequisites, and no pointer to an alternative (e.g. how to find a customer id before calling). Adequate but with clear gaps.

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 openWorldHint=false, so the safety profile is covered. The description adds the shape of the payload (subject, status, customer id, messages), which is useful context, but says nothing about behavior for a missing/invalid ticket or any access restrictions.

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 tight sentences: the action and returned fields come first, and the identifier format constraint follows. No filler, no repetition of the title.

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

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

With an output schema present, the description needn't explain return values, yet it helpfully summarizes them; annotations cover read-only semantics and the lone parameter is fully specified. The only real gap is error/not-found behavior, which is minor for a simple getter.

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

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

Schema description coverage is 100% and the single parameter is fully documented with a regex pattern and example. The description's 'digits only, for example 2318' merely repeats the schema, adding no new semantics; baseline 3 is correct.

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 one support ticket by its number') and enumerates the returned fields, so the agent knows exactly what it gets. It distinguishes itself from search_tickets only implicitly through 'one ... by its number' rather than naming the sibling, which keeps it out of 5 territory.

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

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

Usage is implied by the required identifier: call this when you already have a ticket number. There is no explicit when-to-use statement, no mention of the search_tickets alternative for cases where you only have a name or subject, and no exclusion guidance.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=true, and openWorldHint=true, so the safety profile is covered structurally. The description nonetheless adds two pieces of real context: the confirmation requirement and the at-most-once refund guarantee per ticket/charge pair, which reinforces (and does not contradict) idempotentHint.

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, followed by the idempotency guarantee and the unit convention. Every sentence carries information, though "through the billing provider" is closer to implementation detail than decision-relevant 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?

An output schema exists, so return values need not be explained, and annotations carry the mutation/destructiveness profile. The description covers the action, precondition, retry semantics, and amount units; only failure modes (e.g. already-refunded or invalid charge) are left unaddressed.

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

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

Schema coverage is 67% — charge_id and amount_cents are documented in the schema, ticket_id is not. The description's "Amounts are in cents" restates the unit already conveyed by amount_cents' example (4900 for $49.00), so it adds little beyond the schema. Baseline 3 is appropriate given the schema does most of the work.

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

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

States a specific verb (refund) and resource (a customer's charge for a ticket), and clarifies the path taken (through the billing provider). No sibling tool overlaps with refunding, so there is no ambiguity to resolve against search_tickets, get_ticket, get_customer, export_tickets, or add_internal_note.

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?

"After the user confirms" gives a clear precondition for invocation, which is exactly the kind of guidance an agent needs before calling an irreversible-feeling money operation. It stops short of naming any alternative or when-not-to-use condition, so it does not reach a full 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 only declare readOnlyHint and openWorldHint, so the description's disclosure of page size (50 per page), sort order (most recently updated first), and pagination dependency (cursor from previous page) adds real operational context. Returned fields are enumerated but overlap with the existing output schema, so not a full 5.

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

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

Two tight sentences with the search scope and pagination front-loaded and nothing extraneous. The trailing enumeration of returned fields is largely recoverable from the output schema, a small 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?

With an output schema present, the description needn't explain return values, and it still adds pagination, ordering, and match scope. The main gap is the absence of when-to-use routing against the other four ticket siblings, plus no mention of the status filter.

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

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

Schema coverage is 67%; the description clarifies what 'query' matches against (subject or messages), which adds meaning beyond the schema's terse 'Words to match.' It says nothing about 'status' filtering or 'cursor' usage, so it only partially compensates for the coverage gap.

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

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

Clear verb+resource ('Search support tickets') with the matching scope spelled out (words in subject or messages), which distinguishes it from the single-ticket sibling get_ticket. It does not name any sibling explicitly, so it stops short of a 5.

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

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

The description says how the search behaves but never says when to choose it over get_ticket, export_tickets, or an unfiltered list. The closest thing to guidance ('leave out to list all tickets') lives in the schema, not the description, leaving usage to inference.

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