Sablebolt swaps

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

Annotations already flag the write, non-idempotent, open-world profile, and the description adds genuinely non-obvious behavior: no refund address, failed swaps handled by support via swap id, and floating rate where the final amount is only fixed on deposit confirmation. The only gap is that it doesn't say whether calling twice creates two swaps or whether the quote expires, though non-idempotent is already annotated.

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 action and its return value, then conditions and caveats in descending priority; no filler sentences. The first sentence is dense with a long parenthetical list of URI standards, but since there is no output schema that detail is load-bearing rather than decorative.

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 fully covers the response surface an agent must act on (address, memo, amount formats, wallet URI, status URL). For a non-idempotent, irreversible-value tool it also discloses the no-refund and floating-rate behavior, leaving nothing essential unstated.

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 baseline is 3, but the description adds meaning the schema does not: the deposit must originate from fromAddress and that wallet must be under the caller's control, and the returned amount is expressed both in decimal and base units against the partner's token contract. That clarifies the constraint that makes fromAddress semantically different from toAddress.

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?

Specific verb and resource ("Creates the swap") plus an explicit enumeration of what comes back: deposit address, memo, amount in decimal and base units, wallet URI, status URL. It also names the sibling it is not (swap_page_link), so an agent can route without opening any 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?

Gives an explicit use condition ("only when you control the wallet at fromAddress and will send the deposit yourself") and an explicit alternative for the other case ("for a person use swap_page_link"). The when-not case is stated, not merely implied.

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 readOnlyHint annotation already establishes that this is a safe read operation. The description adds only the unit clarification ('in the asset you send') and does not disclose error behavior, route validity requirements, or return structure beyond what the annotation provides.

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 a single efficient sentence with no unnecessary wording. It is appropriately concise for a simple two-parameter lookup tool, though it could be slightly more front-loaded with an explicit verb such as 'Returns'.

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 read-only tool with two documented parameters, the core purpose is covered. However, with no output schema, the description does not explain the return shape, such as whether minimum and maximum are separate fields or how precision/units are represented, leaving a meaningful gap.

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 defines both parameters. The description adds meaningful semantics by clarifying that the returned limits are denominated in the asset being sent, which is not explicit in the parameter descriptions.

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 resource as the minimum and maximum amount for a route and specifies the denomination as the asset you send. It is understandable without opening the schema, though it does not explicitly differentiate this tool from siblings such as get_quote or list_routes.

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?

There is no guidance on when to use get_limits versus get_quote, list_routes, or create_swap. It also omits any prerequisites or conditions, leaving the agent to infer usage from the name and parameters alone.

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 declare readOnlyHint=true, and the description adds real behavioral context beyond that: the quote is 'floating', the network fee is deducted from the payout, and the final amount is fixed only once the deposit confirms. It does not state quote expiry or time-to-live, which keeps it from 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 no filler, and the core definition is front-loaded. The field list is slightly cryptic (amountTo vs receiveAmount are not disambiguated), but nothing is redundant.

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 no output schema, the description usefully enumerates the return fields and flags the quote as non-final. However, for a tool requiring three identifiers it leaves the meaning of `from`/`to` unexplained and gives no sense of how long a quote remains valid.

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 33% — just `amount` is documented as a decimal string. The description never explains whether `from` and `to` are asset symbols, chains, or addresses, and it instead spends its words on output fields, so it fails to compensate for the coverage gap on two required parameters.

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 (a floating quote for a route and amount) and enumerates the returned values (amountTo, networkFee, receiveAmount, rate), so the agent can tell this is a pricing/estimate call rather than a state-changing swap. It stops short of contrasting itself with siblings like get_limits or list_routes, so differentiation must be inferred.

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?

There is no explicit when-to-use guidance, no mention of calling this before create_swap, and no alternatives or exclusions named. The implication that this is a pre-swap preview comes only from the word 'estimate' and the note about deposit confirmation.

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?

readOnlyHint=true already marks it as a safe read. The description goes further by disclosing the returned domain values, notably the stage scale (1 waiting … 5 done), which an agent cannot infer from the annotations or schema. It omits edge behavior such as what happens for an unknown id.

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?

A single front-loaded sentence that names the scope first and then the payload fields; the compact '1 waiting … 5 done' enum gloss earns its space.

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 no output schema, the description usefully characterizes the return payload, which is the main burden here. Only error/not-found behavior is left unaddressed for a simple one-parameter read.

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 single id parameter is already documented as 'swap id from the status page URL'. The phrase 'by id' adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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 ('Status of one swap by id') and enumerates the fields it reports (stage, addresses, amounts, tx hashes). It is clearly distinct from the mutating sibling create_swap, though it never names a sibling to route against.

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?

Usage is only implied: it is the lookup-by-id tool, and the schema clarifies the id comes from the status page URL. There is no explicit statement of when to prefer it over create_swap or other siblings, and no exclusions.

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?

With readOnlyHint and openWorldHint=false already covering the safety profile, the description still adds real value by disclosing the shape of the payload (slug, ticker, network, confirmations, extra-id name) and the availability flag. Since no output schema exists, this is the agent's only source of return-value information, though it says nothing about ordering, size, or whether availability can change over time.

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?

