Block402

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

The description discloses the most important non-schema behavior: the call costs 0.002500 USDC on Base mainnet, which also explains why readOnlyHint is false despite the 'Read' framing. It further instructs that the private idempotencyKey must be preserved for retries, aligning with idempotentHint=true. It stops short of describing rate limits or exactly which chain endpoint is hit.

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

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

Three short, front-loaded sentences with no filler: identity/cost first, then the retry caveat. The machine-readable CAIP identifiers are dense but pay for themselves by naming the exact chain and payment network.

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 comes back (the hash of the current best block) but does not. Cost and idempotency coverage is adequate for a zero-argument paid call, so the missing return-value meaning is the main 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 50%; the idempotencyKey is already fully documented in the schema (private, persist before payment, reuse only for retries), so the description's retry note largely restates it. The unexplained 'params' parameter is an empty maxItems-0 array, which the description never clarifies must be empty.

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 verb ('Read') and a resource ('getbestblockhash') plus the chain identifier, but 'getbestblockhash' is essentially the tool name restated, so the agent gets little semantic meaning (that it returns the tip block's hash). It does not differentiate from the nearby sibling bitcoin_getblockhash, which is a plausible confusion point.

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 statement of when to use this tool versus the many sibling block/hash lookups. The only conditional guidance is about retry behavior with the idempotencyKey, which is operational rather than a selection criterion.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and openWorldHint=true, but the description adds real value beyond them: the exact cost (0.005 USDC on Base mainnet) and the instruction to preserve the idempotencyKey across retries. That explains the payment-driven non-read-only profile. It still omits what a successful call returns.

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

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

Three tight sentences with no waste, and the operational essentials (cost, idempotency) are front-loaded after the resource. The opening 'Read getblock' phrasing is slightly redundant with the name but costs little.

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

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

For a paid, non-read-only tool with positional array parameters, the description never explains the argument structure or the returned block payload, and there is no output schema to fall back on. The cost/retry context is good but the call itself remains under-specified.

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 50% and the two positional array items (a 64-hex block hash and a 0/1 verbosity flag) carry no descriptions in either the schema or the description. An agent must guess that item 1 is a block hash and item 2 is verbosity; the description compensates for none of this 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 the verb 'Read' and names the method 'getblock' on Bitcoin, plus the chain id, but 'getblock' merely restates the tool name and no detail is given about what block data is returned. It does not differentiate from close siblings like bitcoin_getblockheader, bitcoin_getblockhash, or bitcoin_getblockcount.

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 statement of when to use this tool versus the many sibling block/transaction methods. It only gives a cost figure and a retry hint, leaving selection entirely 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?

The description adds real context beyond the annotations: the exact USDC cost and network (Base mainnet), and explicit retry behavior via the idempotency key. It discloses that money is spent, which explains why readOnlyHint is false. It still omits what happens if payment is insufficient or the response shape, but the disclosure is genuinely useful.

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

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

Three short, front-loaded sentences with no filler; cost and idempotency are stated crisply. The opening clause is slightly tautological ("Read getblockcount") but the size is appropriate for 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?

There is no output schema, so the description carries the burden of telling the agent what the call yields, and it never does — it does not say the result is the current block count/height. It covers network, cost, and idempotency, but for a read method returning data this is a meaningful gap.

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

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

Schema coverage is 50%. The documented idempotencyKey is reinforced by the description's "Preserve the private idempotencyKey for retries," which is helpful. The `params` array is an empty, unbounded-nothing structure that needs no explanation, so the schema plus the description adequately cover the real inputs; no additional meaning is added beyond the schema though.

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

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

The description gives a verb ("Read") and identifies the resource/network ("getblockcount from Bitcoin"), so the agent knows it is a Bitcoin read method. However, it never explains what getblockcount actually returns (the current chain height/block count), leaving the resource name as a cryptic restatement of the tool name. It differentiates the chain from the Ethereum siblings but not from the Bitcoin siblings sharing the same family.

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 tool versus the other Bitcoin methods (getblock, getbestblockhash, getblockhash) or the Ethereum equivalents. It also omits any prerequisite/eligibility context even though it costs money. The only actionable hints are the cost and idempotency note, not usage routing.

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

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

Annotations declare openWorldHint, idempotentHint and destructiveHint=false, so the safety profile is largely covered. The description adds genuinely new behavioral context the annotations do not: the exact cost (0.002500 USDC on Base mainnet), the settlement network, and the requirement to persist the private idempotencyKey for retries. The only mild tension is the word "Read" against readOnlyHint=false, but the disclosed payment explains that flag.

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

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

Three short, front-loaded sentences with no filler: action, cost, and idempotency handling. Tight and well-ordered, though extremely terse given how little semantic content it carries.

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

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

For a paid RPC tool with no output schema, the description handles the payment/idempotency contract well but omits what the call returns (a block hash) and what the sole data parameter represents. An agent knows how to pay and retry but not what to pass or expect back.

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 50%: idempotencyKey is fully described in the schema, but the actual params array (a single 0..100000000 integer) has no description anywhere. The description says nothing about what that integer means (block height), so it fails to compensate for the 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?

"Read getblockhash from Bitcoin" restates the tool name with a generic verb rather than explaining what the method does (return the block hash for a given block height). It adds the chain identity, but an agent that does not already know the Bitcoin RPC name learns nothing about the purpose. No differentiation from siblings like bitcoin_getbestblockhash or bitcoin_getblockheader.

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 tool versus the many sibling block/header/hash methods. The description covers payment and idempotency mechanics, but nothing helps an agent choose this tool over bitcoin_getbestblockhash or bitcoin_getblockheader.

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 safety/idempotency (destructive=false, idempotent=true, openWorld=true), and the description adds genuinely useful context beyond them: a concrete cost (0.002500 USDC on Base mainnet) and the instruction to preserve idempotencyKey across retries. The readOnlyHint=false is explained by the paid nature of the call. It stops short of describing the return payload, but no output schema exists so this is a moderate gap.

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

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

Three short, front-loaded sentences with no filler; the cost and idempotency notes each carry actionable information. The opening clause is the weakest since it largely echoes the name, but the rest is tight.

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

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

For a tool with no output schema and an undocumented `params` array, the description should explain what the array elements mean and ideally what a block header contains. It covers payment and retry semantics well but leaves the core input shape unexplained, which is a meaningful gap.

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

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

Schema coverage is only 50%: idempotencyKey is fully described, but the `params` array (a 64-char hex hash plus a boolean) has no item-level descriptions. The description text says nothing about the array's structure or what the boolean controls (verbosity), so it fails to compensate for the 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?

"Read getblockheader from Bitcoin" essentially restates the tool name rather than defining what a block header is or what the tool returns. It identifies the chain (via CAIP id) but does not distinguish it from siblings like bitcoin_getblock, bitcoin_getblockhash, or bitcoin_getbestblockhash.

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 tool over bitcoin_getblock (full block) or bitcoin_getblockhash (hash only). The only usage hint is the retry note tied to idempotencyKey, which is about re-invocation, not tool selection.

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

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

Annotations only give generic hints (readOnlyHint=false, idempotentHint=true); the description adds concrete context the annotations cannot: a fixed 0.005 USDC cost on Base mainnet and the requirement to preserve the idempotencyKey for retries. This meaningfully explains the paid-call and retry behavior, though it does not say what happens if the key is reused incorrectly or what the response looks like.

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

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

Three short sentences, each front-loaded and free of filler; cost and idempotency guidance appear immediately. The opening clause is somewhat tautological with the method name, but the chain identifier makes it earn its place.

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

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

For a paid read-only RPC wrapper with no output schema, the description covers cost and retry semantics but omits the shape of the params tuple and what data is returned. An agent knows how to pay but not fully how to construct the 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 coverage is only 50%: the idempotencyKey is documented in the schema itself, and the description merely repeats that ('Preserve the private idempotencyKey for retries'). The three-element params array (txid hex, const verbose=false, blockhash) is undocumented in both schema and description, so the description fails to compensate for the 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?

The description names a specific verb (Read) and resource (getrawtransaction) and pins the network with the bip122 genesis identifier, so an agent can tell it apart from the ethereum_* siblings and the other bitcoin_* tools. It is clear, though 'Read getrawtransaction' partly restates the tool name rather than describing the resource in plain terms (a raw transaction by txid).

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 statement of when to use this tool versus alternatives such as bitcoin_gettxout or the block-oriented siblings. The only operational guidance is about payment and retries, which is not tool-selection guidance.

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

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

Annotations give the safety profile (idempotentHint=true, destructiveHint=false, openWorldHint=true), and the description adds genuinely non-redundant behavior: the 0.005 USDC cost on Base mainnet and the requirement to preserve the private idempotencyKey across retries. This financial side effect also implicitly explains why readOnlyHint is false despite the read semantics. It stops short of noting auth/payment failure modes or what the call returns.

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

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

Three short sentences, front-loaded with the operation and chain, followed by cost and retry guidance. Nothing is padding, though the leading sentence is near-tautological with the name.

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

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

With no output schema, the description should ideally say something about the returned data and clarify the positional params, neither of which it does. It covers payment and retry semantics well for a 2-param read tool but leaves the core argument semantics unexplained.

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

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

Schema description coverage is only 50%: the three positional items in `params` (64-hex txid string, 0-100000 integer index, include_mempool boolean) carry no descriptions, and the description does not compensate. It only echoes the idempotencyKey guidance already present in the schema, so an agent must infer the meaning and order of the three positional arguments unaided.

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

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

"Read gettxout from Bitcoin" largely restates the tool name rather than explaining what the method does (look up a transaction output / UTXO by txid and index). The chain identifier (bip122:...) is useful context, but there is no differentiation from sibling reads like bitcoin_getrawtransaction, and an agent unfamiliar with the RPC name learns nothing about the resource being fetched.

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 conveys cost and idempotency-key retry discipline, which are usage-relevant, but it never states when to call this versus alternatives (e.g., getrawtransaction) or what inputs the caller must already possess. No when-to-use or when-not guidance is present.

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