Swapper - XMR to USDC swaps

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

Annotations already declare non-readOnly, openWorld, non-idempotent, non-destructive. The description adds genuinely new context beyond that: the follow-up/continuation model (ticketId + replyToken) that explains the idempotentHint=false repeated-call behavior, and a safety constraint ('Never seed phrases or keys') that annotations don't cover. No rate limits or response shape, but the security note is valuable added behavior.

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?

Three short front-loaded fragments with no filler; the primary use case leads and the security caveat is last. The telegraphic style is efficient but slightly clipped, costing a bit of parseability rather than words.

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?

An output schema exists, so return values needn't be described, and 88% schema coverage handles most parameters. The description covers the essential triggering scenarios, the follow-up flow, and a security constraint, which is adequate for an 8-param, 1-required tool. Minor gaps remain around when this beats request_agent_key or submit_feedback.

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 88%, so the schema already documents nearly all 8 parameters (message, orderId, category, sessionId, walletAddress, patterns). The description reinforces the ticketId+replyToken pairing for follow-ups but adds little syntax or meaning beyond what the schema states ('With ticketId.'). Baseline 3 is appropriate given the schema does the heavy lifting.

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 name/title give the specific verb+resource (open a support ticket), and the description pins the triggering scenarios ('Stuck or failed swap, or a question') and names the sibling get_support_ticket as where answers arrive. An agent can distinguish creating a ticket from reading one without opening a schema, though the telegraphic phrasing leaves the 'create' action implicit rather than stated.

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?

Explicit when-to-use triggers are given ('stuck or failed swap, or a question') plus the follow-up path ('Follow up with ticketId + replyToken'). It routes to get_support_ticket for retrieving answers. What's missing is an explicit when-not (e.g., when to prefer submit_feedback or request_agent_key instead).

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

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

Annotations only cover safety/idempotency flags; the description adds substantive traits they do not: no funds move, orders cannot be cancelled, unfunded orders expire, and the default idempotencyKey yields the same order on retry. It also gates the funding action behind a separate verification call, which is real behavioral guidance.

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?

Dense and front-loaded with the core action first, then constraints, retry, and funding. The colon/semicolon run-on is information-efficient but slightly harder to parse than distinct sentences would be; every clause still carries load.

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?

An output schema exists so return values need no explanation, and annotations cover the safety profile. The description fills the remaining gaps for a stateful, idempotent order-creation tool: upstream source, non-cancellability, expiry, retry behavior, and the mandatory funding precondition.

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 80%, so the baseline is 3, but the description adds provenance the schema cannot: quoteId and to come from get_quote's next.arguments, and to is only supplied when the quote had none. It reinforces 'Never guess' for to, tying parameter values to the upstream call.

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 (creates) and resource (swap order) and positions itself in the workflow as 'Step 2' consuming get_quote's output. It is trivially distinguishable from siblings like get_quote and get_swap_status, which it names explicitly.

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 explicit when-to-use (after get_quote, one order per quote), when-not-to-fund ('only while payable is true'), the pre-signing precondition (paymentCheck.safeToSend), and the next step (get_swap_status). Retry semantics are also spelled out, so an agent needs no inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds useful content scope (what categories of information are returned), but does not say whether this is a static config fetch, how 'lean' vs 'full' differ, or whether the values are stable.

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?

It is a single compact sentence with no filler, which is good, but it is over-compressed to the point of ambiguity, and front-loading 'Optional.' spends the most prominent position on the least informative token.

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?

An output schema exists, so return values need not be spelled out, and annotations cover safety. However, for a discovery tool the description is missing the two things an agent most needs: when to invoke it and what the detail enum controls.

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?

The schema has one parameter, 'detail', with an enum (lean/full) and 0% description coverage. The description never mentions 'detail' or explains what a lean versus full response contains, so it fails to compensate for the schema gap — the one parameter the agent must reason about is undocumented everywhere.

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 description lists the content the tool exposes (chains, limits, quote window, idempotency, validation rules, polling, flow) but never states a verb or a clear resource; it reads as a topic list rather than 'returns the swapper's constraints.' An agent can infer it is a discovery/config tool, but the leading 'Optional.' muddies what exactly is being retrieved.

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?

