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

Annotations already establish readOnlyHint=true and openWorldHint=true, yet the description still adds substantial context: the shape of the returned payload, the polling cadence, the fact that `display` contains markdown with chan images that should be shown to the user, and the post-completion signing workflow. Nothing in it conflicts with the read-only annotation.

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 polling and completion instructions are front-loaded in the first two sentences, which is the right ordering. The trailing sentence cataloguing every swapchan_playbook workflow (find-money, best-swap, rebalance, revoke-approvals, bridge-stuck, token-safety, recover-old-wallet) is promotional padding that does not help invoke this tool.

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 carries the return-value burden and does so thoroughly — status values, progress tuple, running total, per-wallet results, ranked items, summary, plan, and the display markdown. Combined with the polling loop and the completion handoff, an agent has everything needed to call and act on this tool.

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 0% and there is one parameter, jobId, whose format (8-64 chars), provenance, and lifetime are never explained in the description. The mention of find_money_batch implies where the jobId comes from, which is partial compensation, but a 3 reflects that the agent must infer the parameter's origin and constraints.

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 (poll) tied to a specific resource (a find_money_batch job) and enumerates exactly what the response contains: status, progress, running total, per-wallet results, ranked items, summary and plan. An agent can distinguish it from find_money_batch and the sibling read tools without opening any schema.

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 an explicit usage loop: while running, wait pollAfterSeconds then call again and tell the user progress; when done, relay the summary verbatim and walk the plan through verify_tx → human yes → wallet signs → broadcast_tx → tx_status. It names the concrete next-step tools, which is exactly the routing guidance a polling tool needs.

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