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

The description goes beyond simple 'apply' behavior by specifying critical state transitions: the invoice status moves to 'paid' when settled, and the credit note status moves to 'settled' when exhausted.

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 definition is highly dense and structured, efficiently covering the core definition, constraints, alternatives, and resulting effects in a brief manner without any unnecessary 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?

For a state-changing financial tool, the description is complete. It outlines how the tool affects multiple related records (invoice status and credit note status), providing a complete picture of the call's impact.

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?

While the schema defines the type, the description adds vital logic: that omitting the 'amount' defaults to the lesser of the remaining credit or remaining debt. This functional logic significantly elevates the input definitions.

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 and concisely states the core function: applying credit notes to invoices. It establishes the operational scope (O2C financial application) and is clearly distinguished from actions like full payment recording.

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 comprehensive boundaries, explicitly defining constraints (cannot exceed credit or debt bounds) and correctly identifying the alternative (a refund) for when the customer wants cash out instead of application.

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