Ankr Agent RPC

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds real behavior the annotations cannot: a refused method is never sent, probing asks the node and yields yes/no/restricted/unknown, and the catalogue is shape guidance rather than an authoritative coverage list. This is meaningful disclosure beyond the structured fields.

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

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

The core purpose and the rpcCall relationship are front-loaded in the first sentence, and each subsequent sentence carries distinct information (probing semantics, refusal behavior, catalogue caveat). It is dense — two ideas are packed into the probe 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?

There is no output schema, so the description must carry the return-value burden, and it does: positional param shape, a worked example per method, rpcCall's verdict, and the served value set. Combined with the catalogue caveat, an agent has everything needed to invoke and interpret results 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 the baseline is 3, but the description adds value the schema does not: probe requires an explicit methods list, the list is capped at 12, and served reflects the caller's key, tenant and the chain's blockchain schema with the discrete outcomes named. The methods param's dual role (probe target vs. catalogue omission) is clarified.

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 — describes what a JSON-RPC method takes and whether the key can call it — and clearly distinguishes itself from the sibling rpcCall by returning rpcCall's own verdict rather than executing it. An agent can tell these two apart 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 a clear conditional for probing ('Pass probe:true with an explicit methods list ... to also ask the node') and states the fallback behavior when methods is omitted. It ties itself to rpcCall but never says explicitly 'call this before rpcCall to check permission,' so the primary workflow trigger is implied rather than stated.

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

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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=true), so the bar is lower; the description still adds real behavioral context beyond them, notably that a tier-0 Sui view re-read is 'a fresh upstream call, never a replay of the earlier answer.' It also discloses the return shape (next page plus new cursor if more remains), which matters since there is no output schema.

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

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

Three tight sentences, front-loaded with the core action before the cursor-source detail. The middle sentence is dense with jargon ('tier 0 re-reads the view unshaped') but each clause carries information, so little is wasted.

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

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

For a single-parameter continuation tool with no output schema, the description supplies everything needed: what a valid cursor is, where cursors come from, how the re-read behaves, and what comes back including the terminating condition. Nothing material is left for the agent to infer.

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 there is only one parameter, so a 3 would be the baseline. The description goes beyond the schema's generic 'opaque cursor string from a previous tool result' by naming which tool calls legitimately produce such a cursor, which is the actual ambiguity an agent would face.

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

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

The description states a precise verb+resource ('Continue a paged result using the opaque cursor') and enumerates exactly which tools produce valid cursors (getWalletActivity, getLogs, getBalances, Sui views), which separates it cleanly from those producer siblings. An agent can tell this is the consumer/pagination tool without opening any schema.

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

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

