xrpl-referee

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: it is an aggregator of eight external checks, it emits a top-level 'proceed' bool plus a 'do_not_proceed_if' blocker list, and it gates the downstream fund-locking decision. It stops short of disclosing latency, cost, or auth requirements for the underlying checks.

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 purpose, then the aggregation scope, then the return contract and the gating rule. Four tight sentences with no filler; the enumeration of aggregated signals is long but each item is a distinct capability that justifies the tool's existence over its siblings.

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

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

An output schema exists and the description still correctly summarizes the key return fields ('proceed' bool and 'do_not_proceed_if' list) plus the decision rule. Combined with annotations covering safety and a fully documented schema, nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100% and all four parameters (job_type, amount_xrp, worker_address, nft_issuer_query) are already well documented in the schema, including how each feeds the assessment. The description adds no parameter-level syntax or format detail, so the baseline of 3 is correct when the schema carries the load.

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 ('single pre-flight check before locking funds in escrow') and enumerates exactly what it aggregates: trust score, sanctions, KYC, NFT issuer registry, domain status, release conditions, escrow cap, go/no-go rules. This clearly distinguishes it from sibling point-checks like check_wallet_kyc, check_wallet_sanctions, and get_wallet_trust_score.

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

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

Gives explicit ordering guidance ('Run this before create_escrow_vault or hire_and_pay') and an explicit conditional action ('If proceed is False, do not lock funds'). The agent knows both when to call it and what to do with the result, with no inference 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?

Goes well beyond the annotations (readOnly=false, idempotent=false, openWorld=true, destructive=false) by disclosing the fee-gating prerequisite, the anti-replay single-use nature of fee_hash (consistent with non-idempotent), and the semantic contract of the verdict/status/criteria_failed fields. This is exactly the behavioral context an agent needs before invoking a paid, non-idempotent 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?

Front-loads purpose and prerequisite before the response block, and the PASS/FAIL handling is actionable. The embedded JSON response shape is largely redundant with the existing output schema, which is the one inefficiency; the rest of the text earns its place.

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

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

For a paid, AI-driven, non-idempotent verification tool with a rich output schema, the description supplies everything an agent needs: prerequisite call, anti-replay constraint, and how to interpret PASS vs FAIL. Return values are already covered by the output schema, so no further explanation is required.

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 task, work, fee_hash, task_category, and require_consensus are all already documented in the schema. The description adds no further parameter meaning (it never mentions task_category rubrics or the require_consensus option), so the baseline 3 applies.

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

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

States a specific verb+resource: 'Verify whether completed work meets a task specification using AI.' An agent can tell this is an evaluation/verification tool, distinct from job-listing or payment tools. However, it does not differentiate itself from the closely related sibling evaluate_escrow_work, which appears to serve a similar verification role.

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 prerequisite ('Call get_fees() first to get the current fee amount and accepted assets') and conditions the workflow on outcomes ('On PASS: proceed to payment...', 'On FAIL: read criteria_failed...'). It stops short of naming when to use this tool versus alternatives such as evaluate_escrow_work, so it lacks true alternative 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real value beyond that by disclosing the $0.10 fee (XRP or RLUSD) and the parallel, ranked-descending output behavior. It does not explain why the operation is non-idempotent despite being read-only, which is the one notable behavioral gap.

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

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

Front-loaded with the core capability, batch limit and fee, then organized into scannable use-case bullets. The explicit 'Returns:' block is somewhat redundant since an output schema exists, which is the main wasted line.

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 annotations, a 100%-covered schema and an output schema present, the description supplies the fee prerequisite and ranking semantics an agent needs to call it correctly. Minor gaps remain: it doesn't say how partial failures or invalid addresses within the batch are handled.

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 both parameters are fully documented in the schema, including the 50-address cap and the fee_hash payment details, so baseline 3 applies. The description's mentions of 'up to 50' and the $0.10 fee simply restate what the schema already says rather than adding new 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?

States a specific verb, resource and scope: 'Score up to 50 XRPL wallets in a single call', which immediately separates it from the single-wallet sibling get_wallet_trust_score. It also names the batch limit, parallel execution, and ranking behavior, so an agent knows exactly what the call produces.

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?

