stage_invoice_payment

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.