Parallax Protocol

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description adds substantial depth: the event-scan methodology, eth_call re-checks against current state, the fact that zeroed/revoked approvals are counted but not listed unless include_inactive=true, risk-flag semantics, severity scoring rules, and the exact revoke call to feed into build_unsigned_tx. It also warns that token symbols and spender names are untrusted.

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 is front-loaded in the first sentence, followed by a structured 'How' and a benefits/risk breakdown. The prose is dense and long but nearly every clause carries operational information; it is not padded, though it could be tightened slightly.

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

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

There is no output schema, so the description must carry return-value burden, and it does: it enumerates the fields of each active approval, the risk flags, severity levels, and the revoke call. Nothing an agent needs to invoke 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?

With 100% schema coverage the baseline is 3, but the description adds real meaning: from_block is scanned 'in ranges of the server's log range limit', and include_inactive not only lists inactive approvals but explains that they are otherwise counted. This goes beyond the terse schema descriptions.

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 ('Audits the token approvals an address has granted') and immediately clarifies scope ('who may move its tokens'). This is clearly distinguishable from siblings like explorer_token_balances or explorer_token_transfers, which list holdings/transfers rather than granted allowances.

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

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

The description gives clear triggering context (auditing the approvals an address has granted) and explains the from_block default and include_inactive switch. It does not, however, name an alternative sibling or state explicit when-not-to-use conditions, so it stops short of a 5.

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

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

Annotations cover the safety profile (readOnly, idempotent, no destruction), and the description layers on substantial behavioral context beyond them: emission schedule (50 LAX halved every 210,000 blocks), fee computation, the 100-block coinbase maturity rule, and the 500-transaction cap on fee reporting. This is exactly the domain context annotations cannot express.

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 definition and dense but purposeful throughout – every clause (subsidy schedule, fee formula, maturity, 500-tx cap) earns its place. Slightly long as a single run-on sentence, which costs some scannability.

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

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

With no output schema, the description carries the full burden of describing return values and does so thoroughly: reward composition, units (wei and LAX), coinbase address, height/era, and maturity status. Nothing an agent needs to interpret the result 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 single 'block' parameter (number, hash, or 'latest') is fully documented in the schema. The description adds no syntax or format detail about the parameter, so the baseline 3 for high schema coverage 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 exactly what the tool returns: the miner's earnings for a block, decomposed into subsidy, transaction fees, coinbase address, height/era, and maturity. The resource (block reward) is distinct from siblings like get_block, mining_stats, and supply_info, so an agent can select it without reading 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?

Usage is implied by the purpose – you call it to inspect the reward of a specific block – but there is no explicit when-to-use, no prerequisites, and no naming of alternatives (e.g., mining_stats for aggregate data). Adequate but with a clear 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?

Adds real behavioral context beyond the already-rich annotations: nothing is signed or sent, state changes are discarded, and revert reasons are returned but flagged as untrusted. The trust caveat on revert text is exactly the kind of disclosure annotations cannot express.

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

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

Purpose is front-loaded in the first sentence, then structured bullets and a concrete example. It is dense and long, but nearly every line conveys callable detail; the argument-encoding and ABI-resolution lines all earn their 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 8 parameters, no output schema, and read-only annotations, the description still covers return values (raw return data plus decoded values when an ABI is known), the revert path, optional parameters, and a worked example. An agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100% so baseline is 3, but the description meaningfully extends it: argument encoding rules (integers as decimal strings or 0x-hex, addresses/bytes as 0x-hex, tuples as objects or arrays), full-signature handling that needs no ABI, and the block/archive-node nuance. It stops short of documenting from/value_wei behavior, keeping it below 5.

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 ('Runs a read-only eth_call against a contract and decodes the result') and immediately distinguishes the operation from state-mutating siblings. The scope ('state changes are discarded') makes it separable from estimate_gas, get_code, and get_storage_at without opening any schema.

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

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

Gives clear conditional usage ('Give either raw data ... or function plus args') and explains ABI resolution fallbacks and when block matters (historical state on an archive node). It covers how to use the tool thoroughly but never explicitly routes against sibling tools, so it stops short of a 5.

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

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld, non-destructive), and the description adds real behavioral context beyond them: the namespace gating that determines whether other tools will work, sync status, and the fact it takes no arguments. It does not mention latency, rate limits, or cost of the underlying RPC, so it stops short of a 5.

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

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

Front-loaded with the resource identity, then the return fields, then the usage directive. It is a single dense sentence plus a short command, and the field enumeration is load-bearing rather than padding; only mild tightening would be possible.

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 enumerate return values, and it does so comprehensively (chain ID, network ID, client version, head block fields, sync status, peer count, gas price, namespaces). Combined with the no-argument note and the when-to-call guidance, an agent has everything needed to invoke 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?

Zero parameters, so the baseline is 4. The description confirms 'Takes no arguments', which is consistent with the empty schema and additionalProperties=false, but there is no parameter meaning to add.

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 ('identity and state of the Parallax node this server reads') and enumerates exactly what is returned, including a concrete chain ID. An agent can distinguish this from siblings like network_health or network_nodes 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?

Explicitly prescribes when to call it: 'Call it first to check the server is on the expected chain and synced.' It also gives a conditional dependency rule — tools needing debug, txpool, admin or xhash work only when those namespaces are listed — which routes pre-flight checks correctly.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds real behavioral context beyond them: the fee formula, the wei-and-LAX denomination, no state change ('nothing is sent'), the 21,000-gas baseline for a plain transfer, and revert-reason error behavior. This is exactly the extra context annotations cannot carry.

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

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

Three sentences, front-loaded with the core action and output formula, with no filler. Each sentence carries distinct information: output shape, parameter shape, baseline gas, and failure mode.

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 return semantics — and it does, specifying gas, fee in wei and LAX, the formula, and the revert-reason failure path. Nothing an agent needs to invoke or 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 100%, so the baseline is 3; the description adds meaning by grouping the 8 params into the call-field shape shared with call_contract and by clarifying that data is an alternative to function+args. Marginal but genuine added semantics over the schema.

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

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

