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

Adds substantial context beyond the annotations: payments use a throwaway wallet with no real funds, policy (budget/allowlist/approval) is enforced by the sidecar, requests are always GET, responses are clipped at 20,000 characters, and a result may come back as a refusal or a pending approval id. Annotations only cover safety flags, so this is doing the real work; the only gap is that it doesn't say what the pending-approval path means for the caller's retry/cost beyond the schema's idempotencyKey note, which the description never mentions.

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 core action and usage directive before detail, and every sentence carries operational information (endpoints, prices, refusal behavior, return shape). It runs long with an inline docs URL and repeated host enumeration, which costs a bit of tightness but not clarity.

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?

No output schema exists, and the description compensates fully by describing the return shape: a one-line summary with HTTP status, amount paid, decision and receipt id, followed by the body, or a refusal with reason, or an approval id. Combined with the endpoint list and GET/clipping constraints, an agent has everything needed to call it correctly.

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 baseline is 3, but the description adds flow-level meaning: dryRun yields a decision without paying, approvalId completes a payment previously held and approved, and the url must match one of two priced sandbox endpoints with example syntax. It omits any mention of idempotencyKey, leaving that 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?

States a specific verb and resource ('fetches one of the sandbox's paid endpoints') and explains the full path: routed through the spendctl sidecar which applies budget, allowlist and approval policy before paying. This is clearly distinguishable from siblings like check_budget, get_policy and approve, which only inspect or authorize rather than fetch.

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 directive ('Use it for every paid call in the sandbox') plus the two operating modes: dryRun to see the decision without paying, and approvalId to complete a held-then-approved payment. It also bounds applicability by naming the only two permitted hosts and stating that any other host is refused.

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