SwapEazi

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

With no annotations, the description carries the burden well: it discloses that figures are labelled LIVE, INDICATIVE, HISTORICAL, or ESTIMATED, that estimated savings are never realised, that it calls POST /api/v1/payment-analyses, and that it shares the free route-assessment allowance. It stops short of fully explaining persistence, side effects, or authentication behavior beyond the schema's access_key field.

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 purpose is front-loaded and the description is dense with useful context. It repeats the point that estimated amounts are never realised, but the overall length is appropriate for the tool's complexity.

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 15-parameter analytical tool with no output schema and no annotations, the description explains the output categories, data-quality labels, prerequisite, endpoint, and allowance sharing. It remains somewhat incomplete about analysis persistence and when to read an existing analysis_id versus create a new one.

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 87%, so the schema already carries most parameter meaning. The description adds only the important prerequisite that existing_provider is needed, without adding syntax or interpretation for the other 14 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 states a specific analytical purpose: measuring payment cost versus the official rate, split into FX spread and fees, with estimated savings against a recommended route. It is clearly not a generic cost calculator or route recommender, though it does not explicitly name sibling tools it should be preferred over.

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 prerequisite, 'Needs existing_provider', and frames the tool around analysing a current provider. However, it does not explicitly say when to use this instead of siblings such as calculate_payment_cost, assess_route, or compare_payment_providers.

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 no annotations supplied, the description carries the full burden and does most of it: it declares the operation read-only, requires the organisation's key, flags that aprd_ demo items do not work, and describes the state machine including the signed, chained decision record. It stops short of stating what happens for an unknown or malformed approval_id, or how long an issued agent_approval remains valid before expiry.

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 verb and resource, and every clause carries information — the state list, the release hand-off, the safety warning, and the auth caveat. The opening sentence is a long multi-clause run-on of semicolon-separated states, which slightly hurts scannability for a first read.

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?

There is no output schema, and the description compensates fully by enumerating the four possible status payloads and the agent_approval shape. For a one-parameter read-only status lookup, an agent has everything needed to call it and act on the result.

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 is already documented as apr_…/aprd_…, so the baseline is 3. The description adds genuine meaning on top by explaining that an aprd_ item bypasses the organisation key requirement, which the schema does not say.

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 ("Read") plus resource ("a payout the agent held for approval") and the key it is addressed by (approval_id), then enumerates the four terminal states it can return. That is enough for an agent to distinguish it from request_payment_approval, approve_payment_run, release_status, or verify_release_record 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?

It gives a clear when-to-use (look up the state of a held payout) and an explicit when-not-to-proceed ("Do not release a payout while it is awaiting approval, rejected or expired"), plus the hand-off path: pass the returned agent_approval { id, role } to record_release. What it lacks is any naming of adjacent siblings — e.g. release_status or approve_payment_run — to explain which read/decision tool to pick instead.

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

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

With no annotations, the description carries the full burden and does well: it discloses the write side effect (one release record per approved payment), states the guardrail that an agent cannot approve on its own, and says plainly 'Never sends or moves money.' It does not say whether a recorded approval is immutable or how to correct a mistaken approval, which is a meaningful gap for an approval-recording tool.

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?

Purpose is front-loaded and every clause carries information (policy gate, acknowledge rule, returned release instructions, follow-up tool). The weakness is form: it is one very long run-on sentence with inline quoted literals, which makes it harder to parse quickly than a few short sentences would 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 5-parameter, nested-object, no-output-schema mutation tool, it covers the essentials: gating policy, side effect, non-movement of funds, and the shape of the per-payment return (release_in_own_bank with beneficiary, amount, currency, reference, source account, cut-off). It leaves out error/edge behavior such as calling against a run with nothing prepared or replaying an already-recorded approval.

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 linkage the schema does not spell out: held payments require acknowledge: true, payments accepts either the literal "all_prepared" or a list of payment_ids, and approver is the { name, role } of the actual approving person. This meaningfully reduces the chance of a mis-invocation.

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 opening clause gives a precise verb and resource: it records a named person's approval of a run's prepared payments and creates one release record per approved payment. This is clearly distinguishable from siblings such as request_payment_approval (asks for approval), release_status (reads status), and reconcile_payment (records what landed).

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 states the prerequisite (the run's policy must set agent_may_record_approval and name the approver), the fallback when it does not hold (returns the person's own approval path via POST /api/v1/payment-runs/{id}/approve), the precondition for held/pending items (acknowledge: true once assessed), and the follow-on tool (reconcile_payment). That is explicit when-to-use, when-not, and next-step routing.

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 no annotations supplied, the description carries the full burden and does so: deterministic JSON output, per-figure source/read time/freshness/evidence type, data-quality flags, unknowns, and a kept record retrievable by assessment_id with a content hash rather than a signature. It also states the negative guarantees (never ranks, never executes, never claims executability without a firm quote on record) and that the call is free — behavior an agent cannot get from any structured field here.

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 purpose and the pre-payment timing are front-loaded, and the closing sentence of guarantees is well placed. The middle is a single long run-on inventory of return fields, which is dense and hard to scan, though nearly every clause carries information an agent would otherwise lack given no output 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 10-parameter tool with no annotations and no output schema, the description is unusually complete: it explains the shape of the result, the freshness and evidence-type vocabularies, quality flags, and record retention. Minor gaps remain — nothing about auth/permissions, rate limits, or what is returned for an unknown or unassessed corridor.

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 each parameter is already documented in detail, including the default-amount label, the 15-minute as_of window, and the include/exclude behaviour. The description adds no parameter-level meaning beyond that, 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?