'Optional.' is the only usage signal and it is ambiguous — optional relative to what workflow step? No alternatives are named, even though siblings like plan_swap and create_swap clearly relate to pre-flight constraint discovery. The agent is left to guess when to call this versus those.

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

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

Annotations already establish readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds output-shape context (an ordered checklist of quote, fund, re-quote) and asset constraints (native USDC not USDC.e, ETH needed for gas), which is useful. The cryptic 'Offline.' is never explained, so behavioral disclosure is only moderate.

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 sentence is dense and largely front-loaded around the funding requirement, but the leading 'Offline.' is a wasted, unexplained fragment and 'requoteOf' is internal jargon. It is short overall, but not every token earns its 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?

With an output schema present, return values need not be spelled out, yet the description usefully sketches the checklist. Gaps remain: the 'detail' parameter is unexplained, the 'Offline.' claim is unclarified, and the tool's relationship to the quote/swap siblings is left to inference. Adequate but with clear gaps for a 4-parameter 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 coverage is 75%, so the schema carries most parameter meaning, and the direction descriptions in the schema mirror the description's u2x/x2u text. The description adds the compound input form 'from {chain, asset} (and amount)' but says nothing about the 'detail' (lean/full) parameter, leaving one parameter unexplained beyond the schema. Baseline 3 is appropriate.

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 description names the resource (funding instructions for a swap) and distinguishes the two funding paths (native USDC + ETH for gas on Arbitrum One for u2x vs. XMR for x2u). It never states the verb plainly ('returns how to fund'), and the opening 'Offline.' is opaque, but an agent can still grasp what the tool produces. Sibling differentiation from get_quote/plan_swap is implied via the quote/fund/re-quote ordering rather than stated.

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?

'Pass from {chain, asset} (and amount) for one ordered checklist' gives invocation guidance for the input, and the u2x/x2u framing implies when each direction applies. However, it never says when to call this vs. get_quote, plan_swap, or create_swap, and no prerequisites or exclusions are given. Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint, so safety is covered, but the description adds meaningful context: it needs no account or API key, it creates no order, and quotes are estimates only. That estimate caveat is important behavioral context not derivable from annotations.

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-loads 'Step 1' and the core purpose, then adds compact, high-value usage examples. Slightly dense with parenthetical quotes and shorthand, but every sentence carries information and none is wasted.

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?

An output schema exists so return values needn't be explained, and the description still hints at the handoff ('next.arguments'). Combined with the parameter examples and estimate caveat, it is complete enough for an agent to call correctly; only minor detail like the 'detail' enum meaning is absent.

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 high (89%), so the schema documents most parameters. The description goes beyond it by giving concrete invocation examples ('get me 1 XMR' -> direction:"u2x", receiveAmount:"1") and stating the direction+exactly-one-of rule, adding value over the raw 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?

Names a specific verb (Quote) and resource (XMR <-> native USDC on Arbitrum One), and distinguishes itself from siblings by stating 'Step 1' and 'Creates no order', separating it from create_swap/plan_swap. An agent can identify the tool's role without opening the 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?

Positions the tool as the first step of a flow and explicitly names the follow-on ('Next: create_swap with next.arguments'), routing the agent to the correct sibling. It also clarifies 'no account or API key' and 'Creates no order', which further delineates when to use it versus mutation tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds one genuinely useful behavioral fact not in the annotations — that replies arrive in minutes to hours — which informs polling strategy. It says nothing about the replyToken acting as an authorization credential or whether the thread can be partially available.

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?

At two short sentences it is not bloated and the latency note is front-loaded near the end. But the telegraphic noun-phrase style ("status, awaiting, thread") is under-specified rather than concise, and the sentence fragments cost clarity without earning their brevity.

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?

