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

With no annotations, the description carries the responsibility of disclosing behavior. It explicitly states the tool does 'not leak any credential,' a valuable security behavior. It also implies a read-only, non-destructive query. However, it does not mention what happens if the system is not configured or if the return format differs, leaving a minor gap.

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 compact and front-loaded, with the main question posed first. Every phrase earns its place: the list of dialects and the security guarantee are both essential. No redundant or verbose wording is present.

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 zero-parameter tool with an output schema, the description is complete. It explains the tool's purpose, the possible return values, and a key behavioral aspect (no credential leakage). There is no missing information that would prevent an agent from using this tool 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?

The tool has zero parameters, so the baseline is 4. The description adds meaning by enumerating the possible output values (sap_s4hana, netsuite, dynamics365), which clarifies what the tool returns. Since the input schema is empty, there are no parameter details to elaborate on, and the description provides sufficient context.

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 states the tool's function: it identifies which ERP dialect is wired (sap_s4hana, netsuite, or dynamics365). The verb 'confirm' and specific resource ('modeled system') make the purpose unambiguous. It is distinct from sibling tools, which all handle domain operations like purchase orders or approvals.

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 implies the tool is used to verify the system before other operations, noting it 'lets a host confirm the modeled system.' It does not explicitly name alternatives or when-not-to-use, but the context is clear: this is a metadata/configuration tool, not for transactional workflows. A slight lack of explicit exclusion keeps it from 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?

With no annotations provided, the description carries the full burden of behavioral disclosure, and it delivers: it states the hard requirement for a human token, explains that agent-supplied tokens are refused, specifies failure mode when no token is configured (fail closed), and reveals the state transition and mock execution. This is excellent transparency about permissions, security, and side effects.

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 three sentences long, front-loaded with the core purpose, and every sentence provides essential information: purpose, token requirement, execution and failure behavior. There is no redundancy or filler, making it highly concise while remaining comprehensive.

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 tool's complexity (approval token security, state transition, failure modes), the description covers all key aspects: what it does, prerequisites, security caveat, and behavior on success and failure. An output schema exists, so return values need not be described, and no critical context is missing for an agent to invoke the tool 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 coverage is 0%, so the description must compensate for the undocumented parameters. It thoroughly explains the 'token' parameter's semantics (human-only, agent cannot supply it), but it does not explicitly describe 'approval_id' as the identifier of the staged write. The approval_id is inferable from context but not directly clarified, leaving a gap in parameter guidance.

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 opens with 'Approve a staged write,' which uses a specific verb and resource, clearly distinguishing this tool from the sibling staging and query tools. It clarifies exactly which action is performed and the resulting state transition (pending → executed), leaving no ambiguity about its role.

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 clearly conveys that this tool requires a human-provided approval token and that an agent-supplied token will be refused, making it explicit when the tool can be effectively used. While it does not name alternatives, the context of siblings (stage_invoice_payment, stage_po_amendment, list_pending_approvals) makes the workflow apparent, so the usage guidance is strong but not fully explicit about when not to use other tools.

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?

No annotations are provided, so the description carries the burden. 'Return' clearly indicates a read-only operation, but it does not disclose behavior when the ID is not found, permissions needed, or whether the full record is returned. Basic transparency but lacks edge-case context.

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, front-loaded sentence of about 10 words. Every word is useful, and the status values are listed concisely. No filler or repetition.

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 getter with one parameter and an output schema, the description is complete. It specifies what is returned (current record) and the possible status values. No further context needed for an agent to invoke the tool 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 must compensate. It mentions 'for approval_id' but adds little beyond the parameter name itself; the parameter role as an identifier is obvious from the tool name. Does not provide format or examples, but for a simple ID parameter the minimal hint is adequate.

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 uses a specific verb 'Return' with a clear resource 'approval_id', and explicitly lists the possible status values (pending | approved | executed | refused). This distinguishes it from sibling tools like 'approve' and 'list_pending_approvals' that perform different actions.

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 implies usage: to fetch the current status/record for a specific approval ID. It does not explicitly mention when to use this over alternatives or exclude scenarios, but the tool name and description make it clear it is for retrieving individual approval status.

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 no annotations, the description carries the transparency burden. It discloses the return structure (A_MaterialDocumentHeader collection, to_MaterialDocumentItem list, GoodsMovementType 101), item-level annotation semantics, and the empty-collection edge case. It omits error behavior or permissions, but these are less critical for a read-only fetch.

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 front-loaded with the main purpose, uses a compact bullet for the parameter, and every subsequent sentence adds relevant output or behavioral detail. There is no fluff or repetition.

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, the description is complete: it states what is fetched, how to provide the input, what the SAP response looks like, what annotations are included, and the empty-result behavior. It leaves little ambiguity for an 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?

