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

Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=true, so the description's added value is the state precondition and the consequence that the RFQ becomes unquotable/unfillable. It stops short of saying what happens to existing quotes or whether cancellation is reversible once executed.

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, the action and its effect first, the precondition second. No filler or repetition of schema or annotation content.

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 and rich annotations, the description only needs to convey preconditions and consequences, which it does. A brief note on what happens to already-submitted quotes would make it fully complete for a destructive single-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 description coverage is 100% and the single rfq_id parameter already documents its format and provenance (list_open_rfqs, my_rfqs, create_rfq, share link). The description adds no further meaning about the identifier, so the baseline of 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 concrete verb and resource ('Cancel your own request or private order') plus the effect ('so no one can quote or take it'), which makes the outcome unambiguous. The ownership qualifier 'your own' also separates it from any administrative cancellation path implied by the sibling set.

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 precondition ('Only before a deal on it is agreed') and redirects the agreed-deal case to the swap settlement/refund path. The alternative is described as a flow ('its swap') rather than naming the specific sibling tools such as fund_leg or refund_leg, so routing is clear but not fully pinned down.

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?

Goes well beyond the annotations by disclosing the irreversible side effect (the secret is revealed on-chain so the counterparty can settle), the API reporting step, and the pre-flight escrow check that can cause refusal. That is exactly the kind of consequence and failure-mode detail destructiveHint alone cannot convey.

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 critical trait (autonomous settlement, secret revealed) is front-loaded and every sentence carries distinct information. It is dense with parentheticals and a capitalized banner, which makes it slightly harder to scan than it needs to be.

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 destructive, open-world, non-idempotent mutation, the description covers preconditions, alternatives, side effects and the check that may reject the call; the return value is already covered by the 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?

Only one parameter and the schema documents it at 100% coverage, so the description's silence on swap_id formatting costs nothing. Baseline 3 applies since no additional meaning is added 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?

