Radix Community

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

Goes well beyond the readOnlyHint annotation: it discloses the live-ledger validation of every line, the 40-recipient transaction split, the underlying 256-event engine cap, and the try_deposit_or_refund refund-on-refusal semantics. These are exactly the operational traits that change how an agent should call and trust the 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?

Three tight sentences, purpose front-loaded, and the parenthetical about the 256-event cap earns its place by justifying the 40-recipient split. 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?

With no output schema, the description should say what the tool returns (manifest file(s), console links) and how they are consumed; instead it only explains the internal build process. The input side is complete, but the output/next-step side is left implicit for a fairly complex 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 enum/default semantics of locale, network, and the recipients line formats are already fully documented in the schema. The description adds framing ('CSV list') but no field-level meaning beyond the schema, so the baseline 3 applies.

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

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

Names a concrete resource (bulk transfer manifests) and its sibling family is clearly signaled by the build_* prefix. The opening 'Pays many accounts from a CSV list' slightly blurs the verb, since the tool builds a manifest rather than executing payments, but the intent is unambiguous in context.

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 'Pays many accounts from a CSV list' and the input shape (recipients list), but there is no explicit when-to-use guidance and no mention of alternatives such as plan_holder_distribution or build_manifest_from_template. 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?

readOnlyHint=true is consistent with "decodes ... and returns," and the description adds real behavioral context beyond the annotation: the WASM payload is deliberately excluded because it is "too large for the agent," and the connector reads it from disk. This discloses an out-of-band file dependency the annotation alone would not reveal.

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 tight sentences with the core action front-loaded, then the scope exclusion, then the sequencing instruction. No filler or repetition.

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

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

Given a fully documented schema and a simple readOnly annotation, the definition covers inputs, the boundary (no WASM), and the return (the deploy_package call to run). Minor gap: it does not describe what the decoded value looks like or how the connector call is structured, but nothing essential to invocation is missing.

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

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

Schema coverage is 100%, so the schema already documents rpdHex, owner and network fully, including enums and defaults. The description re-characterizes rpdHex as a compiled .rpd Manifest SBOR but adds no format or syntax detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (decodes) and resource (.rpd package definition / Manifest SBOR) and the output it produces (the value needed to publish a Scrypto package, plus the exact deploy_package call). This clearly distinguishes it from the other build_*_manifest siblings, which the agent can tell apart without opening schemas.

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

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

"Use this before deploy_package" gives explicit sequencing guidance, and the note that WASM is not handled here clarifies scope. It does not name when-not to use it relative to the sibling build_* tools, so it stops short of full 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?

Annotations only declare readOnlyHint=true; the description adds real substance beyond that: the output is a diff-based transaction built from current ledger state, the account itself signs, and refused deposits are held in a locker until claimed. It never explicitly says the result is an unsigned manifest returned to the caller rather than submitted, which is a meaningful gap for a build_* 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?

Three sentences, front-loaded with the core action and the diff-from-current-state property, with no filler. The airdrop/locker sentence is a useful caveat but is 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?

For a 9-parameter build tool with no output schema, the description leaves the agent unclear on what is returned (manifest text? signable payload?) and what the next step is (validate_transaction_manifest, preview_transaction, wallet signing). The conflict/precedence between defaultRule and allow/refuse is also 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 description coverage is 100% and the schema already documents each field, including the deposit-badge string format and the 'follow the default rule again' semantics of removeExceptions. The description restates these concepts at a higher level (default rule, always-allowed/always-refused resources, added/removed badges) without adding syntax or precedence rules, 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: builds a single transaction that changes who may deposit into an account, and enumerates the kinds of changes it expresses. It does not name the distinguishing sibling (get_deposit_rules, build_manifest_from_template), so the boundary is inferred 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?

Usage is implied by 'changes who may deposit into an account' plus the note that deposits can be refused without losing airdrops, which hints at when refusal is appropriate. There is no explicit when-to-use / when-not-to-use guidance, no mention of reading current rules first via get_deposit_rules, and no pointer to 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?

Adds substantial behavior beyond the readOnlyHint annotation: the DEX is read from the ledger, the component must actually run the pool, listing is checked only on mainnet because no DEX has a Stokenet API, and the result is "simulated". It also discloses value-flow details (excess returned to the account, position NFTs minted/burned, fees kept on claim_fees). Missing: whether the output requires a signing step or wallet connector, and any validation/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 purpose is front-loaded in the first sentence and the per-operation breakdown follows logically. It is dense and parenthesis-heavy (three nested parentheticals in one sentence), which costs some readability, but nearly every clause carries a decision-relevant fact 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 9-parameter, 3-operation builder with nested `range`/`amounts` objects and no output schema, the description covers what is produced ("the manifest and what the account would receive, simulated") and the per-DEX preconditions an agent must check. A small gap remains around signing/wallet prerequisites and what happens if validation fails.

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; the description still earns credit by adding cross-parameter semantics the schema cannot express: amounts differ per DEX (both tokens in reserve ratio, one side for DefiPlaza with the other only in shortage), range is in y per x and yields a position NFT, and ids default to every position held. It does not name `locale` or `network` behavior beyond the schema, but those are trivial.

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

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

Opens with a specific verb and resource ("Builds one transaction on a pool a DEX runs") and then enumerates the three operations (add, claim_fees, withdraw_positions) with what each does. It explicitly distinguishes itself from the sibling build_pool_manifest by explaining that a DEX-run native pool refuses that tool's "contribute" and that this tool must be used instead.

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 routing rule against the nearest alternative ("A DEX-run native pool refuses build_pool_manifest 'contribute' ... so use this") plus per-DEX conditions for when each add variant applies (Ociswap Basic/Flex vs DefiPlaza vs Precision). It also tells the agent what to do when the pool is unlisted on mainnet: warn the user plainly before signing.

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

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

readOnlyHint=true is consistent with a tool that only assembles a manifest rather than executing anything, and the description reinforces this by framing it as building a request, not performing the transfer. The Stokenet-only network constraint is genuinely useful context beyond the annotations, though it says nothing about downstream sign/submit steps.

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 tight sentences: what it does, the network constraint, and the funding use case, all front-loaded with zero 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 read-only manifest builder with a fully documented 2-param schema and no output schema, the description covers purpose, network scope, and usage. It could mention what the returned manifest is meant to be used with (e.g., signing/submission), but nothing essential is missing.

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

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

Schema description coverage is 100% and both parameters are documented with formats (account_tdx_2_…, en/es), so the schema carries the load. The description adds only the implicit notion of an account to fund, which the schema already conveys.

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

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

States a specific verb and resource ('Builds the manifest that requests free test XRD from the Stokenet faucet and deposits it into an account'), which is unmistakably distinct from siblings like build_validator_manifest or build_wallet_request. The Stokenet-only scope further sharpens its identity.

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 guidance ('Use it to fund a test account before other transactions') and a hard constraint (Stokenet only — mainnet has no faucet). It doesn't name a specific alternative tool for mainnet users, but the exclusion is well articulated.

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, so the safety profile is covered. The description adds real behavioral context beyond that: the token is created with owner=none and open transfers, and the initial supply is deposited into the supplied account. What it omits is the lifecycle point — that this only produces an unsigned manifest that must subsequently be signed/submitted, which an agent might misread as an executed state change.

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, no filler: the capability and its defaults come first, the deposit destination second, and the sibling routing last. Nothing is repeated from the schema or 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?

There is no output schema, so the description carries the burden of telling the agent what comes back and what to do next (a manifest to be signed/submitted, presumably via build_wallet_request or validate_transaction_manifest). It also never explains how the required 'locale' parameter affects output. With 9 required parameters and no return-value guidance, it is adequate but leaves a 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?

Schema coverage is 100%, so the baseline is 3 and the schema already documents name, symbol, divisibility, network, locale, etc. The description still adds meaning the schema does not: the defaults for ownership and transfer rules, and the fact that accountAddress is the recipient of the initial supply rather than, say, an owner address.

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

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

Specific verb (builds) plus resource (transaction manifest for a new fungible token on Radix) with scope qualifiers (sensible defaults: owner none, transfers open) and the destination of the initial supply. It explicitly names the sibling it is not (build_nft_collection_manifest), so the agent can distinguish it without opening schemas.

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

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

Explicit routing: 'For NFTs use build_nft_collection_manifest; for advanced role setups send the user to the console create-token tool.' That gives both the alternate tool and the condition that selects it, going beyond the implied usage most tool descriptions settle for.

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

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

