ChangeNOW

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds behavioral context beyond annotations by explaining what the response includes: current stage, actual deposit and payout amounts, transaction hashes, and a plain-language explanation of the stage and next steps. No contradiction with 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?

The description is two sentences with no filler. The first sentence front-loads the core purpose and enumerates the key return contents; the second sentence gives the usage trigger. Every clause 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?

For a simple status-lookup tool with 2 parameters, full schema coverage, a rich output schema, and strong annotations (read-only, idempotent, non-destructive), the description supplies the missing context: what the tool reports, when to use it, and how it fits in the swap workflow. Nothing essential is missing.

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%, and the schema already describes id as 'Order id returned by create_swap' and sub_id as 'Sub order id, for an order the provider split in two.' The description mentions 'by id' but adds no parameter-specific meaning beyond what the schema provides, so the 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 opens with a specific verb and resource: 'Follow an existing order by id' — this is clearly a status-check operation, not a creation or quote operation. It lists concrete outputs (deposit/payout amounts, transaction hashes, stage explanation) that make its purpose unmistakable and distinguish it from sibling tools like create_swap, quote_swap, and swap_link.

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 description gives clear usage context: 'Use it after create_swap, and again whenever the user asks where their swap is.' This tells the agent the temporal trigger and the user-intent trigger. It does not explicitly state when not to use it or name alternatives, but the usage guidance is specific enough for correct selection.

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?

Beyond annotations, the description discloses key behavioral traits: 'moves no money by itself' but the order is real, can expire, and locks a fixed rate. It also warns that some orders are routed to a partner aggregator rather than ChangeNOW, which is essential context for the agent to relay. Annotations already indicate readOnly false, so this description complements rather than contradictions.

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?

While the description is longer than average, every sentence adds needed context: purpose, side-effect caveat, prerequisite workflow, alternative tool, and post-call relay requirement. Important warnings are front-loaded before workflow details, and there is no filler or repetition.

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 11 parameters with complete schema documentation and an output schema, the description covers the remaining decision-relevant context: when to use it, when to use swap_link, what to confirm with the user, and what to relay from the response. Nothing critical for correct invocation is missing.

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 input schema has 100% parameter description coverage, so the heavy lifting is already done there. The description adds workflow context around parameters (quote first, validate address) but does not introduce new field-level meaning beyond what the schema provides. 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 states a specific verb and resource: 'Create a real swap order and return the deposit address.' It clearly distinguishes itself from the sibling swap_link by noting this version creates a real order that exists in support, can expire, and locks a fixed rate. An agent can immediately tell this apart from quote_swap and validate_address.

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 description gives explicit workflow guidance: quote first, validate the recipient address, confirm both amount and address with the user, and only call this after explicit approval. It also names the alternative tool swap_link with the exact condition to prefer it, and instructs relaying the executor name from the response.

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 behavioral context: the tool returns user-facing warnings, memo labels, address formats, and token contract details, and it deliberately omits pair-specific amount limits.

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 description is two sentences, front-loaded with purpose, and packs the output contents into a compact list. The exclusion of min/max amounts and pointer to quote_swap is placed at the end without redundancy.

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 single-parameter read-only tool with a full input schema and an output schema, the description covers what the tool is for, what it returns, and what it intentionally omits. An agent has enough context to select and 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?

The schema already documents the single required parameter fully, including accepted canonical ids, legacy tickers, and page slugs. The description reinforces that the input is an asset identifier and ties it to swap-building context, but it does not need to add much beyond 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?

The description clearly identifies the tool as returning everything needed to build a swap for a single asset, and enumerates the specific fields returned (canonical id, ticker, decimals, memo requirement, address format, contract, warnings). It also explicitly states what is NOT included and points to quote_swap, making it distinguishable from list_assets and quote_swap.

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 description gives strong routing guidance by stating that minimum and maximum amounts belong to the pair and should be fetched from quote_swap. It implies this tool is the place to get per-asset metadata when constructing a swap, though it does not explicitly compare against list_assets or validate_address.

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 already carry the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower and there is no contradiction. The description adds behavior beyond those annotations: the pagination contract ("When has_more is false the response is the complete answer and no paging is needed") and input-normalization behavior (mapping user phrasing to a canonical "ticker.network" id). This is operational context the annotations cannot express.

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?

Four sentences, each with a distinct job: core purpose, parameter capability summary, call-order directive with rationale, and pagination terminal condition. The most important information is front-loaded in the first sentence, and nothing is redundant with the schema or annotations.

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 the description need not explain return values. It covers purpose, search/filter capabilities, the critical "call before quoting" sequencing, and the pagination stop condition — everything an agent needs to invoke it correctly. Given the rich schema, full annotations, and this context, the description is complete for a read-only lookup 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 100% with per-parameter descriptions and examples, so the baseline is 3. The description adds value by synthesizing the parameters into user-intent terms — "Search by ticker, name or network, filter by network, by fiat or crypto, and by whether a fixed rate is possible" — and by explaining why q requires disambiguation (same ticker on several networks). It earns a 4 for that synthesis, though it does not add syntax details beyond 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?

