confirm_swap

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

Annotations already declare write/idempotent/openWorld semantics, and the description adds substantive context beyond them: verification is server-side, keyed to the owning session, and requires canonical-chain receipt plus exact committed fee details. The closing sentence 'A caller-supplied tx hash alone is not confirmation' is a genuinely useful anti-pattern warning. It stops short of describing the success/failure outcome or what 'required finality' means operationally.

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?

Two sentences, with the core verification requirement front-loaded and the negative constraint placed last for emphasis. The bracketed capability/API/authority header is metadata rather than task guidance and slightly dilutes the opening, but it is compact.

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 five-parameter, fully-required networked write with zero schema descriptions and no output schema, the description covers the verification preconditions but leaves the agent without a picture of what a successful confirmation produces, how failures surface, or what finality threshold applies.

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 0%, so the description must carry the load. It clarifies txHash (insufficient alone) and maps sessionId/sessionToken loosely to 'owning session' and feeEventId to 'committed fee asset/payer/recipient/amount'. However, agentAddress is never explained, and no parameter gets format or construction guidance beyond the schema's regex pattern.

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?

Names a specific verb+resource ('Confirm a compatibility swap') and defines the verification basis precisely. It does not explicitly distinguish itself from sibling confirm tools (confirm_autonomous_swap, confirm_execution), so an agent must infer the boundary from the 'compatibility swap' and feeEventId framing.

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 prerequisites are implied ('only through FarmDash server verification of the owning session... and required finality'), which tells the agent what must be true before calling. But there is no explicit when-not-to-use clause and no routing to the near-identical confirm siblings, leaving the choice to inference.

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