Four concrete use cases (rank candidates, screen bidders, build directories, pre-hire due diligence) give clear context for when this tool applies. However, it never states when NOT to use it, nor explicitly names the single-wallet alternative for one-off lookups.

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

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

The description goes well beyond the annotations by disclosing the consequence of the result ($10,000 escrow cap when verified vs. the default $3,000), the cost of the downstream KYC flow, and the returned fields. One tension is left unexplained: the annotations set readOnlyHint=false, while the text reads like a pure status read, and the description never clarifies whether the check itself writes or caches anything.

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, front-loaded paragraphs with no filler: purpose first, then the consequence, then the fallback action. The final 'Returns:' line is mildly redundant given an output schema exists, but it is brief and harmless.

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-style tool with an output schema, the description covers purpose, outcome thresholds, and next steps, so an agent can call it correctly. It leaves the readOnlyHint=false annotation unexplained and does not position itself against the other wallet-status checks, which are the only real gaps.

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

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

There is a single parameter and schema description coverage is 100%, so the schema already documents wallet_address fully. The description adds no format or constraint detail beyond the schema (the 'r...' address convention lives in 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?

The description states a specific verb and resource: 'Check identity verification status for a wallet operator.' It is clearly distinguishable from the adjacent wallet-checking siblings (check_wallet_sanctions, get_wallet_trust_score) because it names KYC/Didit identity verification explicitly and defines the resulting state (kyc_verified).

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 concrete usage branch: if kyc_verified is false, route the operator to start_wallet_kyc() for the $0.50 verification flow. That is actionable routing, though it does not say when NOT to use this tool versus the other wallet-status siblings (sanctions, trust score), so the alternative-selection guidance is incomplete.

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 burden of behavioral disclosure. It clearly indicates the tool is a read-only informational resource ('Returns the AgentTrust trust model'), which is a meaningful behavioral trait. It also discloses the kind of content returned (guarantees, trust gaps, proof gates vs AI audit). It does not describe output format, but an output schema exists, so that burden is partially shifted.

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

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

The description is two sentences and every word earns its place. It front-loads the core purpose, then adds the usage directive. No fluff, no repetition of the title.

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

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

For a zero-parameter informational tool with an output schema, the description is nearly complete. It explains what the tool returns and when to use it. It could arguably name the sibling alternative (e.g., recommend_release_conditions) for contrast, but the explicit 'read this before designing an escrow flow' guidance is sufficient context for an agent to select and invoke it correctly.

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

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

The tool has zero parameters, so there is no parameter semantics burden. The description adds value by explaining what the returned model contains, which is more useful than a bare 'Returns the trust model' statement. Baseline 4 is appropriate for a zero-parameter tool.

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

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

The description clearly states the tool returns the AgentTrust trust model and enumerates its content: guarantees, remaining trust gaps, and guidance on proof gates vs AI audit. It also includes a direct instruction to read it before designing an escrow flow, which distinguishes it from the many escrow-related sibling 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?

The description explicitly tells the agent when to use this tool: 'Read this before designing an escrow flow.' This is a clear usage directive that helps the agent select it over siblings like prepare_escrow, create_escrow_vault, or recommend_release_conditions. It also implies it is a prerequisite/read-only reference rather than an action tool.

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 delivers: it discloses the HMAC-authenticated Coinbase v2 API usage, free-account compatibility, the credential-missing fallback behavior (returns a setup guide dict instead of throwing), the fact that Coinbase is no longer involved after the call, and the one-time human setup requirement. This is exceptionally transparent about side effects and prerequisites.

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 long but well-structured with section headers, bullet lists, and numbered setup steps. It is front-loaded with the core purpose and each subsequent block earns its place by covering credentials, setup, and failure behavior without unnecessary repetition.

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

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

Given that an output schema exists, the description does not need to document return values. It covers prerequisites, environment variables, credential ownership, setup steps, failure behavior, and post-call state, making it fully sufficient for an agent to decide when and how to invoke the 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 already 100%, but the description adds meaningful semantics beyond the schema: usd_amount's default is explained as covering 1 XRP reserve plus Coinbase fees and price variance, and the credential parameters are framed with ownership warnings. It also documents the required Coinbase API scopes, which is valuable context not present 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 states a specific verb and resource: 'Buy XRP on Coinbase and withdraw it to an XRPL address in one call.' It further distinguishes itself as an 'ONRAMP tool only' and clarifies that escrow creation and settlement happen on XRPL, not Coinbase, so it is unambiguous against the many sibling 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?

The description gives clear context for when to use the tool: a USDC-native or fiat-funded agent bootstrapping an XRPL wallet without manual exchange steps. It also draws a boundary by saying Coinbase is used only to acquire XRP and nothing more, but it does not explicitly name alternative tools or spell out when not to use it beyond that 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that the quote is 'live' and sourced from the XRPL DEX, which is useful context, but it says nothing about quote freshness/staleness or latency, and it repeats return fields already implied by the output schema.

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

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

Front-loads the core purpose, then usage context, then a return summary in three compact sections with no filler. Slightly wasteful in re-listing return fields that the output schema already carries, but overall tight and well-ordered.

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 quote tool with a full output schema and complete parameter coverage, the description is nearly complete: it explains purpose, timing, and rough output. The one meaningful gap is that it never distinguishes itself from the confusingly similar get_rlusd_quote sibling, which an agent must resolve to select 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 100%, so the schema fully documents xrp_amount and worker_address, including the note that worker_address is used to check trustline status. The description adds no parameter-level detail beyond the schema, making the baseline 3 correct 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?

States a specific verb, resource, and mechanism: 'Get a live XRP to RLUSD conversion quote via the XRPL DEX.' This is concrete and actionable. However, it does not differentiate itself from the nearly identical sibling get_rlusd_quote (nor from get_xrp_price), so an agent cannot disambiguate the two quote tools from the text 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?

Gives clear when-to-use context: 'before creating an RLUSD-denominated escrow or before claiming an escrow if you want to understand the current USD value.' That is solid situational guidance. It stops short of naming alternatives (e.g., get_rlusd_quote) or stating when this tool is NOT the right 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds valuable behavioral context beyond the annotations: fees and escrow limits may change, the tool is the single source of truth, and it returns structured categories needed before paid calls. It does not go as far as disclosing rate limits or failure modes, but those are less critical for a zero-parameter read-only 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 description is efficiently structured: a one-sentence summary, a clear usage warning, and a bulleted breakdown of return categories. Every line adds decision-relevant information, and the most important guidance—call before paid endpoints and do not hard-code values—is 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?

For a read-only, zero-parameter tool with a strong output schema and descriptive annotations, the description is fully complete. It covers when to call, why it is authoritative, and what each returned section means, leaving no gap an agent would need to resolve before invoking the tool.

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

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

The tool has zero parameters, and the schema is empty, so there are no parameter semantics to clarify. Per the baseline for zero-parameter tools, a 4 is appropriate because the description instead clarifies the meaning of the returned fields, which is the only semantic ambiguity that matters here.

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: 'Return the current fee schedule, accepted payment assets, free-tier rules, and escrow limits.' It clearly enumerates the tool's full scope and distinguishes it from fee-related siblings like get_xrp_price by covering the broader fee/escrow/payment policy rather than just a price tick.

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

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

The description gives an explicit usage directive: 'Call this before calling any paid endpoint.' It also establishes this tool as the authoritative source and warns against hard-coding fee amounts or escrow caps, which tells an agent when it must consult this tool and how to treat its results.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description's only added behavioral detail is the registry context, which hints that unregistered wallets are a possible outcome, but it never states what happens on a miss, whether auth is needed, or 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?

Front-loaded one-line purpose followed by a use case and a returns list; no filler prose. The 'Returns:' block largely restates the output schema, which is the only wasted line.

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

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

With an output schema present and annotations covering safety, the description needn't enumerate return fields, and it covers purpose, use case and scope adequately. A missing note on the not-found/unregistered case is the only real 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?

Single parameter with 100% schema description coverage, so the schema fully documents the wallet_address format (r...). The description adds no format, validation, or lookup-key nuance beyond the schema, which is the expected baseline at full 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?

States a specific verb (look up) and resource (registered NFT issuer) keyed on an XRPL wallet address, which is a distinct lookup axis from the sibling lookup_nft_issuer. It does not name that sibling or otherwise explicitly contrast itself, 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?

Gives a clear use case — verifying whether an NFT's minting wallet belongs to a known, verified organisation in the AgentTrust registry. It provides no exclusions or alternative-tool routing (e.g. when to use lookup_nft_issuer or verify_wallet_domain instead), so it is context without boundaries.

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 that the seed stays in the agent's environment, that AgentTrust only sees public address and signed transactions, and that create_agent_wallet has the insecure behavior of returning a seed in plaintext. It does not explicitly state 'this tool has no side effects' but 'returns a guide' strongly implies an informational, read-only 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 three-part structure: what it returns, when to use it, and why it's safer than the alternative. Every sentence earns its place even though the second and third paragraphs restate partially overlapping 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 no-parameter informational tool with an output schema, the description provides the key context: purpose, usage, and security trade-off versus the sibling. It could mention what the output guide contains, but that is fairly covered by the output schema and the description's overall scope is sufficient.

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

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

The tool has zero parameters with 100% schema coverage, so the description needs to explain no parameters. Nothing about parameter semantics is missing; a 4 is appropriate for a parameter-less functional tool.

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

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

The description names a specific verb and resource — 'returns the recommended production wallet setup' — and explicitly contrasts itself with create_agent_wallet(), so an agent can distinguish it from siblings without guessing.

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 direct instruction with a condition: 'Call this instead of create_agent_wallet() when building a production agent,' and explains the security rationale that justifies the choice. This is explicit, actionable guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, but the description adds substantial context they cannot carry: rate limits, cost model, the meaning of score bands (below 30 / 30–60 / 60+), and a downstream consequence (KYC-verified wallets can create escrows up to $10,000). This is behavior an agent needs to reason about the result.

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 front-loaded with purpose, then signals, then cost/limits, then score interpretation — a logical order with no wasted sentences. The opening 'Open reputation layer for XRPL agents' is slight positioning flavor rather than operational content, 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?

An output schema exists, so return values need not be explained, and the description still notes that it returns a per-signal breakdown. Combined with cost, rate limits, score bands, and sibling routing, an agent has everything needed to call it and interpret 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?

With a single parameter and 100% schema description coverage, the schema already documents wallet_address fully. The description adds no format or syntax detail for the parameter beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource ('returns a 0–100 trust score for any wallet') and enumerates the 11 signals it aggregates, so the agent knows exactly what it produces. It is clearly distinguishable from narrow siblings like check_wallet_kyc and check_wallet_sanctions, which cover only individual signals.

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

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

Gives explicit routing guidance: 'For scoring multiple wallets at once, use batch_wallet_trust_scores() instead ($0.10 per batch of up to 50).' It also discloses cost ('Free to query') and a rate limit (20 calls/hour/IP), which is the practical condition that would push an agent toward the batch 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?

Goes well beyond the readOnly/idempotent/openWorld annotations: it enumerates all five status values with their trust implications, explains that matching is exact or close only, describes the registered=false + register_url failure mode, and lists the proof fields (verified_at, verified_by, toml_url, accountset_tx_hash) that allow independent confirmation. This is exactly the trust-relevant behavior an agent needs.

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 purpose, then a use case, then caveats, then the status enum, then returns — a sensible ordering with no filler sentences. It is on the long side, but the status-value list and the missing-result warning each carry distinct decision-relevant information.

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

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

For a read-only, open-world lookup, the description covers purpose, trust interpretation of every status, the negative-result case, and the evidence fields. An output schema exists so return values need not be restated, yet the description's summary of returns remains useful without being redundant.

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% for the single query parameter, so the baseline is 3. The description still adds value by clarifying matching semantics (exact-match or close-match only) and by confirming the dual company-name / wallet-address input mode that governs which sibling 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?

States a specific verb (look up) and resource (organisation in the AgentTrust XRPL NFT Issuer Registry) and describes what the registry maps (company names to verified XRPL wallet addresses). It does not explicitly distinguish itself from the sibling get_nft_issuer_by_wallet, which appears to be a near-duplicate lookup, so the agent must infer the split from the query parameter.

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 concrete use case (checking whether an NFT was issued by a legitimate organisation before accepting it as proof of ownership or as an escrow delivery condition) and an explicit anti-pattern (do not treat a missing result as implicit approval). It never names an alternative sibling such as get_nft_issuer_by_wallet or verify_nft_ownership, so routing between near-duplicate lookups 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?

Annotations only cover safety flags (readOnlyHint=false, idempotentHint=false, openWorldHint=true); the description goes well beyond them by disclosing the mandatory $0.05 fee, the accepted currencies (XRP or RLUSD), the exact destination address, and the successful return value (updated attempts_remaining). For a paid, non-idempotent mutation this is exactly the context an agent needs.

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

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

Front-loads the action and the trigger, then the cost and return value — a well-ordered structure. The parenthetical about default 3 attempts and max_submissions pricing is useful background but slightly tangential to invoking 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?

Covers trigger, required payment, destination address, currencies, and post-call workflow, and an output schema exists so return values need not be spelled out. An agent has everything needed to invoke this correctly in the escrow workflow.

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 both parameters are already fully documented in the schema, including the fee_hash format and recipient address. The description largely restates the same payment facts rather than adding syntax or constraints beyond them, so the baseline 3 applies.

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

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

States a specific verb and resource ('Purchase one additional submission attempt') and immediately scopes it to 'a vault that has hit its limit'. This is clearly distinguishable from siblings like evaluate_escrow_work or prepare_escrow without opening any schema.

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

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

Gives an explicit trigger condition — 'When evaluate_escrow_work returns error "submission_limit_reached"' — names the exact alternative tool, and prescribes the follow-up step ('then resubmit with evaluate_escrow_work'). Nothing about when to use this tool 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?

Annotations already declare readOnlyHint=false and destructiveHint=false, but the description goes further: the rating feeds the counterparty's Trust Score (up to 15 pts), is one-per-escrow-per-rater, and is permanent and public. Permanence and public visibility are consequential side effects an agent must know before calling.

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, followed by impact, constraints and timing in short paragraphs. The closing call-to-action partly restates the timing already given, a minor redundancy, but the rationale it adds keeps it useful.

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

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

With an output schema present, return values need not be explained, and 100% schema coverage handles parameters. The description covers timing, effect on trust score, permanence and frequency limits; only permission/auth prerequisites and whether the rating is revocable are left implicit.

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 every parameter including rating, escrow_id and rater_role is already documented in the schema, which sets the baseline at 3. The description only adds the one-rating-per-escrow constraint, which is a modest addition over the schema's own note.

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 (leave a rating), resource (peer rating for a counterparty), value range (1–5 stars) and trigger condition (after a completed escrow). This is clearly distinguishable from siblings like evaluate_escrow_work or audit_task, which judge work rather than record a peer rating.

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

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

Explicit timing is given: call after an escrow completes, whether it passed or failed, and the one-rating-per-escrow-per-rater rule bounds repeated use. No alternative sibling is named as a substitute, so it stops 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds genuinely new behavioral context: the thread is complete ('all messages'), includes both buyer and worker posts, and is ordered chronologically — useful for an agent reasoning about staleness or ordering.

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 action and free of filler. There is minor overlap between 'message thread' and 'all messages posted by buyers and workers,' which costs a point but does not impede scanning.

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

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

For a single-parameter read tool, the definition covers what it does, what it returns (all messages, chronological order), and when to call it, while annotations carry the safety profile and an output schema handles return structure. Nothing needed to invoke it correctly is missing.

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

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

With a single parameter at 100% schema description coverage, the schema fully documents job_id and the description adds no format, source, or constraint detail beyond it. Baseline 3 is appropriate 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?

States a specific verb and resource ('Fetch the message thread for a job') and clarifies the scope as messages 'posted by buyers and workers.' It reads clearly as the read counterpart to send_job_message, though it never names a sibling explicitly the way the top-calibrated examples do.

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 when-to-use: 'catch up on any clarifications or instructions before starting work or submitting a bid,' which ties the call to concrete workflow moments. No when-not-to-use or named alternative (e.g., send_job_message for posting) is provided.

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 provided, so the description carries the full burden. It discloses that the tool returns recommendations rather than executing an action, which implies no side effects, but it never explicitly states that no escrow or transaction is created, and it does not mention permissions or failure 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 description is front-loaded with the core outcome, followed by a compact example list that earns its place. There is no filler or redundant repetition of the title or schema.

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

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

For a single-parameter tool with an output schema, the description covers the input semantics and the high-level contents of the recommendation. It is complete enough to invoke correctly, though it leaves minor gaps around unknown job types and explicit side-effect confirmation.

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%, but the description compensates by defining job_type as 'job or deliverable type' and providing nine concrete examples such as 'software development', 'NFT art', and 'invoice payment'. It does not specify accepted value format or fallback behavior, but it gives an agent solid grounding.

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 uses a specific verb-resource pair: 'returns recommended escrow release conditions' and names exactly what the agent receives (proof gates, AI audit toggle, example parameters). It is clearly distinct from sibling tools that prepare, audit, or evaluate escrow work.

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 establishes clear context for use: when you have a job or deliverable type and need recommended release conditions. The example list helps an agent recognize valid inputs, though it does not explicitly name alternatives or state when not to use this tool.

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

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

Annotations declare non-read-only, non-idempotent, non-destructive, closed-world behavior, so the safety profile is largely covered. The description adds a genuinely useful behavioral fact beyond that: messages are visible to both the buyer and the awarded worker, which affects what an agent should write. It stops short of noting side effects like notifications or the fact that the optional bid_id scoping is unannotated.

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 brief paragraphs, front-loaded with the action and followed by scope and visibility. The closing clause ('without leaving the AgentTrust platform') is slightly promotional padding, but overall it is tight.

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

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

With an output schema present and full parameter coverage, the description only needs to carry purpose and usage, which it does, plus the visibility trait. An agent has enough to invoke it correctly; minor gaps like notification behavior or message-length limits are not decision-critical.

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 five parameters are already documented in the schema; the baseline of 3 applies. The description implies bid_id's tie to pre-escrow negotiation but adds no syntax, format, or constraint detail beyond what the schema 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?

States a specific verb and resource ('Send a message on a job thread') and frames the purpose with concrete scenarios (clarifying requirements, sharing progress, negotiating before escrow). It does not explicitly name the sibling read_job_messages to draw the send/read boundary, but the verb makes the distinction self-evident.

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 clear when-to-use context: pre-escrow negotiation, deliverables, deadlines, scope changes, and staying on-platform. No explicit when-not-to-use or named alternative is given, so it stops short of the 5 bar.

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

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

Annotations only declare non-read-only, open-world, non-idempotent, non-destructive. The description goes well beyond that: it discloses the $0.50 cost, accepted payment assets (XRP, RLUSD, USDC), the required out-of-band browser action via verification_url, automatic notification on completion, the resulting state transition to kyc_verified, and the $10,000 escrow unlock. That is exactly the behavioral context annotations cannot carry.

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

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

Front-loaded with the action and fee, then prerequisites, then return value and effects. Every sentence carries operational weight, though the multi-paragraph form is heavier than strictly necessary for a two-parameter 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?

Despite an output schema existing, the description still names the key return artifact (verification_url) and the downstream consequences. Combined with the prerequisite chain and status-check follow-up, an agent has everything needed to invoke this 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 100%, so baseline is 3. The description adds marginal meaning by tying fee_hash to a concrete $0.50 payment in named assets and by framing wallet_address as the operator being verified, but it does not add syntax or format detail the schema lacks.

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 — 'Start a Didit identity verification session for a wallet operator' — and implicitly distinguishes itself from check_wallet_kyc, which it names as the status-confirmation sibling. An agent can tell exactly what this tool initiates without opening the schema.

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

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

Gives an explicit prerequisite ('Call get_fees() first to get the current fee amount and accepted assets') and an explicit follow-up alternative ('Safe to call check_wallet_kyc() afterwards to confirm status'). When-to-use, prerequisites, and the routing alternative are all present.

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 full responsibility for behavioral disclosure. It states that the tool activates a vault and avoids a confirm call, but it does not disclose side effects, irreversibility, permission requirements, or failure modes. 'Submit' and 'activate' are vague about what happens on success or failure, leaving the agent underinformed for a mutation.

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

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

The description is a single, well-structured sentence that front-loads the primary action and the key advantage (one-step activation). Every word serves a purpose, and there is no redundant phrasing.

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

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

The description, combined with the schema and an existing output schema, covers the basic purpose and parameters. However, it lacks contextual guidance about when this tool is appropriate (e.g., after calling create_escrow_vault), what happens if the blob is invalid, or any prerequisites. Given the tool's mutation nature, this is a meaningful gap.

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

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

Schema description coverage is 100%, and the parameter descriptions already explain what each parameter is. The tool description adds no additional meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states a specific action: submit a locally-signed EscrowCreate transaction blob and activate the vault. It also distinguishes from the sibling confirm_escrow_transaction by noting no separate confirm call is needed, so the tool's unique 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 phrase 'no separate confirm call needed' implies this tool replaces confirm_escrow_transaction, but it does not explicitly state when to use this tool versus alternatives like create_escrow_vault or confirm_escrow_transaction. No exclusions or prerequisites are given beyond the mention of a locally-signed blob.

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

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

Annotations already declare readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description adds genuine context beyond them: the escrow delivery-condition role and the fact that the AgentTrust evaluator invokes it automatically during NFT DvP escrows. It also previews the return 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?

Front-loads the core purpose, then the usage context, then the return values in three tight sentences. No redundancy and nothing 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?

An output schema exists, yet the description still summarizes the return shape (verified, nft_token_id, metadata match, issuer details). Combined with the usage context, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents wallet_address, issuer_wallet, and required_metadata with format examples. The description's 'from a specific issuer, optionally matching metadata' only restates those roles at a high level, adding little beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb and resource: 'Verify that a wallet holds an NFT from a specific issuer, optionally matching metadata.' The NFT-scoped framing implicitly separates it from wallet-level siblings like confirm_wallet_ownership and check_wallet_kyc, but it never names an alternative, so it stops short of full sibling differentiation.

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 concrete when-to-use scenario: 'Use as an escrow delivery condition: before releasing payment, confirm the seller has transferred the correct NFT.' It also notes the evaluator calls it automatically. There is clear context but no explicit when-not-to-use or named alternative.

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

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

The description discloses the key behavioral fact the annotations can't: this reaches out over the open web to fetch a TOML file, and success writes a trust-score contribution (explaining readOnlyHint=false despite the 'verify' name). The idempotent, non-destructive profile is consistent with the stated behavior. It does not mention failure modes or rate limits, keeping 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?

Front-loaded with the core action and mechanism, then a short mechanism/precondition paragraph. Every sentence carries information, though the middle paragraph is slightly padded and the 'Returns' line duplicates the 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?

Given only two well-documented params, an output schema, and annotations, the definition covers what an agent needs: the external-fetch nature, the required TOML location and [ACCOUNTS] key, and the side effect on trust score. A note on failure cases (e.g., what happens if the file is absent or mismatched) 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 description coverage is 100% and both params are documented in-schema, so the baseline is 3. The description reinforces that the domain must host the TOML and that the wallet must appear in it, but adds no format or syntax detail beyond the schema.

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

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

States a specific verb+resource (verify a wallet's domain ownership) and names the exact mechanism (XRPL Foundation xrp-ledger.toml at /.well-known/). This is clearly distinguishable from siblings like confirm_wallet_ownership or verify_nft_ownership, which cover different ownership proofs.

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 precondition for success (the domain must publish an xrp-ledger.toml listing the wallet under [ACCOUNTS]) and the payoff (10 pts toward trust score), which implies when to reach for it. However, it never explicitly says when to use this versus confirm_wallet_ownership or get_wallet_verification_challenge, so alternative selection 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.