The description states a specific verb and resource — "Find the assets ChangeNOW can exchange" — and adds a second distinct purpose: "turn what the user said into a canonical asset id." It differentiates from the sibling tools by introducing the canonical-id concept ("ticker.network"), which is the identity that quote/swap/status tools depend on, so an agent can tell this discovery/resolution tool apart from get_asset or quote_swap.

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 description gives explicit directional guidance: "Always call this before quoting," backed by the reasoning that the same ticker exists on several networks and only the canonical id identifies one. It also provides a concrete stop condition for paging ("When has_more is false the response is the complete answer and no paging is needed"). It stops short of a 5 because it never names the alternative tool explicitly (quote_swap) and gives no when-not-to-use cases.

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?

Beyond the annotations, the description discloses that no funds move and nothing is created, that a fixed rate locks for about ten minutes, and that the tool says so rather than quietly substituting a float rate. It also tells the agent to relay warnings from the response. This is substantial behavioral context beyond readOnlyHint.

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?

Four dense sentences, front-loaded with the core purpose and with no filler. Each sentence adds a distinct piece of information: core behavior, return value, fixed-rate special case, and side-effect-free guarantee.

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 the output schema exists and the input schema already documents all parameters, the description is complete: it covers what the tool returns, how to choose direction, how to request a fixed rate, how the rate_id connects downstream to create_swap, and the fact that no funds move. An agent has everything needed to invoke 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?

The input schema already covers 100% of parameters, so the baseline is 3. The description adds meaningful semantic framing: it explains the directionality of amount_from versus amount_to, the real-world meaning of rate_type 'fixed' and the rate_id it produces for create_swap, and reinforces that fixed availability is pair-dependent.

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 opens with a specific verb and resource: 'Ask what a swap would give, in either direction.' It clearly separates itself from sibling tools by mentioning that it returns a rate_id needed by create_swap and that 'Nothing is created and no funds move,' which distinguishes it from create_swap and swap_link.

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 description gives explicit usage direction: pass amount_from to learn the receive amount, or amount_to to learn the send amount. It also gives a clear selection rule for rate_type: use 'fixed' whenever the user wants a guaranteed number, and it explains the fallback behavior instead of silently returning a float rate. The connection to create_swap is explicit.

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 destructiveHint. The description adds valuable context: 'Opening the link creates nothing' and explains that the user, not the assistant, performs the confirmation. This goes beyond the annotations without contradicting them.

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 description is tightly written and front-loaded with the core action. Every sentence earns its place: what it builds, that it has no side effects, why it is recommended, and when to use the alternative. There is no fluff or repetition.

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 9 parameters, an output schema, and read-only/idempotent annotations, the description covers the essential context: purpose, safety, workflow recommendation, and alternative routing. Parameter details and return values are handled by the schemas, so nothing critical is missing.

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 100%, so the input schema already documents each parameter. The description adds general context about what the link prefills (pair, amount, address, memo), but does not add per-parameter meaning 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 clearly states the tool's purpose: to build a changenow.io confirmation link with swap details prefilled. It uses a specific verb ('Build') and distinct resource ('changenow.io link'), and differentiates itself from the sibling create_swap by explaining the confirmation-first workflow.

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 description explicitly recommends this tool as the default way to finish a swap, explains why (user verifies rate and address on the real page), and gives a precise condition for using the alternative create_swap instead. This is strong, actionable guidance.

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 already mark this as read-only and idempotent, and the description adds meaningful behavioral detail beyond them: it will name the other network instead of simply refusing, and it will say the address could not be checked for assets without a format in the catalogue. This is exactly the kind of edge-case behavior an agent needs to know.

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 description is four sentences with no filler: the core action is first, followed by the critical wrong-network caveat and the uncheckable-assets caveat. Every sentence adds decision-relevant 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?

The description covers the main purpose, the key failure mode (wrong network destroying funds), the memo requirement, and the edge case where validation is impossible. With an output schema present, nothing essential is missing for correct invocation.

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 100%, so the schema already documents all three parameters. The description reinforces that memo is only relevant when the asset needs one, but it does not add substantial new meaning beyond 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?

The description states a specific verb ('Check'), a specific resource ('a recipient address, and its memo when the asset needs one'), and the exact criterion ('against the format the network requires'). This clearly distinguishes it from the swap-related siblings, which are about creating, quoting, or checking swap status.

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 description explicitly says 'Call this on every address the user gives' and places the call 'before any order exists.' It also explains how to handle the wrong-network case and the unverifiable-catalogue case, giving clear situational guidance.

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