States a specific verb and resource ('claim YOUR receive leg of a swap using the preimage') plus the mechanism ('signing with the agent's own key'), which immediately separates it from the sibling reveal_claim and get_deal_secret paths.

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 selection criteria ('Use this when the agent holds the receiving key') and names the alternative workflow ('to claim with your own wallet use get_deal_secret, then reveal_claim'), including the required state (both legs funded, preimage available, initiator status).

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 (readOnly=false, openWorld=true, destructive=false), it discloses the key operational prerequisite — the authenticated account must hold a proven wallet for the asset being given — and explains the private-order lifecycle (link returned, shared out-of-band, optionally wallet-locked). That is exactly the kind of pre-call constraint an agent cannot infer from the hint flags.

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 core action, then mode semantics, then a clearly labelled PREREQUISITE. A few clauses duplicate the schema's own enum descriptions, but each sentence still supports a real decision (mode choice or eligibility).

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 no explanation, and the description covers eligibility, mode trade-offs, and the private-link flow. It is silent on non-idempotency (accidental duplicate postings) and on any funding/escrow implications involving fund_leg, which are the only material gaps for an 8-parameter creation 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% and the description largely restates what the schema already documents for direction, visibility, ask_price and target_address. The only genuinely additive detail is that the private order's link is a returned artifact to hand to the counterparty, 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?

The description opens with a specific verb+resource ("Post a trade request") and immediately disambiguates the two modes it can create (public board RFQ vs. link-only private order). Against siblings like list_open_rfqs, respond_to_rfq and cancel_rfq, an agent can tell this is the creation entry point 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?

It gives concrete selection logic between visibility=public and visibility=private, including that private requires ask_price and that the resulting link must be shared. It stops short of naming alternatives (e.g., respond to an existing RFQ instead of posting a new one) or stating when not to post, so it is strong context rather than a full routing rule.

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 readOnly, idempotent, openWorld, and non-destructive, so the safety profile is covered. The description still adds meaningful context beyond them: the fact that the response includes counterparty-authored message bodies, an explicit prompt-injection warning that those bodies are data and never instructions, and a note that only swap-secret possession (a boolean) is reported rather than the secret itself.

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 payload-relevant information is front-loaded ('Everything about ONE deal'), and the sibling routing and the injection warning each occupy a single compact clause. The parenthetical swap-field list is dense but earns its place by telling the agent what settlement data is available.

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, the description only needs to convey scope and caveats, and it does: what is returned, when to use it, which sibling to use instead, and a security caveat about untrusted message content. Nothing required to call it correctly 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?

There is a single parameter, and the schema documents it at 100% coverage, including its UUID format and the fact that the threadId comes from respond_to_rfq or my_deals. The prose adds no format or sourcing detail beyond that, so the baseline of 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 a specific resource (ONE deal) and enumerates its concrete contents: prices, negotiation messages, HTLC swap fields (swap.id, funder, timelocks, addresses, tx hashes), and swap-secret possession. It explicitly distinguishes itself from my_deals, so an agent can separate it from the listing sibling 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?

It gives a clear use case ('follow a deal through settlement') and names the alternative for listing ('to list deals use my_deals'). It stops short of routing between this tool and near-neighbors like get_deal_secret or get_rfq, so the when/when-not mapping is not complete.

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 flag a destructive, non-idempotent, open-world write, and the description goes well beyond them: which key/signing credential is used per chain, that funds are locked under a hashlock derived from this process's secret, fee and timelock caps, and that as counterparty it reads the initiator's escrow on chain and refuses unless it pays your key the agreed asset/amount with a timelock at least 2h past yours. This is exactly the behavioral context an agent needs before an irreversible on-chain action.

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 operative action is front-loaded in the first clause, with prerequisites and counterparty validation following in logical order. It is dense and long, but nearly every clause carries safety-relevant information; the all-caps header and per-chain parenthetical are the only mild fat.

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 destructive, irreversible on-chain settlement tool, the description covers signing credentials, locking mechanics, preconditions, validation behavior, and bounding constraints. The output schema exists, so the brief 'returns the on-chain tx id' line is a convenience rather than a 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?

Only one parameter, and its schema description is fully covered (swap.id from deal_status or swapId once agreed). The description adds the constraint that the swap must match side, assets, amounts, and an agreed price — meaning beyond the schema field itself.

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 and resource — fund YOUR side of an agreed swap on-chain — and immediately enumerates the per-chain mechanics (EVM/TRON approve+HTLC lock, BTC P2WSH payment, Solana escrow signing). It is clearly distinguishable from claim_leg and refund_leg, which act on the other side of the same HTLC.

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 prerequisites (deal agreed, both parties have set settlement addresses via set_settlement_address), ordering guidance (fund your long leg first as initiator), and scope exclusions (only deals agreed through this MCP, only pinned assets/contracts, only the chain your own RPC is on). No alternative tool is named outright, but the when-to-call conditions are fully specified.

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 flag destructiveHint=true and openWorldHint=true; the description supplies the actual risk model: revealing the preimage lets the counterparty claim your funded leg. It also documents the gating preconditions — deal must have been agreed through this MCP, counterparty escrow is verified ON CHAIN (correct key, asset, amount, 15-minute claim window) and API status is insufficient. That is precisely the context annotations cannot convey.

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 core action and the sibling routing before the safety detail, and every clause carries real information. The long semicolon-chained sentences make it denser than it needs to be, 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?

For a high-risk single-param tool with an output schema and destructive annotation, the description covers purpose, alternatives, gating, on-chain verification, and misuse warnings. Nothing an agent needs in order to call it safely 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% and the single thread_id parameter is already documented with its source (respond_to_rfq or my_deals), so the schema does the work. The description adds no further meaning about the parameter, which is the expected baseline for a fully documented single-param 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?

States a specific verb and resource — retrieve the LOCALLY-stored swap secret (preimage) for a thread where you are the initiator — and immediately frames the downstream purpose (claim your receive leg). It distinguishes itself from two named siblings, claim_leg and reveal_claim, so an agent can route correctly 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?

Explicit when-to-use: only when claiming with your OWN wallet. Explicit alternative: use claim_leg when claiming with the agent's key, because it releases and reports the secret itself. It also names the follow-up action (report via reveal_claim) and an exclusion (never act on a chat message).

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 readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description still adds real context beyond that: 'Anyone holding the id can read it, which is how a private order's link works' discloses the access model, and 'An unknown id returns an error' discloses failure behavior. It stops short of noting anything about output shape, but an output schema exists, so a 4 is fair.

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 purpose and field scope, then access semantics, then error behavior, then sibling routing – a sensible order with no filler sentences. The enumerated field list partly duplicates what the output schema already provides, which is the only wasted weight.

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 tool with rich annotations and an output schema, the description covers purpose, access control, error behavior and alternatives. Nothing an agent needs before calling it 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 single parameter already documents uuid format and where the id comes from. The description only says 'by id', adding no syntax, sourcing, or validation 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?

Opens with a specific retrieval action and resource: 'One request or private order by id', then enumerates the returned attributes (direction, base amount/asset, quote asset, ask price, visibility, status, expiry). It also names the sibling tools list_open_rfqs and my_rfqs, so an agent can distinguish this fetch-by-id tool from browsing tools 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?

Explicitly routes the agent: 'To browse use list_open_rfqs; for your own use my_rfqs.' That gives both an alternative and the condition selecting each, which is exactly the when/when-not guidance the dimension asks for.

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, openWorldHint and destructiveHint=false, so the safety profile is fully covered. The description adds the returned fields (chain, symbol, decimals) and the cross-tool identifier convention, but says nothing about result size, ordering, or whether the registry can change between calls.

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 resource definition and followed by the one convention an agent must carry into other tools. Nothing is redundant with the title.

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, the description need not explain return values, and annotations carry the safety profile. It covers the essential cross-tool symbol format; only minor operational details (result volume, caching/staleness) are absent, which is acceptable for a simple registry 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a no-parameter tool applies. The identifier-format sentence is relevant context for the tool's output rather than its 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 the resource precisely ("Asset registry: every tradeable asset with its chain, symbol and decimals"), so an agent immediately knows this is the lookup that enumerates supported assets. It lacks an explicit verb and makes no direct statement about how it differs from siblings, though the RFQ/deal siblings are clearly a different domain.

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: the note that assets are referenced in other tools as "SYMBOL@chain" signals that this is the discovery step for valid identifiers, but it never says "call this before create_rfq/respond_to_rfq" or when not to call it. No alternatives are named.

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, openWorldHint and destructiveHint=false, so the safety profile is covered. The description goes further with real behavioral detail: a hard result cap of 100, newest-first ordering, the included statuses (open or negotiating), and the exclusion of private orders. It does not say what happens past the 100th result (truncation vs. no pagination), which is the one operational gap.

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 tight sentences, each carrying distinct information: purpose, result shape and cap, filter behavior, and the private-order exclusion with its redirect. Scope and the exclusion are front-loaded, with zero filler or restated title text.

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, the description need not document return fields, and annotations already carry the read-only safety profile. Given only 3 optional parameters, the description covers the remaining unknowns an agent would care about: result limit, ordering, which statuses are included, and what is deliberately 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 description coverage is 100%, including a documented direction enum, so the baseline is 3. The description adds meaning the schema does not: that every filter is optional and that multiple filters are combined with AND, which changes how an agent composes calls.

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 and resource ('Browse the public RFQ board') and immediately frames it in terms of the action it enables ('requests you can quote with respond_to_rfq'), tying it to a sibling. It further distinguishes itself by noting 'your own appear too' and that 'Private orders never appear here', which separates it from my_rfqs and get_rfq 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?

Explicitly routes the agent: private orders must be read via get_rfq with the id from its link, and quoting is done with respond_to_rfq. It also states filters are optional and combine with AND. It stops short of naming an alternative for 'show only my own RFQs' versus my_rfqs, so the coverage of alternatives is strong but not exhaustive.

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 readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds real context beyond them: a hard cap of 100 results, no status filtering, and implicit scoping to the calling user's own deals ('Your'). It doesn't mention ordering guarantees or what happens beyond the 100 cap, which keeps it at 4.

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 dense sentences, front-loaded with the scope and cap before the routing advice; nothing is padding. The enumerated return fields (threadId, status, currentPrice, pendingPrice, acceptance, request) partially duplicate the existing output schema, which is the only mild 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?

With zero parameters, full annotation coverage and an output schema present, the description supplies everything still needed for selection: scope, cap, status coverage, and the sibling to use instead. No gap remains that would cause a misinvocation.

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?

Zero parameters yields a baseline of 4, and the description confirms this explicitly ('Takes no parameters'), removing any doubt an agent might have about passing filters. No further semantic detail is possible for an empty 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?

States a specific resource and scope: 'Your most recent deal threads (up to 100), in every status (open, agreed, closed)', and immediately contrasts with the sibling 'deal_status'. An agent can tell exactly what this returns versus the single-deal 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?

Gives explicit when-to-use ('Use it to find a deal') and names the alternative for the divergent case ('for one deal's messages and HTLC swap use deal_status'). This is a clean routing rule between two siblings.

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 that the tool is read-only, idempotent, non-destructive, and open-world, so the basic safety profile is covered. The description adds useful behavior beyond the annotations: it caps results at the 100 most recent records and confirms that all statuses and private orders are included. It does not describe pagination or return format, but an output schema exists and annotations already carry the safety signals.

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 front-loaded with the primary scope, then immediately contrasts list_open_rfqs, then closes with the no-parameter note. Every clause earns its place, 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?

For a zero-parameter list tool with an output schema and rich annotations, the description supplies everything the agent needs: the result cap, status coverage, privacy scope, and explicit differentiation from the sibling board tool. Nothing material 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 tool has zero parameters, so there is no parameter semantics burden; baseline is 4. The description reinforces this by stating 'Takes no parameters,' which prevents an agent from searching for missing 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 resource and scope: 'Your 100 most recent requests and private orders, in every status (open, negotiating, agreed, filled, expired, cancelled).' It clearly distinguishes this from list_open_rfqs by contrasting private/all-status RFQs with the public open/negotiating board. An agent can identify exactly what this tool returns 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?

The description explicitly names the alternative tool, list_open_rfqs, and explains the condition that selects it: 'The board (list_open_rfqs) shows only public ones that are open or negotiating.' This gives the agent a clear decision rule between this tool and its most similar sibling.

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 destructive/openWorld/non-idempotent annotations, the description discloses the critical behaviors: proposing a price constitutes agreement, accepting names a price so a stale read is refused, and the initiator's swap secret is generated locally with only its hashlock transmitted. These are non-obvious, high-stakes traits that annotations alone could not convey.

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 action list is front-loaded and each bullet is scoped to one action, which makes scanning easy. It is dense and the accept/accept_proposal bullets are long, but nearly every clause carries operational information rather than filler.

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 multi-action, destructive, open-world tool, the description covers all branches, the price-staleness guard, the HTLC swap trigger, and secret handling. An output schema exists, so return values need not be explained, and nothing an agent needs to invoke an action correctly 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%, so the baseline is 3, but the description adds real meaning: it ties 'price' to the specific value each action expects (new total vs pendingPrice vs currentPrice) and explains the 8-decimal constraint's consequence. It stops short of restating the thread_id format, which the schema already handles.

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+resource ('Act in a deal thread') and then enumerates all five actions with their required inputs, so an agent knows exactly what the tool does. It also implicitly separates itself from siblings by pointing to deal_status and my_deals as the source of prices and thread ids.

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?

Each action carries explicit when-to-use guidance: 'accept' is 'needed only when youAccepted is false', 'accept_proposal' is for the counterparty's pendingPrice, 'propose' is a counter. It even explains the exception for an initiator on an older server, which is exactly the kind of conditional routing 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?

Beyond the destructive/non-idempotent annotations, it discloses rail-specific mechanics: EVM/TRON invoke the escrow while Solana/Bitcoin sign a server-built transaction, and Bitcoin additionally requires the chain's median-time-past to clear the timelock, which lags real time by about an hour. It also states where the funds land per rail and that a tx id is returned — context the annotations cannot supply.

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 leads with the precondition framing and each sentence carries non-redundant rail information. The clause describing EVM/TRON payout destinations ('the wallet that funded the escrow — the agent's own key') is slightly convoluted and could be tighter.

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 destructive, single-parameter settlement tool it covers preconditions, rail variance, timing caveats and payout destinations, and an output schema exists so return shape needn't be spelled out. Failure modes (leg not funded, already claimed) are only implied by the precondition statement.

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?

There is a single required parameter with 100% schema description coverage, so the schema already explains swap_id's origin. The description adds no format or sourcing detail beyond that, which is the expected baseline when the schema does the work.

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 verb and resource ('take back YOUR funded leg') plus the exact conditions that make it valid ('after its timelock has passed and the counterparty never claimed it'), which cleanly separates it from fund_leg and claim_leg. An agent can tell what this does 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?

The preconditions are explicit: the leg must be funded, the timelock must have elapsed, and the counterparty must not have claimed. That implicitly states when not to use it, but no sibling tool (e.g. claim_leg) is named as the alternative for the other branches.

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 the key behavioral traits: it opens a private deal thread, returns a threadId usable by negotiate/deal_status, commits the initiator's price via hashlock, and completes only when the creator accepts. This meaningfully explains the destructive/commitment semantics that annotations alone (destructiveHint=true, idempotentHint=false) only flag without explaining.

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 dense but front-loaded with the action and outcome, and each sentence carries useful information about price semantics, return value, and deal commitment. It could be marginally tighter, but 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 the tool's complexity (deal thread creation, price commitment, hashlock acceptance) and the existence of an output schema, the description covers what an agent needs to call it correctly: required inputs are implied by the schema, price semantics are clarified, and the consequence of calling it is explained. No critical prerequisite or behavioral context 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 baseline is 3, but the description adds real meaning about the price parameter: it is the TOTAL quote-asset amount for the whole base amount, explicitly not per-unit. That disambiguates a common and costly mistake beyond what the schema text conveys.

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 ('Respond to an open RFQ with your price') and immediately names the concrete effect (opens a private deal thread) and the return value (threadId). It also distinguishes itself from siblings by naming negotiate and deal_status as the follow-on tools, so an agent can differentiate it from create_rfq or get_rfq without opening schemas.

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 clearly scoped to 'an open RFQ' and the commitment semantics (your quote is your acceptance) tell the agent this is a binding action rather than exploration. It does not explicitly state when not to use it or name an alternative for non-committal exploration, but the context is strong enough to guide 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?

Annotations already declare destructiveHint=true and idempotentHint=true, so the description is not carrying the whole load, but it does explain why disclosure matters (the counterparty and watchers use the secret to settle the other leg) and that the secret passes through the same gate as get_deal_secret. That is real behavioral context beyond the structured fields, though the idempotency and re-submission behavior are left to the 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?

Three tightly packed sentences with the trigger condition front-loaded and no filler. The phrase 'same gate as get_deal_secret' is slightly compressed jargon, but it conveys a prerequisite that would otherwise cost a sentence.

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 described, and the description covers trigger, exclusion, prior step, and secret provenance. What remains unstated is whether re-reporting is safe and whether the counterparty is notified synchronously, which matters mildly given the destructive hint.

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 baseline is 3 and the input schema already explains every field, including the 64-char hex format and the uuid source for swap_id. The description adds the provenance of the secret and clarifies that the leg is 'the one that pays you', but contributes little else 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 names a specific action (report the revealed secret plus claim tx) on a specific resource and states the precondition that selects it (you already claimed your receive leg on-chain with your OWN wallet). It also explicitly separates itself from the nearest sibling, claim_leg, which reports its own claim.

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?

Both the when and the when-not are given: use it after an own-wallet on-chain claim, and it is explicitly not needed after claim_leg. The dependency on get_deal_secret as the secret source is stated, so an agent can sequence the calls without 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?

Beyond the annotations, it discloses a critical behavioral trait: the address is trusted as yours and the secret is released against an escrow paying it, so a wrong address loses funds. This explains why destructiveHint=true matters. It does not say what happens if the address is later overwritten or whether repeated calls replace the prior address.

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 key scoping and security information is front-loaded and the sentences are dense but purposeful. The opening clause and the leg parenthetical slightly overlap in restating the per-leg concept, but nothing is wasted enough to impair use.

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 mutation tool with an output schema and full parameter documentation, the description covers the prerequisite, the leg disambiguation, and the safety consequence of a wrong address. An agent has everything needed to call it correctly and cautiously.

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 real meaning about leg that the schema only states tersely: which leg the maker vs taker funds and receives on, and that leg is needed only when both legs share a chain. This resolves the main ambiguity in invoking the tool.

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 and resource (set receive/refund address for an agreed swap) and scopes it per leg, making it clearly distinct from fund_leg, refund_leg, and claim_leg. An agent knows exactly what this does and that it is a setup step, not a fund-transfer step.

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?

'Required before the HTLC can be funded' gives a concrete prerequisite, and the leg clause explains exactly when the optional leg parameter must be supplied, including which party maps to which leg. It does not name sibling alternatives, but for a prerequisite setup tool that is minor.

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?

Goes well beyond the annotations by disclosing that unreadable keys appear under `localSigners.unusable`, that `solanaLink` reports whether the held Solana wallet is proven to the account, and the failure consequence: naming a key you don't hold makes the leg unsignable. That failure-mode disclosure is exactly the context annotations can't carry. The odd `readOnlyHint: false` on a pure identity query is not contradicted by any claim in the text.

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 the identity statement, then the key-holding distinction, then the operational rule and its failure mode. Dense but each clause carries information; the nesting of backticked paths inside a single long paragraph makes it slightly harder to scan than it needs to be.

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-parameter, read-style identity tool with an output schema, this is close to complete: it explains the two halves of the response, the unusable-key bucket, the proof flag, and the practical consequence of misusing an address. Missing only explicit guidance on when in a workflow to call it relative to siblings.

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?

Zero input parameters, so the baseline is 4, but the description's parameter-like content is about output fields rather than inputs. It adds real meaning to response fields (`localSigners.unusable`, `solanaLink`), though the output schema already exists and covers them, so the added value is moderate rather than decisive.

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 resource: the authenticated account with linked wallet addresses, plus `localSigners.addresses` — what the local process holds keys for. The account-vs-key distinction is precise and an agent can tell it apart from `set_settlement_address`. It doesn't explicitly name siblings, which keeps it from 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 one concrete usage rule — use `localSigners.addresses.solana` as the settlement address on a Solana leg — but that is guidance about interpreting output, not when to call this tool versus `set_settlement_address` or other siblings. When-to-call is only implied (check identity/keys before signing).

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