Update Transaction

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

Annotations only tell the agent this is a safe, idempotent, non-destructive write; the description adds behavior the annotations cannot express, notably that importer markers in the stored description are preserved across the edit and that bank_ref_number will be refused by the API. It also prescribes a post-mutation verification step, which is exactly the kind of write-side context an agent needs before reporting a repair.

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?

Three sentences, front-loaded with what is editable, then the preservation caveat and the refused field, then the verification instruction. Every sentence carries actionable information and nothing is padded.

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 two-parameter mutation with no output schema and full annotation coverage, the description supplies what is missing: side effects on stored text, an API-level refusal, and a verification protocol. Nothing an agent needs to invoke it correctly and report accurately is absent.

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 field list and the 150-character limit are already documented, and the description largely restates them. It does add meaning beyond the schema by explaining the preservation semantics of the 'data' payload (importer markers survive the write) and the refused-field behavior, which is not obvious from the permissive `additionalProperties: {}` object 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 uses a specific verb ("Update") against a specific resource ("transaction metadata fields") and enumerates the mutable fields (counterparty name, bank account number, description, payment reference), which separates it in practice from status-oriented siblings like confirm_transaction, invalidate_transaction and delete_transaction. It does not name those siblings explicitly, so the differentiation is inferable rather than stated.

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?

It gives concrete usage guidance: attempt the metadata edit, and then 'Verify the change with a fresh get_transaction before reporting it as repaired.' It also warns off an unsupported field (bank_ref_number is read-only and refused), which prevents a predictable failed call. There is no explicit when-to-use-this-vs-alternative framing (e.g., update_bank_account for renaming the account itself), so it stops short of a full routing statement.

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