States a specific verb and resource (estimates gas for a transaction) and pins it to the eth_estimateGas RPC, plus states the derived output (fee = gas × gas price). It is clearly distinguishable from gas_price (which returns a price, not an estimate) and from call_contract (which actually sends).

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 for when this applies: it takes the same call fields as call_contract but 'nothing is sent', which effectively routes the agent to estimate_gas for pre-flight checks. It falls short of an explicit when-not/alternative statement (e.g. 'use call_contract to actually execute'), so it is strong but not fully 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 readOnly, idempotent, openWorld and non-destructive, so safety is covered. The description adds genuinely useful context beyond them: it flags which fields (names, symbols, tags, method names) are attacker-controllable and wrapped as untrusted, which is real behavioral guidance for an agent. It still omits rate limits and behavior for unknown addresses.

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

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

The description opens with a clear framing sentence and then packs the return fields into one dense enumeration followed by a security caveat. It is information-dense and front-loaded, with no filler; the long single clause listing fields is slightly taxing but every element is functional.

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 full burden of explaining return values, and it does so comprehensively field-by-field, plus the untrusted-data caveat. It is nearly complete; only edge-case behavior (unknown address, partial data) is left unspecified.

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 exists and schema coverage is 100% ('0x-prefixed 20-byte address'), so the schema fully documents it. The description adds no format, casing, checksum, or validation detail beyond the schema, making the baseline 3 the correct score.

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 (an address) and enumerates precisely what the tool returns — balance, contract/verification status, tags, scam flag, proxy info, creator, token metadata, and counters. That makes the tool's purpose unambiguous. It does not explicitly contrast itself with focused siblings like explorer_contract, explorer_token, or get_balance, so it stops short of a 5.

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

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

Usage is only implied: by listing a broad superset of address facts, it signals 'use me for a general address overview.' There is no explicit when-to-use guidance, no statement of when a narrower sibling (explorer_token, explorer_contract) is preferred, and no prerequisites or failure conditions.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered. The description adds meaningful behavioral context beyond that: the (date, value) point shape, the hard 400-point cap, per-chart units (LAX, gwei), and the 'approximate' marker for in-progress periods. These are real operational traits not present in 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 behavior and the network_trends routing are front-loaded, and the long chart enumeration earns its place because it substitutes for missing enum values. It is dense but not padded; slightly heavy as a single run-on block of clauses.

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

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