The first sentence names a specific verb and resource ('assess the corridor') and fixes the scope to pre-commitment cross-border payments on SwapEazi's own data. The closing clauses ('never ranks a route as advice, never executes') carve out a clear boundary against rank/recommend and execution siblings such as recommend_payment_route or submit_payment, and the endpoint reference anchors it to GET /api/v1/route-assessments.

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 clear timing guidance ('Before a business commits to a cross-border payment') and states the retrieval path for past assessments rather than recomputation. It does not, however, name an explicit alternative for adjacent needs (e.g. price_routes, compare_payment_providers, recommend_payment_route) or state when not to use it, so an agent still has to infer routing among the rich sibling set.

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 no annotations, the description carries the full burden and does real work: it discloses the backend model (one analysis via POST /api/v1/payment-analyses, a persisted pa_ record), the data-quality taxonomy applied to every figure (LIVE, INDICATIVE, HISTORICAL, ESTIMATED), the explicit caveat that estimated savings are never realised, and quota behaviour (free, shares the route-assessment allowance). It stops short of stating authentication requirements, error behaviour, or latency, and the phrase 'the same service for every payment-intelligence tool' is left unexplained.

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 lead clause is front-loaded with the right information, and the trailing caveats about data labels and quota earn their place. However, the prose is telegraphic and runs a long fragment chain ('with each alternative route's cost at the same size. One analysis (POST /api/v1/payment-analyses), the same service for every payment-intelligence tool'), and that last clause adds ambiguity rather than clarity.

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 15-parameter, nested-object tool with no output schema and no annotations, the description covers the return content in enough detail that an agent knows what comes back, plus the data-quality labelling and quota constraints. The main gap is that it never positions itself against the many adjacent pricing/route tools, so an agent must guess whether to call it, price_routes, or assess_route.

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 87%, so the parameters are already documented (currency semantics, due_date eligibility, beneficiary_amount vs amount, existing_provider shape). The description adds little parameter-level meaning beyond establishing that comparison happens 'at the same size', which loosely ties amount to the alternative-route comparison. Baseline 3 applies when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence is a specific verb-plus-resource statement: it computes what a payment costs through the current provider versus the official rate, listing the exact figures returned (effective rate, FX spread, transaction/intermediary/payout fees, total in money and bps, beneficiary receives). It also notes it returns each alternative route's cost at the same size. It never names a sibling to use instead (price_routes, assess_route, compare_payment_providers, swapeazi_landed_cost all overlap), so differentiation is left 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?

Usage is implied by the enumerated output: an agent can infer this is the tool for a full cost breakdown of a specific payment size. There is no explicit 'use this when / use X instead' routing despite roughly 60 sibling tools with overlapping pricing scope. The 'Free: shares the route-assessment allowance' note gives a cost-of-calling cue but not selection 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?

No annotations are supplied, so the description carries the full burden. It explicitly says nothing is executed or issued and that the tool is free, and it describes result categories (inside/outside/unknown) and enriched row fields, though it does not cover auth, rate limits, or error behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

It is dense and front-loaded, opening with the action and closing with safety and cost. A bulleted structure would be easier to scan, but every sentence contributes information rather than restating the name.

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 7-parameter, nested-object tool with no annotations and no output schema, the description is substantially complete: it covers inputs conceptually, return-row verdicts and carried fields, and non-execution. Some operational details (policy key requirement, map-age rule, full response shape) are left to the schema or omitted.

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?

With 86% schema coverage, the baseline is 3; the description adds real semantic value by explaining constraint sources (policy, AP2 mandate, Verifiable Intent, x402 accepts/price) and the unknown-propagation rule. It still does not add meaning for every parameter, such as instrument_classes_allowed or map_id.

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 gives a specific verb-resource pair — re-evaluate every candidate in a stored Options Map against constraints supplied now — and scopes it to four constraint sources. It implies distinction from single-item checkers like check_payment_against_mandate by operating over map rows, though it never names a sibling or exclusion explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It makes the usage context clear: a stored Options Map plus constraints supplied now, with the benefit of dropping ineligible or blocked rows without a second call. It does not state when not to use it or name alternative sibling tools, so it falls short of a 5.

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 no annotations supplied, the description carries the full burden and does much of it: it discloses that nothing is sent (no side effects), that a breach returns mandate_violation plus the failing rule, and that verification is only persisted when the payment is prepared inside a payment run. This last point is a genuinely non-obvious behavioral caveat. It does not cover authorization requirements in concrete terms or failure modes beyond mandate breach.

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?

Six short sentences, front-loaded with purpose and outcome semantics, with no filler. The 'A router key is required' sentence is terse to the point of ambiguity, but otherwise every sentence 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 nine-parameter mutation-adjacent check with no annotations and no output schema, the behavior and return-on-breach story is adequately covered, but the parameter surface is essentially undocumented. An agent can decide whether to call it but will struggle to populate the inputs 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?

Schema description coverage is only 11%, with nine parameters and just one documented, so the description must compensate and largely does not. 'A router key is required' gestures at a credential parameter but never maps it to access_key, agent_id, or rail, and the meaning of from/to, rail values, and mandate_id is left entirely to inference.

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 object ('Verify one payment against a mandate') and pins the moment of use ('before it is prepared'), which separates it from mandate-management siblings like get_mandate or create_mandate. It stops short of naming a specific alternative sibling, so an agent must infer the boundary with check_constraints or payout_rules.

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?

Timing guidance is explicit ('before it is prepared'), and the description clarifies that a pass is not an approval, implicitly routing approval to request_payment_approval or approve_payment_run. There are no explicit exclusions or named alternatives, so the routing is clear but not fully disambiguated.

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 no annotations, the description carries the full behavioral burden. It usefully discloses the possible result states for each venue type, including Rate Receipt-backed values and a 'Being measured' state with a reason. However, it does not state whether the operation is read-only, whether access_key is required for authorization, or how errors and missing evidence are handled.

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 compact, but it front-loads the cryptic 'Spec v1.0 name for liquidity_map' framing before explaining the actual output. The single dense sentence is reasonably efficient, yet its technical shorthand makes the purpose harder to parse 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 six-parameter tool with no annotations, no output schema, and only 17% schema description coverage, the definition leaves too much unexplained. It covers the result categories but does not explain parameter semantics, authorization behavior, or practical usage relative to liquidity_map and the other liquidity-related 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?

Schema description coverage is very low at 17%, so the description needs to compensate for the undefined parameters. It only hints that amount represents the payment size and defers the rest by saying 'Same arguments as liquidity_map,' leaving from, to, access_key, and amount_currency unexplained in this definition.

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 resource and the key output shape: liquidity by venue type, including depth at the requested size, slippage, landing cost, Rate Receipt status, or a 'Being measured' reason. It clearly identifies this as the spec v1.0 name for liquidity_map, but that alias relationship is not the same as helping an agent choose between the two tools.

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 guidance on when to use this tool versus liquidity_map or any of the other payment and routing tools. The only routing information is the statement that it takes the same arguments as liquidity_map, which does not tell the agent when this tool is preferred.

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 no annotations supplied, the description carries the full load and does substantial work: it discloses that the call POSTs /api/v1/payment-analyses and persists a readable analysis, that every figure is tagged LIVE/INDICATIVE/HISTORICAL/ESTIMATED, that estimated savings are never realised, and that the call is free but draws on the shared route-assessment allowance (a quota constraint agents must budget for). Residual gaps are error behaviour and the fact that routes without figures are still returned, which is mentioned but not explained.

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 compact sentences, information-dense with essentially no filler; the output fields come first and the provenance and quota caveats follow. The opening is elliptical (no explicit verb, 'Your current provider beside every route on record') and the phrase 'routes known without figures' is cryptic on first read, 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 15-parameter, nested-object tool with no output schema and no annotations, the description covers return content, provenance labels, persistence and quota well. The critical omission is input sufficiency: with zero required parameters, an agent gets no guidance on the minimum viable call (e.g. invoice_text alone, or amount plus source/destination, or a corridor), nor on precedence when invoice_text and the explicit fields conflict.

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 87%, so the schema already explains almost every parameter, and the baseline of 3 applies. The description adds context that the comparison is run at the same amount and against the same official rate, which explains why amount/currency/source/destination must be pinned down, but it adds no syntax or constraint detail for the 15 parameters, including the nested weights and existing_provider objects.

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 first sentence states precisely what is produced: the agent's current provider set beside every recorded route for the corridor, at identical amount and official rate, with named output fields (all-in bps, total cost, beneficiary amount, eligibility, score). That is a specific comparison resource rather than a restatement of the title. It stops short of distinguishing itself from close siblings such as swapeazi_route_compare, price_routes, calculate_payment_cost or recommend_payment_route, and 'the same service for every payment-intelligence tool' describes infrastructure rather than scope.

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 framing around 'your current provider' signals this is the benchmarking tool when the caller already has an incumbent quote or past payment. The description also documents the read-vs-create branch ('analysis_id ... instead of making a new one'), which is real guidance. But with 60+ siblings and four or five near-neighbours, it never says when to pick this over assess_route, price_routes or recommend_payment_route, and offers 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 no annotations, the description carries the full burden and does disclose real behavior: the source currency is never assumed, the response includes the intent, its hash, and every assumption made, and it is marked 'Free'. Those are meaningful traits (determinism-ish, assumption disclosure, no cost) an agent cannot get from the schema. It leaves out whether compilation is side-effect-free/idempotent and what happens when the text is ambiguous.

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 sentences, front-loaded with the core transformation, then input modes, then return values. Each sentence carries content. The trailing one-word 'Free.' is terse to the point of ambiguity and would read better as a clause about cost.

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 10-parameter tool with a nested payer object, no annotations and no output schema, the description does cover what comes back (intent, hash, assumptions) and the input shapes. The notable gap is that with zero required parameters it never says what a valid call looks like at minimum or how partial inputs (e.g., text only) are resolved. Error and ambiguity behavior is also unaddressed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 90%, so the baseline is 3; the description earns above that by explaining the polymorphic input surface (a plain sentence, a flat form, or a full intent) and by glossing amount_basis as 'what leaves or what must land'. That reframing makes the source/destination distinction easier to act on than the schema text alone. It adds nothing, though, about how payer sub-fields interact or which combination is minimally sufficient.

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 artifact: turning a corporate FX or payment requirement into a PaymentIntent, and it enumerates the fields it captures (currencies, amount, amount basis, value date, constraints). That is far more than a restatement of the name. It stops short of naming which sibling consumes the output (route_intent, decide_intent, payment_intent), so the compile-vs-route boundary is left implicit.

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 example ('pay a Japanese supplier JPY 800m by 15 October') and the three accepted input shapes (sentence, flat form, full intent) implicitly tell an agent how to call it, and the framing suggests this is the entry point of the payment flow. However, there is no explicit when-to-use versus when-not-to-use, no mention of route_intent/decide_intent/payment_intent as the next steps, and no statement of the minimum input needed when zero parameters are required.

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 no annotations, the description carries the full burden. It discloses the key behavior—on-chain receipt reading, verification that the receipt came from the prepared wallet and matches the prepared transaction, returning a signed audit record, and that it is read-only and moves nothing. However, it omits failure/mismatch behavior and does not mention the optional contribute data-sharing side effect (though the schema documents that parameter).

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, front-loaded with the precondition and then the action and result. Every clause adds value and there is no 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?

Given no annotations, no output schema, and low schema coverage, the description supplies the necessary chain of events, verification behavior, and return value. It still leaves the optional contribute privacy trade-off and mismatch/error handling unstated, so it is strong but not fully complete.

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 only 33%, so the description must compensate. It explains that prepare_id identifies the prepared payment and tx_hash is the transaction hash the wallet sent, and it describes what the tool does with them (verify against the prepared wallet and transaction). The optional contribute parameter is covered only by the schema description, not the tool description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: confirm a payment that the wallet has already sent after prepare_payment, reading the receipt and returning a signed record. This clearly separates it from prepare_payment (preparation) and implicitly from submit_payment (sending), though it does not explicitly differentiate from reconcile_payment or reconcile_outcome.

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 a clear precondition: use this after your wallet has sent a payment prepared by prepare_payment, supplying the prepare_id and transaction hash. It lacks explicit when-not guidance or named alternatives for reconciliation scenarios.

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 no annotations, the description carries the full burden and does so well: production sending is off unless the deployment enables it, credentials are proven with a read (no payment sent), encrypted at rest, never returned, and only the last four characters plus created date surface in responses. It also discloses that SwapEazi holds no funds and has no account in the flow, and flags a real risk — credentials traversing the agent's context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

It is a dense single paragraph that front-loads the core action before the caveats and the alternative-path recommendation, and nearly every clause carries information. The leading 'Keyed.' is dead weight and the multi-clause sentences around the default release flow take effort to parse.

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 an 8-parameter, no-annotation, no-output-schema mutation tool this is close to complete: it covers safety implications, the production/sandbox distinction, credential handling, and even what the response will reveal. The gaps are the undocumented sender and access_key parameters and no statement about what happens on failure or duplicate connection.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the schema documents nothing beyond types and enums; the description partially compensates by explaining rail (yellowcard only), api_key/secret, the required cap_per_payment per payment, and the sandbox/production sending distinction behind env. Three parameters — label, sender (a nested object), and access_key — receive no explanation anywhere, and the cap_per_payment currency/value structure is unaddressed.

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 — connecting the business's own account at a rail (yellowcard) — and bounds the scope to reads and sandbox sending. It is clearly distinct from list_rail_accounts and remove_rail_account in the sibling set, though it never names those siblings explicitly. The opening token 'Keyed.' is opaque and adds no clarity.

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 directional guidance: prefer POST /api/v1/rail-connections from your own software because credentials passed through this tool travel in the agent's context, and it explains the default operational flow (business releases payments itself in its own portal). That is strong when-to-use context. It stops short of telling the agent when NOT to use it or pointing at list_rail_accounts to check existing connections first.

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 no annotations, the description carries the full burden and does substantial work: it names the source pool (payments press and regulator feeds), defines three evidence labels with their meanings, states ordering (newest first), discloses the announced_routes split, and notes the tool is free. It omits operational traits like rate limits or paging beyond the limit cap, which keeps it short of 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?

One dense paragraph, but it is front-loaded with purpose and scope, and the enumerations of event types and evidence labels each add decision-relevant information. The regional list is the only mildly expendable phrase.

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?

There is no output schema and no annotations, yet the description sketches the return shape well (per-event source link, evidence label, newest-first ordering, separate announced_routes collection), which is the main thing an agent needs before calling a news-feed tool. Missing only operational details such as rate limits or empty-result behavior.

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 days, kind, pair, limit, and currency are already documented, and the description adds little parameter-level detail beyond listing the event categories that correspond to `kind` values. Baseline 3 is appropriate given the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb+resource ("Dated corridor news for a currency pair or one currency") and immediately enumerates the event classes it returns (route launches/exits, licences, central-bank rule changes, devaluations, limit changes, outages) plus the geographic scope. That is enough for an agent to separate it from rate, registry, or route-selection siblings such as get_corridor_rates or map_options.

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 tool is for news/regulatory events, and the note that pair route launches "come back separately as announced_routes, never as payment options" steers the agent away from treating this as a route-selection tool. However, no sibling is named as the alternative and there is no explicit when-not-to-use statement.

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 no annotations, the description carries the full disclosure burden and does a reasonable job: it reveals the tier vocabulary (evidenced, partial, inferred), that failure rate may not be published yet, and that the call is free — provenance and cost traits an agent could not infer. It never states explicitly that this is a read-only, non-mutating lookup, nor anything about authentication or rate limits, which is a meaningful gap for an annotation-free tool.

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 idea is front-loaded in the first clause, which is good, but the remainder is a single run-on sentence that stacks seven returned fields into a comma chain, making it hard to scan. Every element is arguably informative, yet the packaging costs readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and only 20% parameter documentation, the description effectively doubles as the response contract — listing every returned field including the peg-type enum values — which is exactly what is needed here. The remaining shortfall is the undocumented amount_basis parameter and the absent read-only/permission framing.

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 only 20%, so the description must compensate, and it partially does: it names the pair and 'size' (the amount), and explains country with an ISO example (CI for XOF). However, amount_basis with its source/destination enum is never mentioned, and the from/to pair semantics are left entirely to 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 opening clause states a specific resource and scope: coverage of the map for a given currency pair and size, enumerating the tier, outcome counts, publishers, error band, and peg type. An agent knows exactly what data comes back. What it does not do is distinguish itself from the near-identical siblings get_coverage and swapeazi_coverage, which an agent must disambiguate on its own.

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 when-to-use guidance and no mention of alternatives, despite two obviously overlapping sibling tools. The only usage-adjacent signal is the trailing 'Free.', which tells the agent about cost but not about selection. The optional country argument is described in terms of what it returns rather than when to supply it.

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 no annotations, the description carries the full behavioral burden. It usefully discloses that a router key is required, a person still approves every payment, and the mandate does not move money, but it does not cover idempotency, permission requirements, failure modes, or what happens if a mandate already exists.

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 three tight sentences that front-load the created resource, enumerate its main fields, and then add the key constraints. There is little wasted wording, and the most important behavioral caveats are placed at the end for emphasis.

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 an 11-parameter create tool with 9 required fields, no annotations, and no output schema, the description covers the core concept and several important constraints. It remains incomplete on full parameter semantics, return value, validation behavior, and side effects, so it is adequate but not fully complete.

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 55%, and the description adds meaning for several parameters: rails are listed with their enum values, approver_person_id is framed as the human approver, and access_key is described as a router key. It still leaves agent_id, period semantics, and the cap-object shape largely to the schema, so it partially but not fully compensates for the moderate coverage.

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 a specific verb and resource: create a spend mandate for an agent, and it enumerates the main configuration dimensions. It also distinguishes the tool from payment execution by saying the mandate does not send money, though it does not explicitly contrast with get_mandate or check_payment_against_mandate.

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 as setup/configuration for agent spending controls, and the human-approval requirement hints that this does not replace payment approval. However, there is no explicit guidance on when to use this instead of get_mandate, check_payment_against_mandate, or payment_controls.

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 no annotations supplied, the description carries the full burden and does meaningful work: it discloses that the decision is persisted with timestamp, person, and proposal (an audit record), that a human is mandatory ("an agent cannot approve alone"), and that no outbound message is dispatched ("Nothing is sent"). It omits error behavior, duplicate-decision handling, and what the response contains, which keeps it short of 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?

Sentences are short and front-loaded, and the human-approval constraint and no-side-effect guarantee arrive before any detail. The opening fragment "Keyed." is cryptic and costs a little clarity without carrying clear meaning on its own.

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 four-required-parameter mutation with no annotations and no output schema, the definition covers the essentials an agent needs (human authority, audit retention, no dispatch) but leaves person_role undefined, never explains the access_key, and says nothing about failure or repeat-call behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate, and it only partly does: "named person" maps to person_name, "approves or rejects" to the decision enum, "proposal" to intent_id, and "Keyed" appears to signal access_key. Nothing explains person_role at all, and no formats or value conventions are given for any field.

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 pair (approves or rejects) against a specific resource (a payment intent), and the title adds that the actor is a named person. It does not explicitly differentiate itself from close siblings such as request_payment_approval, approve_payment_run, or approval_status, so the agent must infer the boundary.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

"An agent cannot approve alone" is a real precondition that implies a human must drive this call, which is useful when-to-use context. However, no sibling tool is named and no when-not-to-use case is given, so a model cannot tell from the text whether to reach for this versus request_payment_approval or approve_payment_run.

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?

No annotations are supplied, so the description carries the full burden and does so well: it discloses cost model (free within the daily allowance, a key lifts it), latency profile (under 3 seconds on cached metadata; needed_by triggers one live routing lookup that can take longer), and the always-present what_we_dont_know. It also flags interpretive caveats an agent could otherwise misread — historical_context is band-wide and not caller-specific, hedge_scenarios are presentation only with no recommended ratio, and current_quote is measured against the reference (the Markup Measure).

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 single most important instruction — when to call it — is front-loaded, and nearly every clause carries operative information about output shape, latency, or interpretation limits. It is a dense wall of em-dash-separated clauses rather than paragraph structure, which costs readability for a report this complex, but little of the content is 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 13-parameter tool with nested objects and no output schema, the description covers the essentials: what comes back (per-leg cost in bps, settlement time, licence, evidence class), what changes when needed_by is passed, and how compact versus full output differ. Gaps remain around the payer/client metadata parameters and how constraints like exclude_providers and max_settlement_hours alter results, which an agent must read from the schema instead.

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?

With 77% schema coverage the baseline is 3, but the description adds genuine meaning beyond the schema: needed_by is explained as the switch that unlocks timing_scenarios, fx_exposure and hedge_scenarios (with each scenario family characterized), and detail is framed as compact-pointing-at-the-signed-map versus full report. It leaves several parameters (payer.entity_type, exclude_providers, max_settlement_hours) unexplained beyond their schema text, so it does not fully compensate for the remaining coverage gap.

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 in one line: "a payment requirement in, a signed DiscoveryReport (a Decision Brief) out" across bank, PSP and stablecoin rails side by side. It also declares negative scope ("Nothing here ranks, picks or recommends. Does not execute, hold or price money"), which separates it from siblings like recommend_payment_route and the payment execution tools without needing their 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?

Gives an explicit trigger: "Call this before initiating any cross-border or cross-currency payment," plus a clear boundary that it never executes or recommends. It does not name the concrete alternative sibling to use for ranking/execution, so the agent must infer the handoff rather than being routed to it explicitly.

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 no annotations supplied, the description carries the full disclosure burden and does well: it declares read-only behavior ('changes nothing and moves no money') and states an authorization prerequisite ('Cases opened with an organisation's key need that key'). It omits error behavior and any rate or pagination details, which keeps it below a 5 for a tool with zero annotation coverage.

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 purpose and return contents, then moves to usage, safety, and auth notes in a logical order. The long parenthetical inventory of Evidence Passport components is dense but each item earns its place by telling the agent what fields to expect; it is not padded.

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?

There is no output schema, so the description must explain what is returned, and it does so thoroughly by listing lifecycle status, evidence provenance and freshness, provider access, decision, outcome, unknowns, exceptions, and timeline. It also covers read-only safety and the organisation-key requirement. Only the absence of any error or failure-mode guidance keeps it from a 5.

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 intent_id parameter is already documented in the schema, including the pi_ prefix and provenance from POST /api/v1/cases. The description repeats the 'pi_…' hint but adds no new syntax, format, or validation meaning beyond the structured field, so 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 gives a precise verb and resource ('Read a payment case by intent_id') and then enumerates exactly what the composite view contains: lifecycle status, reporter, Evidence Passport components, unknowns, exceptions, and timeline. This clearly separates it from narrower siblings like intent_status or payment_intent, which return only a status rather than the full evidence dossier.

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 states a concrete usage condition: 'Use it before acting on a payment, to see what is current, what has expired and what must happen next,' which tells the agent when this tool should precede action tools like submit_payment or approve_payment_run. It does not name specific alternative tools or exclusion cases, keeping it just short of a 5.

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 no annotations, the description carries the full burden; it does disclose the returned evidence structure (source, read time, freshness, evidence type) and that results are bound to an assessment_id, which is genuinely useful. However it never states that the call is read-only, says nothing about authentication via access_key, rate limits, or whether an assessment_id must pre-exist or is minted by the call.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

It is a single dense run-on sentence that front-loads meta-information about spec versioning rather than the operation itself. Most of the content earns its place, but the ordering and lack of sentence breaks make the payload list hard to scan.

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?

There is no output schema and no annotations for a 5-parameter tool, and the description covers the return payload only in outline while leaving three parameters and the relationship to assess_route unexplained. It is not complete enough for an agent to invoke it confidently over its 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?

Schema coverage is only 40% — from, to, and access_key are undocumented — and the description compensates only by deferring to another tool ('Same arguments as assess_route'), which is not self-contained. It adds no meaning about the pair-vs-corridor override or the access_key other than the schema's own example for corridor.

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 (official rate for a currency pair plus per-route all-in cost, FX, settlement and requirements) but never states a clear verb — it opens with versioning metadata ('Spec v1.0 name for assess_route') rather than what the tool does. It does distinguish itself from assess_route by framing itself as the v1.0-named counterpart, but the reader is left unsure whether it is an alias or a distinct operation.

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?

'Same arguments as assess_route' hints at equivalence but never says when to call this instead of assess_route, price_routes, or recommend_payment_route. There is no guidance on prerequisites (e.g. whether access_key is needed) or on which sibling to prefer, so an agent has to guess between near-duplicate tools.

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

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

With no annotations supplied, the description carries the load and does well: it commits to a semantic guarantee ('never proven without a closed landing'), discloses an access-tier behavior ('free callers see masked route names'), and lists the returned timestamps and counters. Gaps remain around ordering, volume/pagination, and any rate limits for a large corridor list.

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 behavior, then statuses, then return fields, then access-tier caveat. Every sentence carries information; the parenthetical status definition is dense but useful 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 one-parameter read tool with no output schema, the description compensates by naming the returned fields and defining every status value, plus noting the equivalent REST endpoint. The main omission is routing guidance against the crowded family of adjacent coverage/rate tools.

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% for the single optional access_key parameter, so the schema already explains it fully. The description adds nothing about the credential parameter or how it interacts with the 'free callers see masked names' behavior, which is the one place it could have added meaning.

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 ('List corridors and each route's standing') and enumerates the three possible statuses with a definition of 'proven'. An agent can tell what data comes back, but the description never distinguishes this from close siblings such as 'coverage', 'swapeazi_coverage', or 'get_corridor_rates'.

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 definition of the standing states tells the agent which questions this answers (is a route proven? priced only? dead?), but there is no explicit when-to-use, when-not-to-use, or named alternative among the many similar coverage/rate 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?

No annotations exist, so the description carries the full burden. It usefully discloses the auth requirement (router key via header or access_key) and the org scoping boundary, which is real behavioral context. It does not describe return shape, error behavior for unknown ids or foreign-org mandates, or whether this is a pure read.

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 and id format, then the auth prerequisite. No filler or redundant restatement.

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 tool is simple (3 params, full schema coverage, no output schema), so a short description is defensible and the auth/scoping note is valuable. However, with no annotations and no output schema, it should indicate what a returned mandate contains and how not-found or cross-org access behaves.

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 all three parameters are already documented, including 'man_...' and the router-key alternative to a Bearer header. The description adds the org-scoping meaning of the key but little else beyond the schema, so 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 and resource ('Read a mandate by id') and gives the id format ('man_...'), which clearly separates it from create_mandate and the broader payment siblings. It does not explicitly contrast with catalogue/analysis tools, but the purpose is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description says a router key is required and that the mandate must belong to the router key's organisation, but gives no when-to-use guidance relative to alternatives such as check_payment_against_mandate or create_mandate. An agent must infer the retrieval use case on its own.

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 no annotations, the description carries the full burden, and it does disclose a real behavioral trait: response content varies by credential tier (masked publisher for free callers, source name for router keys). It says nothing about not-found/expired receipt handling, what max_age_seconds actually gates, or rate 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?

Four short, front-loaded sentences with no filler; the identifying information comes first and the credential-tier caveat follows. Slightly telegraphic ('Schema swapeazi.rate_receipt.v1') but every fragment 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 simple 2-parameter read with full schema coverage and no output schema, this covers the essentials, including response variance by caller tier and the presence of max_age_seconds. A brief note on missing/expired ids would make it complete.

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 baseline is 3, but the description adds meaning beyond the schema by explaining the consequence of access_key (elevated visibility of the publisher) rather than just repeating its format. The id parameter gets no extra semantics beyond what the schema states.

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 ('Return a stored Rate Receipt by id') plus the id format (rr_...) and schema version, so the operation is unambiguous. It does not name a sibling (e.g. price_routes, which mints the ids) to differentiate against, 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?

Usage is only implied: the agent infers it should call this after obtaining an rr_... id from price_routes. The free-vs-router-key sentence gives auth context but no explicit when-to-use/when-not or alternative-tool routing.

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 no annotations, the description carries the full burden, and it does disclose two useful traits: the output is 'Signed' and 'Facts only; SwapEazi moves no money', signalling a non-mutating read. It does not cover behavior for unknown/stale intent_ids, freshness of the daily history, or any access requirements.

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 first names the object and then enumerates returned fields; nothing is padding. It is dense with nested parentheticals and would read better as two shorter sentences, costing it a point.

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?

Despite no output schema and no annotations, the description enumerates the payload well: today's route, cost of paying now, rate lock, unhedged hold need, daily history, and the changed fields (selected route, cost, lock-at level, due date). For a one-parameter read tool this is close to sufficient, with only error/freshness behavior 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 single parameter has 0% schema description coverage, so the description must compensate. It partially does by explaining that intent_id refers to an intent retained via route_intent with remember: true, giving provenance that the bare string schema lacks, but adds no format or validity detail.

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?

Identifies a specific resource — a remembered payment intent created via route_intent with remember: true — and distinguishes itself from route_intent by naming that origin. The verb is implicit (the description is a noun phrase describing returned state), so it is clear but not crisply action-oriented.

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?

Implies usage by stating the intent comes from route_intent with remember: true, which tells an agent when an intent_id would exist and be worth querying. It offers no explicit when-not or comparison against nearby siblings such as payment_intent, compile_intent, or decide_intent.

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 no annotations at all, the description carries the full behavioral burden, and it does disclose some real traits: that rails may attach a quote feed via API key or OAuth connection plus exactly one published rate, and that SwapEazi takes no custody of funds and sells no placement. What remains undisclosed is significant for a write-like operation: whether re-joining is idempotent, whether the contact is verified, what permissions or approvals are needed, and what a successful call returns.

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 short and broken into digestible sentences, so it is not bloated. But the telegraphic style works against it: the opening "Keyed." is an unexplained fragment, and the ordering puts an ambiguous word ahead of the actual subject of the tool.

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 nine-parameter registration tool with no annotations, no output schema, and zero schema description coverage, the description is far too thin. It explains neither the required fields nor the outcome of the call, so an agent could not reliably construct a valid invocation from it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% across nine parameters, so the description must compensate and largely does not. It gives meaningful hints for only party (business/rail/agent), quote_feed (api_key vs oauth) and rate (one published rate); the required parameters name and contact, plus from, to, rail_kind and access_key, receive no explanation of format or semantics.

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?

"A business, a rail or an agent joins" restates the name join_network rather than naming the operation (register/onboard party onto the network), though it usefully enumerates the three participant types that map to the party enum. The opening fragment "Keyed." is opaque and adds no discriminating meaning. An agent can broadly guess this is an onboarding/registration call but could not confidently distinguish it from siblings like connect_rail_account or request_introduction.

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?

No when-to-use guidance, no prerequisites, and no named alternative is given. "No placement is sold" and "SwapEazi does not hold or move money" are trust disclaimers, not selection criteria. The agent is left to infer on its own whether this tool or connect_rail_account is the right entry point.

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 no annotations, the description carries the burden and does substantial work: it discloses the access-tier behavior (free callers get anonymized venue labels, router keys get names), the disclaimers 'Figures, not advice' and 'Unknowns listed', and the fact that SwapEazi 'never holds, creates or moves liquidity'. It also enumerates the output shape (depth, slippage, landing cost, Rate Receipt, largest supported size, 'Being measured' reason). What is missing is a plain statement of whether the call itself is read-only/idempotent and any rate 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 core is a single ~130-word run-on sentence whose clauses chain venue types, per-venue status, slippage, Rate Receipt and fallback states without any list or punctuation breaks. The opening frame is well front-loaded, but the middle is a dense wall an agent must re-parse, which undercuts the otherwise substantive 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?

For a seven-parameter tool with a nested object and no output schema, the description covers a lot of the return surface: venue coverage, per-venue depth verdict, slippage and landing cost, largest supportable size, failure states, and prefunding-related costs and peg/exit depth. Remaining gaps are the read-only nature of the call and the missing differentiation from sibling liquidity tools.

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 71%, so the schema already documents pair, amount, amount_currency, access_key and the nested prefunding object. The description only adds that prefunding involves 'amount held, days held' and that amount is a ticket size, which mostly restates the schema; nothing is said about how from/to interact with pair or about the prefunding sub-fields' optionality.

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 ('Map liquidity for a currency pair ... and a ticket size') and enumerates the venue types covered (order books, stablecoin pools, P2P adverts, ramps, OTC desks, banks). An agent can tell what this produces, though it never explicitly distinguishes itself from near-siblings like check_provider_liquidity or onchain_liquidity.

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?

No when-to-use or when-not guidance is given, and no sibling is named as the alternative despite roughly sixty siblings including several liquidity-adjacent ones. The prefunding narrative implies a use case (cost to enter/exit at a size while holding prefunding) but the agent must infer it, and the access-tier note ('Free callers see Route A, Route B; a router key shows venue names') is a payload detail rather than routing 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?

With no annotations, the description carries the full burden. It does add a genuinely useful security disclosure — the response never includes a key or secret, only the last four characters — which tells the agent the output is safe to surface. It stops short of stating that this is a non-mutating read, what authorization the access key needs, or what an empty result looks like.

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?

Very short with no filler, and the scoping statement plus the field list are front-loaded. But the fragment style ("Keyed.") and colon-led field enumeration are cryptic rather than economical — a few more words would have bought substantial clarity.

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?

There is no output schema, so the description appropriately enumerates the returned fields, which is the right call. It nevertheless leaves key gaps for a credential-adjacent tool with zero annotations: no statement of read-only behavior, no auth or rate-limit context, and no handling for the optional access_key.

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% for the single parameter, so the description must compensate and largely does not. "The rail accounts connected with this router key" only obliquely links access_key to which key's accounts are returned; it never says what the parameter is, whether it is optional (the schema marks it non-required), or what happens if omitted.

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 implies a listing of rail accounts scoped to a router key and enumerates the returned fields (rail, env, label, key suffix, created date, cap), which clarifies what the tool yields. However, the phrasing is telegraphic ("Keyed.") and never states the read/list action outright, nor distinguishes it from siblings like connect_rail_account or remove_rail_account.

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?

"Keyed" hints that an access key is involved, but there is no explicit when-to-use guidance, no statement of what the tool is an alternative to, and no mention that connect_rail_account is the way to add accounts. The agent must infer usage entirely from the name.

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 no annotations provided, the description carries the full behavioral burden and does well: it says the map is signed, stored, compact by default, potentially over 100 KB in full mode, and free within a daily allowance that a key lifts. It does not specify permissions, error behavior, or side effects, so it stops short of 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?

The description is front-loaded and every major sentence describes an output, constraint, or invocation behavior, which is justified for a complex mapping tool. It is still a dense single paragraph that would be easier to scan with structure, which keeps it from a 5.

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?

Because there is no output schema, the description does the necessary work of enumerating the returned fields, sorting rules, compact/full behavior, and map_id reuse. It omits explicit coverage of country and release_at behavior and some error cases, but those are secondary for this mapping 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%, so the schema already documents all six parameters and the baseline is 3. The description adds a useful cross-reference to compile_intent for the intent form and reiterates the compact/full default and map_id read-back, but it says nothing about country or release_at 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 opening sentence names the exact artifact returned — a signed Options Map for a PaymentIntent — and specifies its scope: every rail and provider the graph holds for the pair and size. The phrases 'never by a rank' and 'A guide, not advice' help distinguish it from recommendation or route-selection siblings.

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 context ('so an agent can filter out ineligible or blocked routes before quoting') and says to pass an intent or intent_id. It also signals that the result is guidance rather than advice, but it does not name sibling tools or spell out explicit when-not 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?

With no annotations, the description carries the full burden and does so well: it discloses provenance (KyberSwap, ParaSwap, Jupiter, Across, CCTP, LI.FI), that every figure carries a source, timestamp and Rate Receipt, that failures retain their reason, that unsourced countries are reported as 'not established' rather than guessed, that results are never ranked, and that the service never holds funds or requests signatures. It also states the pricing model ('free within the daily allowance') and the equivalent REST endpoint.

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 purpose and primary scope are front-loaded, but the body is a dense multi-clause wall of text with stacked parentheticals that is hard to parse on first read. Most clauses carry information, yet some (the REST-endpoint mapping, the repeated non-custody disclaimers) could be compressed without loss.

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 six-parameter tool with no output schema, the description is unusually complete: it enumerates the returned data blocks (depth and cost, bridge cost and time, hourly reads with age, destination block), the provenance and receipt model, and the failure semantics. An agent knows what it will get back and how to interpret gaps without seeing a response 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?

Schema coverage is already 100%, so the baseline is 3, but the description adds real meaning: it explains what amount means in practice (price impact benchmarked against a USD 100 quote, cost against par with gas and stated fees), what destination unlocks (documented supplier stablecoin acceptance plus off-ramp venues), and what to_asset/from_asset do at the currency level. It does not clarify the access_key versus Bearer-header behaviour beyond what the schema says, but overall it exceeds 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 precise verb-and-resource: executable on-chain depth and cost for dollar stablecoins at a given ticket size, enumerating the chains, coins, aggregators and metrics covered. It is unmistakably not a generic rate tool. It never names or contrasts a sibling (check_provider_liquidity, liquidity_map, swapeazi_dex_cost all overlap in theme), so differentiation is inferential rather than explicit.

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: 'at your size', the destination block behaviour, and the note that hourly reads cover USD 10k/100k/1m/5m hint at when the tool applies. There is no explicit when-to-use versus when-not, no named alternative for provider-side or route-comparison questions, and no prerequisites beyond the passing mention of an access key for venue names.

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 no annotations, the description carries the full burden and does meaningful work: it discloses coverage (nine named currencies), the null-with-reason behavior when adverts are too few, and the crucial caveat that a missing gap is never zero. It also flags 'Free' as a cost signal. It omits cadence/pagination and confirmation of read-only nature, which keeps it short of 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?

Five short sentences, front-loaded with what the series is and immediately followed by the disclaimers that prevent misuse. No filler; each clause (market-observed, currency list, null rule, not-zero rule, free) communicates a distinct operational fact.

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 one-optional-parameter read tool with no output schema, the description conveys the series shape (dated, per currency), the coverage set, and the null semantics well enough to call it and interpret results correctly. A hint at the series length or return container is the only material 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 coverage is 100%, with the single optional date parameter fully documented (YYYY-MM-DD, default today UTC). The description adds only the word 'dated' and no further meaning about the date parameter, so the schema does the heavy lifting and 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 states precisely what is returned: a dated per-currency series of the gap between a public-advert median and the official rate, and explicitly frames it as market-observed, never official. That is a specific resource with a clear measurement semantic. It does not name a sibling (e.g. get_corridor_rates, rate_deal_history) as the alternative, so differentiation is left to inference from the wording.

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 agent can infer this is for measuring parallel-market premium, and 'Free' signals it is a no-cost reference series. There is no explicit when-to-use versus when-to-use-a-sibling guidance, and no stated prerequisites.

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 no annotations supplied, the description carries the full burden and does well: it declares read-only semantics, states the authentication requirement (organisation key), and discloses the scope of returned data including today's and month-to-date spend against each budget. It does not mention pagination, result volume, or freshness/latency, which are the remaining gaps for a multi-view read.

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?

Purpose is front-loaded in the first clause, followed by the three returned views and then the two short operational facts (read-only, key required). Dense but well ordered. The first sentence is long and runs three list items together, which slightly hurts scannability.

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?

There is no output schema, so the description must convey return content — and it does: spend profiles versus budget, pending approvals including any pre-prepared transaction, and the prepared/confirmed audit trail. For a single-optional-parameter read tool this is close to sufficient; only detail on shape or pagination of the lists 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?

Only one parameter and schema coverage is 100%, so the baseline is 3. The description does add real meaning beyond the schema by explaining that supplying approval_id switches the tool from a collection read to a single-approval read — a mode change the schema alone does not convey. That modest addition keeps it at 3 rather than higher, since id format and provenance are already in 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 opens with a specific verb and resource ('Read the controls that govern the payments') and enumerates the three views returned: spend profiles with budget consumption, payments awaiting human approval, and the audit trail of prepared/confirmed payments. An agent knows exactly what it gets. It stops short of naming which siblings (e.g. approval_status, request_payment_approval) cover overlapping ground, 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?

It gives a clear conditional mode: with approval_id it reads that single approval, otherwise it reads the full control set. It also states the prerequisite ('Needs the organisation's key'). However, there is no explicit guidance on when to use this versus approval_status or request_payment_approval, so the agent must infer the boundary.

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 no annotations at all, the description carries the full burden and does substantial work: it states SwapEazi does not hold or move money, that a person still approves, that returned figures may be measured, a non-locked public quote, or still being measured, and that the selected route minimizes total payer outlay. What it leaves unstated is whether calling it persists an intent record (side effects), and what 'Keyed' and the access_key mean for authentication.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

It is front-loaded and dense, with each sentence carrying new information about inputs, outputs, selection logic or trust model. The staccato fragments and capitalized 'Being measured' make it slightly harder to parse than a clean prose version, but there is almost no wasted wording.

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 seven-parameter tool with no annotations and no output schema, the description covers the return shape (route families, negotiated rate, selection rule) well. It is incomplete on whether the call creates a persistent intent, on error conditions, and on the access_key/customer_id identity parameters, which matters because without annotations the agent has no other signal about side effects.

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 only 14% (only deadline is documented), so the description must compensate, and it does clarify the most important ambiguity: amount_receive is what the payee must receive, not what the payer sends, and from/to form the corridor. But the two non-required parameters, access_key and customer_id, get no explanation in either the schema or the description, leaving an authentication/identity gap.

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 gives a concrete verb and resource: a business states payee, corridor, amount and deadline, and the tool returns a route proposal. That is specific enough to distinguish it from pure rate lookups like get_corridor_rates or price_routes. It does not, however, name or contrast itself with close siblings such as compile_intent, route_intent, decide_intent or prepare_payment.

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 description shows the situation in which you would supply an obligation and get proposals back, but never states when to call this instead of route_intent, compile_intent or price_routes. There are no exclusions or prerequisites, so an agent must infer placement in the workflow from the narrative 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?

With no annotations, the description carries the full load and does well: it discloses the authentication/ownership requirement (the key that made the run), and it explains that the export path degrades gracefully, reporting 'no evidence' for payments missing an assessment, approval or release record rather than failing. It does not mention pagination, cost, or whether reading has any side effects, so it stops short of full coverage.

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 sentences, front-loaded with the resource and the returned fields, then the export variant, then the key requirement. The middle sentence is dense but each clause carries information; only the parenthetical status list is slightly hurried given it lacks explanations for the enum values.

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?

There is no output schema and no annotations, so the description must explain both returns and behavior, and it largely does: it describes the per-payment payload, the alternate export payload, and the missing-record behavior. Minor gaps remain around volume/pagination for large runs and the exact shape of Rate Receipts.

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 earns more: it clarifies that export: true swaps the return shape to a JSON audit export, that run_id accepts pr_... values from run_payments plus the pr_sample sentinel, and that access_key must specifically be the router key that created the run — a constraint the schema only hints at.

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 ('Read a payment run by run_id') and enumerates exactly what comes back: per-payment status values (prepared, needs_attention with reasons, no_evidence), assessment, Rate Receipts, approval, release record and landed amounts. It is clear what the tool returns, though it never names which sibling to use for a narrower single-record view (approval_status, release_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?

It gives useful calling context — pr_sample needs no key, a real run requires the router key that created it — and explains when to pass export: true. What it lacks is routing guidance: no statement of when to prefer approval_status or release_status over this composite view, so the agent must infer the choice from sibling names.

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?

No annotations exist, so the description carries the full behavioral burden, and it does substantial work: it discloses the three outcome states (ok, needs_person, blocked), the full reason taxonomy, the optional signed record with its privacy properties (hash and states, no names or accounts), and the payment/auth requirement (paid, Authorization Bearer key with pricing URL). What it omits is operational behavior an agent would still want: output format, file size limits, and how malformed input is reported.

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 check and its pre-release framing are front-loaded, then formats, then outcomes, then the non-custody and paid caveats — a sensible order with little filler. The long comma-spliced list of rejection reasons is dense and would read better as a structured list, but each item carries information an agent needs.

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 annotations and no output schema, the description must stand alone, and it covers input formats, the verdict vocabulary, the reason set, the optional signed artifact, the paid/auth requirement, and the custody boundary. Remaining gaps are the concrete response shape (field names, per-row identifiers) and failure behavior for unparseable files.

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 all three parameters are already documented, establishing a baseline of 3. The description does add real meaning on top: accepted formats (pain.001 .03 to .12, CSV with comma or semicolon and Dutch or English headers) and the mapping of review_above to 'the company's own review limit' producing needs_person, which a schema alone would not convey.

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 ('Pre-release check on a whole payout file') plus scope ('before it goes to the company's own bank or PSP'), which clearly separates it from row-level checks like swapeazi_beneficiary_check. It never names a sibling tool explicitly, so the differentiation is inferable rather than stated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives a clear trigger point (pre-release, before the file reaches the bank or PSP) and states the limits of the service ('SwapEazi never sends, holds or routes the money: the company releases the file itself'), which implicitly routes release actions elsewhere. It stops short of naming the alternative tool for actually sending or approving a run.

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 no annotations, the description carries the full behavioral burden and does well: it states the tool is read-only, free, and requires no key, and it discloses that drafts are never answered as law and that output is not legal advice. It does not cover rate limits, pagination, or error behavior, so it stops short of full transparency.

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 core question and remains reasonably tight despite a dense, run-on first sentence. The caveats and route_intent note earn their place, though some phrasing could be cleaner.

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 read-only lookup tool with no output schema, the description explains what each rule answer contains: applies, depends, or does not apply, plus dated steps, official document, and read date. It also covers legal caveats, though it does not describe output structure or behavior when no rules are found.

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 the parameters and enum. The description reinforces the corridor and route concepts but adds no syntax or conditional 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 resource and scope: which payout rules reach a payout for a corridor and route, and whether each rule applies, depends, or does not apply. It also distinguishes the tool from route_intent by noting that route_intent carries applicable rules in its own rules field.

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 usage is implied by the corridor-and-route framing and the reference to route_intent, but there is no explicit 'use this when' or 'do not use this when' guidance. An agent can infer the purpose, but alternatives and exclusions are not clearly stated.

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

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

With no annotations supplied, the description carries the full burden and does so: it discloses that the output is unsigned, that SwapEazi never signs, holds keys or moves funds, that every payment is human-approved via /approvals, that recipient screening and spend-profile checks precede preparation, that failures come back as an explanation, and that private mode settles in full or refunds to the wallet. That is exactly the mutation/safety context an agent needs and cannot infer from structured fields.

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 purpose is front-loaded in the first clause, but the prose then collapses into two very long semicolon-chained sentences that mix workflow, custody disclaimers, parameter sourcing and Tron edge cases into an undifferentiated block. Nearly every fact earns its place, yet the packaging makes it 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 13-parameter, no-output-schema, no-annotation preparation tool, the description covers purpose, screening, approval handoff, failure mode, private mode and key parameter sourcing. Remaining gaps are the inline `rules` object semantics and `destination_currency`, plus what the returned payload contains beyond the approval_id.

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 77%, so the schema already handles much of the surface. The description still adds real meaning beyond it: how map_id and candidate_id pair up and where they come from, what private mode actually does and which tool tracks it (private_payment_status), and the Tron/EVM constraint on private. It is silent on the inline `rules` object and `destination_currency`, leaving a small gap.

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 ('Prepare an unsigned USDC or USDT transaction'), enumerates the supported chains and the Tron/TRC-20 special case, and distinguishes itself from neighbours by naming payment_controls as the post-approval retrieval step and discover_payment/map_options as the source of map_id and candidate_id. An agent can tell this apart from prepare_payment_instruction or submit_payment without opening a 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 concrete workflow conditions: within the rules it returns an approval_id and the transaction comes later from payment_controls; outside the rules it explains why; map_id and candidate_id must come from discover_payment or map_options; private: true is required between Tron and an EVM chain; profile_id needs the organisation's key. It stops short of explicitly excluding near-siblings like prepare_payment_instruction or submit_payment, but the routing context is otherwise clear.

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 no annotations, the description must carry the whole burden. It does disclose two valuable behavioral facts: the tool is non-terminal (never approves or sends) and it returns each payment's lifecycle state per item. It says nothing about authentication requirements (access_key is unexplained), whether preparing creates persistent records, idempotency, or error behavior for invalid payees — significant gaps for a multi-stage preparation operation.

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 compact single paragraph that proceeds from identity to operations to constraints to arguments without filler. The version/alias preamble is mildly self-referential but does convey useful provenance. Nothing is redundant enough to flag.

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 five-parameter tool with no annotations, no output schema, and zero schema coverage, the description is thin: it does not explain inputs, auth, side effects, or result shape beyond 'lifecycle state'. The one genuinely complete claim is the non-approval/non-send boundary. An agent could not construct a correct payables payload from this definition alone.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% across five parameters, so the description must compensate and largely does not. Only 'sample: true for the synthetic run' is explained; file, payables, access_key, and source_currency are left entirely to inference. 'Same arguments as run_payments' is an indirect pointer to a sibling rather than an explanation of what these arguments mean.

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 gives a specific verb and resource and enumerates the actual work performed: payee validation, route assessment, instruction construction, and approval digest. It also clarifies the aliasing relationship to run_payments, so an agent can locate the canonical operation. It stops short of 5 because the 'Spec v1.0 name for run_payments' framing front-loads naming trivia rather than the distinction from siblings like prepare_payment.

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?

'Never approves or sends' usefully excludes the approval/send siblings (approve_payment_run, submit_payment, confirm_payment), which is real routing guidance. However, there is no explicit statement of when to choose this over prepare_payment or run_payments, and no prerequisites are given despite the presence of an access_key parameter. Usage is implied rather than stated.

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

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

With no annotations at all, the description carries the full burden and does well: "Never executes" declares it a read-only, non-mutating operation, it states no partner key is required, and it discloses that missing figures come back as null with a reason rather than erroring. It also reveals a visibility difference by credential tier (free callers see Route A/Route B, router keys see source names), though it says nothing about rate limits or quotas.

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 lead sentence front-loads what the tool returns and the key constraint, and the following sentences each add distinct information (receipt fields, freshness, null semantics, tiering, no execution). The receipt field enumeration is dense but load-bearing given there is no output schema; minor cost is a long unbroken paragraph.

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?

There is no output schema, so the description must describe the return shape itself, and it does: it names the receipt schema, lists every field, and enumerates the status values (proven, priced_only, no_live_route). Combined with null-with-reason semantics, freshness guidance, and the never-executes guarantee, an agent has everything needed to call and interpret this 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%, so baseline is 3, but the description adds real meaning beyond the schema: it explains that access_key changes what publishers are named in the response, and that amount is the "payment size" at which figures are quoted. The from/to vs corridor relationship is left to the schema, which already documents it as an either/or.

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?

"Read public prices for a corridor at a payment size" gives a specific verb and resource and enumerates the sources covered (on-chain pools, public order books, public adverts) plus the no-partner-key constraint. It does not name or contrast any sibling such as get_corridor_rates or swapeazi_route_compare, so an agent must infer the boundary from the "public / no partner key" qualifier alone.

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 by the framing (public, no key, quoted at a payment size) and there is useful refresh guidance in "max_age_seconds says when to read again," plus an access-tier note about free vs router key callers. However, there is no explicit when-to-use/when-not or named alternative among the many rate siblings, so the selection decision is left to inference.

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

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

No annotations are supplied, so the description carries the full burden and does real work: it declares 'Read-only, free, no key,' enumerates the exact status vocabulary, and states that a reason is returned when the status cannot be read. It does not cover what happens with an unknown or non-private deposit_address (error vs. status value), which keeps it short of 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 sentences, densely packed, with the precondition and the read-only/free/no-key facts front-loaded. Every clause earns its place; the only cost is the slightly tangled opening clause that muddles subject and action.

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 must explain returns, and it does: the full status enum plus the failure mode of returning a reason. Combined with the read-only/no-key disclosure and parameter provenance, an agent has everything needed to call this single-parameter read tool 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?

Schema coverage is 0% and the sole property is an unqualified string, so the description must supply meaning — and it does, explaining that deposit_address originates from the quote_proof of a private payment. That provenance is exactly what an agent needs to source a valid value, though nothing is said about format or address validation.

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: returns the NEAR Intents status for a payment prepared with private: true, and names the resource being read (deposit_address from its quote_proof). It distinguishes itself from generic status siblings (intent_status, payment_run_status) by tying the lookup to the private-payment deposit address, though the first sentence's phrasing ('give the deposit_address from its quote_proof') momentarily reads as an instruction for obtaining the input rather than what the tool does.

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 qualifier 'For a payment prepared with private: true' gives a clear precondition that implies when to use it. However, no alternative is named — an agent can't tell from the description whether intent_status or payment_run_status should be used for non-private payments or before a deposit address exists, so routing must be inferred.

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

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

With no annotations, the description carries the full load and does so well: it states the default is that the business releases the payment in its own portal and SwapEazi never sends it, that sending is sandbox-only and production-gated by YELLOWCARD_ENV, that the rail's own idempotency key is used, and that SwapEazi holds no funds. It also discloses the exact refusal conditions (no recorded approval, payment changed, above cap, wrong account) and the adapter-is-stub behavior when no live connection exists.

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?

Nearly every clause carries real information, but it is delivered as one dense semicolon-chained block that is hard to parse and hard to scan for the relevant mode. The leading fragment 'Keyed.' costs a slot without orienting the reader.

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 10-parameter, multi-mode tool with no output schema and no annotations, the description covers modes, rollback/refusal semantics, and environment gating well, but omits what the status-read mode actually returns and what several parameters (reason, channel_id, network_id, access_key, account_type) are for.

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 only 10%, so the description must compensate, and it does explain the roles of intent_id, run_id, payment_id, and connection_id and their combinations. But reason, access_key, channel_id, network_id, and account_type are left entirely undefined in both schema and description, leaving half the surface unexplained.

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 concrete resources and verbs: it returns the approved instruction plus a Rate Receipt with intent_id, submits a single Payment Run payment with run_id/payment_id/connection_id, and reads rail status with run_id/payment_id alone. The multi-mode branching is distinguishable from siblings like submit_payment or release_status, though 'Keyed.' as an opener is opaque.

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 mode is gated on an explicit parameter combination and precondition ('after a person has approved', 'Sandbox only', 'with run_id and payment_id only'). It does not, however, tell the agent when to prefer this tool over near-neighbors such as verify_release_record, release_status, or record_release.

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?

No annotations are supplied, so the description carries the full burden. It does add genuine behavioral value by enumerating the three possible position outcomes and disclosing how missing data is represented ("Being measured"), which is information the schema cannot convey. It says nothing, though, about the access_key requirement, permissions, whether this is a read-only lookup, or latency/caching behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The definition is short, but its brevity comes partly from under-specification rather than economy. The leading fragment "Keyed." is opaque and the final sentence, "A missing figure is Being measured.", is awkwardly capitalized and grammatically odd, so the reader must work to parse it. The core purpose is not front-loaded.

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 annotations, no output schema, and 0% schema coverage on three parameters, the description is the only source of context and it is thin. It partially compensates by describing the return states and the missing-data marker, but it omits authentication, endpoint semantics, and any routing guidance among a large set of near-duplicate rate and cost 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?

Schema description coverage is 0% across three parameters, so the description must compensate and largely fails. "For one corridor" weakly implies that from and to are corridor endpoints, but neither is named or explained, and the access_key parameter is never mentioned at all, leaving the agent to guess that it is a credential. Two of three parameters carry no meaning from either source.

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 does convey the resource and comparison: for one corridor it puts the rail's own published rate beside the official rate and an optional market read, yielding a position of lower_landed_cost, higher_landed_cost or unknown. However, it opens with the cryptic fragment "Keyed." instead of a verb, and it never distinguishes itself from closely related siblings such as get_corridor_rates, price_routes, or swapeazi_landed_cost, so an agent cannot tell from the text alone which of these to pick.

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 and no stated alternatives or exclusions. The phrase "For one corridor" implies the scope of a single lookup, but nothing tells the agent when this is preferable to the many other rate and cost tools in the sibling list. The only usage-adjacent signal is the informal convention that a missing figure shows as "Being measured."

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 no annotations, the description carries the full burden and does substantial work: it discloses units (drift in bps and in the sent currency), the meaning of the above_negotiated flag relative to a stored tolerance, null handling for missing figures, and that payment identity stays with the customer's own bank. What it does not cover is ordering, pagination, or result volume for a presumably unbounded history query.

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 content is dense and largely front-loaded with the resource and payload described before the caveats, and most sentences carry distinct information. The one-word opener 'Keyed.' is opaque, and the closing 'A router key is required' largely restates what the access_key schema field already describes.

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 no output schema and no annotations, the description does unusually well at explaining the return shape — field meanings, units, the derived above_negotiated flag, and null semantics. The remaining gaps are the date-range semantics and result ordering/limits, and the dangling corridor reference that the schema cannot satisfy.

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 25%, so the description must compensate; it scopes customer_id to a single customer and implies from/to bound the dated window, which is some added meaning. However, it never states the date format or inclusivity, and it repeatedly references a 'corridor' dimension that has no corresponding parameter in the schema, which muddies rather than clarifies the parameter set.

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 — the dated history of rate-vs-deal comparisons for one customer and corridor — and enumerates what each record contains (official rate, negotiated deal with margin in bps or fixed spread, public market price). That is enough to distinguish it from point-in-time siblings like get_corridor_rates or get_rate_receipt, though it never names those siblings explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the scope 'for one customer and corridor' and by the focus on prepared or reconciled payments, so an agent can infer this is a retrospective audit/summary call rather than a live quoting call. There is no explicit when-to-use, when-not-to-use, or named alternative, leaving the routing decision to inference.

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

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

With no annotations supplied, the description carries the full burden and does substantial work: it discloses the eligibility gates applied, the scoring dimensions, what the response contains on both success and failure paths, the data-quality labelling scheme (LIVE / INDICATIVE / HISTORICAL / ESTIMATED), the warning that estimated savings are never realised, and the quota model ('Free: shares the route-assessment allowance'). It does not say whether a POST analysis is persisted or what happens on repeated calls, which keeps it out of 5 territory.

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 opening sentence is a single unbroken chain of clauses and parentheticals, and the mid-text aside about POST /api/v1/payment-analyses and a shared service for all payment-intelligence tools is more confusing than useful. The caveats and labelling rules do earn their place, but the dense packing hurts scannability.

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 15-parameter tool with no annotations and no output schema, the description covers the gap well: decision process, eligibility criteria, output shape on both success and no-recommendation paths, quoting caveat, data-freshness vocabulary and quota behaviour. What is left implicit is that zero parameters are required and which input mode is expected, which an agent must derive from the schema alone.

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 87% with 15 parameters, so the schema already documents most fields including the nested existing_provider object. The description reinforces a few semantics — the five scoring dimensions map to the weights object, and due-date settlement is an eligibility gate — but it adds no usage rules for the mutually exclusive input modes (invoice_text vs. amount/currency vs. beneficiary_amount) or for analysis_id replay. Baseline 3 given the high schema coverage.

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 operation on a specific resource: it runs hard eligibility gates, then weighted scoring, then returns a recommendation with rationale, alternatives, data used, missing information and freshness. That is far more concrete than the title. It stops short of naming which sibling it replaces (assess_route, price_routes, compare_payment_providers), and the line 'the same service for every payment-intelligence tool' actively blurs the boundary between them.

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 through the eligibility preconditions (complete cost, not stale, settles by due date, licence active, route health) and the caveat that this is not a firm quote to be confirmed with the provider. There is no explicit when-to-use/when-not-to-use statement and no routing against the many sibling analysis tools, so the agent must infer the choice.

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 no annotations, the description carries the full burden and does disclose a non-obvious side effect: outcomes are retained only by pair and size band and later maps at that size inherit them, so bands tighten. It also discloses no cost ('Free') and the signed return value. It omits idempotency (can an outcome be re-posted or corrected?), permissions, and what happens on a failure-flagged outcome.

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 short sentences, front-loaded with the trigger ('After the money moved') and the retention behavior, with no wasted framing. Density is high and some phrasing requires domain fluency, 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 mutation tool with no annotations, no output schema, and 40% schema coverage, the description covers the trigger, the retention side effect, and the return shape. It still leaves an agent uncertain about re-submission/correction semantics and authorization, which matters for a write that permanently adjusts future routing bands.

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 40%, so the description needs to compensate somewhat. It clarifies that realised may be expressed as sent versus landed or as an all-in cost, which maps onto the nested realised fields, and ties the post to the map it was chosen from. It adds nothing about source (an enum of four ingestion channels) or about failure and settled_at inside the nested object, leaving materially undocumented 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 states a concrete action: post what was sent and what landed (or the all-in cost) against the map the payment was chosen from, and return the expected band beside the realised cost. The verb and resource are specific, but the vocabulary ('map', 'band', 'signed') is domain shorthand and the tool is not contrasted with near-siblings like reconcile_payment or record_landed, so an agent must infer the boundary.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

'After the money moved' establishes the trigger condition clearly, and 'Economics only. Free.' bounds scope, but there is no explicit statement about when to use this instead of record_landed, reconcile_payment, or swapeazi_guardrail_reconcile. Usage is implied rather than routed.

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 no annotations supplied, the description carries the full burden and does substantial work: it discloses idempotency (the same proof reference is rejected the second time), a validation-only mode that writes nothing, a 'no_evidence' flag when a payment has no assessment, an auth requirement (router key except for pr_sample), and the reassurance that it never sends money. Gaps remain around what a successful write returns and whether a recorded reconciliation can be corrected or overwritten.

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 the operational constraints. Dense but every clause carries a distinct rule or caveat, and there is no filler. The long recorded-fields enumeration in the opening sentence is the only part that could be trimmed or moved.

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 write tool with no annotations and no output schema, the definition covers the important unknowns: side-effect safety, idempotency, validation mode, auth requirement and one failure mode. It is nearly complete; what is missing is the success response shape and any precondition that the run must actually be in a released state before reconciliation is attempted.

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 already 100%, so the baseline is 3. The description adds some meaning the schema does not, notably the duplicate proof_ref rule and the dry_run write-nothing contract, but it also lists recording fields (official rate with a Rate Receipt, realised all-in cost in percent and sent currency, position vs the assessment range) that do not appear among the schema's payment item properties, leaving an agent unsure whether those are inputs or derived outputs.

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: record what actually landed for released payments in a run, and then enumerates the recorded dimensions (amount sent, amount landed, settlement time, proof reference, realised cost, range position). That is far more than a restatement of the name. It stops short of a 5 because it never names its closest siblings (record_landed, reconcile_outcome) to explain why a run-level reconcile differs from those.

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: it applies to 'released payments in a run', and dry_run: true is offered for validate-only. There is no explicit when-to-use versus when-not, and no guidance on choosing this over record_landed, reconcile_outcome or run_payments, even though those siblings plausibly overlap. The pr_sample auth exception is the one concrete conditional given.

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 no annotations, the description carries the full burden and delivers real behavioral context: the result is measured against an independent reference and against the routed amount, every later route on the pair inherits it as a measured payment, and on a recurring intent it closes only the current cycle while the series advances to its next due date. It also imposes a data-constraint rule (amounts only, never names or account numbers). It stops short of coverage on permissions, failure/mismatch behavior, or idempotency.

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 and its trigger are front-loaded in the first clause, and the later sentences each add new information (measurement, route propagation, recurring behavior, data constraints) rather than restating the title. It is dense and long-sentenced, but no sentence 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 7-parameter mutation with no annotations and no output schema, the description covers purpose, side effects, and recurring semantics well, but omits what the call returns and how errors or measurement mismatches are surfaced. The provider and settled_at semantics are left entirely to the schema, which only partly documents them.

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 57%, and the description meaningfully compensates for the two bare numeric params by defining sent as what left (source currency) and landed as what arrived (destination currency), plus the chain/hash pairing for the stablecoin leg. It adds nothing for intent_id, provider, or settled_at beyond what the schema already says, leaving the uncovered remainder partly undocumented.

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: close a remembered intent once funds have arrived, recording what left, what arrived, and optionally a stablecoin leg by chain and tx hash. It is unambiguous about the operation, but it never names or distinguishes itself from likely-overlapping siblings such as confirm_payment, reconcile_payment, or record_release, 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?

Timing guidance is implied clearly enough ('once the money arrived'), and the recurring-intent branch tells the agent which case it is in. However, there are no explicit exclusions or named alternatives for the adjacent settlement/confirmation tools, and no preconditions (e.g. intent must exist or be in a pending state) are stated.

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

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

With no annotations, the description carries the full burden and does so well: it discloses the side effect (append to the organisation's hash chain, signed), the return artefact (Release Evidence Record), non-blocking semantics, an edge case (a release with no map is still recorded, flagged as a policy miss), and an auth prerequisite (the organisation's key). The notable omission is idempotency — whether re-recording the same payment_ref duplicates or upserts an evidence record.

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 trigger and the payload, then behavioural guarantees, then the edge case and auth requirement — a sensible ordering with no filler. Some sentences are long and compound, but each adds distinct 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 an 11-parameter mutation tool with no annotations and no output schema, the description covers the return value, side effects, a failure-adjacent edge case and the key requirement. Remaining gaps are idempotency/retry behaviour and the semantics of the amount and intent_hash fields.

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 only 36%, and the description compensates for the opaque fields by explaining what map_id, measure_id, exception (reason + approver) and agent_approval mean in policy terms, including the agent_autonomy tier and approver_role linkage. It leaves amount, intent_hash, uetr and released_at unexplained, so the compensation is incomplete.

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 ('record it against the organisation's release policy') and enumerates what the record captures (map_id, measure_id, releaser, exceptions). The clause 'It records; it never blocks, executes or moves money' separates it from execution-oriented siblings like run_payments or submit_payment. It does not name the closest siblings (verify_release_record, release_status), so differentiation is partial.

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?

Timing is stated precisely ('At the moment a material payment is released') and the 'material' qualifier implies scope, but there is no explicit when-not-to-use or pointer to verify_release_record / release_status for reading records back. Usage is implied by context rather than routed against alternatives.

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 no annotations present, the description carries the full burden and does real work: it declares 'Read-only' and 'Needs the organisation's key', covering the safety and auth profile an agent would otherwise lack. It also enumerates the possible reconcile states (pending, done, overdue, not required) and the chain-check outcome (ok or first breaking record), though it says nothing about error behavior or volume of records returned.

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 front-loaded sentences with no filler: the primary lookup mode comes first, the no-id fallback second, and the operational constraints (read-only, key required) are compressed to the end. 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?

With no output schema and no annotations, the description steps in to describe return values for both modes and the auth prerequisite, which is most of what an agent needs before calling. Remaining gaps are minor — no guidance on interpreting an 'overdue' status or on what happens when a supplied rer_id does not exist.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the bare 'string' type for rer_id gives an agent nothing. The description partly compensates by tying rer_id to record lookup and by defining the meaning of its absence (organisation-wide verification), but it never says what a rer_id looks like or where one is obtained.

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 ('Read a Release Evidence Record by rer_id') and spells out the dual mode: lookup by id versus a whole-organisation chain verification when rer_id is absent. It is clear what the tool does, though it never names the adjacent siblings (verify_release_record, record_release, reconcile_outcome) that an agent must choose between.

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 conditional 'With no rer_id, verifies the organisation's chain of records' gives a concrete selection rule between the tool's two behaviors. It stops short of stating when an agent should prefer verify_release_record or record_release instead, so there is no exclusion guidance against alternatives.

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 no annotations, the description carries the full behavioral burden. It usefully discloses what is destroyed (the account and its stored credentials) and what survives (previously sent payments stay readable in the business's own rail account), which is real value. However, it omits authorization requirements implied by "Keyed," irreversibility, and whether pending or scheduled payments, mandates, or routes tied to the account are affected.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, front-loaded with the destructive action and then the data-preservation guarantee, with no wasted wording. The one-word "Keyed." opener is efficient but too terse to be informative.

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?

This is a destructive mutation with no annotations, no output schema, and zero parameter documentation, so the description is the only place this information could live. It covers the core effect and one side effect but leaves authentication semantics, error behavior on unknown ids, and downstream impact on pending payments unexplained.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must explain both parameters, but it never mentions connection_id and only vaguely alludes to access_key via the word "Keyed." The agent learns nothing about identifier format, where to obtain the connection id, or what the access key is for.

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: deletes a connected rail account together with its stored credentials. That clearly separates it from siblings like connect_rail_account and list_rail_accounts. The leading fragment "Keyed." is cryptic, but the core purpose statement 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?

There is no explicit when-to-use guidance, no prerequisites, and no mention of alternatives or consequences to check first (e.g., active payments, mandates, or routes tied to the account). The only contextual hint is that already-sent payments remain readable, which is a consequence statement rather than usage 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?

With no annotations, the description carries the burden and does so well: it discloses that calls answer RETIRED and that no contact details are collected, so the agent knows there are no side effects and no data returned. It does not say whether the response is an error or a normal payload, which is the only remaining ambiguity.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, front-loaded with the retirement date and status, then the replacement path. No filler and nothing that could be mistaken for an instruction to call it.

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 retired, zero-parameter, no-output tool, the description supplies everything needed: status, reason, expected response, and the correct alternative flow. Nothing an agent needs in order to act 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?

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to clarify. The empty schema matches the retirement status.

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 (introductions) and states unambiguously that the tool is retired as of 19 Oct 2026 because SwapEazi collects no contact details. The original verb is only implied, but an agent immediately knows this tool does nothing useful and returns RETIRED.

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 explicitly states the tool must not be used and names the correct next step: after route_intent, go to the chosen route's handoff_url, the provider's own sign-in or account page. That is a direct when-not/alternative pairing referencing a real 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?

With no annotations supplied, the description carries the full burden; it does clarify the key behavioral trait that this never mutates and never approves, which is valuable. However it says nothing about authorization requirements for viewing approval queues, whether the approver role implies restricted access, or limits/size of the returned list.

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 scope and returned contents are front-loaded in a single information-dense sentence, and the exclusion clause follows. The sentence is long and list-heavy but every element conveys a distinct returned field, so little 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?

There is no output schema, so the description correctly takes on the job of describing return values field by field (amount, route, assessment, approval_digest, approver role, lifecycle state, reason). For a two-parameter read tool this is close to sufficient, with only access/permission context and any list-size behavior left 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%, with run_id documented as a payment run (pr_...) or pr_sample, so the baseline is 3. The description adds no further meaning for run_id or for access_key, which is never mentioned in the prose.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description enumerates concretely what the tool surfaces for a payment run: payments awaiting approval with amount, route, assessment and approval_digest, the approver role, plus not-ready payments with lifecycle state and reason. That makes the read/list nature unmistakable despite the name 'request_payment_approval' suggesting a write, and it names approve_payment_run as the contrasting sibling.

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 scopes usage to 'for a payment run' and explicitly excludes the approval action ('Never approves: a named person approves with approve_payment_run'), which routes the agent correctly. It does not distinguish itself from adjacent read siblings such as approval_status or payment_run_status, leaving some ambiguity about which status tool to pick.

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 no annotations at all, the description carries the full behavioral burden and largely meets it: it discloses side effects (remember: true persists the intent, reprices daily until due, returns intent_id), the read/quote semantics ("SwapEazi executes nothing and takes no fee from any provider"), auth behavior (free verification masks names; a Bearer rk_... router key unmasks), result ordering logic (payer policy, strongest evidence: landed payments then published prices, estimates only if policy allows), and the default compact output. That is well beyond what the schema communicates.

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 lead sentence is well front-loaded, but the body is a wall of long run-on sentences chaining clauses with commas and semicolons, and the treasury-parking sub-mode is buried mid-paragraph with no structural signal. Every sentence carries information, yet the density makes it easy to miss the mode switch and the remember/repeat semantics on a first read.

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 16-parameter tool with a nested policy object, no annotations and no output schema, the description does substantial work on the payment path and the return contents (routes, policy-selected route, saving, where to pay, time-split options, intent_id). However, the recurrence family (`repeat`, `repeat_count`, `repeat_until`, `nudge_lead_days`) is entirely absent from the description and lives only in schema strings, and the stray verification sentence adds ambiguity rather than completeness.

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?

At 81% schema coverage the baseline is a 3, and the description earns the upgrade: it gives a worked example of the `text` sentence format, explains that parsed fields are reported in intent.understood and overridden by explicit `policy` fields, describes what `due_date` unlocks (pay now / forward / convert-and-park / hold unhedged), and states that `have` shows what existing accounts can do versus what a new account adds. `lock_at` is left to the schema, but overall it adds real meaning beyond the parameter list.

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 ("Route one cross-border payment") and defines two operating modes: a single payment given as fields or a sentence, and treasury parking for idle money. It is clear what the tool does, but it never distinguishes itself from the many closely overlapping siblings (recommend_payment_route, price_routes, assess_route, compare_payment_providers, compile_intent, decide_intent), so an agent cannot tell from this text alone which of these to call.

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 explains internal input modes ("given as fields or as one sentence", "explicit policy fields override it") and mentions that a sentence about idle money triggers treasury parking, which is useful routing guidance. But there is no when-to-use / when-not guidance relative to alternatives, and in a sibling set this crowded that omission is significant. The stub "The free verification returns the verdict with names masked" also reads like guidance belonging to a different tool (swapeazi_verify_record) rather than this one.

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 no annotations at all, the description carries the full burden and does substantial work: it discloses the verification checks (changed bank details, duplicates, missing fields), the assessment contents (route assessment_id with Rate Receipts and evidence provenance), the three possible per-payment outcomes (prepared, needs_attention, no_evidence), and the key requirement. It stops short of covering idempotency, re-run behavior, or size/time limits on a batch.

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 intent is front-loaded, but the middle is a chain of dense parenthetical asides that are hard to parse in one pass. The 'assess, assess, prepare' duplication in the title and the unexplained 'xero' branch add noise without adding callable capability.

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 an 11-parameter, nested-object batch tool with no output schema, the description covers the important ground: outcome states, the returned run_id, the human-approval gate, and key/sample modes. Remaining gaps are secondary — how the returned run_id is consumed and what a needs_attention result expects from the caller next.

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 explains every parameter, including previous ('Not kept'), sort, and the include/exclude type semantics; baseline 3 applies. The description adds almost nothing beyond restating the three input sources, and it actually names a 'xero' source that has no corresponding parameter in the schema, which could mislead an agent.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.