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

Adds substantial context beyond the annotations: funding is taken from one source per call and never split, insufficient funds produce a reply listing what each source holds and the shortfall, 72-hour expiry closes the result unpaid, and a review window returns in_review. This is consistent with destructiveHint=true (real money is spent) and non-idempotent behavior, and it discloses the failure/terminal states an agent must handle.

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?

Front-loaded with the action and payment sourcing, then failure handling, then expiry and review states in a logical order. The long parenthetical listing remediation tools is dense but every clause carries operational meaning; only slight reflow would improve readability.

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?

There is no output schema, so the description must carry return-value semantics — and it does, naming call_failed, in_review, pay_link, and 'next' as response elements. Combined with the funding-source and expiry rules, an agent has everything needed to call this correctly and interpret the reply.

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 only 50%, and the description clarifies agent_key's role by tying payment to 'the key's call credits' and 'its balance,' which is useful. However, call_id is never explained — the agent must infer it comes from a prior capability_call — and the uuid format and additionalProperties:false constraints are left entirely to 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?

Opens with a concrete verb and resource: 'Pay for a part result held as locked and get all of it,' which tells an agent exactly what state transition occurs. It is clear enough to separate from capability_call (which creates the call) and capability_call_get, though it never names those siblings explicitly to reinforce the boundary.

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 strong conditional guidance: retry 'next is this same unlock' when funding is short, and points to specific remediation tools (balance_topup_link, key_prepaid, spend_limits_set, pay_link) with the condition selecting each. Also covers the expired case (72 hours, re-call with a new idempotency_key). It stops short of saying when to prefer capability_call_get or capability_call_dispute instead.

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