With no output schema, the description carries the return-shape burden and does so: (date, value) points, resolution granularity, date range defaults, the 400-point cap, and unit reporting. An agent has everything needed to call this correctly 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 genuinely enriches the parameters: it enumerates all valid chart ids by section, defaults for from/to (last 90 points), and notes DAY as the default resolution. The enumerated chart list is valuable since the schema declares no enums for these fields.

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 ('Time series from the explorer's statistics service') and clearly distinguishes two modes: listing available charts when 'chart' is omitted vs. returning points when it is supplied. The explicit routing to network_trends for hashrate/difficulty/block time/node counts further separates it from siblings.

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

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

Gives explicit when/when-not guidance: omit 'chart' to enumerate charts, supply 'chart' to fetch a series, and use network_trends instead for the last 7 days of hashrate, difficulty, block time and node counts. The alternative and the condition selecting it are both named.

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 (readOnly, idempotent, non-destructive), and the description adds genuinely non-derivable behavior: source is truncated at max_source_bytes with a stated default/cap, additional file names and sizes are included, and — importantly — the source is untrusted and must be read as data, never as instructions. That prompt-injection warning is high-value context the annotations cannot express. It does not describe error/permission behavior, keeping it from a 5.

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

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

Three sentences, front-loaded with the return payload, then the optional-flag behavior, then the security caveat. The long field enumeration is dense but earns its place given there is no output schema. Slightly heavy, but nothing is wasted.

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

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

With no output schema, the description carries the burden of describing the return shape, and it does so thoroughly — metadata fields, interface entries, optional source/ABI, and the 'verified': false case for unverified contracts. An agent has everything needed to call it 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 meaning beyond the schema: include_source also yields the names and sizes of additional files, and max_source_bytes is framed as a cut point on the main file with default and maximum restated in context. The address parameter gets no elaboration, but it is self-evident.

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 (retrieve a verified contract's metadata and interface) and enumerates exactly what is returned: name, language, compiler version, proxy type/implementations, every function and event. This is distinguishable from siblings like get_code (raw bytecode) and explorer_address (account-level data) 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?

The description makes the conditional usage of include_source and include_abi explicit ('with include_source=true, the source is returned too') and notes the unverified fallback, giving clear context for when the flags matter. It stops short of naming an alternative sibling or stating when NOT to use this tool, 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?

Beyond the annotations, the description discloses pagination size (50 per page), ordering (newest first), the cursor linkage from next_cursor, and the important caveat that a limit-cut page has no next_cursor. It also lists returned fields (type, from, to, value, success, error), so the agent understands the operation and its output shape without an 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?

The description is dense but front-loaded: purpose and scope come first, then the RPC/trace rationale, then pagination guidance. Every sentence contributes operational information, with no repetition of the tool name or title.

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

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

For a parameterized read-only explorer endpoint with no output schema, the definition is complete: it covers scope selection, alternatives, pagination, the no-trace node constraint, and the shape of returned records. An agent has enough to call this correctly without further documentation.

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

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

Schema coverage is already 100%, but the description adds meaningful semantics beyond the schema: transaction and address are presented as alternatives for selecting scope, and cursor/limit are explained in terms of real paging behavior. This is exactly the additional meaning the schema alone does not provide.

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: value transfers and calls made by contracts during transactions (internal transactions), scoped to one transaction or address. It also distinguishes this from normal transaction listings and from trace_transaction, giving an agent enough to identify the tool without opening the schema.

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

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

It explains when to use this tool: when the public RPC cannot trace and the agent needs internal LAX movements without a debug-enabled node. It also names trace_transaction as the alternative and gives explicit paging behavior for cursor vs limit, so the agent knows how to invoke it correctly across pages.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety bar is low. The description adds genuinely useful context beyond them: that names, symbols, tags and method names are author-supplied and wrapped as untrusted, which affects how an agent should treat the results.

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

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

One compact paragraph, front-loaded with what is searched and followed by return fields and the untrusted-data caveat. Slightly run-on, but no sentence is wasted.

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

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

With no output schema, the description carries the burden of describing returns (match type, name, symbol, address/hash, verification status) and does so. Pagination via limit/cursor is left entirely to the schema, which is a minor gap but not a blocker.

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

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

Schema description coverage is 100%, so the schema fully documents query, limit and cursor. The description only illustrates query formats ("pepe", hash, address), adding marginal value over the schema's own enumeration. 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 (search/find) and enumerates the resource types it covers: addresses, tokens, contracts, transactions, blocks. This clearly distinguishes it from the entity-specific siblings like explorer_address and explorer_token, so an agent can route 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?

Usage is implied by the example query forms ("pepe", a hash or an address), which shows when the tool is appropriate, but it never states when to prefer a sibling such as explorer_address or get_transaction for a known identifier, nor any exclusions. Adequate but leaves routing 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 establish readOnly, idempotent, openWorld and non-destructive behavior, so the bar is lower. The description still adds real value beyond them: units are supplied per counter, fees are denominated in LAX, and the average block time is the explorer's own figure rather than a header-derived one — a meaningful provenance caveat.

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

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

A single front-loaded sentence that says what the tool returns and then layers on units and the mining_stats distinction. It is dense but every clause carries information; the parenthetical caveat and unit note are the only parts that could be trimmed.

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

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

There is no output schema, so the description carries the burden of describing return content, and it does so thoroughly by list and currency. It stops short of stating freshness/snapshot semantics or approximate response shape, a minor remaining gap for a zero-parameter stats tool.

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

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

The tool takes zero parameters, so the baseline is 4. The only schema-adjacent remark, 'Units are given per counter; fees are in LAX', concerns returned values rather than inputs, and no parameter meaning is needed.

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

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

It names the exact resource (chain-wide explorer counters) and enumerates the counters returned: blocks, transactions, addresses, accounts, contracts, verified contracts, tokens, LAX transfers, 24h transaction/fee figures, average fee and average block time. It also distinguishes itself from the sibling mining_stats by noting that mining_stats derives block time from headers rather than the explorer's figure.

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

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

Usage is implied by the content (aggregate chain statistics rather than per-entity lookups), and the mining_stats contrast gives a partial alternative-selection signal. However, there is no explicit 'use this when…' or exclusion guidance against siblings like chain_info, supply_info or network_health, which also surface chain-level data.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds genuinely non-obvious context the annotations do not: that names, symbols, tags and method names come from whoever deployed/verified the contract and are wrapped as untrusted, which is a meaningful security caveat. It stops short of covering failure modes (non-token address, unverified contract).

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

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

Two sentences: the first front-loads the return payload, the second delivers the untrusted-data caveat. Nothing is redundant, though the field list is dense and the description opens with a noun phrase rather than an action verb.

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 it well by enumerating the fields. Combined with 100% schema coverage for the sole parameter and safe-read annotations, an agent has nearly everything needed; only edge-case behavior (invalid or non-token address) is unstated.

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

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

There is a single parameter and schema description coverage is 100%, so the schema fully documents the 0x-prefixed 20-byte address. The description adds no further semantics about the address (e.g. that it is the token contract rather than a wallet), so the baseline of 3 applies.

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

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

The description names the resource (a token) and enumerates the exact fields returned — name, symbol, token standard, decimals, supply, holder count — which is far more specific than the title 'Token info'. It implicitly distinguishes itself from siblings like explorer_token_holders, explorer_token_balances and explorer_token_transfers by scoping to metadata only, though it never names them or states a verb explicitly.

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

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

Usage is only implied: an agent can infer this is the call for token metadata versus balance/holder/transfer listings, because the description enumerates what it returns. There is no explicit when-to-use statement, no exclusions (e.g. non-contract addresses, unverified tokens), and no routing to alternatives.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds behavioral facts they don't cover: a hard cap of at most 100 tokens returned and, importantly, a security warning that names, symbols, tags and method names come from untrusted deployers/verifiers. These are the kind of traits an agent must know before trusting or re-using the 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?

Front-loaded with the return contract, then the two caveats (native coin, untrusted strings); every clause carries information. It is dense — the first sentence packs the full item shape — but nothing is redundant.

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

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

No output schema exists, yet the description enumerates the returned fields, so an agent knows what to expect. The only gap is that the 100-token cap is stated without saying how (or whether) to retrieve more, but for a simple read tool this is largely complete.

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

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

Schema description coverage is 100%, so the single 'address' parameter (0x-prefixed 20-byte) is already fully documented by the schema. The description adds no additional syntax or format detail beyond that, so the baseline 3 is appropriate.

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

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

The description names a specific resource (ERC-20/721/1155 balances of an address) and details the exact shape of each returned row, which cleanly separates it from siblings like explorer_token_holders and explorer_token_transfers. It also explicitly disambiguates native-coin lookups by stating 'LAX itself is not a token: use explorer_address or get_balance.' An agent can route without opening any schema.

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

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

It gives an explicit when-not with named alternatives for the native-coin case (explorer_address, get_balance), which is genuine routing guidance. It stops short of telling the agent when to prefer this tool over the other token-related siblings (explorer_token, explorer_token_holders), leaving that to be inferred from the 'balances of an address' framing.

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 read-only, non-destructive, idempotent, open-world. The description adds substantial behavioral context beyond that: page size (50), ordering ('newest first'), the cursor/limit paging pitfall (no next_cursor if limit is used), and a security warning that contract-provided names are untrusted. This is highly transparent.

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

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

The description is front-loaded with the core purpose and result shape, then covers paging nuances and a security note. It is dense but every sentence earns its place; slightly verbose on the untrusted warning for a read-only listing.

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

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

An agent has everything needed to invoke the tool correctly: what it returns, ordering, paging rules including the limit/cursor interaction, and the untrusted-data caveat. With no output schema and good annotation coverage, this description is complete.

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

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

Schema coverage is 100%, so the schema already documents limit, cursor, and address. The description adds semantic context for limit and cursor (paging behavior) but does not provide syntax or format beyond what the schema already gives. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource ('A token's holders, largest first') and immediately enumerates the exact fields returned. It is clearly distinguishable from sibling tools like explorer_token_balances or explorer_address.

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

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

It explains the crucial when-to-paging condition: 'leave limit out when paging through everything' and how to use the cursor. It does not name alternatives or say when not to use this tool versus the sibling token tools, but the context is clear for a paginated holder list.

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 readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: 50-per-page, newest-first ordering, cursor-passing mechanics, the non-obvious limit/next_cursor interaction, and a security warning that contract-supplied names, symbols, tags and method names are untrusted. That last point is behaviorally important and appears nowhere in 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?

Purpose and scope are front-loaded, and every sentence carries load (return fields, paging, the limit caveat, the untrusted-data note). It is a dense single block, which slightly hurts scannability, 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 enumerates the returned fields (hash, block, time, from, to, token, amount raw and whole, token ID) and covers pagination and data-trust caveats. 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 real meaning: the 'token' default for scope, how address is interpreted under each scope, and the interplay between limit and cursor that the schema alone doesn't explain. It does not document the limit range beyond what the schema already states.

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

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

The description states a specific verb+resource (token transfers) and immediately disambiguates the two modes via the scope parameter, distinguishing it from siblings like explorer_token_balances or explorer_token_holders. An agent can tell exactly what data class this returns without opening the schema.

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

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

It gives explicit when-to-use guidance for the two scopes (token default vs address) and a clear when-not for limit ('leave limit out when paging through everything'). It does not name any sibling tool as an alternative, so it stops short of the 5 bar, but the usage conditions are concrete.

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 read-only/idempotent annotations, it discloses pagination granularity (50 per page, newest first) and a genuine gotcha — a page cut by limit has no next_cursor — plus the security-relevant note that names, symbols, tags and method names are deployer/verifier-set and wrapped as untrusted. That is exactly the behavioral context annotations cannot carry.

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

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

Front-loaded with the core purpose and otherwise dense with useful content; the long enumeration of returned fields consumes a lot of the paragraph but substitutes materially for the absent output schema. No filler sentences, though it is a single heavy 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, the description appropriately documents the return payload, and it covers paging end-to-end (page size, order, cursor round-trip, limit caveat) and data-trust caveats. An agent has everything needed to call and page this tool correctly.

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

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

Schema coverage is 100% so per-parameter meaning is already documented; the description still adds value by explaining the interaction between limit and cursor and restating direction defaults. It does not add much on address format beyond the schema's '0x-prefixed 20-byte address'.

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

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

States a specific verb+resource ('transactions sent from or to an address') with an explicit scope qualifier ('as the explorer indexed them') and enumerates the returned fields, which lets an agent distinguish this from focused siblings like explorer_token_transfers or explorer_internal_transactions by payload shape.

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 operational context: direction values with default, page size, ordering, and how to advance via cursor, plus the non-obvious rule to omit limit when paging. It never explicitly says when to prefer this over explorer_token_transfers or explorer_internal_transactions, so no alternatives/exclusions are stated.

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

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

Annotations already declare read-only/idempotent/non-destructive, and the description adds substantial context beyond them: no EIP-1559 base fee, the exact cost formula, the estimator's block horizons, the meaning of "legacy_fallback": true when data is scarce, and the availability of 21,000-gas transfer costs in LAX. This is real behavioral disclosure an agent cannot get from the 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?

Front-loaded with the core answer (current fee levels in wei/gwei) before the formula and estimator detail. It is dense and somewhat run-on, but with no output schema most of this detail 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 carries the full burden of explaining return values, and it does so thoroughly: node eth_gasPrice, per-horizon smart-fee estimates with success rates, the legacy_fallback flag, and derived transfer costs. Nothing an agent needs to interpret the result is missing.

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

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

The tool takes no parameters, so there is nothing for the description to disambiguate and the baseline is 4. The description spends its space on return semantics instead, which is a reasonable use of a zero-param definition.

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

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

The description states a specific resource and unit (current fee levels in wei and gwei) and explains the fee model (gas used × gas price, all to the miner). It is clear what the tool returns, though it never explicitly names its closest sibling, estimate_gas, so an agent must infer the distinction between 'current chain fee levels' and 'estimate for a specific call'.

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

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

Usage is implied rather than stated: the description makes clear this is a snapshot of current fee levels, but it gives no explicit when-to-use or when-not, and no guidance on choosing it over estimate_gas or block_reward. Adequate but with a clear 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?

Annotations already declare readOnly, idempotent, non-destructive, openWorld. The description adds real behavioral context beyond that: the archive-node requirement and the error it produces, plus the coinbase-maturity caveat that rewards are counted in the balance but unspendable for 100 blocks. These are non-obvious traits an agent would otherwise miss.

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 what is returned and the block scoping, then caveats. Dense but every clause carries information; only the maturity note is slightly tangential to invocation.

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

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

For a read-only tool with no output schema, the description usefully enumerates the return values (balance in wei and LAX, nonce) and covers the key failure mode (archive node). Nothing critical to calling it correctly is missing.

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

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

Schema coverage is 100%, so both parameters are already documented, including block accepting number/hash/latest. The description reinforces that block accepts a number or hash and defaults to latest but adds no format or syntax beyond the schema, so baseline 3 is appropriate.

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

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

The description states a specific verb+resource: it returns the LAX balance (in wei and LAX) and nonce of an address, at a given block. Scope is precise enough that an agent knows exactly what it gets back. It does not explicitly contrast itself with siblings like explorer_address or explorer_token_balances, which keeps it from a 5.

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

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

It implies when the tool applies (latest block vs a specific block number/hash) and warns about the archive-node prerequisite for old blocks, but never names an alternative tool or a when-not-to-use condition. Usage is contextual rather than directive.

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 readOnly/idempotent/openWorld, and the description goes well beyond them: it lists every returned field, explains Parallax-specific semantics (epochStartTime at multiples of 2016, 600-second target block time), flags extraData as untrusted text, and discloses a hard 200-transaction cap with a transactions_truncated marker. That is exactly the kind of operational context 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?

Front-loaded with the block lookup modes before the long return-field inventory, and the transaction-detail and truncation caveats come last where they belong. The field enumeration is dense but every clause carries information; a slightly tighter grouping of the return fields would make it fully optimal.

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

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

With no output schema and no annotation coverage of return values, the description carries the full burden and does so thoroughly, describing fields, units, truncation behavior, and data-trust caveats. Nothing an agent needs to call this correctly or interpret the result 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% and already documents both parameters, so the baseline would be 3. The description earns extra credit by detailing what full_transactions actually yields (from, to, value in wei and LAX, gas price, nonce, calldata selector) and by stating the 'latest' default and the 200-item truncation limit, which the schema omits.

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

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

The opening sentence names a specific verb+resource ('A block by number, hash or "latest"') and enumerates all three accepted lookup modes, which cleanly separates it from siblings like get_transaction, get_receipt, and wait_for_new_block. An agent can identify the tool and its input contract 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?

Three concrete invocation examples show how to call it and the full_transactions toggle is explained, which implies the usage context (historical/point lookup). However, it never states when to prefer this over siblings such as wait_for_new_block for real-time needs or block_reward for subsidy-only queries, so no explicit alternative routing is 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 already cover readOnly/idempotent/non-destructive, but the description adds genuinely useful behavior: the block defaults to 'latest', bytecode output is truncated at 4096 bytes, and an empty result indicates an EOA or self-destructed contract. These interpretive details go beyond the 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 and stays dense without padding, with each sentence contributing (purpose, option behavior, empty-result interpretation, sibling routing). The mid-sentence colons and quoted '"block"' make the first sentence slightly clunky to parse.

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

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

With no output schema, the description fully carries the return-value burden by explaining contract detection, size, hash, and the optional bytecode, plus how to interpret the empty case. Combined with annotations covering safety, nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents address, block, and include_code. The description restates the include_code truncation and default block behavior but adds little syntax or format detail beyond what the schema provides, landing at the 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?

States a specific verb and resource (deployed bytecode of an address) and enumerates exactly what is returned: contract status, code size in bytes, keccak256 hash, and optionally the bytecode hex. It explicitly separates itself from the sibling explorer_contract, which covers source code and ABI.

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 a clear routing rule: 'For source code and ABI use explorer_contract,' which tells the agent when another tool is the right choice. However, it doesn't address other adjacent capabilities such as verifying a contract's balance or storage, so the exclusion set is 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 the safety profile (readOnly, idempotent, openWorld, non-destructive), and the description adds substantial beyond that: the 10000-block range cap, the 500-log result cap with a "truncated": true signal, default block windows, one explorer request per contract when decoding, and a warning that event string values are untrusted.

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 limits, and every sentence carries information (caps, defaults, topic semantics, decode behavior, trust warning). It is dense and runs long, but no sentence 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?

No output schema exists, and the description compensates by explaining the return shape (capped at 500 logs, truncated flag) and the decoding behavior. Combined with the rich parameter semantics, an agent has everything needed to call and interpret this tool.

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

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

Schema coverage is 100% so the baseline is 3, but the description goes beyond the schema by explaining topic positions (0 = signature, 1-3 = indexed args), that event_signature computes topic 0, and that from_block defaults to to_block minus 1000. That meaningfully enriches several parameters rather than restating them.

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 (event logs in a block range) and names the underlying mechanism (eth_getLogs), which cleanly separates it from the explorer_* and receipt/transaction siblings. An agent can tell exactly what it returns without opening the schema.

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

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

Gives clear operating context (filter by contract addresses/topics, narrow the range when truncated, defaults for the block window), which is real usage guidance. It does not explicitly name an alternative sibling or a when-not condition, 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 already cover the safety profile (readOnly, idempotent, openWorld), but the description adds a non-obvious behavioral fact: proof nodes are only counted by default and only returned when include_proof=true, because they are large. That default-return behavior is real value beyond the 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?

Two dense sentences with the resource front-loaded and no filler. The first sentence is slightly overloaded (field list plus block scoping plus quoted "block"), 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 correctly enumerates the returned values and explains the optional proof-node payload, which is the key thing an agent needs to know. It omits error/limit handling (e.g., behavior when more than 20 slots are requested), but is otherwise complete for this read-only tool.

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

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

Schema coverage is 100%, so the schema already documents address, block, slots, and include_proof, including the 20-slot cap and default block. The description only restates the include_proof rationale, adding little parameter meaning beyond what is structured.

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 — the Merkle proof of an account and its storage slots — and anchors it to a known standard (eth_getProof, EIP-1186). Listing the returned fields (balance, nonce, code hash, storage root, slot values) makes it easy to distinguish from sibling read tools like get_balance, get_code, or get_storage_at.

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

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

Explicitly states the intended use: verify state against a block's stateRoot without trusting this server or the node, and explains the include_proof tradeoff. It does not, however, name the sibling alternatives (get_storage_at, get_balance) or state when a plain value read 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, open-world), yet the description adds real behavioral context: logs are capped at 100, event string values are untrusted, log decoding depends on a verified ABI or standard ERC-20/721 matching, and a pending transaction yields no receipt. The untrusted-data warning and the log cap are exactly the kind of operational caveats an agent needs before consuming the 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?

Two sentences, front-loaded with the resource and its main fields, then the log details and the pending-transaction caveat. Dense but not padded — the enumeration earns its place because there is no output schema. Slightly list-like, but nothing is redundant.

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

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

With no output schema and no nested params, the description carries the return-value burden and does it well: field-by-field contents, units for the fee/gas price, the log cap, decoding rules, and the pending-transaction edge case. An agent knows what it will receive and when it will get nothing.

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

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

There is a single required parameter (hash) and schema description coverage is 100%, with the schema stating '0x-prefixed 32 bytes'. The description never mentions the hash argument or adds validation/format guidance beyond that, so the baseline of 3 applies.

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

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

The description names a specific verb+resource (retrieve the receipt of a mined transaction) and enumerates exactly what that receipt contains: status, gas used, effective gas price, fee paid, created-contract address, and event logs. The closing line 'A transaction that is not mined yet has no receipt' cleanly separates it from get_transaction in the sibling list. An agent can pick this tool over get_transaction or get_logs 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?

Usage is only implied: the receipt exists for mined transactions and is absent otherwise, which tells the agent the precondition but not how to respond. No sibling is named as an alternative or a complement (e.g. get_transaction for pending txs, get_logs for log-only queries). Adequate context, but the routing decision is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds useful behavioral context: the 20-slot limit and that values come back as both 0x-hex and unsigned decimal, which is not in the annotations or 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?

Two sentences, front-loaded with the core purpose, then parameter and return details. No filler or repetition.

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

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

Given moderate complexity, three parameters, and no output schema, the description covers purpose, slot formats, the 20-slot limit, block default, and return encoding. It is complete enough for correct invocation, though it omits explicit alternative-selection guidance.

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 adds meaning for the 32-byte hex key case (mapping entries computed off-chain) and restates slot format and block default, slightly exceeding schema detail.

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

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

States a specific verb+resource: retrieving raw 32-byte storage slot values for a contract. Distinguishes from siblings like get_code or get_proof by naming the exact resource, though it does not explicitly contrast with alternatives.

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

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

No explicit when-to-use or when-not-to-use guidance; it does not mention alternatives such as call_contract or get_proof. Only implicit usage is conveyed by the resource and parameter limits.

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

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

Goes well beyond the annotations by disclosing chain-specific behavior: no base fee so gas price is the whole per-gas price, no type-2 transactions, calldata truncated at 2048 bytes, decode provenance ('verified' vs 'standard' guess), a warning that decoded strings are untrusted, and that pending transactions have no block. These are exactly the caveats an agent needs and none are in the 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 identity of the tool and its result shape are front-loaded, and the routing sentence is placed last where it belongs. The field enumeration is dense and long but nearly every clause carries real information; it stops just short of being 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 must describe return values, and it does thoroughly: field list, nullability for pending txs, calldata truncation, and decode source semantics. An agent has everything needed to interpret the response.

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 with 100% schema description coverage ('0x-prefixed 32 bytes'), so the schema already carries the semantics. The description reinforces that lookup is by hash but adds no format or syntax detail beyond the schema — baseline 3 for a fully documented single param.

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 ('a transaction by hash') and then enumerates the exact fields returned (block, position, from, to, value, gas, nonce, type, calldata). It explicitly distinguishes itself from get_receipt, 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?

Ends with an explicit alternative and the condition that selects it: 'Use get_receipt for status, gas used, fee and events.' This is clear routing guidance, though it only covers one sibling (not explorer_transactions or get_block) and offers no explicit exclusions for the rest.

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 (readOnly, idempotent, non-destructive), and the description adds substantial context beyond them: two independent data sources (node txpool vs. status page), the fact that either may be missing with its failure surfaced in 'errors', interpretation thresholds (under 0.5 light, over 2 backlog), and the expectation that Parallax's mempool is usually near empty.

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 concept ('Transactions waiting to be mined') and every sentence carries concrete information about returned fields. It is dense with nested quoted terms but not padded; slightly heavy for a single-status tool, but each clause earns its place.

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

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

With no output schema, the description fully carries the burden of explaining return values, and it does so field by field, including the failure-reporting mechanism. Nothing an agent needs in order to call and interpret this zero-parameter 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?

The tool takes zero parameters, so the baseline of 4 applies. The description correctly documents the empty input contract implicitly by describing only the returned data, adding no misleading parameter expectations.

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

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

States a specific resource (mempool) and precisely enumerates what is reported: pending/queued counts, median pending across nodes, 'pressure', blocks to clear, and current gas price. It is clearly distinguishable from siblings like gas_price (single metric) and network_health (network-wide).

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 field semantics imply when the tool is useful (assessing congestion/pending load), but the description never states when to prefer it over siblings such as gas_price, network_health, or mining_stats, nor any exclusions. Usage is left to inference.

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

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

Annotations already cover read-only/idempotent/open-world safety. The description adds substantial behavioral context: timestamp caveats ('single intervals can be zero or negative'), statistical swing on hashrate ('±8%, one standard deviation is 1/√blocks'), and trust caveat on pool names ('names are untrusted'). This is rich disclosure beyond 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 description is a long multi-paragraph dump front-loaded with formulas rather than a lead sentence stating purpose. While the content is dense and useful, it is not appropriately sized or structured for quick scanning, and reads more like documentation than a tool description.

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

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

For a read-only analytics tool with no output schema, the description fully documents every returned field, its derivation, and its caveats, leaving nothing an agent needs to interpret results missing. Complete for the tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description goes further by explaining the meaning of the window size (default 144 ≈ a day, max 2016) and its statistical implication (±8% at 144 blocks), adding value over the schema's terse 'window size in blocks'.

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 (mining statistics) and enumerates exactly what metrics are returned, each with a definition. An agent can distinguish this from siblings like chain_info or explorer_stats by the mining-specific scope. No sibling computes hashrate, block time, or miner distribution.

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 window semantics ('last blocks blocks, default 144, at most 2016') implicitly define when the tool applies, and the metric list implies its analytical use. However, there is no explicit when-to-use vs. alternatives guidance relative to chain_info, network_health, or explorer_stats.

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

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

Annotations already declare readOnly/idempotent/non-destructive/open-world, but the description adds substantial behavior beyond that: partial-failure semantics ('If either source is unreachable the other's data is still returned with the failure in "errors"'), coverage caveats (status page covers only nodes run with --prlstats, unverified rows are self-reported), and the admin-namespace conditional (uptime and address book). This is exactly the operational context an agent needs before calling.

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

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

It is front-loaded correctly (purpose first, then 'From the status page', 'From the node', 'issues'), but the body is extremely long and dense, enumerating every alert type and status value. Since no output schema exists this detail is partly justified, but much of it reads as field-by-field output documentation rather than selection-relevant content, so it is not tightly economical.

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 full burden of explaining return values, and it does so exhaustively: status page fields, node fields, issue aggregation, failure behavior, and data-provenance limits. An agent has enough to call it 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?

The tool takes zero parameters, so there is no parameter syntax to document and the baseline of 4 applies. The description adds nothing here, but nothing is needed.

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

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

The opening sentence states a specific verb and resource (health report of the Parallax network) and defines its distinguishing trait: it is a composite that combines the status page with the configured node in one call. This differentiates it from siblings like mempool_status, network_nodes, network_propagation, and mining_stats without requiring the schema.

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

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

The phrase 'One-call health report' and the note that 'issues lists what needs attention in one place' imply this is the aggregate tool to reach for when a full picture is wanted rather than individual calls. However, it never explicitly names alternatives (e.g., mempool_status, network_nodes) or states when-not to use it, leaving routing 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 establish that this is a safe, idempotent read. The description goes beyond them usefully: it flags the description field as untrusted, marks 'ongoing' for open incidents, states ordering (newest first), declares the coverage window (default 30, at most 90 days), and notes that uptime/recording-start data is bundled in. No permissions or rate-limit detail, but solid added context.

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

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

The primary resource is front-loaded and the dense parentheticals (incident-type definitions, 'ongoing' marker, untrusted warning) all carry interpretive value for the returned payload. It is somewhat crammed into a single long sentence, but 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?

With no output schema, the description assumes the full burden of describing return values, and it does so: incident level, start/end with 'ongoing' semantics, duration, description field, average uptime, and recording start. An agent knows what it will receive and over what range.

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

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

Schema coverage is 100% and the single 'days' parameter is fully documented in the schema (default 30, at most 90). The description merely repeats these same bounds, adding no syntax or semantic 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?

The description names a specific resource (the status page's incident record) and enumerates what each record contains plus the incident-type taxonomy (majority, withholding, spread, split, reorg). This lets an agent distinguish it from siblings like network_health and network_trends 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?

Usage context is implied by framing it as 'the status page's incident record', but there is no explicit when-to-use guidance and no mention of alternatives such as network_health or network_trends. An agent must infer that this is the historical/incident-view tool rather than being told.

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 annotations (readOnly, idempotent, openWorld, non-destructive), the description adds meaningful behavioral context: name data is untrusted/self-reported for unverified nodes, IP addresses and cities are never published, and propagation delay is omitted when it was not timed. These are real caveats an agent needs, though no pagination or rate-limit behavior is mentioned.

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

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

It is a dense run-on paragraph, but every clause earns its place by documenting returned fields that have no output schema to carry them, and the filter semantics are front-loaded. Slightly heavy nesting of field lists costs it a point.

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

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

With no output schema, the description appropriately carries the return-shape burden and covers filters, trust caveats and privacy constraints. It is effectively complete for invoking the tool, though it says nothing about ordering, limits, or truncation of the node list.

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 default-state semantics the schema omits: offline nodes are filtered out unless include_offline=true, and verified_only keeps operator-verified nodes only. This clarifies the consequence of omitting each flag rather than merely restating 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?

The description states a specific resource (the nodes reporting to the status page) and enumerates the exact fields returned, making it distinguishable from siblings like network_health, mining_stats or network_propagation. It never frames the action as a verb ('list'), but the scope and content are unambiguous.

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

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

It gives clear context on filtering behavior (offline nodes are excluded by default unless include_offline=true; verified_only=true keeps only verified nodes) and a scope boundary ('the nodes that report to it, not every node on the network'). However, no alternative or sibling tool is named for the cases where this dataset is the wrong one.

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

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

Annotations cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint), so the description's burden is lower. It adds meaningful behavioral context beyond annotations: it enumerates the exact metric families (propagation delay percentiles, 90% reach time, slow miner detection, stale blocks over 2,000 heights, reorg counts and depth) that will be returned, which is more informative than a generic 'status' label.

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

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

The single run-on sentence is long and crams many metric families together without clear front-loading of the core purpose. It is information-dense but poorly structured, forcing careful reading rather than giving a scannable summary first.

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

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

With no parameters, no output schema, and rich annotations, the description carries the burden of describing what data is returned. It does this comprehensively, naming nearly every metric family (propagation delays, percentiles, slow miners, band delays, stale blocks, reorgs, chain splits). A minor gap is that it does not describe response shape or time-window boundaries for all metrics, but overall completeness is strong.

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

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

There are zero parameters and 100% schema description coverage, so the baseline is 4. The description correctly does not fabricate parameter semantics; instead it details the data categories exposed, which is the value it can add with no inputs. It could be tightened but 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 names a specific subject: propagation delay statistics (median, p90, p99), 90% node reach time, slow miners, stale blocks, and reorganizations with depth/history. This is differentiated from related siblings like network_health, network_nodes, and network_trends by focusing precisely on block-propagation latency and chain-tip stability metrics. An agent can distinguish it from every listed sibling.

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

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

The parenthetical 'from the status page' implies the source but does not state when to prefer this over siblings like network_health or network_trends. No exclusions or alternative routing are given, so usage is only implied rather than 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?

With annotations already covering read-only/idempotent/non-destructive, the description adds substantial context beyond them: UTC slices 4 hours wide ordered oldest-first, null where nothing was measured, and the pooling semantics (block_time and hashrate pooled over the 24 hours to each slice's end so single-slice luck does not bias them). It also defines the derived series (hashprice_lax, security_budget_lax at today's block pay, mempool_pressure as pending share of a block).

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 time window are front-loaded, followed by metric definitions and then the sibling routing sentence. It is dense and long, but nearly every clause carries information the agent needs to interpret the series; minor compression of the metric list is possible but nothing is filler.

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

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

No output schema exists, and the description compensates by enumerating all returned fields with their units and aggregation semantics, including null handling and slice width/ordering. An agent has enough to call the tool and interpret the response without further documentation.

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

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

Schema coverage is 100% and the single 'metrics' parameter's enum is already listed in the schema, so the baseline is 3. The description earns extra credit by explaining what each selectable series actually measures, which materially helps an agent decide which metrics to request and interpret the result, plus it restates the default-all behavior.

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+resource (the status page's figures over the last 7 days) and enumerates every returned series, so an agent knows exactly what this tool produces. It also explicitly distinguishes itself from explorer_charts, which covers longer transaction/fee/gas histories.

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

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

It names an explicit alternative for a specific case: 'For longer histories of transactions, fees and gas, use explorer_charts.' That routes the agent away from this tool when appropriate, but it gives no guidance about when this tool is preferred over other siblings such as network_health, mining_stats or mempool_status.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive, so safety is covered. The description adds genuinely useful non-annotation behavior: pagination via max_bytes/offset with next_offset chaining, Markdown output, and the inclusion of a citeable published URL. No auth or rate-limit details, hence not a 5.

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

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

Front-loaded with the core purpose and return format, then pagination and path-format details. Dense but every clause carries information; the parenthetical path examples make it slightly heavy though none 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 3-param read tool with no output schema, it covers what is returned (Markdown page/PIP), how to page through long content, and that a URL is included for citation. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds accepted path variants beyond the schema ('PIP-4', parallax:// URIs, docs.parallaxprotocol.org URLs) and explains the offset/max_bytes relationship dynamically. Offset semantics are slightly clarified but the schema already documents the byte range.

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

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

States a specific verb and resource ('Returns a page of the Parallax documentation or a PIP in full') and fixes the output format (Markdown). It positions itself against search_docs by naming it as the source of the path, so an agent can distinguish read from search 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?

The phrase 'by "path" from search_docs' tells the agent where the required input comes from, effectively routing it to search_docs first. It stops short of an explicit 'use search_docs if you don't know the path' instruction or any exclusion of alternatives, 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 already declare readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description adds value beyond that by disclosing the return shape (title, path, summary, excerpt around matching text) and the follow-up workflow (read_doc + cite url), though it says nothing about ranking or pagination limits.

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

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

Front-loaded with the verb and parallel structure across three short paragraphs (what / when / params), with no wasted sentences. The long parenthetical enumerations of doc topics and PIPs are dense but earn their place by signalling corpus coverage.

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

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

No output schema exists, and the description compensates by describing the result fields and the read_doc handoff for full content. Combined with explicit usage criteria and query examples, an agent has everything needed to call and follow up correctly.

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

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

Schema description coverage is 100%, so the baseline is 3; the description goes further by giving concrete query examples ('mining pool setup', 'how does the fee estimator work') and restating the kind values, which helps the agent phrase inputs. It does not clarify the limit parameter, which is fully handled by the schema.

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

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

States a specific verb and resource ('Searches the official Parallax documentation... and the Parallax Improvement Proposals') and enumerates the topical coverage so the agent knows exactly what corpus is searchable. It also distinguishes itself from the sibling read_doc by describing search-vs-read roles.

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 says when to use it ('whenever a question is about how Parallax works or how to do something with it') and gives the rationale (Parallax diverges from Ethereum/Bitcoin, so don't answer from general knowledge). It also routes to the alternative: use read_doc to read a page in full and cite its url.

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 readOnly, idempotent, non-destructive and openWorld, so the bar is lower. The description adds genuine behavioral context beyond them: it names the underlying node call (eth_getTotalSupply), states that the value is independently recomputed and that a 'mismatch' flag is set if the two disagree, and notes block rewards are spendable only 100 blocks later.

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

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

It is a single dense paragraph of ~150 words that opens with emission-schedule exposition (halving cadence, 'no premine, burn or protocol lock') rather than the tool's behavior. Those chain facts help interpret the numbers but many sentences do not earn their place for the purpose of selecting and invoking the tool, and the useful return-value list is buried mid-paragraph.

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

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

With no output schema, the description carries the burden of describing return values and does so thoroughly — head height, issued supply in wei and LAX, node vs. recomputed, share of cap, remaining to mine, reward/era, daily issuance, and next-halving fields. For a zero-parameter read tool with rich annotations, this is close to complete, missing only sibling guidance.

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 no parameters, so the baseline of 4 applies. The description does not need to explain inputs, and the schema is empty by design.

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 core purpose is stated explicitly: it 'Returns the head height, issued supply in wei and LAX from the node ... and as recomputed here from the schedule,' which is a specific verb plus resource an agent can act on. However, the description is front-loaded with chain tokenomics ('LAX issuance against the 21,000,000 cap', halving schedule) before the tool's function appears, and it never distinguishes itself from the sibling block_reward despite overlapping on 'the current reward and era.'

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 call this versus alternatives, and no prerequisites or exclusions. Sibling tools like block_reward, mining_stats and explorer_charts plausibly overlap on supply/reward data, so an agent gets no routing help at all.

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

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

Annotations already mark this as a non-destructive, read-only, idempotent, open-world operation. The description adds substantial behavioral context beyond that: average block times, wide interval variance, reorg marking, timeout return shape, and the special 90-second limit without HTTP sessions.

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

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

The description is dense but front-loads the core behavior and then moves through return fields, timeout behavior, alternatives, and a usage tip. It is appropriately sized for a tool with waiting and timeout complexity, though it could be slightly easier to scan with clearer sentence breaks.

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, but the description lists the returned fields and describes the timeout and reorg cases. Together with the annotations and full schema coverage, an agent has everything needed to invoke and interpret the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds useful semantics: after_block defaults to the current head, and timeout_seconds has a server-dependent maximum of 90 seconds without HTTP sessions. This is meaningful beyond the schema's stated 1-600 range, though it does not deeply elaborate on edge cases.

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: waits until the chain has a block above a given height, then returns that block. It clearly distinguishes itself from siblings like get_block by emphasizing the waiting behavior and defaulting to the current head.

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 says to use it to wait for a transaction's next confirmation and then check with get_receipt, and it names resource subscriptions as a better alternative for supported clients. It also explains what happens on timeout and that the tool can be called again.

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