With readOnlyHint=true already signaling no side effects, the description adds substantial domain context: one transaction per resource per 40 recipients, single signature for create+batch, badge holder gating, only the claimant account can claim, and allowRecover's effect on unclaimed tokens. The notable gap is that it never states the tool returns an unsigned manifest that must then be signed/submitted — the mutation-sounding language ('takes back', 'airdrop') relies on the title to disambiguate.

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 with heavy nested parentheses and quoted sub-conditions, which is hard to parse for a 14-parameter tool. The opening marketing line ('The right way to airdrop on Radix') costs space without adding selection value, and the per-operation content would read far better as a short list.

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 14-parameter, 5-operation builder with no output schema, the description covers operational semantics well but omits what a caller needs next: what the tool returns, whether the manifest must be signed/previewed with preview_transaction, and the 'Badges are resolved from the account' line is left unexplained. Adequate but with real gaps at the front and back of the 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 93%, so parameter-level meaning is already documented; the description's value is cross-parameter conditional logic the schema cannot express (recipients also triggers a first batch during create; claim vs lockers alternates; tryDirectSend only matters with recipients). It stops short of explaining the recipients CSV shape or the two-column/defaultResource line format.

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 concrete resource (AccountLocker manifests) and enumerates the five operations (create, airdrop, recover, recoverAll, claim), so the agent knows exactly what surface the tool covers. It does not explicitly contrast with the closest sibling, build_bulk_send_manifests, leaving the 'airdrop' vs 'plain send' boundary to be inferred from the opening line.

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 rich guidance on which operation applies to which situation (create vs airdrop vs recover vs claim, and tryDirectSend behavior). However, this is operation selection within the tool, not tool selection: nothing says when to use this instead of build_bulk_send_manifests, plan_holder_distribution, or build_manifest_from_template, which is the agent's harder decision.

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 carry readOnlyHint, so the description adds meaningful behavior: it renders, validates, and returns a manifest rather than submitting anything, and signing happens externally in the web console. It still says nothing about validation failure behavior or how missing/extra field values 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?

A single front-loaded sentence covering render, validation, and the handoff to signing, with the template dependency folded in as a parenthetical. No wasted clauses.

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-parameter, fully-documented tool with no output schema, the description covers purpose, prerequisource, validation, and the next step for the returned artifact. Gaps are minor: no statement of failure modes or how template/values mismatches surface.

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% with enums documented for locale and network, so the schema carries the burden. The description only references 'given field values' and the template, adding no syntax or constraint details beyond what the schema already 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 chain: renders a manifest template with given field values, validates it, and returns a signable manifest. That is clearly distinct from the fixed-purpose siblings (build_fungible_token_manifest, build_nft_collection_manifest), though the differentiation is implied by 'template' rather than stated outright.

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 real workflow context: pull template ids and fields from list_manifest_templates, then sign the result in the web console. It does not spell out when to prefer this over the other build_*_manifest tools or what happens when values fail validation, so it stops short of explicit when/when-not 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 only declare readOnlyHint=true, so the description usefully adds that the manifest is built with sensible defaults (owner: none, transfers open) and that NFTs land in the given account. It does not explicitly say the output is an unsigned manifest requiring preview/signing, which would remove the mild ambiguity between 'builds' and 'creates'.

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: the first front-loads what is built and its defaults, the second handles the escape hatch to the console tool. No filler or repetition.

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

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

For a 9-parameter builder with no output schema, the description covers the effect, the defaults and the fallback path, which is enough to invoke it correctly. It stops short of describing the returned manifest or the expected next step (preview/validate/sign).

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 every parameter (name, nfts, mintable, burnable, network, locale, accountAddress, iconUrl, description) is already documented in the schema. The description restates the NFT payload fields and defaults but adds no syntax or format detail 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 (builds) and resource (transaction manifest creating an NFT collection on Radix), plus the scope of what the manifest does (initial NFTs deposited into an account). It is clearly separable from the other build_* manifest siblings and from get_nft_data.

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 routing rule: for custom data fields or advanced role setups, send the user to the console create-token tool. It does not contrast against build_fungible_token_manifest or build_manifest_from_template, but the boundary for this tool's supported subset of cases is 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 only readOnlyHint=true declared, the description carries most of the burden and does so well: it discloses that badges are auto-resolved from the account, that poolProfile and badge fields are minted in the same transaction, that the pool unit cannot be named at creation, that emptyReserves leaves other holders with nothing to redeem, and that freezing is irreversible and must be confirmed with the user. It also states the return contract ("Returns the manifest for the user to sign").

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 real information, but the single dense paragraph packs seven operations into one run-on sentence, making per-operation lookup harder than a short bulleted list would be. Nothing is wasted; the structure could be tighter.

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

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

For a 19-parameter, seven-operation manifest builder with no output schema, the description covers the transaction grouping, badge requirements, irreversibility hazards and the returned artifact — everything an agent needs to pick an operation and avoid a destructive mistake. Remaining gaps (network, locale) are fully documented in the 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 100%, so the baseline is 3; the description earns above that by mapping parameters to operations ("poolProfile and the badge fields are written in the same transaction", "kind" implied for create, managerBadge vs. fresh mint) and by explaining conditional applicability the flat schema cannot express. It does not, however, describe the shape of the amounts map beyond what the schema already says.

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 ("Builds one native pool transaction") and then enumerates all seven operations with their distinct semantics, which lets an agent distinguish this from build_dex_manifest, build_locker_manifest and other manifest builders in the sibling list. The scope (native pool only, one transaction, returns a signable manifest) 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?

Per-operation guidance is unusually strong: each of create/contribute/deposit/withdraw/redeem/profile/manage is tagged with its precondition ("needs the manager badge", "public", "needs the owner badge"). It does not, however, say when to prefer this over the sibling manifest builders or mention what to do if the user has no pool yet, so it stops short of explicit 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?

Adds real context beyond readOnlyHint=true: it discloses that owner badges held by the account are auto-resolved into a single proof, that invalid operation combinations are rejected rather than silently produced, and that the output is a manifest for the user to sign in their wallet. No contradiction with the read-only hint, since the tool composes rather than submits.

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 core action, then behavior, then the return contract. Every sentence adds information 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 output schema, the description correctly states the return value (a signable manifest) and the failure mode (rejected combinations). It leaves some gaps for a builder tool — whether the built manifest still needs validate_transaction_manifest or preview_transaction, and any network-specific caveats — but the essentials are covered.

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 per-parameter semantics are already documented, including the enum values and the note that field names come from list_validator_operations. The description only reinforces that badges are resolved from the signing account; it adds nothing about the 1-20 operation bound or how the operations array interacts with the single proof.

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?

Names a specific verb and resource ('Builds one transaction manifest') plus the input domain ('validator operations'), which cleanly separates it from the other build_* manifest tools (deploy, NFT, pool, DEX). It does not, however, name a competing sibling such as build_manifest_from_template that an agent might otherwise 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?

'One or more validator operations' implies the domain of use and 'Refuses combinations the ledger would garble' signals a precondition, but there is no explicit when-to-use / when-not-to-use guidance and no pointer to list_validator_operations or validate_transaction_manifest (both only implied by the schema).

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

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

With readOnlyHint=true already covering the safety profile, the description adds real behavioral value: it discloses the return payload (interaction JSON, fresh ROLA challenge when something is signed, the validation problems the wallet would reject, and the matching radix-connector call) even though no output schema exists. It omits permission/auth prerequisites and any rate or size limits, so it is strong but not exhaustive.

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, followed by the scope enumeration and then the return/next-step sentence. The opening sentence is long and dense with the auth-mode list, but every clause carries information 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?

For a 9-parameter tool with nested objects, enums, and no output schema, the description covers purpose, request scope, and return contents adequately. Remaining gaps are minor — no explicit mention of error behavior beyond validation problems or of prerequisites relative to setup_wallet_connector.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds cross-parameter meaning beyond the schema — e.g. that a request may ask for no address at all and that certain modes need a persona. This helps an agent reason about valid parameter combinations the flat schema does not spell out.

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 (builds the exact schema-v2 wallet interaction a dApp sends to the Radix Wallet) and enumerates the request categories it covers. It also names the sibling verify_rola_proofs as the follow-up verification step, so an agent can place it in the workflow without opening the schema.

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

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

The enumerated auth modes and the note that a request may ask for NO address give clear context for when each configuration applies, and it points to verify_rola_proofs for the signed answer. It does not explicitly contrast with near siblings like setup_wallet_connector or check_signing_request, so no true exclusions 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?