It clearly states the trigger condition: use it when you hold an opaque cursor from a previous call, and it names the four cursor sources. It stops short of saying when NOT to use it (e.g., don't re-invoke the original tool to get the next page), so it is clear context rather than full 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/openWorldHint, but the description discloses far more: dust summarisation thresholds, the distinction between unpriced assets and zero-value assets ('Unknown is not zero'), off-page counts, and scam-token max-uint balances being flagged and withheld. This is exactly the non-obvious data-semantics context an agent needs to interpret output correctly.

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

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

Front-loaded with purpose and overall dense, but it runs several long lines with some emphatic restatement ('Unknown is not zero', 'never add it to a total') that could be tightened. Every sentence is relevant, so the length is defensible rather than wasteful.

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 full burden of explaining the return shape, and it does: per-line chain naming, USD-descending ranking, dust counts, 'USD value unknown' for unpriced assets, and how many assets exist off-page. Nothing needed to call or interpret the tool 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 75% and the schema already documents minUsd, maxTokens and blockchains. The description still adds meaning beyond the schema by explaining how minUsd and maxTokens interact with dust summarisation and ranking, and what happens when `blockchains` is omitted.

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

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

States a specific verb+resource+scope: 'Balance of an account across many blockchains, by 0x address or ENS name, via the Ankr Advanced API indexer.' It also distinguishes itself from the sibling getBalances ('call getBalances for structured JSON'), so an agent can route between 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?

Explicitly names the alternative (getBalances) and the condition that selects it (want structured JSON). It also gives concrete operating guidance: default top-20 listing, tune with maxTokens/minUsd, and the warning that omitting `blockchains` queries every chain and interleaves results.

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

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

Annotations cover only readOnly/openWorld, yet the description discloses genuinely non-obvious behavior: dust bucketing (count + USD total), unpriced assets ranked last and never summed, implausible balances (>=2^128) with the formatted balance withheld, ENS resolving for token lookup only, and raw-RPC-only chains returning native alone. These are exactly the edge cases an agent could not guess from the schema or annotations.

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

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

The core (address + one chain, what is returned) is front-loaded in the first sentence, followed by ranking/dust rules and then a scoped Sui exception. It is dense and telegraphic, but nearly every clause carries information; the only minor cost is length and compressed notation like 'usd: null, unpriced: true'.

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 itself, and it does: `tokens`, `dust`, `full_count`, `unpriced_on_page`/`unpriced_total`, `implausible`, and `native`, plus how each varies by chain family. For a 5-parameter tool with no structured output, nothing an agent needs to interpret results is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description exceeds that by explaining cross-parameter interaction the per-parameter schema text doesn't: minUsd drives the `dust` bucket, maxTokens caps token rows and on EVM counts the native coin as one of them while Sui does not, and includeTokens is a no-op on Sui.

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 is precise: an address's balances on ONE chain, native via eth_getBalance plus ERC-20 via the Ankr indexer, and it even carves out the Sui special case. That is a specific resource with a clear scope. What it does not do is differentiate itself from near-siblings such as getAccountBalance or getTokenHolders, so an agent must infer the distinction.

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?

Defaults and tuning knobs are stated ('top 20 by default; tune with maxTokens/minUsd'), which implies when each parameter matters, and the Sui paragraph effectively says when the EVM semantics do not apply. However, it never names an alternative tool or states when to prefer getBalances over getAccountBalance/getTokenHolders. Usage is inferable but not explicit.

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/openWorldHint, so the safety profile is covered. The description adds real behavioral context beyond that: Tier 2 drops verbose header roots and bloom, includeTxs ABI-decodes and compacts transactions, and a large includeTxs payload can blow the compression budget (watch tier_degraded). These are meaningful operational caveats.

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

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

The purpose is front-loaded and the sentence count is low, but it leans on undefined jargon ('Tier 2', 'tier_degraded', 'verbose header roots and bloom') that an agent cannot resolve from the definition itself, costing clarity per word.

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 carry return-shape burden; it gestures at tiering and degraded mode but never explains the response structure or where tier_degraded lives. It is adequate for a read tool with full param coverage, but the unexplained tier machinery leaves an agent unsure how to act on the caveat.

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 value the schema lacks by enumerating the actual tag values (latest, finalized, safe, earliest, pending) and by clarifying the Sui meaning of 'block' as a checkpoint number or digest. That goes beyond the schema's generic 'a tag' wording.

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

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

The description opens with a specific verb+resource ('Get a block') and enumerates the accepted identifiers (hash, number decimal/0x-hex, tags latest/finalized/safe/earliest/pending), which cleanly separates it from getTransaction and rpcCall. It is clear and self-contained, though it does not explicitly name a sibling it is not.

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 implicit when-to-use guidance: use the tag forms for canonical blocks, use Sui's checkpoint semantics for that chain, and check tier_degraded when a block with includeTxs is large. But it never states when to prefer this over rpcCall or getTransaction, so usage is inferred rather than directed.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety profile. The description adds the indexer source (Ankr Advanced API) and cross-chain constraint, but does not describe return format, pagination, or indexing latency. With annotations carrying the safety burden, a 3 is appropriate.

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 purpose. Every sentence earns its place: purpose, input constraint, and workflow positioning. No waste.

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

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

For a simple read-only tool with one parameter and no output schema, the description covers purpose, input scope, and usage context. It leaves the definition of 'interacted with' vague, but that 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 coverage is 100% for the single address parameter, so baseline is 3. The description adds meaningful context by stating 'Cross-chain, so there is no chain argument,' which explains the parameter set and prevents an agent from attempting to pass a chain filter, going beyond what the schema 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 'List' and resource 'blockchains an address has interacted with'. Distinguishes from siblings by noting it is cross-chain with no chain argument, unlike per-chain balance or activity tools. An agent can select it correctly 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?

Provides clear context: 'Useful as a first step before fetching balances or activity per chain,' implying workflow and alternatives. No explicit when-not-to-use or named sibling, so it falls short of a 5.

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

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

Annotations only cover readOnlyHint/openWorldHint, but the description adds substantial behavior: Tier 2 output shape {contract,event,args}, raw fallback with _event_unknown, the tier_degraded warning, ascending chunking with cursor and range_fully_scanned/note, the more_available vs full_count distinction, and liability to tier 0 on unbounded ranges. This is far beyond what annotations provide.

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

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

Front-loads purpose, then tiers, then chunking behavior, then Sui specifics. Dense and mostly information-bearing, though sentences are long and the Sui paragraph could be tightened; still no dead weight.

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

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

No output schema exists, so the description carries the return-shape burden and does so thoroughly: log tuple structure, undecodable fallback, tier_degraded, cursor, note, more_available, full_count, plus Sui row fields (checkpoint/digest/index). An agent has what it needs to call and interpret results.

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 cross-parameter semantics the schema lacks: address as package[::module] on Sui, fromBlock required for Sui, topics refused on Sui, and maxLogs bounding upstream fetch as well as display. It meaningfully supplements the parameter docs.

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

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

States a specific verb and resource (retrieve event logs on one chain, filtered by address/topics/block range) and immediately distinguishes the two operational modes. An agent can tell this apart from getTransaction, getBlock, or rpcCall 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?

Explains the conditions that select chunked scanning versus a single unbounded eth_getLogs call, and details the Sui path (checkpoint range, required fromBlock, topics refused). It does not name an explicit alternative tool (e.g. rpcCall) for arbitrary getLogs use, so routing is inferable rather than 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 declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds real behavioral context beyond them: the data comes from an indexer (implying indexed/lagging rather than direct chain state) and results are paged via pageToken, which the agent must know to iterate.

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 with the purpose front-loaded, followed by the returned field list and pagination note. No filler, no restatement of the title or name.

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

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

With no output schema, listing the returned fields (collection, name, token id, contract, standard, image) is valuable and largely compensates. Remaining gaps are minor: no note on whether results are exhaustive, how ENS names resolve across the 25 chains, or failure behavior.

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

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

Schema coverage is 75% (address, pageSize, pageToken are all described; chain is an enum). The description only reinforces pageToken ('Paged via pageToken') and implicitly chain; it adds essentially nothing about pageSize or address format beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb+resource (NFTs owned by an address on a chain) and enumerates the returned fields, so the agent can immediately distinguish this from getBalances or getTokenHolders. It does not explicitly name or contrast any sibling, which is the only thing separating it from a 5.

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

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

There is no guidance on when to use this versus siblings like getTokenHolders, getWalletActivity, or getBalances, nor any stated prerequisites or exclusions. The 'via the Ankr Advanced API indexer' phrase hints at a data source but does not tell the agent when that source is appropriate.

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 and openWorldHint, so safety is covered. The description adds real behavioral context beyond that: the returned payload (holder address with balance, total holder count, token decimals) and pagination behavior ('Paged via pageToken'). It does not mention rate limits or indexer staleness, but the added disclosure is meaningful.

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 front-loaded with the resource, then return fields, then pagination; nothing is wasted. It is slightly packed but every clause carries information.

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

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

With no output schema, the description carries return-value duty and does so by listing the payload fields, and it covers pagination for a paged endpoint. The only gap is the lack of any hint about ordering or limits on how holders are ranked, which for a read-only indexed query is a minor omission.

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 75%, with pageSize, pageToken and contractAddress documented inline, and chain self-documenting via a 25-value enum. The description only echoes pageToken for pagination and adds no syntax or constraints beyond the schema, so the baseline 3 for high coverage is appropriate.

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

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

The description states a specific resource (holders of an ERC-20 token contract on a chain) and even names the backing indexer, so an agent knows exactly what it retrieves. It does not explicitly differentiate itself from siblings like getBalances or getWalletActivity, but the resource is distinctive enough to be inferred.

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

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

There is no when-to-use guidance and no mention of alternatives; the agent is left to infer that this tool is for enumerating token holders rather than for account balances (getBalances) or transfers (getLogs). Pagination is noted, but no conditions for picking this tool over siblings are given.

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

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

Annotations only declare readOnlyHint and openWorldHint, so the description carries the real behavioral burden and does so well: it discloses the staleness/lag semantics of as_of, and the non-obvious fact that native-coin queries are priced through the wrapped token, which explains a field value that would otherwise look wrong.

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

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

Front-loaded with the core purpose, then the mode selection rule, then the return shape, then the one genuinely surprising semantic detail. No filler sentences; each one carries unique 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 inlines the response shape and the meaning of as_of, which is what an agent needs before reporting a number. It does not cover failure/unpriced-token behavior or how fresh a price is expected to be for a typical chain.

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 parameter meanings are already documented. The description still adds value by explaining why contractAddress is left empty and what happens internally in that case. It does not mention the deprecated `blockchain` alias that the schema flags.

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

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

States a specific resource (USD price of a token) with an explicit scope constraint (on one blockchain), which cleanly separates it from getTokenPriceHistory and getBalances. An agent knows exactly what it gets back: one spot price, not a series or a portfolio.

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

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

Gives concrete conditional usage: pass a contract address for an ERC-20, omit it for the native coin. It also directs the agent to read as_of before reporting a price. It stops short of naming alternatives (e.g. getTokenPriceHistory for time series), so it is clear but not fully routed.

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

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

Annotations only declare readOnlyHint and openWorldHint; the description goes well beyond by disclosing the response contract: `limit_applied`, the default 100 / max 1000 cap, and the crucial fact that there is NO continuation token, so `possibly_truncated: true` is the only truncation signal and a clipped series is indistinguishable from a complete one. This is exactly the non-obvious behavior an agent needs to avoid reporting partial data as full history.

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 resource and return shape, then the truncation caveat. It is dense but nearly every clause carries distinct information; the single long paragraph slightly buries the truncation warning rather than giving it its own line.

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

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

There is no output schema, so the description carries the full burden of return values, and it delivers: the quote fields, the metadata fields (`limit_applied`, `count`, `possibly_truncated`), and how to interpret them. Nothing an agent needs to call and correctly interpret this tool 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 83%, so the schema already documents most parameters (baseline 3). The description adds meaning beyond it by tying `limit` to the observed `limit_applied` value and to the truncation flag, and by framing `fromTimestamp`/`toTimestamp` as the manual paging mechanism in place of a cursor.

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

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

The description states a specific verb and resource: historical USD price series for a token contract on a chain, with the exact quote shape ({ timestamp, usd, block }). 'Historical' implicitly separates it from the getTokenPrice sibling, but the description never names that sibling or states the contrast explicitly, so an agent must infer the routing.

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 real operational guidance on what to do with a clipped result (raise `limit` or walk `fromTimestamp`/`toTimestamp`), which is actionable. However it offers no when-to-use/when-not guidance relative to getTokenPrice or other price-related siblings, so the alternative-selection dimension is missing.

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/openWorldHint, so the description carries the rest and does so well: default receipt fetching, the cost trade-off of `include`, the tier_degraded caveat, the exact shape of tier-2 fields including decimal-string numerics and EIP-55 checksummed addresses, and the Sui digest path. This is meaningful behavior disclosure beyond structured data.

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

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

Front-loads the core purpose, then the cost/`include` guidance, then the return-field contract. Every sentence carries information, though the enumerated tier-2 field list is dense and slightly dump-like in a single block.

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 present, the description must describe the return shape, and it does — field names, value formats, log object variants, and the unknown-event fallback. Combined with the include semantics and Sui exception, an agent has everything needed to call and interpret this tool.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds value the schema lacks: that `include` controls cost (halving it) and is ignored on Sui, and that txHash is a digest on Sui. It reinforces the default ("all") documented in the schema rather than merely repeating it.

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+resource ("Get a transaction by its hash on one blockchain") plus a scope qualifier (tier-2 decoding requested). This is clearly distinguishable from sibling read tools like getBlock, getLogs, and rpcCall, which an agent can rule out 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 concrete operational guidance: the receipt is fetched by default, set include="transaction" to skip it and halve cost, and check tier_degraded before reading function/args. It also notes Sui ignores `include`. It stops short of explicitly naming an alternative tool or stating when another sibling should be preferred.

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

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

Annotations only cover readOnly/openWorld, so the description carries the rest and does so well: item shape, RAW WEI warning, selector-is-not-a-name, omit-rather-than-guess, and the time.iso/time.iso_unavailable contract. These are exactly the data-contract facts an agent needs to avoid downstream errors.

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 each sentence conveys contract information, so the length is largely earned given there is no output schema. It is dense and slightly repetitive in emphasis ('RAW WEI, not ether and not token units'), and the 'no second alias key' aside reads as defensive, minor deductions.

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 thoroughly covers return values, which is the main completeness burden. It leaves the pagination mechanism unexplained (the schema exposes only pageSize, yet 'every continuation' is referenced) and says nothing about auth or rate limits for an openWorld indexer call.

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 chain/address/pageSize are already documented, and the baseline is 3. The description adds no parameter-level meaning beyond what the schema states (it never addresses pageSize semantics or chain slug format directly).

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

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

The first sentence gives a specific verb, resource, and scope: recent transactions for one address on one chain, newest first. That framing inherently distinguishes it from getTransaction (single tx), getInteractions, and getLogs, so an agent can route without opening another 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?

Usage is implied by the stated scope rather than stated outright. There is no explicit when-to-use vs alternatives (getTransaction, getInteractions) and no pagination/continuation guidance, though the Sui note ('transactions SENT BY the address') is a useful invocation caveat.

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 and openWorldHint; the description adds substantial behavioral context — TORPC tier-2 compression behavior, which chains pass through unchanged, and that suiChains are shaped in-server with _meta.tier/tier_source indicating what was applied and by whom. That is genuine value beyond the annotations, though much of it covers sibling tools rather than listChains' own output.

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

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

The opening sentence is well front-loaded, but the body drifts into extended detail about raw-RPC reach, suiChains, and TORPC compression tiers that belongs more to those sibling tools than to a chain-listing call. It is informative but overlong relative to the simplicity of a no-argument discovery 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?

With no input/output schema, the description must carry the meaning of the return values, and it does so by defining exactly which chains appear and how they relate to the rest of the server. An agent has enough to decide whether to call it and how to interpret the list, even if the tier/compression detail is more than the tool strictly needs.

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 are no argument semantics to document; the baseline for a 0-param tool is 4. Nothing in the description contradicts or omits parameter information.

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 chains where the Ankr Advanced API indexer is available (token balances, NFTs, holders, transfers, prices). This scope is concrete and lets an agent distinguish it from searchChain and the raw-RPC siblings. The core purpose is slightly buried under later caveats, but it is clearly 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?

The description explicitly clarifies what the list governs (indexer/Advanced-API support) versus what it does not (getTransaction, getLogs, getBlock, rpcCall reach 200+ chains regardless), which routes the agent correctly. It gives clear context for when to consult this list, though it stops short of an explicit 'use this when you need to know whether a chain supports getTokenHolders' style instruction.

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, openWorldHint), and the description adds real context beyond them: the underlying eth_getCode/eth_call/eth_getStorageAt passthrough, and the caveat that token metadata is best-effort and may be absent on non-standard contracts. It does not discuss latency, rate limits, or failure behavior for unreachable chains.

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 outcome and followed by implementation and reliability caveats. Every sentence carries information an agent needs; nothing is 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 carries the return-value burden and does so: it names the three result categories and warns that metadata may be missing. For a two-parameter read-only tool with annotations covering safety, 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 both parameters (chain slug with the listChains pointer, and 0x-prefixed address) are fully documented in the schema. The description adds only the framing 'an address on a chain' and no format or edge-case 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 (inspect/resolve) and resource (an address on a chain) and enumerates exactly what it determines: contract-vs-EOA, ERC-20 metadata, and EIP-1967 proxy implementation. This distinguishes it from siblings like rpcCall, getAccountBalance, or getNFTs, which do not do address classification.

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

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

