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

Goes well beyond the annotations, which only declare readOnly=false, idempotent=true, destructive=false, openWorld=true. It discloses payment rails (USDC on Base, no IMD needed), settlement ordering ('USDC settles first'), failure behavior ('the desk records a refund owed'), receipt location (Ethereum), and safety-critical token handling ('Keep the private orderToken; recover it with the same verified payment... Never sign a replacement for a pending payment'). That token and payment-replay guidance is exactly the context an agent needs for an irreversible spend.

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 trigger, which is good. However, the body is a run-on of marketing framing ('1,000+ AI agents on Claude Code and Codex'), repeated payment claims ('Pay USDC on Base, no IMD needed' then 'USDC settles first'), and a dangling orderToken warning that is not tied to any parameter or return field, so several sentences do not earn their place.

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 tool that spends real funds and has no output schema, the description covers the important ground: prerequisites, payment currency and chain, failure/refund behavior, receipts, and recovery from a lost answer. What it omits is what comes back on success (a job id? an order token?) and how to track the resulting job, which is left to the sibling swarm_job.

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% — the payment parameter is documented in-schema, but quoteId has no schema description at all. The description partially compensates by implying the quote must be obtained first ('Get a free checked quote first') and by explaining payment-signature constraints, but it never states where quoteId comes from or that it must reference a previously issued quote, leaving the mandatory parameter's origin ambiguous. Baseline 3 for partial compensation with a real remaining gap.

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 ('Hire AI agents and pay a checked x402 quote') and enumerates the concrete job types it covers (website build, sourced research, Solidity audit, contracts/tests/frontends/images). The prerequisite step ('Get a free checked quote first') implicitly distinguishes it from the sibling swarm_quote, so an agent can route between the two without opening schemas.

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 trigger condition ('when an agent needs work an LLM call cannot do alone') and a clear sequencing rule ('Get a free checked quote first'), which tells the agent to call swarm_quote before this tool. It stops short of explicit when-not-to-use guidance or criteria for choosing among audit vs. build job types.

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