readOnlyHint=true already declares the safety profile, and the description reinforces it with 'Read-only Gateway query' while adding genuinely useful behavioral detail: it tells the agent what the call returns (required signers, who has signed, completeness). It omits rate limits, caching, or failure behavior for an unknown/incomplete request, 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?

Three short sentences, front-loaded with the core purpose, followed by the id example and the return contents. 'Read-only Gateway query' overlaps with the annotation but is a small redundancy at worst.

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

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

With no output schema, the description usefully summarizes the return payload, and the required inputs are fully covered by the schema. It is complete enough to call correctly, with only minor gaps around error/edge-case 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 100%, so both required parameters and the optional docHash are already documented in the schema with pattern/format guidance. The description restates the requestId example but adds no syntax or semantics beyond what the schema provides, matching the baseline 3 for high-coverage schemas.

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 ('Reads the on-ledger status of a Radix Seal signing request') and adds scope detail (lookup by id) plus expected output. It is clear enough to distinguish from verify_document_signature or verify_rola_proofs, though it never explicitly contrasts itself with those signing/verification 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?

Usage is implied rather than stated: an agent can infer you call this after a signing request exists to check its state, and 'Read-only Gateway query' signals the read-only context. There is no explicit when-to-use, when-not-to-use, or named alternative, so it stays at the minimum-viable level.

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

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

readOnlyHint=true already tells the agent this is a safe read; the description adds genuinely new behavior: account conversions also return the compressed secp256k1 public key and a wallet-import QR payload, and it explicitly reassures that the payload contains only public data (never a seed phrase or private key). It stops short of describing failure modes for malformed or resource-form addresses.

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

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

Four sentences, purpose front-loaded, and the behavioral/security details are ordered after the core definition. The wallet-import rendering instructions are slightly operational rather than tool-defining, but they earn their place by telling the agent what to do with the output.

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 carries the return-value burden and does so: Babylon equivalent for both branches, plus public key and QR payload for accounts. For a 6-parameter, read-only conversion tool this is complete enough to call and interpret 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%, including enums for network and accountType, so the schema already carries the parameter meaning and the baseline is 3. The description adds no per-parameter detail beyond the account/resource distinction it already makes at the purpose level.

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 (converts) and resource (legacy Olympia address), and explicitly distinguishes the two input forms it handles: 'rdx1… account or _rr1… resource'. An agent can tell this apart from siblings like inspect_address or resolve_vault_address 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 clear situational context: this is the legacy-wallet import path, and the returned string must be rendered as a QR (Settings → 'Import from a Legacy Wallet') to complete the import. It does not, however, name an alternative tool or state when-not to use it relative to siblings like inspect_address.

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

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

Annotations cover the safety profile (readOnlyHint=true), so the bar is lower, and the description still adds real behavior: Scrypto vs Manifest SBOR is auto-detected from the prefix byte, and the return is human-readable text. It stops short of describing malformed-payload behavior or failure modes.

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, zero filler, and the core capability plus the auto-detection behavior are front-loaded. Nothing could be trimmed without losing 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 two-parameter read-only tool with no output schema, the description tells the agent what payloads are valid and what the output looks like (human-readable text). Only error handling and the practical size/round-trip use case are unstated, which are minor omissions.

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 both the hex pattern and the network enum with the same 5c/4d prefix detail the description restates. The description adds no semantics beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (decodes) and resource (hex-encoded SBOR payload) with concrete scope examples: component state, events, schemas. It is reasonably distinguishable from siblings like explain_manifest, though it never names an alternative to sharpen 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?

Usage is implied by the description — an agent can infer it should use this when it has a hex SBOR payload to read. There is no explicit when-to-use/when-not guidance and no sibling routing (e.g. explain_manifest vs decode_sbor).

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

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

readOnlyHint=true already establishes this is a safe, non-mutating operation, so the description's burden is lighter. It adds the nature of the output (plain-language step-by-step narrative) and the supported locales, but says nothing about whether explanation is generated locally or via a model, whether errors are surfaced for invalid manifests, or how long/large manifests 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?

Two sentences, zero waste: the first defines the transformation and its output shape, the second states the use case. The core action is front-loaded and the parenthetical list of explained elements is compact and 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?

For a two-parameter, fully schema-documented tool with no output schema, the description adequately covers what the tool does and roughly what it returns. It could go slightly further by noting behavior on malformed manifests or the relationship to validate_transaction_manifest, but nothing essential for invocation 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%, with both `manifest` and `locale` (enum en/es, default en) fully documented in the schema. The description's mention of "English or Spanish" echoes the locale enum without adding syntax, format, or constraint detail beyond it, 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: translating a Radix transaction manifest into a plain-language, step-by-step explanation, and enumerates the content types covered (withdrawals, deposits, proofs, component calls). This clearly distinguishes it from the sibling build_*_manifest, validate_transaction_manifest, and preview_transaction tools, which construct, check, or simulate rather than explain.

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?