Usage is implied by the enumerated outputs — an agent can infer 'call this when you need to know what an address is' — but there is no explicit when-to-use, when-not-to-use, or named alternative (e.g. versus rpcCall for raw eth_getCode).

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/openWorldHint; the description goes far beyond by enumerating the refusal boundary (broadcast/signing, transaction building, admin/dev namespaces, mutating verbs, dot-namespaced wallet families), disclosing TORPC tier negotiation with contract 2 and _meta.tier, the Sui gRPC bridging rule, and that a forwarded read may still return "Method disabled, reason: restricted by blockchain schema" as the authoritative answer.

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: the what and the routing advice come first, with the long refusal enumeration pushed after. The mid-paragraph parenthetical is dense, but for a tool with an unbounded method space each refusal category carries distinct information, so the length is largely earned 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?

No output schema exists, and the description supplies what an agent needs to act: tier semantics and where to read the negotiated value, the refusal-error shape, per-chain-family constraints, and pointers to listChains/describeMethods for the discovery this tool deliberately does not internalize.

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 parameters are already documented and baseline is 3. The description adds genuine meaning for `tier` (negotiated per call, contract 2, inspect _meta.tier) and clarifies the escape-hatch nature of `chain`/`method` via listChains and describeMethods, exceeding what the schema alone 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?

