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

Beyond annotations it discloses the two things an agent most needs: existing lines are wholly replaced (not merged) and the order state is reset to Draft, which matters most for an unapproved-only operation. It also surfaces the two-step confirmation guard from preview. Minor tension with destructiveHint=false given full line replacement, but since the target is an unapproved draft that is recoverable via resubmission, this reads as scoping rather than 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?

Purpose and state effect are front-loaded in two sentences, then a compact Args block with one line per parameter. No filler; the docstring format is slightly mechanical but every entry 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?

An output schema exists so return values need no explanation, and the description covers the state rule, replacement semantics, and prerequisite confirmation code. Remaining unstated behavior (validation errors on approved orders, whether prices/approvers are re-derived) is not critical to calling 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 description coverage is 0%, so the description carries the full burden and mostly does: po is the order ID, lines is the complete replacement set (explicitly not additive) and defers shape to create_purchase_order, confirmation_code's provenance is spelled out, notes is optional. Only gap is that the exact object shape of a line is left entirely to a sibling tool.

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 ('Replace the lines of an unapproved order') plus the resulting state change ('goes back to Draft for resubmission'). It also implicitly distinguishes itself from create_purchase_order by referencing that tool's line shape, though it never explicitly names which sibling to use when the order IS approved.

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 hard precondition ('unapproved order') and a required workflow step: confirmation_code must come from preview("amend_purchase_order", <these same args>). That is real when-to-use guidance. It stops short of naming the alternative path for approved orders (e.g. cancel/reject + recreate), leaving that 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 only declare this as a non-idempotent, non-destructive write; the description adds the critical policy that approval happens as the configured user and never as the requester, plus the preview-code gate. It omits failure behavior for missing/invalid codes and says nothing about reversibility of an approval, which matters for a non-idempotent 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?

Front-loads the action and the actor constraint before the Args block, and every line conveys something actionable. The docstring-style Args formatting is slightly mechanical but not wasteful.

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 described, and the description covers the actor identity rule and the two-step preview/confirm flow. It lacks any statement of what happens on an invalid or absent confirmation_code and whether a completed approval can be undone.

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 carries the load, and it defines all three parameters: po as the purchase order ID, confirmation_code with its exact source expression, and comment as optional. The po format/example is still unspecified, leaving a small gap the schema does not fill.

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 ('Approve a pending purchase order') and narrows scope to pending POs, which separates it from amend/cancel/reject siblings. It stops short of naming those siblings explicitly, so an agent must infer the boundary rather than read it.

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?

Establishes a clear prerequisite: approval requires a confirmation_code obtained from preview('approve_purchase_order', <same args>), which routes the agent through the correct prior tool. It does not say what to do when the PO is not pending or when no code is available, so exclusion cases are unstated.

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, so the safety profile is covered. The description adds real value by disclosing that refused write attempts are included, but it says nothing about ordering, retention window, or whether results are truncated by recency — gaps that matter for an audit 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 purpose is front-loaded in one sentence, followed by a compact Args block. Every line earns its place, though the 'Args:' formatting is a bit list-like rather than prose-integrated.

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 both optional parameters are documented. However, for a low-annotation-burden read tool with 0% schema coverage, the description still omits result ordering and the meaning of 'recent' (how far back), leaving an agent unable to reason about result scope.

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% — the schema exposes 'target' as a bare anyOf string and 'limit' as an integer with only a default — so the description carries the full burden and mostly meets it. It explains that target accepts a purchase order or supplier document ID and that limit is bounded 1-100, which the schema never states.

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 precisely ('po-guard audit records') and clarifies scope ('every write attempt, including refused ones'), which clearly separates it from the purchase-order CRUD siblings. It lacks an explicit verb (list/read), but the noun phrase is unambiguous enough that an agent can identify it as a read of audit 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 word 'Recent' implies a recency scope and 'including refused ones' hints at an investigation/audit use case, but there is no explicit when-to-use or when-not-to-use statement and no mention of alternatives among the 13 siblings. Usage is inferable rather than stated.

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, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds useful semantics about what 'committed' means (spend from live orders), but says nothing about how 'live' is defined, caching, or freshness of the figures.

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 blocks, front-loaded with the payload summary; the example is high-value. The 'Args:' docstring formatting is slightly mechanical but wastes no 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?

