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

The description goes well beyond the annotations by disclosing that the tool is non-reversible once approved, that it requires explicit user confirmation, and that it does not actually execute the posting or payment—it merely proposes a change. It also clarifies the underlying API limitations. These details significantly enhance the agent's understanding of side effects and safety considerations, fully complementing the destructiveHint and readOnlyHint 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?

The description is long but every sentence carries essential safety and operational information. While it could be trimmed, the verbosity is justified given the irreversibility and potential consequences of the action. The core purpose is stated upfront, and the critical constraints are front-loaded; the length is a necessary trade-off for completeness.

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 and the absence of an output schema, the description fully explains the tool's behavior: it queues a pending change, requires human approval, and mentions the approvalUrl field in the response. It also covers edge cases like refusing non-AU pay runs and clarifies that it does not handle payroll lodgement or payments. No essential operational detail 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?

The input schema already provides descriptions for all three parameters (payRunId, confirm, organisation), and the description essentially repeats these details without adding new information. Since schema coverage is 100%, the description adds no extra semantic value beyond what the schema already states. It correctly reinforces constraints like confirm must be true and payRunId must be DRAFT, but does not contribute beyond that.

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

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

The description clearly states the tool's purpose: proposing to move an existing DRAFT pay run to POSTED, with a explicit constraint that it is for Australian organisations only. It distinguishes itself from creation tools by emphasizing it operates on an existing pay run and states it does not touch Xero directly. This leaves no ambiguity about 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 provides explicit when-to-use guidance: only for Australian organisations, and it refuses for NZ and UK. It also clarifies that this tool only queues a pending change that requires human approval, and it is not for lodging with the ATO or paying employees. This effectively routes the agent to use this tool only under the right conditions and explains prerequisites like obtaining payRunId from list_xero_pay_runs.

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