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

Beyond the readOnlyHint annotation, the description discloses key non-obvious behaviors: it cannot spend money, unregistered does not mean purchasable, reserved/premium names answer the registry the same way, only a registrar quote settles a price, and prices are identical regardless of budget. It also explains scan_id convergence behavior across re-queries.

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 long but densely packed and front-loaded with the most important invocation trigger. Each subsequent sentence adds workflow, exclusion, or behavioral guidance; the rename note and pricing caveats earn their place by preventing common agent mistakes.

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 no output schema, the description still communicates what comes back (ranked candidates classified by availability) and provides the operational constraints needed to call it correctly. It also completes the wider workflow by naming scan_namespace, score_name, and check_live as the surrounding steps, leaving no critical gap for an agent.

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 semantic value beyond the schema by explaining that query is a 'CONCEPT', that results are ranked and classified by availability, and that re-querying the same scan_id walks deeper into the namespace. Limit, offset, and tlds still rely mostly on the schema, so this is not a full 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?

The description opens with a specific behavior: 'returns candidate names across a namespace' for a user choosing or inventing a name, and includes concrete trigger phrases. It clearly distinguishes itself from sibling tools like scan_namespace and score_name rather than merely restating the tool name.

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 ('START HERE when the user is choosing or inventing a name'), example user utterances, and direct alternatives: 'Use scan_namespace instead when you already have an explicit list.' It also sequences the workflow with score_name and check_live, and explains when NOT to treat results as final pricing.

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