With an output schema present and read-only annotations covering safety, the description only needs to explain the computation and its input, which it does. Minor gaps around order-liveness criteria and name matching are not blocking for a single-param lookup.

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%, so the description must carry the burden — and it does supply the meaning of cost_centre plus a concrete format example ('Fleet Operations - LDU'). Matching semantics (exact vs partial name) remain unstated, keeping it below a 5.

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 and scope: a cost centre's annual budget, committed spend from live orders, and remaining balance. Clearly distinct from the PO-mutation siblings, though it doesn't explicitly name or contrast any alternative.

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?

No guidance on when to call this versus e.g. list_purchase_orders or preview, no prerequisites, no exclusions. The agent must infer usage from the one-line content summary.

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 and destructiveHint=true, and the description adds genuinely non-derivable context: the cancel is a soft state change, the record is retained, and nothing is deleted. It does not state whether cancellation is reversible, whether approvals are required, or what happens if the confirmation code is stale, and 'nothing is deleted' mildly softens the destructiveHint framing without contradicting it.

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 irreversible-effect caveat is front-loaded in the first two sentences, then a compact Args block covers each of the three parameters in one line each. No restatement of the tool name, 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?

An output schema exists, so return values need not be described. Parameters, the soft-cancel semantics, and the preview prerequisite are all covered for a 3-param mutation. What remains unaddressed is failure behavior — missing, expired, or mismatched confirmation codes — which an agent calling a destructive operation would benefit from knowing.

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 carries the full burden, and it does: po is identified as the purchase order ID, reason as the rationale, and confirmation_code is given provenance (obtained from preview with the identical argument set). That provenance detail is the single most important thing an agent needs and is absent from the schema entirely.

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 ('Cancel a purchase order') with an added effect clause ('stays on record as cancelled; nothing is deleted'). An agent can distinguish it from siblings like amend_purchase_order or reject_purchase_order by verb alone, but the description never explicitly contrasts those adjacent operations in the same approval workflow.

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 confirmation_code documentation encodes a clear workflow: call preview("cancel_purchase_order", <these same args>) first, then call this tool with the returned code. That is concrete, actionable guidance tied to a named sibling. It stops short of saying when cancel is the correct choice versus amend or reject.

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 cover the safety profile (not read-only, not destructive, not idempotent, closed-world), and the description adds real context beyond them: the result is a draft (not submitted for approval), a preview-confirmation gate is required, and notes are stored verbatim. It doesn't say what the response contains or whether duplicate calls create duplicate POs, but the output schema covers returns.

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 front-loaded sentence states the action and the gating requirement, then a compact Args block. Every line adds information an agent needs; nothing is padding.

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 mutation tool with an output schema already present, the description supplies the missing pieces: the draft semantics, the confirmation-code workflow, and full parameter documentation. An agent has everything needed to invoke it correctly without guessing.

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 carries the full burden and does: it documents all six parameters including the nested line-item shape (item_code, qty, rate, optional description), the provenance of supplier and confirmation_code, and an ISO date example for required_by. This is meaning the schema alone does not provide.

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 ('Create a draft purchase order') and the qualifier 'draft' distinguishes it from submit_for_approval and approve_purchase_order in the sibling set. An agent can tell immediately this is the creation step, not the workflow-transition step.

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 prerequisite and names the alternative: the confirmation code must come from `preview` called with these same args, which establishes the required two-step workflow. It also points to search_suppliers as the source of the supplier ID, so the agent knows the ordering of calls.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds a field inventory of the returned record, but says nothing about not-found/error behavior, permissions, or whether all listed fields are always present.

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 compact elements: a front-loaded field summary and a single argument note. The raw docstring formatting with the trailing newline and indented Args block is slightly unpolished but wastes no 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?

