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

Beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true), the description discloses the duplicate-request outcome: a second call is refused with the existing invoice number as a CONFLICT. That is genuinely useful error semantics an agent cannot infer from structured fields, though there is mild tension worth noting — idempotentHint=true while repeats are rejected rather than silently succeeding (the net state is still one invoice, so this is not a contradiction).

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

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

Three short sentences, zero filler, with the core action and its derived amount front-loaded and the failure modes packed into the follow-up clauses.

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 and all three parameters are documented, so the description need not explain return values; it covers the key constraints (uniqueness, conflict, order-state gating). It could still say what happens to the invoice after issuance (e.g., whether it is sent or merely created), which is the main residual gap.

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

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

Schema description coverage is 100%, so order_id, notes, and due_in_days are already fully documented in the schema, and this establishes a baseline of 3. The description adds only that the amount equals the order total (i.e., it is not a settable parameter), which is minor added meaning.

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 ("Issue the invoice for an order") and immediately pins the derived amount to the order total, so the agent knows exactly what is created. This is clearly distinct from siblings like issue_refund and update_order_status; no overlap is possible.

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 gives the preconditions for use: one invoice per order, and cancelled/refunded orders cannot be invoiced. It does not name an alternative tool or explain what to do instead when refused, but no sibling tool is a real substitute, so the guidance is close to complete.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety bar is largely met structurally. The description adds value by revealing that the response includes derived state — allowed next statuses, refundable remainder, days late — which tells the agent this call is a decision substrate for writes. It does not mention error behavior for a missing order.

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 dense sentence enumerating the payload followed by a single imperative directive; the operational rule is front-loaded at the end with zero filler. Nothing repeats 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?

With an output schema present the description need not explain return values, yet it still orients the agent on what matters. For a simple one-param read it is near-complete; only failure modes for an invalid or nonexistent order_id are 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 100% and the single order_id parameter is already documented with an example in the schema. The description adds no format, range, or lookup guidance beyond it, 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 ('Full detail for one order') and immediately scopes it against the sibling list_orders by emphasizing a single order with full detail. The enumeration of what 'full detail' means (status, customer, line items, totals, refunds, invoice, delivery timing) removes any ambiguity about the payload.

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?

'Call this before any write on an order' gives a concrete precondition that ties it to update_order_status and issue_refund. It stops short of an explicit negative case (e.g. use list_orders to browse), so it is strong but not fully 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 destructiveHint=true and idempotentHint=true, and the description adds substantive behavioral context beyond that: amount limits, refusal cases, idempotency replay semantics, order state transition to 'refunded', and audit logging. This is rich transparency 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?

The description is dense but well-structured, front-loading the purpose before listing guardrails, idempotency behavior, and side effects. Every sentence carries useful information and none is wasted.

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, idempotent mutation with an output schema and full annotation coverage, the description supplies everything an agent needs: purpose, eligibility, refusal cases, idempotency behavior, and side effects. No important behavioral gap remains.

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 four parameters are already documented in the schema. The description reinforces the amount guardrail and idempotency-key behavior, but much of that is already present in the schema descriptions, so this is baseline rather than added semantic 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?

States a specific verb and resource ('Refund money on a paid order') and clearly scopes the operation to paid orders. An agent can distinguish this from sibling tools like get_order or update_order_status 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 gives clear when-to-use conditions and explicit when-not cases: unpaid, cancelled, and fully-refunded orders are refused. It does not name sibling alternatives such as using get_order to check the remaining refundable amount, but the guardrails are otherwise strong.

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, destructiveHint=false and openWorldHint=false, so safety needs no restating. The description adds that results are paginated and that late_only can mean two different things resolved via a per-row delivery_status — useful behavioral context — but the sentence about row contents largely restates fields the output schema already exposes.

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 verb and filter scope, with no filler. The second sentence about row contents is slightly redundant against the output schema, which is the only thing keeping it from a 5.

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 need not explain return values, and the annotations cover the safety profile. Given 10 optional parameters at 90% schema coverage, the description supplies what is left: that results are paginated and that late-only spans delivered-late and overdue orders.

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 90%, so nearly every parameter is self-documenting in the schema and baseline 3 applies. The description's parenthetical filter list mirrors the schema rather than adding format, defaults, or edge-case behavior, and it never mentions the sort parameter or limit caps.

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?

Says "Search orders" with a concrete enumeration of the filter dimensions (status, customer, placed date range, total range, late-only) plus pagination, so the verb+resource+scope are unambiguous. It stops short of naming siblings such as get_order or search_customers, so the distinction from a single-order fetch must be inferred from the word "Search".

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

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

Usage is only implied: the filter list tells the agent this is the filtered/multi-row retrieval path, but there is no explicit "use this when / prefer get_order when you already have an id" statement. The sibling set (get_order, sales_report, search_customers) is common enough that an agent can guess, but the description does not route it.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so safety is covered. The description goes beyond that by disclosing the boundary condition ('strictly below', so at-threshold items are excluded), the sort order, and the exact derivation of the suggested reorder quantity (refill to target, rounded up to the supplier case pack) — real behavioral value the agent could not infer from 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?

