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

Beyond the annotations, the description discloses the credit-holding behavior (CR-0001), the VAT carry-and-reclaim mechanics, the accounting postings against Customer prepayments (2400), and the cost of $0.01 per call with no charge on failure. This is unusually rich behavioral context for a write 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 front-loaded with the core purpose and lifecycle, and each sentence adds concrete value about VAT, postings, or cost. It is dense but not wasteful, though it could be slightly tighter for an 8-parameter tool.

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 lack of an output schema, the description does a thorough job explaining the tool's behavior, side effects, and cost. It does not describe what the tool returns (for example, a prepayment identifier), which is the main remaining gap for an agent invoking 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 coverage is 63%, and the description adds meaningful semantics for tax_rate by explaining how VAT is carried and later reclaimed. However, it does not clarify the customer object, date, method, currency, or reference parameters, so it only partially compensates for the remaining schema gaps.

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: 'Record money a customer paid before there is an invoice, like a deposit, as Xero's prepayments'. It distinguishes the tool from its sibling invoices_use_credit by naming it as the consumer of the credit, and the phrase 'before there is an invoice' implicitly separates it from standard invoice-payment 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 clearly says when to use this tool: when money is received before an invoice exists, such as a deposit. It also names the alternative invoices_use_credit and describes the lifecycle, but it does not explicitly rule out invoices_record_payment or state what to do once an invoice exists, leaving some inference to the agent.

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