"Call ANY JSON-RPC method on a supported chain: the escape hatch beyond the routed tools" gives a specific verb plus resource and immediately positions it relative to the sibling suite (getTransaction/getLogs/getBlock, describeMethods, listChains). An agent can tell in one sentence that this is the raw fallback rather than a routed convenience 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?

Explicit routing guidance: "Prefer getTransaction/getLogs/getBlock where they fit," "describeMethods says which are bridged," and "Call listChains for coverage." It also states the negative space in detail (what is refused, on which chain families), so both when-to-use and when-not-to-use are covered.

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

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

Goes well beyond the readOnlyHint/openWorldHint annotations by disclosing fallback behavior (tx hash falls back to block hash), tier-2 decoding for tx/block vs passthrough for addresses, the eth default, and the exact failure kinds (kind:"unknown", kind:"ens") with reasons. An agent knows precisely what this will and won't do before invoking.

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 resolution rule, then structured bullets for shape mapping and unsupported inputs. Every sentence earns its place, though the ENS limitation is stated twice (in the unsupported paragraph and again implicitly in the schema), a minor 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 compensates by describing the return kinds and the contract-vs-EOA distinction. Combined with the covered schema, an agent has everything needed to call this correctly and interpret the result.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it specifies the exact query formats accepted, the fallback semantics for ambiguous 0x hex, and that chain defaults to eth. This is more than the schema conveys on its own.

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 (resolve) and resource (on-chain identifier) and immediately enumerates the three accepted shapes, which cleanly separates it from siblings like getTransaction, getBlock, and resolveContract. An agent can tell what this tool does and does not handle 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 defines the when-to-use conditions (0x+64 hex, 0x+40 hex, all digits) and the when-not-to-use cases (tickers, names, labels, ENS), with a directive to get a contract address another way first. It stops short of naming the specific sibling that should be used instead (e.g. resolveContract), which is the only gap.

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

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

