Update Transaction

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

Annotations already declare this a non-read-only, non-destructive, idempotent mutation, and the description is consistent with those hints — no contradiction. Beyond the annotations, the description adds genuine behavioral value with 'Importer markers in the stored description are preserved,' disclosing an internal mechanism an agent must not disturb. It does not, however, cover what happens if the transaction is already confirmed or whether the update affects bank-matching, though the annotations carry the safety burden.

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?

Two tight sentences with zero filler. The first front-loads the purpose and the editable fields; the second carries the single most important operational caveat (importer-marker preservation). Every sentence earns its place and nothing is redundant with the parameter schemas.

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 2-parameter mutation with no nested objects and full schema coverage, the definition is essentially complete: fields are listed, the marker-preservation behavior is disclosed, and the `data` nuance is captured in the schema. The only absence is the return value/response shape after the update, which is typical for a mutation and not required given no output schema exists.

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 100%, so the schema already fully documents both parameters (id as 'Transaction ID', and data with its allowed field names, the 150-char constraint, and the ref_number canonicalization note). The description's human-readable field list adds only marginal value over the schema's precise field names, so the baseline-3 applies. It does not meaningfully compensate beyond restating what the schema states.

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?

Uses a specific verb + resource ('Update transaction') and enumerates the exact metadata fields involved: bank reference, counterparty name, bank account number, description, and payment reference. The phrase 'metadata fields' effectively separates this from sibling create/invalidate/delete/confirm_transaction tools, so an agent can tell it apart without evaluating anything else.

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?

Usage is implied by the field enumeration — if you need to change an existing transaction's metadata, this is the tool — but there is no explicit when-to-use, when-not-to-use, or alternative routing. It neither names a sibling (e.g., create_transaction for new records, invalidate_transaction for reversing) nor states conditions that would rule it out, so an omniscient agent is left to infer the boundary between metadata edits and structural operations.

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