For a one-parameter read tool with an output schema (so return shape is already specified), the definition covers purpose, scope, and ID format adequately. Missing only error/not-found behavior, which is minor given the read-only annotation.

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 'po' property has no description, so the description carries the burden — and it does so by naming the parameter and giving a concrete ID format example ("PUR-ORD-2026-00012"), which is the key thing an agent needs to format the call correctly.

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 clearly that it fetches a single purchase order and enumerates the fields it returns (supplier, cost centre, lines, total, status, requester, approver). The phrase 'One purchase order' implicitly contrasts with the sibling list_purchase_orders, but no sibling is named 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: the required 'po' ID signals a lookup of one known record, which suggests list_purchase_orders when the ID is unknown. There is no explicit when-to-use guidance, no statement about what happens if the PO doesn't exist, and no alternatives named.

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, destructiveHint=false, and openWorldHint=false, so safety is covered. The description contributes the ordering behavior (newest first) and the limit ceiling of 1-100, but says nothing about the 25-row default, total counts, or whether results page beyond limit — the kind of detail that matters for a listing 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 one-line summary is front-loaded and immediately usable; the Args block is justified here precisely because the schema documents nothing. Slight waste in restating argument names without added detail in a couple of cases, but no filler sentences.

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-value detail is unnecessary, and all four optional parameters are explained in the description. A 4 rather than 5 because the absence of any pagination or result-count signal leaves an agent guessing how to retrieve beyond the first page.

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 carries the full burden, and it largely does: it clarifies what supplier and cost_centre identify, enumerates the five valid status values that the schema does not constrain via enum, and bounds limit at 1-100. Remaining gaps are the unstated default of 25 and the argument types.

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 purchase orders") plus an ordering guarantee ("newest first"), which distinguishes it from the singular get_purchase_order by implication. It stops short of explicitly naming the sibling it contrasts with, but the plural/list framing makes the read-many vs read-one split clear.

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 filter arguments imply the intended use — browsing/narrowing a collection by supplier, cost centre, or status — but the description never states when to prefer this over get_purchase_order, nor when to use which filter. With thirteen siblings, including several single-record operations, an explicit routing sentence would have earned a higher score.

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 write, non-idempotent, non-destructive, closed-world. The description adds genuinely new context: duplicate checks run on name and tax_id, notes is stored verbatim, and bank details are never accepted. It does not say what happens on a duplicate hit (error vs. merge) or what the confirmation code failure mode looks like.

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 front-loaded one-sentence purpose, a sharp constraint ('No bank details, ever.'), then a compact Args block. Every line earns its place with no restatement of the schema.

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?

Output schema exists, so return values needn't be explained, and the preview prerequisite is covered. Remaining gaps are the duplicate-check outcome and the failure behavior of an invalid confirmation code, which matter for a non-idempotent write.

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 carries the full burden and largely succeeds: all four parameters are documented, including the non-obvious confirmation_code provenance and that tax_id is duplicate-checked and notes is stored as-is. Only 'name: Legal name' is thin for a field that determines duplicate matching.

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 first sentence names a specific verb and resource (add a supplier) and states the scoping behavior (to the master, after duplicate checks). It is trivially distinguishable from siblings like search_suppliers or create_purchase_order, though the description never explicitly contrasts itself with them.

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 confirmation_code arg line embeds a concrete workflow prerequisite: call preview("onboard_supplier", <these same args>) first. That is real usage guidance an agent can act on. It stops short of explicit when-not-to-use guidance (e.g., use search_suppliers to check existence rather than attempting an onboard).

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=true and destructiveHint=false, which matches 'without writing anything' and removes the need to argue safety. The description still adds genuinely new behavior: it returns a one-time confirmation code, and that code must accompany identical arguments on the real write. However, it doesn't explain what the caller gets when checks DO block, or the lifetime/scope of the code beyond 'one-time'.

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 behavioral contract is front-loaded in the first sentence, and the Args block is clearly separated. Every sentence — including the exclusion of confirmation_code from `args` — prevents a concrete misuse 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 two-parameter dry-run wrapper with nested free-form args, the description supplies the action vocabulary, the argument mapping, and the confirmation-code handshake. An output schema exists, so the omission of detailed return-value documentation is not a 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 coverage is 0%, so the description must carry the burden and it does: it enumerates all seven valid values for `action` (the schema gives no enum) and defines `args` as the exact arguments for the downstream tool, explicitly excluding confirmation_code. This is information that exists nowhere in the structured 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 (preview/show exactly what a write would do) and a precise scope (every check result, no side effects). This immediately distinguishes it from the sibling write tools it simulates, without requiring the agent to open any 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 prescribes the workflow: call this first, receive a one-time confirmation code when no check blocks, then pass that code to the write tool with the identical arguments. It also names the exact alternatives (the seven write actions) so the agent knows which tool this gates.

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=false, and idempotentHint=false, so the safety profile is known; the description adds that the PO returns to the requester and that the reason is surfaced to them, which is real behavioral context. The confirmation_code requirement also signals a two-step, non-repeatable flow, though the description never says whether rejection can be undone or what permissions are needed.

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 front-loaded sentence states the action and effect; the Args block is minimal and each entry adds information an agent could not get elsewhere. No filler or restated annotation 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 described, and the description covers the action, the required precondition, and every parameter. It stops short of describing reversibility, side effects such as notifications, or failure modes, which matter for a non-idempotent state-changing 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?