With readOnlyHint and openWorldHint already declared, the description adds genuinely non-obvious behavior: the response is complete and never truncated or paginated, and non-declared names are refused by the node rather than approximated (a real failure-mode disclosure). It does not cover auth or rate-limit behavior, so it earns solid but not maximal credit.

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, purpose front-loaded, and every sentence carries distinct information (payload contents, completeness guarantee, input provenance and error semantics). The first sentence's long em-dash clause is dense but not wasteful.

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

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

There is no output schema and no annotation-driven pagination safety net, yet the description compensates by enumerating the returned fields and guaranteeing no truncation or paging, plus the error path for unknown names. Only the input format details and any auth expectations are omitted.

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

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

Schema coverage is 0%, so the burden falls on the description, and it only partially compensates: it tells the agent to source `package` and `module` from suiGetPackage, but the `function` parameter and the regex constraints on all three fields remain unexplained. Useful provenance for two of three params, but incomplete against a 0% coverage gap.

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

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

States a specific verb and resource — fetching one Move function's signature — and enumerates exactly what the signature contains (visibility, entry flag, type parameters, parameter types, return types). It even frames the payload's purpose ('what a programmable transaction block needs in order to call it') and names the sibling suiGetPackage as the source of input names, so it is distinguishable from neighboring 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?

