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

Goes well beyond the annotations (destructiveHint=true, idempotentHint=true): it discloses that re-attaching re-checks ownership of the new parent, that a null parent without a replacement is rejected as unassignment, and that cross-kind moves require a matching category in the same call. These are non-obvious failure modes an agent cannot get from the schema or hints; only return/response behavior is left unstated.

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?

Dense but front-loaded: partial-update contract first, then prerequisites, then parent-move rules, then category presets. Every sentence carries a rule, though the final category sentence is long and could be split for scanability.

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 an 11-param mutation with no output schema and near-zero schema descriptions, the description covers the risky dimensions: exclusivity of the journey/stay parent, ownership validation, rejection of bare nulls, and category validity. Only the remaining numeric/currency params and the returned shape are untouched.

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 only 9% (only id is described), so the description carries the burden and does explain the highest-risk params: journeyId/stayId parent semantics and category presets. But fxRate, feesMinor, amountMinor, currency, spentAt, payerPersonId and description remain uninterpreted in both places, leaving a substantial gap.

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?

Opens with a specific verb+resource scoped by id: "Update fields on an existing expense by id." It immediately distinguishes itself from log_expense (creation) and delete_expense by defining partial-update semantics, which no sibling 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?

Gives clear conditions for the tricky paths: call get_tripledger_guide first if unfamiliar, set the new parent (optionally nulling the old wire field) to move an expense, and include a category valid for the new kind when switching journey/stay. It stops short of naming sibling alternatives explicitly (e.g., use log_expense to create), so not a full 5.

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