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

Annotations are minimal (readOnlyHint=false, etc.) and the description carries the burden. It discloses that doing both double-counts, that a source_ref makes a re-run idempotent, and that setting amount_usd to a guessed historical rate freezes it forever (while omitting it lets the app use the honest live rate). This adds real behavioral context beyond the schema and annotations, with no contradictions.

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, well-structured paragraph that front-loads the core purpose, then gives the key usage rule, then the source_ref caveat. Every sentence earns its place — no fluff or redundancy. The warning about double-counting is placed early where it matters.

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 create tool with 10 parameters and no output schema, the description covers all critical nuances: when to use vs. siblings, how attribution works (omitting stay_id lets the date determine the stop), the amount_usd honesty rule, and idempotency via source_ref. Nothing essential is missing, and the high schema coverage fills in the rest.

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 90%, so most parameters are documented. The description adds semantics for amount (total actually paid, not deposit or per-night rate), amount_usd (only set when source states a USD figure, else omit), and source_ref (unique per user, repeat import refused). It clarifies a few non-obvious fields without repeating the schema, which is above the baseline for high 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 opens with 'Record one thing the user spent money on' — a specific verb and resource. It immediately scopes the tool to spend with no itinerary item of its own and distinguishes it from the update_flight/update_accommodation/update_activity siblings, so an agent can tell them apart without examining schemas.

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 when to use this tool (spend that isn't already on the itinerary) and when not to (if the purchase is already on the itinerary, use the update_* tools, and warns that doing both counts it twice). It also mentions passing source_ref for imports to prevent duplicates — clear, actionable guidance with an explicit alternative.

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