Gives clear context and a prerequisite: 'Take the package and module names from suiGetPackage,' which routes the agent correctly through the sibling set. It also states the failure condition for unknown names. It stops short of an explicit when-not-to-use or an alternative tool for a different query shape, 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?

Annotations already cover read-only and open-world hints, but the description adds substantial context beyond them: batch size limit, no-trimming/no-cursor behavior, positional failure reporting under 'failed' with request index and gRPC status, and confirms reads only. This is exactly the extra value the annotations don't provide.

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 action and scope, then covers batch limits and failure semantics efficiently with no wasted words. Every clause (batch, 50 limit, no trim, failed array, reads only) 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 explains the response shape (id, type, version, owner, decoded Move fields under 'json') and error handling (positional 'failed' entries). For a 2-param read tool with annotations covering safety, 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 'ids' and 'version' are fully documented in the schema. The description confirms the 50-id limit and positional failure behavior, which aligns with the schema, but adds no syntax or format detail beyond it. Baseline 3 is appropriate.

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

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

States a specific verb+resource ('Move objects by id') and adds scope detail (batch, up to 50, no cursor). It clearly distinguishes from siblings like suiListOwnedObjects (which lists owned objects) by framing this as direct id lookup with positional failure reporting.

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 batch nature and 50-id limit imply when to use this versus single-object siblings, and the 'no cursor' note clarifies a boundary condition. However, no explicit alternative is named for single-id reads or when a cursor-based listing is preferable.

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 readOnly/openWorld annotations, it discloses real behavioral traits: the whole package is never returned (0x2 framework ~484 KB), there is no upstream paging so a truncated index carries no cursor, and repeated addresses arrive as `$n`/`@n` handles resolved by side tables. These are exactly the operational caveats annotations cannot convey.

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

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

