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

Annotations already declare readOnly/idempotent/non-destructive behavior, lowering the bar. The description adds significant transparency about dual routing, backward compatibility with legacy semantic fields, and conditional endpoint selection—none of which are visible from annotations or schema. There is no contradiction with the structured metadata.

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 comprehensive and front-loaded with purpose, but it is somewhat verbose—the 'cheap, fast, and backed by the creator lookup index' phrase adds little functional value. The example block is useful, though it could be tightened without sacrificing clarity.

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 dual-mode tool with 12 parameters, the description covers primary use cases, routing behavior, return-value chaining, and sibling-tool boundaries. It thoroughly compensates for any schema ambiguity and gives the agent enough context to select and invoke the tool correctly, especially given the output schema exists.

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 description adds rich context for query usage (e.g., 'query "cris" with query_type "creator_lookup"') and explains how legacy fields are routed. However, the input schema's query description explicitly says 'Do not pass exact handles or usernames here,' which directly conflicts with the tool's primary purpose and creates contradictory parameter guidance for the agent.

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 verb and resource—'Find a creator by name/handle'—and explicitly frames it as the default creator lookup tool. It distinguishes itself from siblings like get_profile (exact handle lookup) and semantic_search_creators (topical/niche discovery), making its role 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 provides explicit when-to-use and when-not-to-use guidance: prefer get_profile for exact handles/platforms, use this tool for rough names or partial handles, and prefer semantic_search_creators for niche discovery. Concrete examples for each scenario reinforce the guidance, leaving little room for misinterpretation.

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