One sentence with no wasted words, and the most decision-relevant facts — the filter condition and the ordering — are front-loaded. Parenthetical glosses for the derived field are compact and unambiguous.

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 and annotations are rich, so the description need not explain return values or safety. It covers the qualifying condition, ordering, and derived-quantity logic. Minor gaps remain: 'most urgent' is not defined (e.g. largest absolute vs. relative shortfall) and there is no mention of result limits or the empty-result case.

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 optional parameter is an enumerated category, so the schema fully documents the input. The description does not mention the category filter or clarify whether it is optional, adding nothing beyond the schema. 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?

The description names a specific resource (products below their reorder threshold) and adds scope-defining detail — 'strictly below' and 'most urgent first'. It reads as a return-value spec rather than a verb-led statement ('List products...'), but the semantics are unambiguous. None of the sibling tools operate on inventory at all, so no sibling differentiation is required.

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 explicit statement of when to call this versus alternatives, but the definition of the qualifying condition ('stock strictly below their reorder threshold') implicitly tells an agent the tool answers a restocking question. With no inventory-related siblings, there is little ambiguity to resolve, so the omission is minor rather than damaging.

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 (readOnlyHint=true), the description details the complex calculation logic (net = gross minus refunds), the unit of measurement (all in cents), and the specific filtering behavior (excluding pending/cancelled orders).

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 highly dense but structured logically, moving from what the tool generates to its calculations, and finally its limitations. Every sentence adds unique, essential 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?

Given the complexity of multiple grouping options and specific financial calculations, the description covers all critical behavioral details—including what is excluded and how data is processed—making it maximally complete for an AI agent.

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?

Since schema coverage is 100%, the description's primary value is reinforcing the context of the grouping parameters. It specifies that the grouping (day, week, month, etc.) operates on the 'order placed date,' adding vital context to the input constraints.

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 defines the tool's function: generating a 'Sales report.' It specifies the resource (sales data) and the scope (date range), making its purpose unambiguous relative to other sibling 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?

It provides critical constraints on how the tool behaves, specifying that it aggregates data based on the 'order placed date' and explicitly excluding 'Pending and cancelled orders.' This gives the agent precise boundaries on 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 declare read-only, idempotent, closed-world behavior, so the safety profile is covered. The description adds real value beyond that: it lists what each match contains (contact details, order count, lifetime spend) and defines an ambiguity-handling protocol keyed on the `ambiguous` flag.

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 what the tool does, then result shape, then the disambiguation branch. No filler or repeated annotation 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?

With an output schema present, return structure needn't be spelled out, and the ambiguity case is handled explicitly. Minor gaps remain around zero-match behavior and truncated results at the limit cap, but nothing essential for a correct call 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 schema already documents length bounds, defaults, the 25 maximum, and case/accent-insensitive typo tolerance. The description's mention of partial and fuzzy matching largely restates that, adding no format or syntax detail 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?

States a specific verb and resource ('Find customers') plus the searchable fields (name or email) and matching modes (exact, partial, fuzzy). No sibling tool overlaps with customer lookup, so the scope 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?

Explains the search modes available and gives an explicit follow-up rule when `ambiguous` is true: ask the user for a disambiguating attribute before acting. It stops short of naming when to prefer a different tool, but no sibling performs customer lookup.

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

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

Annotations declare destructiveHint=true and idempotentHint=true; the description corroborates and enriches this by explaining the rejection behavior (409 CONFLICT with the allowed next statuses in the response), the no-op on same-status writes, and that changes are audit-logged. These are exactly the failure modes and side effects an agent needs before invoking a mutation.

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

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

Four short sentences, front-loaded with the transition table, followed by the failure mode, the exclusion, and the idempotency nuance. No filler; each clause carries an operational rule.

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-parameter mutation tool with full schema coverage, rich annotations, and an output schema, the description covers everything an agent needs: valid inputs, rejection semantics, the excluded value, and side effects. Nothing material is delegated to guesswork.

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 would be 3, but the description adds real meaning the schema does not: 'refunded' appears in the enum yet must never be set directly, which materially changes how the status parameter should be used. The note parameter's audit-log purpose is left to the schema, which already documents it 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?

States a specific verb and resource and immediately defines the exact state machine it operates on (pending->paid|cancelled, paid->shipped, shipped->delivered). It also names the sibling tool to use instead for 'refunded', so an agent can separate this from issue_refund 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?

Explicitly enumerates valid transitions, states that other transitions are rejected with CONFLICT plus the allowed next statuses, and routes 'refunded' to issue_refund. It also pre-empts the redundant-call case by noting that re-setting the current status is a no-op.

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