Five dense sentences that are largely front-loaded and each carries information (output shape, cap, escalation, size limit, handle resolution). The opening clause 'so a caller can pick what to inspect next' is slightly indirect, but 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?

With no output schema, the description still characterizes the return shape (index rows vs full module contents) and discloses the truncation/no-cursor limitation plus the maxModules-to-module-to-suiGetFunction escalation. For a read-only, three-parameter tool this is complete enough to invoke 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 only 33%, so the description carries most of the burden: it explains `module` (returns that module in full with every signature and datatype) and `maxModules` (raises the cap, ignored when `module` is given). It also touches handle resolution relevant to `package`, but does not spell out what the `package` value must be (package ID vs object ID), leaving a small gap.

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

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

The description states precisely what the tool yields: an index of modules with names and function/datatype counts by default, or one module's full function and datatype declarations when `module` is passed. It differentiates from the sibling suiGetFunction ('suiGetFunction for a single signature') so an agent can route without opening a schema.

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

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

It gives an explicit escalation path: use the default index, raise `maxModules` past the 50-row cap, pass `module` for full detail, and drop to suiGetFunction for a single signature. This is a clear when-to-use ladder with a named alternative, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so 'Reads only' is largely redundant, but the description adds real behavioral context: the value is a BCS blob deliberately omitted from the response, default page size is 50 and capped at 200, and a cursor covers the remainder. That is disclosure beyond what the annotations supply, though return format is described only in outline.

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 and scoping are front-loaded in the first clause, and pagination plus the value-omission caveat follow efficiently. The prose is somewhat ornate ('and 200 at the outside') and a couple of clauses could be trimmed, but every sentence carries information.

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

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

With no output schema, the description carries the return-shape burden and does so: a row names the field's object id, kind, keying name and Move value type, and it explains that the value is withheld and how to retrieve it. Pagination and default limits are also covered, so an agent can call and consume this correctly.

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

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