A single front-loaded sentence with no filler; scope comes first, then the field list. 'Extra-id name' is mildly jargonish, but every clause carries 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?

For a zero-parameter read with no output schema, the description covers what the agent needs to decide to call it and what it will receive. What is missing — field types, enumeration of networks, whether unavailable assets are included or filtered — is minor for a simple catalog 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?

The tool takes zero parameters, so there is no parameter semantics to explain and the baseline of 4 applies. The description correctly spends no words on inputs.

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 a specific resource (assets) and its scope, namely 'every asset the swap form knows', and enumerates what each entry carries. The verb is only implicit ('list'), and it never distinguishes itself from siblings like list_routes or get_limits, but the resource is unambiguous enough for an agent to pick the right tool.

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?

Usage is only implied: a zero-parameter catalog read is self-evidently a lookup tool, and 'which assets exist / are available right now' is the obvious trigger. There is no explicit when-to-use or when-not-to-use statement, and no pointer to alternatives such as list_routes or get_limits.

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?

readOnlyHint=true and openWorldHint=false already establish the safety profile, so the description is not carrying that burden. It adds real value by disclosing that results are unfiltered ('every route') and include a live availability flag, but says nothing about result size, ordering, or whether availability is a snapshot.

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?

One sentence, front-loaded with the resource and its scope, with no filler. The parenthetical '(from/to slugs)' is slightly compressed and takes a beat to parse, but nothing 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?

For a no-argument, read-only list tool with no output schema, the description covers what comes back and the key availability signal. Minor gap: 'whether both sides are available' leaves the exact shape of the availability fields ambiguous without an output schema.

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 tool takes zero parameters, which is the baseline-4 case; there is no schema semantics for the description to supplement. The mention of from/to slugs correctly signals these are output fields rather than inputs.

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 pair ('every route') and names the payload fields it returns (from/to slugs, availability). It does not distinguish itself from siblings such as list_assets or get_quote, 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?

Usage is only implied: the mention of slugs and 'available right now' hints that this is the discovery step before quote/swap calls, but no when-to-use, when-not-to-use, or alternative tool is named. An agent must infer the routing from sibling names alone.

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 and openWorldHint=false, so safety is partly covered. The description adds genuine context beyond that: no transaction is executed here, a human opens the link and sends the deposit from their own wallet, and the agent never signs. Link lifetime, revocation, and single-use behavior are not disclosed.

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 core fact (a prefillable link for human completion) is front-loaded, which is good, but the second sentence restates the same idea at greater length before the useful create_swap contrast at the end. A tighter version would put the alternative first.

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 three-parameter read-only link generator with no output schema, the definition covers who executes the swap and how the deposit is funded. Missing details are secondary: the exact return shape and link validity window.

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 0%, so the description carries the burden. It does clarify the roles – 'amount prefilled' implies amount is optional, and 'both addresses' implies from/to are the two swap sides – but it gives no format, chain, or address-type detail for those fields.

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 the concrete resource: a page link where a person completes a swap with the amount prefilled. It explicitly contrasts itself with create_swap, so an agent can distinguish the hand-off path from the programmatic path. It is slightly indirect in that it never says 'returns a URL', leaving the output type to inference.

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 routing is given in both directions: a swap for a person is completed by that person via this link, while an agent controlling the sending wallet should use create_swap and pay the returned instruction. This is exactly the when/when-not/alternative structure an agent needs.

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?

With readOnlyHint=true already supplied, the description adds real value by defining the boundary of the check: format only, not ownership and not memo/tag requirements. That prevents a costly false-positive interpretation where an agent treats a passing validation as proof the address is safe to send to. It does not state how an unknown asset slug is handled or the exact return shape, which keeps it below 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 short sentences, front-loaded with the core check and followed immediately by the scope exclusions. Every clause carries information an agent needs; nothing is restated from the title or schema.

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 two-parameter read-only check with no output schema, the description covers purpose and boundaries but never says what comes back: the word 'whether' implies a boolean result but does not confirm it, and error behavior for an unrecognized asset slug is unspecified. An agent can probably call it correctly, yet the return contract is left to inference.

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 50%: 'address' has no description at all and 'asset' only says 'asset slug'. The description mentions both an address and an asset but adds no format detail for either, such as expected address encoding or the slug convention. With half the parameters undocumented, the description neither compensates nor is obligated to, so the baseline 3 fits.

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 check on a specific resource: format validity of an address for a given asset. The second sentence sharply bounds the scope by naming two things it does not verify (ownership, exchange memo), which lets an agent separate this from any transfer-related sibling. It stops short of an explicit verb like 'validates and returns a boolean', but the intent 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?

Usage is implied rather than stated: an agent can infer this is a pre-flight check before sending funds, and the explicit exclusions ('does not check who owns it or whether an exchange needs a memo') tell it what this tool cannot answer. There is no positive guidance about when to call it or what to do with the result, and none of the swap/quote siblings are named as alternatives.

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