With 0% schema description coverage, the description carries the full burden and does define all three parameters: po as the purchase order ID, reason as the text the requester will read, and confirmation_code as the value obtained from preview. It adds genuine meaning beyond the bare schema titles, but gives no format or validation hints for the ID or code.

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 ("Reject a pending purchase order") plus the outcome ("back to its requester"), which clearly separates it from approve_purchase_order or amend_purchase_order. It does not explicitly say how it differs from cancel_purchase_order, the closest sibling, leaving that distinction to inference.

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 "pending" qualifier establishes the precondition, and the confirmation_code note gives an explicit prerequisite workflow via the sibling tool preview("reject_purchase_order", <these same args>). It never states when rejection is inappropriate (e.g., already approved or cancelled POs) or what happens if preview is skipped.

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, non-destructive, closed-world behavior. The description adds meaningful behavior beyond that by specifying fuzzy name matching and the maximum row range, though it does not discuss result ordering or response shape, which is acceptable because an output schema 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 short, front-loaded with the tool purpose and usage context, then documents the two parameters compactly. There is no redundant or wasted 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?

For a simple read-only lookup tool with annotations and an output schema, the description is complete enough: it covers purpose, usage timing, fuzzy matching, both parameters, and limit bounds. It does not need to explain return values because the output schema 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?

Schema description coverage is 0%, so the description must carry parameter meaning, and it does: query is a partial supplier name with an example, and limit is the maximum rows with a 1-50 range. It omits the default limit value, but that is already present 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?

The description states a specific verb and resource: find suppliers by name using fuzzy matching. It also clarifies the downstream purpose, getting the supplier ID before ordering, so an agent can distinguish this lookup tool from sibling purchase-order and supplier-management 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 gives clear usage context: use before ordering to obtain the supplier ID. It does not name alternatives or when-not-to-use conditions, but there is no obvious sibling supplier-search alternative listed.

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 the mutation profile (readOnly=false, idempotent=false, destructive=false, openWorld=false). The description adds one genuinely valuable behavior: a confirmation_code must be obtained from a prior preview call, which the annotations cannot express. It does not disclose the resulting PO status, whether submission is reversible, or what failure modes look like.

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 front-loaded sentence states the action and eligibility, followed by a compact Args block. The Args block partially duplicates schema titles but earns its place by adding the preview invocation 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?

An output schema exists, so return values need not be described, and annotations cover the safety profile. The one non-obvious prerequisite — the confirmation_code workflow — is documented, leaving nothing an agent needs in order to invoke this 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 0%, so the description carries the full burden and largely does: it defines 'po' as a purchase order ID and, more importantly, tells the agent exactly how to obtain 'confirmation_code' via preview("submit_for_approval", {"po": ...}). That is meaningfully more than the schema's bare titles. It omits the type/format of the ID and whether confirmation_code is mandatory.

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 ('Send a ... purchase order for approval'), which is meaningfully distinct from approve_purchase_order and amend_purchase_order. It never explicitly names those siblings, so the agent must infer the submit-vs-approve split from the verb alone.

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?

'draft (or rejected and fixed)' gives a clear state precondition that tells the agent which POs are eligible, which is real usage context. It stops short of naming alternatives or stating what to do if the PO is already pending approval.

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, non-destructive and closed-world, so safety is covered. The description adds one piece of real value beyond that – that the response includes approval authority, not just an identity – but says nothing about session/auth assumptions or how a missing identity is reported.

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 clause that front-loads identity and adds the approval-authority detail. No filler, nothing repeated from annotations or schema.

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 the description doesn't need to enumerate return fields, and it names the two most important ones. For a zero-param read tool this is nearly sufficient; only the auth/session context 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?

Zero parameters, so the baseline of 4 applies. There is nothing the description could add on this dimension.

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 concrete resource: the ERP user the server acts as, plus their approval authority. That distinguishes it from every sibling, which all deal with purchase orders or suppliers. Slightly terse but 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?

Usage is only implied: knowing the acting user and their approval authority is obviously useful before approve/reject calls, but the description never says when to call it or names an alternative. No explicit when/when-not guidance.

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