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

Beyond annotations (read-only, idempotent, non-destructive), the description adds meaningful behavior: the response echoes the resolved mode (homepage, direction, homepage_direction), sets sourceUserId only when a seed resolves, and describes how field shape varies by platform (YouTube adds channelId/channelTitle, TikTok adds userId/uniqueId/nickname/averageLikeCount). It also includes response size and latency measurements. This goes well beyond the annotation hints.

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 every sentence earns its place: the first sentence gives purpose, the second iterates required inputs and constraints, the third explains mode resolution, the fourth lists match fields, the fifth covers platform-specific field differences, the sixth gives performance metrics, and the seventh provides an alternative tool. It is front-loaded with the core purpose and efficiently structured.

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?

Considering the tool's complexity — nested filters, platform-specific output, multiple modes, and alternative tools — the description covers all critical aspects an agent needs: input constraints, output shape differences, performance expectations, and an explicit fallback. The presence of an output schema further supports that the description is complete enough; no knowing would lead to incorrect invocation.

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 80%, but the description adds relational semantics: it explains that seedProfileUrl and contentDirection can be used 'or both,' and that the response mode depends on which is provided. It also clarifies that filters apply to regions, languages, follower and average-view ranges. This adds meaning beyond individual parameter descriptions.

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: 'Finds creators similar to a seed profile, a natural-language content direction, or both, on YouTube or TikTok.' This clearly distinguishes it from siblings, especially post_waveinflu_email_lookup, and notes it does not match Instagram creators. The title 'Similar Creators' alone would be vague, but the description fully disambiguates it.

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 explicitly provides usage conditions: platform is required, supply a seedProfileUrl or contentDirection or both, and states the limit range. It also gives a specific alternative: 'use post_waveinflu_email_lookup for the ones that come back null and for Instagram creators, which this endpoint does not match.' This covers when to use and when not to use, including a named sibling.

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