An output schema exists, so return values need not be spelled out. That still leaves the tool incomplete: two required parameters, one of which is a credential-style token, plus a detail enum, are undocumented anywhere, and the description gives no guidance on handling pending or missing replies.

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%, so the description is the only place parameter meaning could be added, and it fails to compensate. "Your ticket" loosely gestures at ticketId, but replyToken (a patterned secret, likely an auth credential) and the lean/full detail enum are entirely unexplained in both the schema and the description.

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 title and the phrase "Support's answer on your ticket" establish that this reads a support reply for a given ticket, which distinguishes it from the sibling create_support_ticket. However, the body of the description is a cryptic fragment list ("status, awaiting, thread") that never states a clear verb+resource relationship or what the tool actually returns, so an agent must infer the purpose rather than read it.

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?

"Answers take minutes to hours" hints at expected latency and therefore a polling cadence, which is faint usage guidance. There is no statement of when to call this versus create_support_ticket or how to obtain the replyToken needed to invoke it, so the agent is left to infer the trigger conditions entirely.

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

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

Annotations already mark this read-only/idempotent/non-destructive, and the description adds substantial behavioral context beyond them: the full state lifecycle, the refunding and terminal failure outcomes (refunded, failed, expired), the long-poll loop semantics, and a safety rule for the payment field ('sign only if paymentCheck.safeToSend'). This is real operational context the agent needs to poll and to avoid signing an unsafe payment.

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?

Dense but efficient — every clause carries polling or safety information, and the state progression is front-loaded. The opening 'Step 3.' fragment is slightly cryptic without external ordering context, and the telegraphic style trades readability for brevity, but no sentence is wasted.

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?

An output schema exists, so return-value explanation is unnecessary, and the description covers the state lifecycle, terminal outcomes, long-poll loop, and the payment-safety gate — enough for a 6-parameter polling tool. It omits what 'detail: lean/full' changes and how verify is used, minor gaps given the existing schema descriptions.

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 already 83%, but the description adds meaning beyond the schema: waitSec guidance (25), that sinceState should equal the last observed state, and that payment is 'what your wallet will sign' gated on paymentCheck.safeToSend. These are semantic rules not present in the field descriptions, though detail/verify/get parameters are not elaborated.

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 description names the resource (swap) and its purpose through a concrete state machine (waiting_for_funding -> deposit_detected -> swap_processing -> completed, or refunding/terminal_failure) plus the long-poll mechanic, so an agent understands this is a status-polling tool. It doesn't explicitly distinguish itself from list_swaps, which also surfaces swap state, so it stops short of a 5.

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 explicit when-to-use triggers ('Call it before funding or showing a deposit again') and prescriptive polling instructions ('Long-poll with waitSec 25 and sinceState = the last state; repeat next until terminal'). The terminal condition and the repeat loop are both stated, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so safety is covered structurally. The description adds genuinely new behavioral facts beyond them: addresses are redacted and returned states can lag behind reality. It stops short of covering pagination, result limits, or what happens on a miss, so it is not a full 5.

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 recovery scenario, then the keys, then the caveats and next step. Very dense and largely waste-free, though the telegraphic 'Next: get_swap_status (live state, payable)' phrasing is compact at the cost of a little readability.

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?

An output schema exists, so return-shape explanation is not required. The description covers trigger conditions, both lookup keys, read-only semantics, redaction and staleness, and the follow-up tool. The only real hole is the undocumented detail enum, which leaves the agent guessing between lean and full.

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 67% and the description largely restates what the schema already says about idempotencyKey (default q_<quoteId>) and sessionId. The third parameter, detail (enum lean/full), is never explained in either place, so the description does not compensate for the coverage gap. Baseline 3 is appropriate.

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+resource ('find orders') and pins the exact scenario it exists for: recovering orders when the orderId was lost after a new chat, crash, or unknown create outcome. It also distinguishes itself from the live-state sibling by naming get_swap_status as the next step, so an agent can separate the two without opening either 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?

