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

Excellent disclosure beyond annotations: the 422 non_ascii_name path and its non-charging, the 5xx-on-malformed-node behavior and its non-charging, CCIP-Read offchain records being reported but not fetched, 1-3 s latency, USD 0.003 price, the shared 10-reads/IP/day free pool, and an untrusted-data warning. Annotations already cover readOnly/idempotent/destructive, so this is pure added value.

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

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

Front-loads purpose and input, then packs return shape, constraints, failure modes, and pricing into dense but non-redundant sentences. It is long and run-on, but nearly every clause carries operational information an agent would otherwise lack, so it earns its length.

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: it names resolver/wildcard, address decoding formats, contenthash schemes, and text record keys. Combined with error modes, timing, and cost, 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?

Only one parameter, and schema description coverage is 100% — the schema already documents `name` as an ASCII ENS name with an example and length bounds. The description restates the example and the ASCII constraint but adds little syntactic or format detail beyond the schema. Baseline 3 applies.

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

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

States a precise verb+resource ('read an ENS name's records') and enumerates exactly what is returned: resolver/wildcard, addresses (eth/btc/base), contenthash protocols, and text keys. The scope (Ethereum mainnet, ASCII names) is explicit. It does not, however, differentiate itself from the sibling resolve_ens, which an agent could easily confuse with this tool.

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

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

The description gives operational conditions ('ASCII names only', offchain records reported but never fetched, malformed answers produce 5xx) which imply when the call succeeds or fails, but it never says when to choose this over the sibling resolve_ens or which record types warrant this heavier call. Usage is implied rather than directed.

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