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?

The description adds meaningful behavioral context beyond the annotations: it clarifies that no money moves by itself but the order is real, can expire, and locks a fixed rate. It also warns that the response names an executor and that some orders route to a partner aggregator, which is non-obvious and critical for the agent to relay to the user.

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 deliver the core function first, then caveats, preconditions, the alternative tool, and a routing warning. Every sentence earns its place; there is no fluff or repetition of schema details.

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 11-parameter schema with full coverage and an output schema, the description supplies all the non-schemaable guidance an agent needs: when to call, what to do first, when to avoid, and what to relay from the result. 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?

The schema has 100% description coverage for all 11 parameters, so the baseline is 3. The description connects the overall workflow to some parameters—e.g., 'Quote the swap first' refers to rate_id—but it does not add per-parameter meaning beyond what the schema already provides.

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 identifies the output: 'return the deposit address the user has to send funds to.' It further distinguishes the tool from siblings by calling the order 'real' and explicitly routing non-approved cases to 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 preconditions: 'Quote the swap first, validate the recipient address, and confirm the amount and the address with the user before calling this.' It also states clear exclusion criteria: if the user has not approved, 'use swap_link instead and let them confirm on the page.' This is actionable and unambiguous.

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 readOnlyHint annotation, the description adds concrete behavioral traits: no funds move, fixed-rate locks expire after about two minutes, and the tool reports when a fixed rate is unavailable instead of falling back. This gives an agent a clear safety and timing 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?

Four dense sentences front-load the main behavior, then cover return value, rate selection, and safety, with no filler or repetition of schema details.

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?

Together with the rich schema and annotations, the description covers behavior, directionality, fixed-rate nuances, timing, output contents, and safety. Nothing needed for correct invocation appears 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%, so the schema carries the definitions; the description adds the complementary 'either direction' semantics and the dependency between rate_type fixed and the rate_id needed by create_swap. This extra layer justifies above baseline.

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: asking what a swap would give, in either direction. It distinguishes quote_swap from creation by stating it returns the rate_id create_swap needs and that nothing is created.

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?

It gives explicit usage conditions: pass amount_from or amount_to depending on the desired direction, ask for fixed whenever the user wants a guaranteed number, and quote again right before creating the order because the lock lasts about two minutes. It also explains that unsupported fixed rates are reported rather than silently falling back.

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.