Explicit when-to-use ('when the orderId is lost') with the failure scenarios enumerated, plus the two alternative lookup paths (idempotencyKey or sessionId) and the follow-up tool (get_swap_status for live/payable state). Nothing about routing 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.

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false). The description adds that the call is optional and offline, which is useful context an agent needs, but doesn't disclose return shape or rate/permission behavior beyond what annotations and the output schema provide.

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?

Three short, front-loaded sentences with zero filler. The critical 'optional, offline' qualifier leads, followed by behavior and the skip condition.

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?

Given annotations carry the safety profile and an output schema exists to explain the returned next question, the description supplies what's needed: that it validates partial input, is optional/offline, and when to skip it in favor of get_quote.

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 80%, so the schema already documents most parameters. The description lists which fields constitute a partial request, reinforcing which inputs are validated, but adds little syntax or format detail beyond the schema. Baseline 3 is appropriate.

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 action ('Checks a partial request') and names the inputs it examines (direction, amount/receiveAmount, to) plus its output (the next question). It does not explicitly differentiate from the sibling get_quote, though 'skip it when you have what get_quote needs' hints at the boundary.

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 clear when-to-use context ('checks a partial request', 'skip it when you have what get_quote needs'), notably 'optional, offline'. It names get_quote as the alternative and states the condition for skipping, but doesn't spell out the full when-not beyond that.

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

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

Annotations already declare the write/non-idempotent/open-world profile, and the description adds genuinely new disclosure: the operator sees the name and contact supplied, and the key carries pricing consequences downstream. It does not clarify whether repeated calls mint multiple keys (relevant given idempotentHint=false) or how long a key lives, which keeps it off a 5.

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 tight sentences, with the crucial 'Optional.' qualifier front-loaded before the mechanism. The parenthetical 'swapper://trust' is internal jargon that costs a little comprehension, otherwise there is no waste.

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?

The output schema covers return values and the annotations cover the write profile, so the remaining burden is modest. Still, the 'detail' enum is opaque, key persistence/non-idempotency is unaddressed, and the description never says whether registering is a prerequisite for anything or purely a pricing/identity optimization.

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 75%, so the baseline is 3. The description adds meaning to agentName and contact by stating the operator sees them, but it says nothing about 'detail' (lean vs full), the one enum parameter that is undocumented in both the schema and the description.

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 concrete verb and resource ('issues a key that identifies this agent') and immediately explains the key's effect: quotes made with it (get_quote agentKey) and their orders use the agent fee. That distinguishes it from every sibling, none of which mint an identity key. It stops just short of 5 because 'request' vs 'issues' and the scope of what the key unlocks are only sketched.

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?

'Optional.' plus the get_quote agentKey linkage implies when it matters: use it if you want agent-fee pricing and operator visibility. However there is no explicit when-to-use/when-not guidance, no prerequisites, and no statement of what you lose by skipping it, so usage must be inferred.

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

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

The annotations only declare the generic write profile (readOnlyHint=false, idempotentHint=false, openWorldHint=true, destructiveHint=false). The description adds real behavioral context beyond that: the rating is deduplicated to one count per completed order, and a publishable comment only appears after operator review, which is a moderation-latency fact an agent could not infer.

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 tight sentences with the action and its trigger front-loaded, followed by the counting/moderation rules. No filler, though the rating range restates the schema's min/max rather than adding information.

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?

An output schema exists, so return values need not be explained. But for a 6-parameter write tool at 17% schema coverage, the omission of orderId and agentName leaves the description insufficient to tell an agent how to target the right order.

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 only 17%, so the description carries most of the burden, yet it mentions only rating (1-5) and comment/publishable. It never explains orderId (which order is being rated), agentName, or the 'lean'/'full' detail enum, leaving half the parameters semantically opaque in both the schema and the prose.

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+resource (submit a rating/comment for a swap) and the trigger point ('after a swap'), which cleanly separates it from siblings like create_support_ticket or get_swap_status. It does not explicitly name an alternative, but the purpose is unambiguous.

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?

'Optional, after a swap' gives timing context, so an agent knows this is a post-completion action rather than a prerequisite. However, it never states when not to use it (e.g. only after a completed order, not a pending one) or points to any alternative tool.

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