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

The description is consistent with readOnlyHint=false — it creates a ticket — and adds useful context that the ticket routes to a human support team. It does not say what happens after escalation (ticket ID returned, expected response time, whether the conversation ends or the customer must be told anything), which matters for a hand-off 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 sentences, no filler, with the action front-loaded and the usage triggers following. Every clause earns its place.

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

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

For a two-parameter hand-off tool with no output schema and minimal annotations, the description covers what is needed to decide to call it. The remaining gap is post-call behavior — whether a ticket reference comes back and what the agent should tell the customer — which keeps it from being 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?

Only one of two parameters (summary) has schema text, leaving the description to compensate for the 50% coverage gap, which it does not do at all. The undocumented 'priority' is an enum (low/normal/urgent) whose values are largely self-explanatory, so the practical loss is small but guidance on when to use 'urgent' would have been valuable.

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

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

The description gives a specific verb and resource — 'Open a ticket for the human support team' — that an agent cannot confuse with any sibling (lookup_customer, get_order, issue_refund, etc.). The action and its recipient are stated in the first clause.

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 enumerates concrete triggers (customer asks for a person, warranty claims, cancellations) plus an explicit fallback rule: 'anything the other tools and policies cannot solve.' That fallback implicitly tells the agent not to escalate when a sibling tool can resolve the request.

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?

readOnlyHint already establishes the safety profile, so the bar is lower. The description still adds real value by naming the data returned and by declaring its role as a mandatory prerequisite to issue_refund. It says nothing about behavior when the order doesn't exist or about response latency, which keeps it below a 5.

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

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

Two sentences, no filler. The content summary is front-loaded and the call-condition follows immediately, which is the right order for an agent scanning the definition.

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

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

With no output schema, the description usefully enumerates the fields returned, and the prerequisite relationship to refunds is stated. Missing are failure-mode behavior (invalid or unknown order_id) and any hint that track_shipment should be consulted for carrier-level detail.

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 order_id parameter is documented with a concrete format example (NW-5001). The description adds no further meaning about the identifier, so the baseline 3 applies.

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

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

States a specific verb and resource (get one order) and enumerates the returned content: status, items, totals, refund eligibility, shipping address. This distinguishes it from lookup_customer and track_shipment, which cover adjacent but different resources.

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 explicit when-to guidance: 'before answering any question about a specific order, and before issuing a refund,' which directly gates the sibling issue_refund. It does not address when track_shipment is the better choice for a purely shipment-status question, so a boundary case remains unaddressed.

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=false, so the description carries most of the behavioral burden — and it does well, disclosing the 30-day window, the remaining-balance ceiling, and that refunds over $100 are held for human approval rather than executed. What it omits is the observable result of a held refund (does the call succeed with a pending status or fail?), which matters 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?

Three short sentences, front-loaded with the action, followed by enforced constraints and the prerequisite call. No filler; each clause carries actionable 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 3-param mutation with no output schema, the agent knows the action, the hard policy limits, the prerequisite lookup, and that high-value refunds are gated. The remaining gap is what a successful versus held response looks like, but nothing prevents a 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 amount, reason, and order_id are already fully documented with format examples. The description adds only the notion that 'amount' may be partial, which is marginal. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource — refunding part or all of an order to the original payment method — which no sibling tool (get_order, escalate_to_human, etc.) shares. The scope ('part or all') is precise enough that an agent can pick this tool without inspecting the schema.

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

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

Explicitly names a prerequisite sibling and action: 'Call get_order first to check amounts.' The policy block also functions as when-not guidance (over 30 days, exceeding remaining balance, >$100 requires human approval). It stops short of naming escalate_to_human as the alternative for the held case, leaving that inference to the agent.

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, so safety is covered. The description adds useful implicit scoping — the result is tied to the signed-in identity since there is no customer id parameter — but it doesn't say what happens with an unauthenticated/missing session or how many orders come back.

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 primary when-to-use cue placed first. Every clause carries information an agent needs to route the call.

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 no-argument read tool with no output schema, the description covers what is retrieved (profile plus orders) and when to reach for it. Order volume/truncation and authentication failure behavior are the only uncovered edges.

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 there is nothing for the description to disambiguate; the baseline applies. It implicitly explains why there are no arguments by tying the lookup to the signed-in customer.

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

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

