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

Annotations already declare readOnly, idempotent, non-destructive behavior, so the bar is lower. The description adds meaningful context: the tool outputs verification guidance, reflects blocking costs, and can be called via the same implementation over HTTP. No contradiction with annotations exists.

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 description is useful, but it is front-loaded with a lengthy JSON-RPC example for calling whoami, a different sibling tool. That embedded request is noise for an agent trying to understand classify_user_agent and consumes space that should describe this tool. The remaining content is otherwise efficient.

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 single-parameter, read-only tool with no output schema, the description covers inputs, outputs, an example, a verification alternative, and even a non-MCP fallback endpoint. Nothing essential for correct invocation 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 value beyond the schema by giving a concrete example ('GPTBot/1.2'), showing what the parameter should contain ('raw User-Agent header value'), and illustrating the expected output mapping. This clarifies parameter usage without inventing ambiguity.

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: 'Identify the crawler behind a raw User-Agent header' and enumerates the exact output dimensions (operator, category, robots.txt stance, verification method, blocking cost). It also distinguishes itself from the sibling is_verified_crawler_ip by positioning that tool as the confirmation step.

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 contextual guidance: a User-Agent is only a claim, so results should be confirmed with is_verified_crawler_ip. It does not explicitly compare against lookup_crawler or list_crawlers, but the specific use case of classifying a raw UA string is unambiguous and the named alternative covers the main follow-up path.

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