Schema description coverage is 100%, so both parameters are already documented, including the parent id pattern and the 50/200 page-size constraint. The description restates these rather than adding syntax or format 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 and resource ('Whatever a Move package stored under one object's UID: tables, bags and dynamic object fields, listed from the parent id') and by naming suiGetObjects as the tool that returns decoded values, it disambiguates itself from that sibling without the agent needing 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 routes the agent: this tool lists field ids/kinds/names, and 'hand that field id to suiGetObjects and it comes back decoded' names the alternative and the condition that selects it. The scope ('from the parent id') further clarifies when this is the right call.

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 and openWorldHint, and the description reinforces with 'Reads only.' It adds real behavioral context beyond annotations: pagination defaults (50/200), cursor behavior, and that the source is the node's own owner index rather than a global indexer.

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

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

Front-loaded with the purpose, then the type-filter semantics, then pagination, then the read-only note. Dense but every sentence carries usable information with 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 does the work of describing the return page shape, size, and cursor hand-off to expandResult. It stops short of naming the returned fields, but covers enough for correct invocation.

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 genuine meaning for the type parameter: a bare Move type matches any type parameter while a fully applied one matches only that instantiation. This goes beyond the schema's 'with or without its type parameters.'

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

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

States a specific verb+resource (list owned objects) and clarifies the data source: 'out of the node's own owner index.' It is clearly distinguishable from suiGetObjects (fetch specific objects) and positions expandResult as the pagination companion.

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?

Explains the type-narrowing use case with a concrete example and routes the agent to expandResult when more pages exist. It doesn't explicitly contrast against the sibling suiGetObjects, so the when-not condition is left implicit.

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

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

Annotations only cover read-only and open-world traits, yet the description discloses substantive behavior: the four possible `status` values with their meanings, the warning that an expired record's target address must not be trusted, the counter-intuitive fact that reverse resolution returns the address's own default name, and that results are never capped or paged. This is exactly the kind of context annotations cannot provide.

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

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

Front-loaded with the core action, then a compact block on the status field's interpretation. Every sentence adds information the agent needs — status semantics, the forward/reverse asymmetry, and the absence of pagination — with 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?

There is no output schema, so the description bears the burden of explaining what comes back, and it does: a single uncapped record plus the `status` discriminator that governs how to read it. An agent can call this correctly and interpret the response from the description alone.

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

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

With 0% schema description coverage the description must carry the load, and it does add the mutual-exclusivity rule ('exactly one of name or address') that the schema cannot express since both properties are optional. It reinforces the .sui suffix restriction, though it leaves the hex address format to the schema pattern.

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 (resolve) and resource (SuiNS name / address) and covers both directions of the mapping. It also scopes the domain explicitly with 'Only .sui names', which separates it from the sibling resolveContract tool.

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

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

Gives a precise invocation rule — 'Give exactly one of `name` or `address`' — and instructs the caller to read `status` before trusting the record. It does not name an alternative tool or state when to prefer it over siblings such as resolveContract, 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?

Goes well beyond the readOnlyHint/openWorldHint annotations: it discloses that nothing is broadcast, that the server cannot reach Sui's execute RPC at all, that no signature is accepted, and precisely which fields the report contains. This is the kind of safety and behavior detail an agent needs before calling a transaction-simulation 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?

Front-loaded with the core action and the result payload, then the input contract, then the no-broadcast guarantee. Every sentence carries information, though the middle sentence is dense with a long enumeration of reported fields that could be trimmed 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?

There is no output schema, so the description must carry the return-value burden — and it does, itemizing abort location, gas, created/mutated/deleted objects, per-address balance changes, decoded command return values, and emitted events. Combined with the input contract and safety notes, 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?

Only one parameter and schema coverage is 100%, so the schema already documents the base64 BCS TransactionData format, pattern and length bounds (baseline 3). The description adds non-schema meaning — that it is the exact argument sui_dryRunTransactionBlock takes and that no signature is required or accepted — which nudges it above baseline.

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+resource ('Run a transaction against current state') and enumerates exactly what it reports: success/abort, gas, object mutations, balance deltas, return values, events. It also names a sibling (expandResult) and an equivalent (sui_dryRunTransactionBlock), so an agent can place it precisely among the other Sui 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?

Clearly states the operating context: it takes the same base64 BCS TransactionData a wallet/SDK produces, accepts no signature, and never broadcasts. It names expandResult as the alternative for raw/unshaped output. It lacks an explicit 'when not to use this vs suiGetObjects/rpcCall' statement, but the context 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?

Annotations only declare readOnlyHint and openWorldHint; the description adds the critical non-obvious trait that nothing is pushed and the first call returns NO events while establishing a cursor, plus cap semantics (50 default, 1000 max, more_available means poll again immediately). This is exactly the behavioral detail 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?

Dense but every sentence carries load: purpose, polling model, cursor handoff, sibling contrast, filters, cadence, cap behavior. Purpose is front-loaded in the first clause with no 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?

With no output schema, the description fully covers the return contract: first call returns no events plus a cursor, expandResult enumerates what accumulated since, and more_available signals the cap was hit. An agent has everything needed to drive the poll loop 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 address, sender, eventType and maxLogs are already documented at the schema level. The description largely restates them, adding only the useful note that row and body keys match getLogs; baseline 3 is appropriate since 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 (follow Sui Move events by polling) and immediately contrasts with the sibling getLogs, which it explicitly says scans a named checkpoint range. An agent can distinguish the two 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 (continuous following with no gaps) and when-not-to-use (getLogs for a fixed range), plus a concrete polling cadence tied to Sui's ~4 checkpoints/second and a rule for reacting to more_available. Nothing about selection is left to inference.

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