Specific verb and resource ('Get the signed-in customer's profile and a list of their orders') that also previews the return payload. It is clearly distinct from get_order, which targets a single identified order.

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 actionable trigger plus priority ordering: 'Call this first when the customer refers to an order without giving its number, or asks about their account.' It stops short of naming get_order or track_shipment as the alternatives to use once an order number is known.

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, so the safety profile is covered. The description adds meaningful context about what corpus is indexed and the intended pre-answer workflow, but says nothing about ranking, result limits, or what an empty result means. Adequate but with clear gaps for search 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 sentences with zero waste; the resource and scope come first and the operational instruction follows. Nothing redundant with the name or title.

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

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

For a single-parameter, read-only lookup with full schema coverage and annotations, the description supplies the domain and the intended workflow, which is enough to call it correctly. Only the return-behavior details (result count, ranking, no-match handling) are missing, and those are minor for 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 description coverage is 100% and the schema already gives format guidance via the example ('return policy', 'warranty'). The description adds no additional query syntax, keyword-vs-phrase, or length guidance beyond what the schema provides, so baseline 3 applies.

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

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

States a specific verb (full-text search) plus the exact resource (the Northwind Gear help center) and enumerates the content domains covered (policies, shipping, warranty, sizing). This makes it unmistakably distinct from the operational siblings such as get_order, track_shipment, and issue_refund.

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 says to call it for 'any policy or how-to question' and to do so 'before answering from memory', which is a clear usage trigger. It stops short of naming exclusions or pointing at a specific alternative for non-policy questions, so it is strong but not fully specified.

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 readOnlyHint annotation already establishes this is a safe, non-mutating lookup, so the description's burden is lower. It usefully discloses the shape of the returned data, but says nothing about failure modes (order not found, no shipment on file) or latency/auth considerations.

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

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

Two sentences, zero filler, with the returned-fields summary front-loaded and the invocation condition following. 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?

With one required parameter, annotations covering the safety profile, and no output schema, the description appropriately fills the return-value gap by enumerating the fields returned. It is essentially complete for a simple read tool, missing only edge-case 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 the single order_id parameter is documented in the schema with a concrete example (NW-5001). The description adds no meaning beyond the schema, which is the expected baseline when the schema does the work.

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

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

States a specific verb ('Get') and enumerates exactly what the tool returns: carrier, tracking number, delivery status, ETA and scan history for an order. An agent can immediately distinguish this shipment-tracking read from siblings like get_order or lookup_customer.

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

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

Gives a concrete trigger: 'Call this when the customer asks where a parcel is or when it will arrive.' That is clear usage context, but it names no exclusions or alternatives (e.g., when to prefer get_order for order-level questions), 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 only declare readOnlyHint=false, so the description must supply the rest. It adds a genuinely useful state constraint (the order must not have shipped) and an anti-hallucination guard, but says nothing about what happens on failure, whether the change is reversible, or whether shipping cost/dates are recalculated.

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 precondition front-loaded before the invocation guardrail.

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

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

For a two-parameter mutation with no output schema, the description covers the two things an agent could most plausibly get wrong: calling too late and inventing address data. It could still say what the tool returns or how it reports rejection for a shipped order.

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

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

Schema coverage is 50%; order_id and the address subfields are largely documented in the schema itself. The description reinforces that the address must be complete (no partial or guessed values), but adds no field-level meaning beyond that.

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

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

Names a specific verb and resource (change the shipping address of an order) plus a qualifying precondition (not shipped yet) that immediately separates it from sibling mutations like issue_refund. It stops short of naming an alternative tool, but no sibling competes for this operation.

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 explicit call-time guidance: only call after the customer has supplied the complete new address, and never guess missing parts. That is clear when-to-use and when-not-to-improvise guidance, though it does not state what to do instead when the order has already shipped.

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