Reconcile Inter-Account Transfers

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

With destructiveHint=true and idempotentHint=false already declared, the description adds the crucial safety model: the two-step dry-run/execute flow, the requirement that execute=true carry the reviewed handle, and the duplicate-safe guarantee that already-journalized transfers are skipped. This tells the agent exactly what will be mutated and under what guard.

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?

Four dense sentences, no filler, with the core purpose front-loaded and the safety model immediately after. Every sentence carries distinct information an agent needs.

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?

No output schema exists, yet the description explains what the dry run returns (a plan_handle enumerating the reviewed confirms/deletes) and how that artifact feeds execution, so the two-step workflow is fully self-contained.

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 coverage is 100%, so the baseline is 3, but the description adds real meaning: it ties plan_handle to the dry-run review step and explains the conditional requirement for target_accounts_dimensions_id. Its "2+ possible targets" threshold is looser than the schema's "3+ bank accounts and counterparty IBAN missing," which leaves a minor ambiguity.

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?

States a specific verb and resource ("Match own-account bank transfers") and the "own-account" qualifier implicitly scopes it away from the sibling reconcile_bank_transactions. It never names the alternative tool explicitly, so an agent must infer the boundary itself.

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 operating context: dry run by default, execute=true requires the plan_handle from a reviewed run, and target_accounts_dimensions_id is needed for one-sided transfers with multiple candidate targets. It does not state when to prefer this over reconcile_bank_transactions or reconcile_currency_rounding.

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