The sole parameter, po_id, is explained as a 'corpus PO id' with a concrete example ('PO-8801'). This adds meaning beyond the schema, which only declares it as a required string, and fully compensates for the 0% schema description coverage.

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 uses a specific verb and resource: 'Fetch the goods receipt(s) for a PO.' It also positions the tool as 'the GRN actual leg of the match,' distinguishing it from sibling tools like get_purchase_order and get_invoice.

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 clear context by stating the tool retrieves goods receipts for a PO within a matching workflow. It does not explicitly name alternatives or exclusions, but the intended use case is unambiguous.

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 no annotations provided, the description fully carries the behavioral disclosure burden. It explicitly states that the tool raises on unknown invoices, returns different structures per ERP system, and includes a warning about duplicate-invoice detection (the PO-8808 trap). This is rich, actionable behavior detail beyond the schema.

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 structured with a clear opening sentence, a bullet for the parameter, and then system-specific return details. Every sentence adds value, and there is no fluff. It is appropriately sized for a tool with cross-system behavior.

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 tool handles multiple ERP systems and has an output schema, but the description still explains key return shapes and edge cases like duplicate invoices. It also covers error behavior. For a single-invoice fetch with this complexity, the description is 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?

The input schema only provides the parameter name 'invoice_id' with no description (schema coverage 0%). The description compensates fully by explaining it is a 'corpus invoice id' and gives a concrete example ('INV-01'). This is exactly the kind of semantic addition needed.

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 starts with a specific verb+resource: 'Fetch one supplier invoice' and further clarifies it as the 'charged' leg of the match, distinguishing it from sibling tools like get_purchase_order or get_goods_receipt. It clearly states what the tool does.

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 implies usage context: it fetches a single invoice by ID, supports multiple ERP systems, and is part of an invoice-PO matching workflow. It provides clear context but does not explicitly state when-not-to-use or name alternatives, so it misses the top tier by a narrow margin.

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 no annotations provided, the description carries full responsibility. It discloses ERP-specific response envelopes (SAP/Netsuite/Dynamics), including data format differences (stringified decimals, /Date(ms)/ dates, JSON numbers, OData etag), and clearly states it 'Raises if the PO is unknown'. It does not mention auth or rate limits, but for a read-only getter this is strong disclosure.

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 well-structured with a one-line summary, a bullet for the parameter, then ERP-specific return details, and an error statement. Every sentence provides necessary information; there is no redundancy or 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?

Despite having an output schema, the description adds substantial context about expected response shapes across three ERP systems, which is unlikely to be captured by generic JSON schema. It also covers error behavior and parameter semantics, making this fully self-contained for a getter 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?

The input schema only lists po_id with a type, providing zero semantic content. The description compensates fully by explaining it is the corpus PO id, giving a concrete example 'PO-8801', and labeling it as the join key across the entire kit – essential meaning absent from 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 opens with 'Fetch one purchase order' – a specific verb and resource that clearly distinguishes this from sibling tools like list_open_pos (list) and get_invoice (invoice). The phrase 'as the configured ERP would return it' also sets accurate scope expectations.

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 states the tool fetches a single PO and calls po_id the 'Join key across the whole kit', implying this is the canonical lookup for cross-tool workflows. However, it does not explicitly exclude alternatives or name when to prefer this over related getters (e.g., get_approval_status), so it lacks explicit exclusions but provides clear context.

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 no annotations, the description provides thorough behavioral detail. It precisely defines 'open' via billed vs. ordered quantity, and discloses exact response formats for sap_s4hana, netsuite, and dynamics365, including envelope shapes and count fields. This goes far beyond a typical description.

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 front-loaded with the core purpose, then defines the key term 'open', then gives system-specific details. Every sentence adds value; the response format details are essential for parsing across ERP backends. No wasted 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 zero-parameter list tool, the description is complete: it states what qualifies as 'open', clarifies no arguments, and provides output shapes even though an output schema exists. The extra examples increase usability without significant length.

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?

There are zero parameters, so schema coverage is complete. The description explicitly notes 'Takes no args', which reinforces the schema. Per the baseline for 0 params, a 4 is appropriate; there's nothing more to add.

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 states 'List purchase orders with no fully-matching invoice yet' — a specific verb (list) plus resource (purchase orders) and scope (open three-way-match workqueue). It distinguishes this tool from siblings like get_purchase_order or list_pending_approvals by focusing on the open-match condition.

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 implies usage: this is the workqueue for open three-way matches. It doesn't explicitly name alternatives or say when not to use it, but the purpose is clear and distinct from sibling list tools. The 'Takes no args' note also clarifies invocation.

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?

No annotations are provided, so the description carries full responsibility. It clearly discloses the read-only nature, the filtering by status=pending, and the limitation that the agent cannot approve. This is transparent and directly addresses the behavioral trait that matters most.

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, each adding distinct value: what it lists, that it's read-only, and the human/agent approval distinction. No filler or repetition.

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 zero-parameter, simple list operation with an output schema, the description covers purpose, scope, read-only behavior, and the agent's limitation. It is fully sufficient to guide correct usage.

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

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

