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

Annotations already declare read-only, idempotent and non-destructive, and the description adds substantial behavior beyond that: the resolution ordering, the optional QIE ID API fallback with free names first, the reverse-resolution verification against a published record store, and the guarantee that no name is guessed. Failure modes (null name, unresolved on testnet) are spelled out rather than left for the agent to discover.

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

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

Front-loaded with the core purpose, then ordered by resolution path and failure cases, which is easy to follow. The closing sentence about price, APY, yield and investment advice is a policy guardrail rather than lookup semantics and slightly dilutes an otherwise tight definition.

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

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

There is no output schema, and the description compensates by describing the returned shape (status ok with name null, status unresolved) and the conditions producing each. Combined with the resolution rules and fallback chain, an agent has enough to call it and interpret results 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%, so the baseline is 3, but the description adds meaning beyond the schema by explaining the semantic consequence of the network parameter: testnet lookups return status unresolved because QIE ID is not deployed there. The address parameter itself is not elaborated beyond the schema's hex-address note.

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 ('look up the QIE ID ... for an address on QIE mainnet') and pins the chain (1990), which immediately distinguishes it from the forward-direction sibling qie_resolve_name. It also clarifies what value is returned when several names exist (owner's default, else the free QIE ID held).

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 conditions where the tool is the right call and where results will be empty: no QIE ID yields status ok with name null, and testnet (chain 1983) yields unresolved. It never explicitly names qie_resolve_name as the forward-direction alternative, so the when-to-use-vs-sibling routing is only implied.

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