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

The description adds substantial behavior beyond the annotations: sandbox-only sending, production gating via YELLOWCARD_ENV, no SwapEazi custody of funds, the rail's own idempotency key, a return Rate Receipt and release record, and refusal conditions for missing approval, changed payment, connection cap, or unapproved account. These details materially clarify side effects and safety limits for a mutation tool whose annotations only declare idempotency and non-destructiveness.

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 dense and front-loaded with the unclear word 'Keyed.' before the reader knows what is being keyed. The conditional modes are separated with semicolons and long clauses rather than clean structure, which makes the critical send-versus-read distinction harder to parse. Most sentences contain useful information, but the organization could be significantly tighter.

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 complex multi-mode mutation tool with no output schema, the description covers the important operational details: mode selection, sandbox restriction, refusal reasons, return artifacts, and the no-custody model. It is nearly complete, though it could better clarify how this handoff relates to adjacent submission and release tools in the sibling set.

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 each parameter already has its own description. The tool description still adds useful cross-parameter semantics by explaining how intent_id, run_id, payment_id, and connection_id select different modes, and by noting that account_number is matched against the approved instruction while only its last four characters are retained. This goes beyond per-field schema text, though not every parameter combination is exhaustively documented.

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 names a handoff to the user's rail and distinguishes three keyed modes: intent_id returns an approved rail instruction, run_id + payment_id + connection_id sends a sandbox payment, and run_id + payment_id alone reads rail status. However, the opening 'Keyed.' is cryptic, and the tool's primary action is buried across conditional branches rather than stated as one clear verb+resource. It also does not differentiate this handoff from sibling payment submission tools such as submit_payment or run_payments.

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?

The description gives explicit conditions for each mode: use intent_id after a person has approved, use run_id/payment_id/connection_id to send a sandbox payment, and use run_id/payment_id only to read status. It also states that the default business behavior is to release payment in its own bank portal, and that sending is sandbox-only unless production is explicitly enabled. It stops short of naming alternative sibling tools for overlapping workflows.

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