There are zero parameters, so the baseline is 4. The description adds meaning by clarifying what the tool returns—staged, not-yet-approved writes—which compensates for the absence of parameter-specific details.

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 uses a specific verb ('List') and clearly identifies the resource ('this server's staged, not-yet-approved writes (status=pending)'). It distinguishes itself from sibling tools like get_approval_status and approve by specifying the pending status and the read-only nature.

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 clearly indicates the tool is for viewing pending items and explicitly states what the agent cannot do ('cannot approve'). This provides practical context for when to use the tool, though it doesn't explicitly name alternative tools or enumerate exclusion conditions.

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 no annotations provided, the description carries the full transparency burden. It explicitly says 'read-only; no state change' and discloses exactly what is returned for each ERP system (e.g., 'SAP Advanced Event Mesh CloudEvents envelope', 'SuiteScript user-event callback', 'Business Events envelope'). It does not cover auth, error handling, or rate limits, but for a simulation tool it communicates the key safety and output behavior well.

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 concise and front-loaded with the main purpose. The bullet list for parameters is scannable, and the system-specific details are useful. It could be slightly tightened, but every sentence contributes meaningful 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 tool's moderate complexity and existing output schema, the description covers purpose, parameters, system-specific behavior, and use case. It is missing guidance on prerequisites like the active_system dependency and possible error/failure scenarios, but overall it is complete enough for an agent to understand and invoke the 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?

Schema description coverage is 0%, so the description is the only source of parameter meaning. It explains po_id with an example ('corpus PO id, e.g. "PO-8801"') and event_type with allowed-looking examples ('e.g. "Created" | "Changed"'), adding critical semantic value beyond the bare 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 clearly states the tool 'Synthesize an inbound ERP change event for the given PO', which is a specific verb+resource combination. It distinguishes itself from sibling tools (get_, stage_, approve, etc.) by focusing on simulation/event synthesis rather than data retrieval or state-changing actions, and reinforces this with 'read-only; no state change'.

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 an explicit use case: 'Use it to exercise event-driven wiring.' It also explains system-specific behavior under SAP, NetSuite, and Dynamics 365, giving context for when it applies. However, it does not explicitly mention prerequisites like calling active_system or name alternative tools for different needs.

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 no annotations, the description carries full responsibility for behavioral disclosure. It reveals that the tool validates invoice existence and numeric amount, records a pending record, returns a specific response structure, models an SAP API, does NOT pay anything, and requires human approval via approve(). It also notes the policy-gating of 'pay_invoice' in policy.gated_actions. This is exceptionally transparent.

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 front-loaded with the key message 'STAGE (do not execute)' and uses a clear bullet list for parameters. It is somewhat repetitive about the non-execution aspect (emphasized three times), but each sentence adds value—covering validation, return payload, SAP model, the approval workflow, and policy gating. It is dense but efficient, with minor redundancy 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?

The description covers all essential aspects: parameter semantics, validation behavior, side effects (pending record), return payload shape, the required next step (approve), policy gating, and the underlying SAP model. It even notes the output schema implicitly by naming key response fields. This is complete for an agent to correctly select and invoke the 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?

Schema description coverage is 0%, so the description must fully explain parameters. It does: invoice_id is a corpus invoice id with example 'INV-01', amount is echoed for human confirmation, currency is ISO with default 'USD'. This adds meaning well beyond the schema's type/title/default fields.

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 states the tool's purpose: 'STAGE (do not execute) a supplier-invoice payment for human approval.' It uses a specific verb ('STAGE'), identifies the resource (supplier-invoice payment), and immediately clarifies a critical distinction—it does not execute payment—which differentiates it from sibling tools like 'approve' and 'stage_po_amendment'.

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 provides strong usage context: it explicitly says this tool does not pay anything, that human approval is required via approve(approval_id, token), and that the action is policy-gated. While it doesn't explicitly name alternative tools for comparison, it clearly places this tool in a staging workflow and tells the agent when not to use it (to actually pay), which is nearly complete 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?

With no annotations provided, the description fully discloses behavior: it records a pending record, validates PO existence, requires at least one change, returns pending_approval and approval_id, models a PATCH with If-Match/x-csrf-token, is gated, and executes only on human approval. This is rich behavioral context beyond what annotations would provide.

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 well-structured with a bold intro, bulleted parameters, and a concise behavior paragraph. Every sentence contributes critical information without redundancy or wasted 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?

The description covers purpose, parameter semantics, validation logic, side effects, authentication requirements, gating, and return values. Given the output schema exists, the description adequately handles all relevant context for an agent to select and invoke the tool 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 coverage is 0%, but the description explains each parameter: po_id with example format, new_qty as optional order quantity, and new_unit_price as optional net price per unit. It also notes that at least one change must be present, adding meaning beyond the bare 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 clearly states the tool stages (not executes) a PO amendment for human approval. It specifies the verb 'STAGE' and the resource 'PO amendment', and distinguishes from siblings like 'approve' (which would execute) and 'get_purchase_order' (read-only).

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 explicitly states the tool is for staging changes for human approval and that execution happens only after approval. It does not explicitly name alternatives or exclusions (e.g., 'use approve to execute'), but the context is clear enough to infer appropriate usage.

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