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

Annotations (readOnlyHint=false, destructiveHint=true, not idempotent, openWorld=true) are dramatically enriched by text explaining the timing and locus of side effects: 'NOTHING executes until the user opens the approval URL and signs', 'never signs and never sees a key', the distinction between proposing an intent (this tool) and executing (user action), fee-quote-baked-into-tx semantics, and the Reg S/OFAC compliance layer for security tokens. This converts a terse 'destructive + not idempotent' annotation into an actionable mental model.

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 definition is genuinely front-loaded (the single most important fact — propose-only, user approval required — is first), and the return shape {intent_id, approval_url} is repeated for emphasis. However, at ~400 words it is long, and the FEE PARITY paragraph is bloated with internal design reasoning ('Decision: pay_in_crank IS exposed here...') and rationale ('Without this an intent proposed via this Lane 1 rail could be fee-classified differently') that an agent doesn't need to invoke the tool. There's also an empty link '(follow-up to )' and the return value is described twice. The meaningful info could be cut in half.

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 with 0% schema coverage and full behavioral annotations, the description covers the most safety-critical aspects: keys are never touched, nothing executes without user signature, fee parity is guaranteed, geo/OFAC gating applies, and amount units are pinned down. But it omits several agent-relevant behaviors: what happens on slippage/who passes validator keys, retry semantics for a non-idempotent call (the existence of idempotency_key is mentioned nowhere), and whether wallet_address must be pre-verified. The description is rich where it matters for compliance and safety, but thin on the operational edge cases an agent would hit when actually retrying or recovering.

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?

With 0% schema coverage and 11 parameters, the description carries the full documentation burden and only partially delivers. It explicitly documents amount ('in input-token base units'), implicitly documents pay_in_crank (quoted via the discount-aware classifier pipeline), jurisdiction (declared once for Reg S), and ip (origin for the identity-proof layer). But slippage_bps semantics on an unsigned proposal, allow_unverified behavior, idempotency_key semantics on a non-idempotent call, wallet_address binding, and the two token params are entirely undocumented.

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?

The opening line 'Create a propose-only execution intent; returns an approval URL to hand to the user' pairs a specific verb with a clear resource and a distinctive behavioral qualifier ('propose-only') that separates this from a direct execution tool. The 'Lane 1 (non-custodial default)' framing further clarifies scope. It doesn't earn a 5 because it never names a sibling to differentiate from (e.g., jupiter_swap for direct execution), so an agent must infer the exact nature of the alternative path.

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?

Provides explicit follow-up guidance — 'poll get_intent_status and report ONLY the persisted on-chain state (CONFIRMED before any success claim)' — which is a clear directive on how to chain this tool with its sibling. The Geo Gate section tells agents which control applies ('same control jupiter_swap/trade_equity enforce') and the non-custodial framing implies the correct invocation context. However, it never explicitly says 'use X instead when you need direct (custodial) execution,' so the when-NOT-to call decision is left to inference.

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