update_transaction

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

With no annotations provided, the description carries the full burden of behavioral disclosure — and it delivers. It reveals the all-or-nothing batch semantics, atomic one-save behavior, that splits stays single-transaction, the force requirement for reconciled splits with detailed explanation of why a date move is destructive, and the notes-to-clear behavior. This is comprehensive for a mutation tool with zero annotation coverage.

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 well-structured with clear sections, front-loaded purpose, and minimal waste. It uses code formatting for parameters and covers important edge cases. It's slightly long but every sentence contributes value — the length is justified by the tool's complexity (batch semantics, split constraints, force behavior). Only minor redundancy (repeating GUID format details also in the schema).

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?

This is a complex mutation tool (6 params, batch behavior, split reconfiguration, reconciled-state handling) but the description covers all critical aspects: batch semantics, split matching rules, cross-currency handling, force requirements, and per-field optionality. An output schema exists to handle return-value documentation. The description is essentially complete for an agent to use this tool 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 description coverage is 0%, so the description must compensate fully — and it does. It explains GUID formats (32-char hex or 8+ char prefix, or a list), ISO date format, the splits matching requirement ('must match existing splits by account name and balance to zero'), cross-currency quantity semantics, memo-override behavior, decimal string format for amounts, and the notes-empty-string-to-clear behavior. Every parameter gets meaningful semantic context beyond the schema.

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 updates existing transactions, with a specific verb (update) and resource (transaction). It explicitly distinguishes from siblings: 'For per-row DIFFERENT values, use update_transactions' — providing direct differentiation from the sibling tool update_transactions, and notes splits stays single-transaction. The distinction from update_transactions is particularly strong, giving the agent clear selection guidance.

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?

Excellent when/when-not guidance. It explains the batch case explicitly ('one book open / one save, all-or-nothing'), gives a concrete use case ('one note across 35 related entries, one call'), and explicitly directs to the alternative tool (update_transactions) for per-row different values. The force requirement for reconciled splits is clearly articulated with reasoning about date moves shifting out of reconciled statement periods.

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