"Use it to help the user understand what they are about to sign" gives a concrete usage scenario and a clear trigger. It does not name alternatives (e.g., validate_transaction_manifest or preview_transaction) or state exclusions, so it falls short of the explicit when/when-not guidance a 5 requires.

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 only readOnlyHint=true available, the description carries extra weight and delivers: it discloses the data source ('reads the Gateway'), the recovery mechanism (extract secp256k1 public key from the account's last 10 withdrawal signatures and keep the one that derives the address), and the precise meaning of each failure result. This is behavior an agent genuinely cannot infer from annotations or 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?

Purpose, mechanism, precondition and result semantics are ordered from most to least immediately useful, and every clause adds information — there is no filler or repetition of the 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?

There is no output schema, and the description covers the important part — the shape of unsuccessful results ('found: false' plus a reason) — but it never states what a successful return contains beyond the implication of 'found'. Given the non-obvious grunt work this tool performs, some indication of the success payload would be useful.

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 documented, and the description adds no format or syntax detail beyond clarifying that babylonAddress is a Babylon (hashed-key) account rather than an Olympia one. 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 — 'finds the legacy Olympia address (rdx1…) behind a Babylon account' — and immediately positions itself relative to the sibling convert_olympia_address as its reverse. An agent can distinguish this from the forward converter and from inspect_address 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?

Sets a hard precondition ('only works once the account has signed a Babylon transaction') and explains what the failure outcomes mean for usage decisions — 'no-transactions' does not mean non-legacy. It does not explicitly recommend an alternative when the precondition fails (e.g. use convert_olympia_address or inspect_address instead), which keeps 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?

Beyond the readOnlyHint annotation, the description discloses the actual data sources searched (accounts' touched pools, Ociswap/DefiPlaza/Reddicks published pools mainnet-only largest-first, recent network activity) and a critical completeness caveat. This is exactly the kind of behavioral context the annotation 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?

It is front-loaded with the core purpose and uses two dense, well-ordered sentences. The source enumeration is lengthy but each clause contributes, so it earns its length; it could be tightened slightly.

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 need not explain return fields, but it does not characterize the result shape at all. It fully covers sources, scope, and the incompleteness caveat, which is the important context for this tool, leaving only result format 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 100%, so the baseline is 3, but the description adds real meaning: it clarifies that the query matches name OR address, and that 'accounts' expands the search to pools those accounts have touched. That ties the parameters to the source-selection behavior in a way the schema alone does not.

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: 'Finds native pools (pool_…) and Account Lockers (locker_…) by name or address'. It even disambiguates the two resource types by their address prefixes, so an agent can distinguish it from siblings like lookup_entity and get_pool_state without opening the schema.

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

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

It names a concrete use case, 'resolve "the XRD/HUG pool" into an address before get_pool_state', which tells the agent both when to call it and which sibling to call next. It also warns that results are incomplete ('No API lists every pool or locker') and that a missing one can still be used by address. It stops short of explicit when-not-to-use guidance, keeping it out of the top band.

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, so the safety profile is covered. The description adds useful return-shape context (fungible amounts, NFT local ids), which matters since there is no output schema, but it says nothing about pagination, ordering, or whether empty accounts return an empty 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?

A single sentence with no filler, and the resource (what is listed) is front-loaded ahead of the qualifier (held by a Radix account). Every clause earns its place.

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

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

With no output schema, the description correctly carries the burden of describing the return shape, and does so adequately for a two-parameter read tool. Minor gaps remain around pagination or result size for accounts holding many tokens.

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%, with address format examples and a mainnet/stokenet enum plus default already documented. The description adds no parameter meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb ('Lists') and a precisely scoped resource: fungible tokens with amounts and NFTs with local ids held by a Radix account. The scope wording is strong enough to distinguish it from siblings like get_resource_holders or get_nft_data, though it does not name 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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as get_component_state or lookup_entity. Usage is only implied by the tool name and the 'held by a Radix account' phrasing.

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

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

Annotations only declare readOnlyHint=true; the description adds ordering semantics, the fact that the first page is usually sufficient, the scale risk ('accounts can have thousands of transactions'), and how the returned cursor is meant to be used. That is substantial behavioral disclosure well beyond the annotation.

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, no filler, front-loaded with purpose and the anti-pattern warning before the sibling reference. Every sentence carries distinct guidance.

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, the description covers what comes back (newest-first page plus cursor) and the paging contract, so an agent knows how to call it and what to do with the result. Nothing material is missing for this read-only list 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 address, network, limit and cursor are already fully documented in the schema, including that cursor fetches the next/older page. The description adds the 'newest first' framing but no syntax or format detail 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 ('Transaction history of any entity'), enumerates the entity kinds (account, validator, component, resource), and fixes the ordering ('newest first'). It also explicitly distinguishes itself from get_transaction, so an agent can separate them without opening either schema.

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

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

Gives explicit when-to-use ('the first page already shows the most recent activity, which is what users almost always want'), an explicit when-NOT-to ('do NOT keep paging to the end'), and names the alternative tool for the single-transaction case. The condition that triggers further paging is spelled out.

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 cover safety (readOnlyHint=true), so the bar is lower. The description adds genuine context beyond that: it discloses the return content (functions/methods with argument names and types) despite there being no output schema, and explains the auto-resolution behavior for component addresses.

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

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

Two tight sentences with zero waste; the output definition is front-loaded and the calling convention follows immediately. 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, the description compensates by describing what is returned, and annotations cover the safety profile. It is nearly complete, lacking only error/failure behavior for invalid addresses.

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 'Ignored for component addresses' for blueprintName. The description restates the address/blueprintName relationship but adds little syntax or format detail 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+resource: returns the 'callable interface' of a component or package blueprint, specifying it lists every function/method with argument names and types. This clearly distinguishes it from state-oriented siblings like get_component_state or lookup_entity, though it never names an alternative 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?

The second sentence gives practical calling guidance (pass a component address, or a package address plus optional blueprintName), and notes the blueprint is resolved automatically. However, it offers no when-to-use vs. when-not guidance against siblings such as get_component_state or inspect_address.

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

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

With only readOnlyHint available, the description does real work: it discloses the security findings are ordered worst-first, that package code is immutable, and — critically — that the analysis covers permissions, not code safety ("nothing here says the code is safe"). That caveat prevents a serious misreading of the output. It does not mention batching limits or failure behavior, which the schema partially covers.

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 verb and resource are front-loaded, which is good, but the body is one enormous run-on sentence with deeply nested parentheticals that blur the security findings together. For the amount of genuinely useful content it is defensible in length, but splitting the enumeration into a structured list would make it far easier 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, so the description must carry the return contract — and it does thoroughly, naming every field group plus the ordering of security findings and what those findings mean. The one interpretive limit it flags (permissions vs. code safety) is the most important caveat for this tool. Only minor gaps remain, such as behavior on an invalid or non-component address.

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, including the enum for network and the cap of 10 addresses. The description only restates that a component looks like component_… and that several can be read at once, adding no format or semantics 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 concrete verb and resource ("Reads one or several Radix components") and enumerates exactly what the result contains — name, blueprint, package, ownership, roles, holdings, royalties, and a security analysis. The "same card the console's Component info section shows" anchor makes the scope concrete. It stops short of naming when to prefer get_component_state or get_component_blueprint, so sibling differentiation is only 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?

Usage is implied rather than stated: the heavy emphasis on roles, who can change things, and security findings signals this is the permissions/security overview tool. There is no explicit when-to-use or when-not, and no alternative is named even though get_component_state and get_component_blueprint sit right next to 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?

The readOnlyHint annotation already establishes this as a safe read, and 'Live decoded on-ledger state' reinforces freshness. The description adds the response contents (package, blueprint), but gives no error behavior, auth/permission notes, or data-volume context, so with annotations covering safety this lands at an adequate 3.

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-loading the primary purpose and appending the sibling routing note. No filler or 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?

With no output schema, the description carries the burden of describing return values, and it does so by enumerating what the state includes plus the package/blueprint. Complete enough for correct invocation, though error and edge-case behavior is 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 description coverage is 100%, so the schema fully documents address format and the network enum/default. The description adds nothing beyond that, which is the correct baseline 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 ('Get decoded on-ledger state of a component'), gives concrete examples (oracle prices, pool reserves, configuration), and explicitly distinguishes itself from the sibling get_component_blueprint. An agent can tell it apart from get_component_blueprint without opening either schema.

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

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

Explicitly routes the agent to get_component_blueprint for callable methods, which is the most likely confusion given the sibling name. It does not, however, clarify when to prefer this over other state readers like get_validator_state or get_key_value_store.

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 only readOnlyHint=true in the annotations, the description carries the rest of the burden and does so well, disclosing the return semantics (default rule enum values, always-allowed/always-refused exceptions, badges) and the crucial behavioral caveat that owner deposits are unaffected. It doesn't cover latency, caching, or how multi-account batches behave.

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 and keeps the routing advice and caveat in a compact paragraph with no filler. The single dense block is longer than strictly necessary but each 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?

There is no output schema, so the description's enumeration of return fields (default rule, exceptions, badges) is exactly what the agent needs. Combined with the usage triggers and the deposit-scope caveat, nothing material is missing for a 2-parameter read 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%, with the account list cap (10) and network enum already documented in the schema. The description only echoes 'one or several accounts' and adds no syntax or format beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Reads who may deposit into one or several accounts') and then enumerates the returned content: default rule (Accept/AllowExisting/Reject), per-resource exceptions, and depositor badges. It is clearly distinct from the sibling builders, which produce manifests rather than read 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?

Gives explicit use cases ('explain why an airdrop or a payment did not arrive') and a named downstream alternative ('before build_deposit_rules_manifest'), plus an exclusion scoping the tool: these rules only govern try_deposit_* third-party deposits, while owner deposits always land.

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, so the safety profile is covered. The description adds one genuinely useful behavioral fact: results are decoded to JSON. It says nothing about whether the full store is returned, size or pagination limits, or failure modes for malformed addresses.

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

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

Two short sentences, front-loaded with the core action. The second sentence is a slightly clipped fragment but carries real disambiguating information about the address prefix rather than padding.

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

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

For a two-parameter read tool with readOnlyHint and full schema coverage, the description covers what the tool does and the shape of the output (JSON-decoded entries). With no output schema, a little more detail on completeness of the returned entries would be ideal, but nothing essential is missing.

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

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

Schema description coverage is 100%, so both parameters and the network enum are fully documented in the schema. The description reinforces the internal_keyvaluestore_… address format but adds no syntax or semantics beyond what the schema already provides; 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 ('Reads the entries of an on-ledger key-value store') and clarifies the domain concept as component internal storage. The closing note about where KVS addresses appear implicitly ties it to get_component_state, though it never names a sibling 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 rather than stated: the note that 'KVS addresses appear inside component state' hints you arrive here via get_component_state, but there is no explicit when-to-use, no when-not-to-use, and no 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?

readOnlyHint=true already establishes the safe-read profile, so the bar is lower. The description adds genuine value by disclosing the exact return content and the wallet-signing relevance (dApp definition + origin), which no structured field provides.

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

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

Two front-loaded sentences with no filler, and the content enumeration plus the usage clause each earn their place. It is dense but 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?

With no output schema, the description compensates by enumerating what is returned (addresses, badges, dApp definition/origin), which is what an agent needs. Nothing essential for calling the tool correctly is missing.

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

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

There is a single parameter with 100% schema description coverage and a documented enum (mainnet/stokenet), so the schema already carries the full parameter meaning. The description adds no param-level detail beyond that, making the baseline 3 correct.

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?

It names a specific verb and resource (get canonical well-known network addresses) and enumerates the exact contents: XRD resource, faucet, native packages, system badges, plus the dApp definition and origin. This clearly distinguishes it from address-resolving siblings like inspect_address and resolve_vault_address.

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?

"Use it to fill manifest addresses without guessing" gives a clear, actionable context that ties it to the build_*_manifest siblings. It stops short of naming an alternative or stating when-not to use it, so it is strong but not exhaustive.

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

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

The readOnlyHint annotation already signals a safe read; the description adds substantial behavioral context beyond it, disclosing that results include badge rules and whether the account holds each badge, recoverability before claim, and per-recipient outstanding items. With no output schema, this return-shape disclosure is the main value, though batch/failure behavior for multiple locker addresses is not addressed.

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 and the usage sentence lands last, which is the right ordering. The middle enumeration of returned fields is long and comma-chained, bordering on run-on, but every listed field earns its place given there is no output schema to carry that burden.

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 has no output schema, so the description carries the entire return-value burden and does so thoroughly, covering ownership, badge rules, recoverability, claim links, holdings, and per-recipient state. Required parameters and the network enum are fully documented in the schema, so 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%, so the baseline is 3, but the description adds meaning beyond it: the optional account parameter is explained as yielding "everything waiting in it for that account," clarifying its filtering effect rather than just its name. The locker parameter's batch nature is left to the schema's maxItems of 10.

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 ("Reads one or several AccountLockers") and anchors it to a concrete, recognizable artifact (the console's "Locker info" section). It then enumerates the exact contents returned, so an agent can distinguish it from build_locker_manifest or get_component_state 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 clear when-to-use context: "Use before building a claim or a recovery, or to tell a recipient whether a locker is safe to leave tokens in." It does not name a specific alternative tool or state when NOT to use it, so it falls short of the explicit-alternative bar, but the trigger conditions are unambiguous.

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

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

The readOnlyHint annotation already establishes this as a safe read, so the bar is lower. The description adds the concrete contents of the response, which is genuinely useful given there is no output schema. It says nothing about freshness, caching, or whether stokenet lags mainnet, so there is room left.

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

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

A single front-loaded sentence with no filler, and the most important identifier (Radix network) comes first. It is a fragment rather than a sentence, but nothing is wasted.

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

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

With no output schema, the description correctly compensates by listing the return fields, and the one input parameter is fully covered by the schema. It is nearly complete for a simple read tool; only usage context is absent.

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

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

Schema description coverage is 100% and the single 'network' parameter is fully documented with an enum and default. The description does not mention the parameter at all, so the baseline of 3 applies since the schema carries this dimension entirely.

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 exact resource (Radix network status) and enumerates the specific data points returned: epoch, total XRD staked, active validator count, average APY, average uptime. This distinguishes it implicitly from granular siblings like get_validator_state or get_xrd_price, though no sibling is named 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?

There is no when-to-use guidance, no mention of prerequisites, and no routing to alternatives. The agent must infer from sibling names alone that this is the network-level aggregate rather than a per-validator view.

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

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

readOnlyHint=true is consistent with the description, so the safety profile is already covered; the description adds non-annotation context in the form of the max-10-NFTs-per-call batching limit and the nature of the returned payload (local ids vs decoded traits/fields). It does not say whether listing a large collection's ids is itself capped or paginated.

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 discloses both modes and the batch cap with no filler; every clause earns its place.

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

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

With no output schema, the description does the necessary work of characterizing both return shapes (list of local ids vs decoded traits/fields), which is enough to call it correctly. Minor gaps remain around pagination/listing limits and behavior for invalid or out-of-range ids.

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

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

Schema coverage is 100% and the schema's own 'ids' description already says 'Omit to list the collection ids' and carries the maxItems: 10 constraint, so the description largely restates structured data. It adds no format or addressing detail beyond the schema example ("#1#").

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

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

States a concrete verb and resource (explore an NFT collection) and spells out the two operating modes: list local ids when "ids" is omitted, decode on-ledger trait/field data when it is supplied. That is far more precise than the title 'Get NFT ids and data', but no sibling (e.g. get_resource_holders, list_claimable_stake_nfts) is named to anchor 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?

"Without 'ids' it lists... with 'ids' it returns..." tells the agent exactly which input selects which behavior, which is real invocation guidance. It stops short of saying when to prefer this tool over sibling lookups such as get_component_state or list_claimable_stake_nfts.

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 readOnlyHint=true: it discloses filtering rules (native units only counted 'when the unit and its pool name each other on the ledger'; Precision collections only if minted by a real PrecisionPool that names them), that fees and withdrawal returns are 'simulated with the real transactions', how 7/30-day change is computed (geometric mean, ledger state as it was then), and the operational meaning of out-of-range positions ('earns no fees until the price comes back'). This is exactly the kind of 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?

Every clause is informative, but the content is delivered as a single sprawling sentence with nested parentheticals, so no single fact is front-loaded and the reader must parse clauses to find the scope. It is dense rather than tight; splitting the native-pool and Precision portions into separate sentences would preserve all substance and improve scanability.

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 return contents — and it does thoroughly: per-unit redemption value, pool share, DEX listing and reported APR, 7/30-day value change, claimable fees, withdrawal simulation results, and in-range status. An agent can predict the shape of the response without opening anything else.

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 (account address format, mainnet/stokenet enum) are fully documented in the schema, so the baseline 3 applies. The description adds nothing about the network parameter's effect on results or about address-format expectations.

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 ('Everything an account has in pools') plus the explicit enumeration of the two position families (native pool units, Ociswap Precision concentrated-liquidity NFTs) makes the resource unmistakable and clearly distinct from siblings like get_pool_state or find_pools. It loses a point because the purpose is embedded in a very long run-on sentence rather than stated as a crisp verb+resource up front.

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 downstream routing: 'Use build_dex_manifest to act on them, build_pool_manifest "redeem" for native units', which tells the agent what to do after reading. It does not, however, say when to prefer this over get_pool_state or find_pools, nor state any exclusions or prerequisites (e.g. account must be on the given network).

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?

Read-only is already covered by annotations, but the description adds substantial context the agent could not otherwise know: the security analysis is findings-worst-first, it checks permissions rather than code, and pools with an AllowAll manager can be drained via protected_withdraw. It also discloses that the response expands when account is supplied.

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, which is good, but the middle collapses into two very long comma-chained sentences enumerating findings and reserve-token risks. The density makes it slow to parse; several clauses could be trimmed without losing selection-critical 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?

There is no output schema, so the description must carry the return-value burden, and it does so exhaustively: profile fields, security findings, role permissions, and the optional per-account position. Combined with full schema coverage on inputs, 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 coverage is 100%, so baseline is 3, but the description earns extra credit by explaining the account parameter's effect on the result (position, share, redeem return, badge ownership) and by implying pool is a batchable list. It does not restate enum values, which the schema already handles.

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

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

Opens with a specific verb and resource ('Reads one or several native Radix pools') plus the three pool flavors, then enumerates the exact profile fields returned. This clearly separates it from find_pools (discovery), get_pool_positions (positions) and get_component_state (generic state).

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 sequencing rule: 'Use it before build_pool_manifest.' It also explains the conditional branch for the account parameter ('With an account, also its position...'), which shapes usage. It stops short of stating when to prefer get_pool_positions or get_component_info instead, so no exclusion 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?

readOnlyHint=true already covers the safety profile, so the description is free to add the behavioral facts it does: results are network-wide, only committed transactions, and ordered newest first. It doesn't mention the 50-item cap or pagination, which are minor gaps against an annotated read 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?

Two sentences, zero filler, and the core behavior (what you get, in what order) is front-loaded before the pointer to the sibling 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?

No output schema exists, so the description carries some of the return-shape burden; it says transactions are committed and newest-first but not what fields a transaction record contains. For a simple two-parameter list tool with full schema coverage, this is close to 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% – both network (enum, default mainnet) and limit (1-50, default 10) are fully documented in the schema. The description's 'network-wide' phrase aligns with the network parameter but adds no syntax or bounds beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource (recent transactions), plus scope (network-wide), ordering (newest first), and status (committed). It is immediately distinguishable from the sibling get_transaction, which requires an intent hash.

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

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

Explicitly routes the agent: use get_transaction with an intent hash to get the full breakdown of one of these results. That is a named alternative plus the condition that selects 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 readOnlyHint=true already declaring safety, the description adds real behavioral context: pagination default, the 20,000-holder cap, sort order, and what aggregate data accompanies the list. It could say more about rate limits or pagination mechanics, so 4 not 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?

Dense, front-loaded paragraph: purpose and ordering first, then pagination, then filters, then the sibling redirect. No filler sentences.

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

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

No output schema exists, and the description compensates by naming the returned aggregates (top holder, top 10, holder kinds). For a read-only, six-parameter tool this is nearly complete; only edge-case behavior (empty results, cap exceeded) is 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 100%, so the schema carries the per-parameter documentation. The description adds meaning beyond it by tying all:true to the concrete 20,000 cap and noting the filter set (kinds, minAmount, exclude) in one place, though it doesn't elaborate on filter 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 and resource (lists holders of a token or NFT collection) plus ordering (largest first) and the extra data returned (concentration, holder kinds). An agent can distinguish it from sibling read tools like get_nft_data or lookup_entity 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?

Explicitly describes the default behavior (first page of 100) and the all:true escalation (up to 20,000), and routes the agent to plan_holder_distribution for the airdrop use case. This is a clear when-to-use and alternative-naming 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?

The readOnlyHint annotation already establishes this as a safe, non-mutating operation, so the description need not restate that. It does sketch the response content (sections with URLs and descriptions), which is useful, but says nothing about caching, freshness, or how the locale changes output behavior. Adequate but thin on behavioral 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?

Two short sentences with the tool's output front-loaded and the usage cue second; nothing is wasted. The phrase "Radix Community web" is slightly informal but still parses clearly.

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 low-complexity, single-parameter, read-only tool with no output schema, the description covers what it returns (sections, URLs, offerings) and when to reach for it. Only minor ambiguity remains about the exact response format (structured data vs. prose).

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

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

Schema description coverage is 100% and the single locale parameter is documented in the schema with an enum and default, so the schema does the heavy lifting. The description never mentions locale at all, so it adds no meaning beyond the structured field — this is the baseline 3 case.

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 deliverable: a map of the Radix Community site listing every section with its URL and contents. That distinguishes it from content-fetching siblings like read_radix_doc and search_radix_docs, though it never names those siblings directly. It is clear but does not explicitly contrast itself with 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?

"Call it first when you need to know where something lives on the site" gives an explicit usage condition and positions the tool as a discovery/orientation step. It stops short of naming the alternative tools (search_radix_docs, read_radix_doc) or stating when not to use 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?

readOnlyHint=true already establishes the safe-read profile, and the description adds that it returns status, fee, timestamp, entities, balance changes and manifest. However, it does not mention behavior for non-existent or uncommitted hashes, nor any auth/rate considerations, so it only partially goes beyond the annotation.

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 identifying the resource and key, followed by a compact colon list of returned data. No filler or redundancy.

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

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

With no output schema, listing the returned fields (status, fee, timestamp, entities, balance changes, manifest) usefully fills the gap, and the parameters are fully covered by the schema. Only the absence of error/edge-case behavior 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%, with both network and intentHash fully documented in the schema. The description restates the txid_… format but adds no new syntax or constraint beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (Fetches), resource (committed transaction), and key (intent hash/txid). The word 'committed' implicitly distinguishes it from preview_transaction and the recent/address transaction list siblings, though no sibling is named 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 'committed transaction by its intent hash', which signals you need a known txid rather than a filter, but there is no explicit when-to-use/when-not guidance or named alternative (e.g., get_recent_transactions, preview_transaction).

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

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

readOnlyHint=true already establishes this as a safe read, and since there is no output schema the description carries the burden of disclosure — it does so thoroughly, naming the warning cases (not registered, fee at 100 %, fee going up, node down) and the account-position fields. It stops short of error behavior (e.g. unknown address) or cost/latency notes.

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, purpose front-loaded, with the payload enumeration confined to the second sentence. Given the absence of an output schema, every listed field earns its place rather than being 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?

With 3 params, no output schema, and only a readOnly annotation, the description supplies the full return-value picture an agent needs, including the optional account branch and warning conditions. It is only short on edge/error cases and on routing versus list_validators.

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 validator (address or list of up to 10), network enum, and the optional account. The description largely restates these; the only real addition is a slightly richer account semantic (withdrawals still waiting for their epoch, ownership). 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?

States a specific verb and resource ("Reads one or several validators") and pins the scope to a known console view, plus enumerates the payload. It does not name or distinguish itself from the sibling list_validators, so an agent must infer that this is the per-address lookup versus the bulk list.

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: pass explicit validator addresses (up to 10) and optionally an account to enrich the result. There is no explicit when-to-use versus list_validators or list_validator_operations, and no stated exclusions or 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?

readOnlyHint=true already establishes the safety profile, so the description's main addition is the data source (CoinGecko) and that values are live. It does not disclose refresh cadence, caching, rate limits, or behavior when the upstream API is unavailable. Useful context beyond annotations, but not rich.

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

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

A single front-loaded sentence that names the source and then lists the payload fields. No filler, 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?

With no output schema, the description correctly takes on the job of enumerating returned fields, which is the key completeness requirement here. It omits only secondary details such as refresh interval or failure behavior, which are minor for a no-arg read 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?

There are zero parameters, so per the rubric the baseline is 4. The schema description coverage is 100% and there is nothing for the description to compensate 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?

States a specific verb and resource (get XRD market data) and enumerates exactly what is retrieved: USD/EUR price, 24h change, market cap, circulating supply, TVL. This is unmistakably distinct from every sibling, which are all Radix node/network/manifest tools rather than market-data lookups.

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 never says when to reach for this tool, when not to, or what alternatives exist. For a zero-parameter convenience tool this is a mild gap, but no usage context is provided at all.

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

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

With readOnlyHint=true already declaring the safety profile, the description adds genuinely new behavioral context: the operation is fully offline and issues no network calls, so there is no latency, rate-limit, or side-effect risk. It also discloses that checksum validity is reported rather than enforced, implying invalid input is handled gracefully.

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 dense sentence that front-loads the key constraint ('Offline') and then lists the outputs. Every clause earns its place; nothing is padding.

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

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

No output schema exists, and the description compensates by stating what is returned (entity type, network, checksum validity), which is exactly what an agent needs. The lone parameter is fully documented, though error behavior for malformed non-bech32m input is not spelled out.

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?

One parameter with 100% schema description coverage ('Any Radix address or transaction id'), so the schema carries the semantics. The description slightly narrows scope to bech32m addresses, but adds no format, casing, or edge-case 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?

Names a specific verb and resource ('Offline analysis of any Radix bech32m address') and enumerates what it extracts: entity type, network, checksum validity. The 'offline / no network calls' framing implicitly separates it from network-fetching siblings like lookup_entity, 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?

There is no explicit when-to-use/when-not guidance or named alternative among the many siblings (convert_olympia_address, resolve_vault_address, lookup_entity). The 'Offline... No network calls' phrase is only an implied selection cue — it tells the agent the tool is appropriate when a local, side-effect-free decode is wanted.

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

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

readOnlyHint=true already declares this a safe read, so the description only needs to add context. It does so usefully by disclosing the shape and meaning of the returned data (per-validator attribution, redeemable XRD, maturity flag), which tells an agent why it would call this before a claim. Pagination or result-size behavior is not addressed.

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, no filler. The core scope (what is listed) is front-loaded, and the second sentence is purely actionable routing information. Every clause earns its place.

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

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

With no output schema, the description must convey the return shape, and it does name the salient fields an agent needs to decide whether to proceed to a claim. It leaves minor gaps: whether all NFTs are returned or the list is bounded/paginated, and what an empty result implies.

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?

Both parameters are fully documented in the schema, including the mainnet/stokenet enum and the account_… address format, so the schema carries the burden. The description adds no parameter-level detail (e.g., network defaults or address validation), which matches the baseline 3 when coverage is 100%.

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: it lists the stake claim NFTs an account holds, and goes further by naming the three attributes returned (minting validator, redeemable XRD, maturity). This is well beyond a tautology and is clearly distinct from generic siblings like get_nft_data or list_validator_operations, though it never explicitly contrasts itself with any of 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?

Gives clear downstream context by naming the sibling and the intent: feed the matured NFTs to build_validator_manifest as a claim-xrd operation. That effectively describes the workflow this tool feeds. It stops short of stating exclusions, such as when to prefer get_nft_data or what to do with unmatured entries.

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

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

With readOnlyHint=true already covering the safety profile, the description adds genuine value by disclosing the return shape (each tool plus its URL and whether it requires a connected wallet). It does not mention pagination, caching, or locale-dependent behavior, so it is not exhaustive.

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, no filler: the first front-loads what is returned, the second states the routing use case. Every clause earns its place.

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

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

For a read-only, single-param listing tool with no output schema, the description covers the essentials of what comes back and when to call it. It omits locale effects on the returned labels/links, a minor gap given the schema documents the parameter.

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

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

Schema description coverage is 100% and the single locale parameter is fully documented in the schema, including its enum and default, so the description cannot add much. It never mentions locale or language behavior, making this the baseline 3.

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 (lists) and resource (every tool of the web developer console), and enumerates the categories covered (send transactions, staking, token creation, package deployment, metadata, SBOR decoding), which clearly separates it from the sibling API/query 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?

"Use it to route the user to the right console page" gives a clear context for invocation, so an agent knows this is a discovery/router tool. It stops short of naming when-not-to-use or an alternative tool, so it is not a full 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=true, so the safety profile is covered. The description adds value beyond that by disclosing the return content shape - template categories plus 'the fields each one needs' - which is the key behavioral fact for a listing tool. No pagination or rate-limit behavior is mentioned, but a static template catalogue plausibly has none.

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 resource and its coverage, then the routing instruction. No filler, and every clause earns its place.

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

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

For a one-parameter read-only listing tool with no output schema, the description covers purpose, content, and the natural follow-up tool, which is nearly everything an agent needs. Minor gaps remain: it does not describe the returned structure beyond field lists, nor note that locale changes the returned labels/links.

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 'locale' parameter is fully documented in the schema with its enum and default. The description says nothing about locale, so it adds no meaning beyond the schema; 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 ('Lists the ready-made transaction manifest templates') and enumerates the concrete template categories covered (transfer, stake, mint, burn, faucet...). It distinguishes itself from the many build_* siblings by naming build_manifest_from_template as the renderer, so an agent can tell this is the discovery/listing tool.

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

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

Explicitly routes the agent: 'Use build_manifest_from_template to render one,' which is a clear follow-up condition and separates this tool from all the build_* siblings. It does not state any when-not condition (e.g., that this is static and needs no prior setup), so it falls short of a full 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=true, so the safe-read profile is covered and the description need not restate it. The description goes beyond that by disclosing the per-operation metadata returned (owner-badge requirement and transaction-sharing compatibility), which is genuine behavioral content. It does not mention pagination or caching, but for a static catalog listing that gap is minor.

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 sentence, front-loaded with the verb and resource, followed by the enumeration and the two returned flags. The long parenthetical list is dense but each item is an operation name the agent would otherwise have to discover; it earns its space, though it could be trimmed.

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 parameters and no output schema, the description carries the return-value burden and does so: it names the operation set and the two boolean attributes per entry. An agent can decide to call it and interpret the result without further documentation.

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

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

The tool takes zero parameters, so there is nothing to disambiguate and the baseline is 4. The description correctly implies a no-argument, full-catalog call rather than introducing filtering semantics that do not exist.

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 (Lists) and a precise resource (every operation a validator supports), then enumerates the operation set so the agent knows exactly what will be returned. It is clearly distinguishable from siblings like list_validators or get_validator_state, which operate on validators, not on the operation catalog.

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

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

Explicitly states usage timing: 'Use it before build_validator_manifest,' which names the downstream sibling and the sequencing condition. It does not state when not to use it or cover the other alternative paths, but the primary routing guidance is unambiguous.

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

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

With readOnlyHint=true the safety profile is already covered, and the description usefully adds sort order and returned fields. However, it is silent on pagination/truncation behavior (the 200 cap) and on whether the full validator set is always returned, which matters for a list 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?

Two short sentences, front-loaded with the core behavior, followed by the filter and the use case. No filler or redundancy.

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

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

There is no output schema, and the description compensates by naming the returned fields and the ordering, which is the key information an agent needs. It omits anything about result size limits or how to page beyond the limit parameter, leaving a small gap.

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

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

Schema description coverage is 100%, so network, limit and find are fully documented in the schema. The description only restates the find filter ("Filter by name or address with 'find'") and adds no syntax or interaction detail beyond it, 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 ("Lists the validators of the Radix network") and immediately scopes it with the ordering (stake rank) and the fields returned (stake, fee, uptime, APY). This clearly separates it from the single-entity sibling get_validator_state and from list_validator_operations.

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?

"Use it to answer questions about staking targets or a specific validator" gives an explicit use context, and the find-filter hint tells the agent how to reach the specific-validator case. It stops short of naming alternatives or when-not-to-use conditions (e.g., use get_validator_state for a single validator's detail).

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

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

With readOnlyHint=true already declaring the safe-read profile, the description still adds real value: it discloses the return shape (entity type, metadata, and a *summary* of details), which implicitly tells the agent this is a shallow generic read rather than a deep type-specific one. It omits any note on pagination, size limits, or error behavior for unknown addresses.

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, front-loaded with scope, then return shape, then the routing hint. No filler and nothing an agent needs is buried.

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

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

With no output schema, the description usefully compensates by naming the returned fields and flagging that details are a summary. It stops short of telling the agent where to go for full details of a component/validator, which is the one gap for a tool this broad.

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 both parameters are fully documented in-schema (Bech32m examples, network enum with default). The description adds no syntax, format, or constraint detail beyond what the schema already carries, 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?

Specific verb ('fetches the on-ledger state') plus explicit resource scope, enumerating every address family it covers (accounts, components, packages, resources, validators, pools). An agent can distinguish it from get_component_state, get_validator_state and inspect_address purely from the description.

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?

'For account token balances prefer get_account_balances' gives one explicit alternative with the condition that selects it. However, it is silent on the other heavily overlapping siblings (get_component_state, get_validator_state, get_nft_data, inspect_address), which an agent must disambiguate 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?

Annotations only declare readOnlyHint=true; the description adds real behavioral detail beyond that: truncation to the token's divisibility so the total is never exceeded (i.e. integer-down rounding, dust left behind), and that the output is a recipients CSV rather than a signed transaction. It does not cover empty-result behavior or size/rate limits on scanning all holders.

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, both earning their place, with the core mechanism front-loaded and downstream routing last. The inline '(filters: kinds, minAmount, exclude)' list partially duplicates the schema and makes the first sentence dense, which keeps it just below top marks.

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-output-schema read tool, the description supplies the missing return-value information (recipients CSV) and the numeric guarantee that the sum never exceeds total, plus the handoff targets. What remains unexplained (CSV column layout, empty-holder case) is minor and inferable.

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?

Above the 3 baseline for 75% coverage: the description maps mode to its plain meanings ("equally or pro rata") and names the three filter levers (kinds, minAmount, exclude) in context of filtering holders. It also clarifies the two-resource model implicit in holdersOf vs sendResource by saying holders of one token receive another token.

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

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

Specific verb+resource with full mechanism: reads every holder of one resource and splits an amount of another resource among them, equally or pro rata, with truncation. It also names the two downstream consumers, so it is clearly distinguishable from get_resource_holders and the build_*_manifest 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 routes explicitly to build_locker_manifest (operation "airdrop", recommended) or build_bulk_send_manifests as the next step, and the parenthetical 'recommended' expresses a preference. There is no explicit when-not guidance (e.g. for large holder sets or for non-airdrop use cases), so it falls 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?

The readOnlyHint annotation already declares a safe read, but the description adds real value on top: it runs 'without any signature' (no auth/signing required) and returns execution status, fee, per-entity balance changes and engine logs. It does not mention rate limits or size constraints, keeping it below a 5.

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

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

Two tight sentences, front-loaded with the core action and benefit, with the pre-signing workflow guidance placed last. No filler or redundancy.

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

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

With no output schema, the description carries the burden of describing returns and does so by naming execution status, fee, balance changes and engine logs. Combined with 100% schema coverage for inputs, an agent has what it needs, though a note on dry-run semantics vs. actual execution would round it out.

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 every parameter including blobs, network and locale is already documented in the schema; the baseline is 3. The description adds no syntax or format details beyond that (e.g. nothing on blob/manifest relationship), so it does not earn higher.

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 ('Dry-runs a transaction manifest on the Gateway') plus the notable constraint ('without any signature'), and even enumerates what it returns. However, it does not differentiate itself from the close sibling validate_transaction_manifest or explain_manifest, so an agent must still infer which one 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?

Gives clear workflow context: 'Always preview a manifest before asking the user to sign it,' which tells the agent exactly when in the flow to call this. It offers no explicit exclusions or named alternatives (e.g. when to prefer validate_transaction_manifest), 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?

readOnlyHint=true already tells the agent this is a safe read, so the description's added value is the disclosure that the entire page body is returned as Markdown and that content is locale-dependent. It does not address behavior on an invalid or stale docId, page size, or versioning.

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, zero filler, with the output format stated up front and the parameter-sourcing hint placed last. Every clause earns its place.

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

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

For a simple two-parameter read tool with no output schema, the description covers purpose, how to obtain docId, the return format, and the language dimension, which is enough to invoke it correctly. Only failure behavior for bad ids is 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 description coverage is 100% and both parameters carry their own descriptions plus an enum for locale, so the schema already does the work. The description only echoes the language option and the source of docId, adding no syntax or format 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 (returns full content), resource (one curated documentation page), format (Markdown) and supported languages. The 'one page' scope plus the docId sourcing note cleanly separates it from the sibling search_radix_docs.

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 the prerequisite workflow explicitly: get valid doc ids from search_radix_docs. What is missing is any when-not-to-use guidance (e.g. don't use it to search or to fetch multiple pages) or a note that ids not from search will fail.

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, so the safety profile is covered. The description adds genuine behavioral context beyond that: the one-vault-per-account/resource invariant and the conditional extra NFT-id output for non-fungibles. It omits what happens when the account does not hold the resource, but that is a modest gap for a read-only lookup.

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 tight sentences, front-loaded with the core verb and resource, followed by the invariant and the downstream consumers. Every sentence carries information; 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?

With no output schema, the description carries the return-value burden and does so for the main case (vault address) and the conditional case (NFT ids). It is complete enough to call correctly; only the not-found/empty behavior and any pagination or size caveats on NFT ids are unstated.

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

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

Schema coverage is 100%, so the schema already documents account, resource, and the network enum and its default. The description adds no parameter-level syntax or format detail, so it sits at the baseline for a fully documented 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 (resolves) and resource (internal vault address holding a resource in an account), and uniquely identifies itself among siblings — no other tool in the list resolves a vault address. It also adds scope detail (exactly one vault per account/resource) and a secondary output (NFT ids for non-fungibles).

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 context: it identifies the target a recall/freeze needs and names the four manifest templates that consume its output (recall-token / recall-nft / freeze-vault / unfreeze-vault). It stops short of explicit exclusions or naming an alternative tool, but there is no obvious competing sibling for this lookup.

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 readOnlyHint=true, so the safety profile is already carried. The description adds real context beyond that: results include document URLs, and there is a distinct list-all mode when query is omitted. It stops short of noting result limits or pagination, so it is not 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?

Four tight sentences with no filler; the content scope is front-loaded and the listing mode plus sibling routing follow naturally. Every sentence carries 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?

With no output schema, the description usefully discloses that matches come with URLs, and it covers the listing fallback. Minor gaps remain around result volume/pagination, but the essentials for correct invocation are present.

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 both "query" (free-text, omit to list all) and "locale" (en/es, default en) are already documented in the schema. The description's note about omitting query largely duplicates 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?

Names a specific verb (Searches) and resource (curated documentation), and enumerates the covered content (whitepapers, Scrypto/developer guides, node & validator guides, DeFi concepts). It also distinguishes itself from read_radix_doc, which retrieves full content rather than search matches.

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 operating conditions: call without "query" to enumerate all documents, and route to read_radix_doc to fetch full content. The when-to-use boundary against the sibling is stated, not 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?

Annotations only declare readOnlyHint=true; the description goes well beyond this by revealing that the tool returns installation/usage instructions rather than performing signing, that the local connector holds the wallet channel, and that the phone approves. This is exactly the kind of architectural 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?

Three tight sentences, front-loaded with what the tool is before the when-to-call triggers. No filler, and each sentence contributes distinct information (purpose, architecture, invocation criteria).

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 does convey that the response is explanatory content and clarifies the signing boundary. It could say slightly more about what the returned instructions contain (installer links, registration snippets), but it is complete enough for an agent to call 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 100% with both parameters (os, client) fully described and enum-constrained, so the schema carries the semantics. The description adds no additional param syntax or format detail beyond what the schema provides, making the baseline 3 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 (explains/installs) and resource (the LOCAL Radix signing connector, radix-connector-mcp), and explicitly distinguishes this tool from the stateless HTTP server that 'cannot sign'. An agent can tell this apart from build_wallet_request and check_signing_request without opening 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, concrete trigger list: 'Call this when the user wants to send/sign a transaction, stake, create a token, deploy, or log in with Radix.' It does not name a specific alternative tool for the non-signing cases, so it falls just short of full when-not/alternatives 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 only declare readOnlyHint=true, so the description usefully adds that validation is 'statically' performed via the Radix Engine Toolkit and that the exact parse error is reported on failure. It doesn't state the success response shape or whether oversized manifests are rejected, so it adds moderate value beyond the annotation.

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 well-formed sentence that front-loads the core action and ends with the failure behavior. No filler or repetition of the name/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 simple two-parameter, annotation-covered validation tool with no output schema, the description covers the essential behavior including the error path. Only the precise success/return shape is left unstated, which is a minor 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%, with both parameters documented including the mainnet/stokenet enum. The description adds no syntax, format, or size guidance for the manifest string, so the schema does the heavy lifting — baseline 3.

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 ('Statically validates') plus resource ('Radix transaction manifest syntax') and names the implementing toolkit. It implies a distinction from execution-oriented siblings like preview_transaction, but never explicitly contrasts itself with them, 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?

There is no when-to-use guidance, no mention of alternatives (explain_manifest, preview_transaction), and no prerequisites. Usage must be inferred from the verb 'validates' alone.

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

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

Annotations only declare readOnlyHint=true; the description reinforces 'Read-only' and adds substantial context the annotation does not: the key vs owner-badge distinction, the Access Controller case, roles, factor counts for signing/recovery, timed-recovery delay, and in-flight recovery/badge-withdrawal attempts.

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?

Dense and front-loaded, leading with the core determination before branching into badge/controller detail, and closing with the read-only guarantee. Slightly run-on, but every sentence carries substantive 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, the description must convey the return shape, and it does thoroughly: control type, controller presence, roles, factor thresholds, recovery delay, and pending attempts. An agent can predict the response without further documentation.

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%, with address format and network enum already documented in the schema. The description adds no parameter-level detail (no address formats, no network semantics), 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 (reads) plus the exact resource and concept it resolves: who controls a Radix account – key vs owner badge – and what else it reports. This is clearly distinguishable from siblings like inspect_address, get_account_balances, or lookup_entity.

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 content (check how an account is protected, controller roles, recovery status), but there is no explicit guidance on when to choose this over inspect_address or lookup_entity, and no stated prerequisites or 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?

Beyond the readOnlyHint annotation, it discloses what is actually checked (each signature against the shared payload, ROLA proofs and/or on-ledger chain of custody) and that it reports certificate completeness. It stops short of describing the report shape or failure semantics, but adds real behavioral context the annotation does not cover.

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 tight sentences, front-loaded with the verb and resource, then the internals, then the input boundary. No filler and every sentence 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 one-parameter, read-only verification tool with no output schema, the description covers what is verified and that a completeness verdict is returned. It could do slightly more on expected failure reporting, but nothing essential for invocation 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?

Single required parameter with 100% schema description coverage, so the schema already documents 'certificate' as the full .radixsig.json contents. The description adds no syntax, format, or size guidance beyond that, 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 (verifies) and resource (Radix Seal document-attestation certificate / .radixsig.json contents), and pins the scope to the certificate rather than the document. It does not explicitly differentiate itself from the sibling verify_rola_proofs even though it mentions ROLA proofs internally, so it falls short of a 5.

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

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

Usage is implied by the artifact named (.radixsig.json certificate), and the 'receives ONLY the certificate, never the document itself' line draws a useful boundary. However, no when-to-use/when-not guidance and no alternative sibling (e.g., verify_rola_proofs) is named for related verification tasks.

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 carry readOnlyHint=true; the description adds substantial behavior beyond that: it enumerates the exact checks performed (challenge/dApp-definition/origin signature, ledger owner_keys vs derived virtual address) and states that it 'Reports the reason for every failure'. It also discloses the anti-replay security requirement, which is critical operational 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?

Front-loaded with purpose, then input alternatives, then the security warning last, so the most important routing and safety information lands first. It is dense rather than padded, though the single long opening sentence carries several clauses that could be split for 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?

For a read-only verification tool with no output schema, the description covers what an agent needs: what it verifies, the two ways to supply proofs, the origin/dApp-definition linkage, that failures report reasons, and the replay caveat. Nothing material is left undefined.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds real meaning: it clarifies that proofs and wallet_response are alternate input forms ('every proof in it is found') and explains the security-relevant semantics of the challenge parameter. It stops short of field-level detail, which the schema already owns.

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 ('Server-side ROLA verification of the signed challenge proofs') and frames the exact trust decision a dApp backend must make. It is clearly distinguishable from siblings like build_wallet_request (which produces the challenge) and check_signing_request, and spells out the two things checked: signature over challenge + dApp definition + origin, and key-controls-entity via owner_keys or virtual address.

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

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

Explicitly states the two input routes ('Pass EITHER the raw wallet response ... OR proofs in the {type, address, proof} format') and names build_wallet_request as the source of the challenge. It also gives a strong when-not condition: never verify against the challenge inside the response, since that would accept a replayed answer.

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