get_creators_bestselling_tool

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

With no annotations present, the description carries the full burden and does disclose meaningful traits: it states a permission requirement ('requires Bestsellers scope') and the shape of the result ('bucketed gmv_range per creator'). It does not cover read-only semantics, rate limits, or pagination, but the auth and output disclosures are real value beyond structured fields.

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-loads the core purpose, then terse parameter lines, then a one-line use case. No wasted prose; the structure is easy to scan. Slightly telegraphic parameter lines lose a bit of readability.

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?

An output schema exists, so return values need not be explained further, and the description usefully notes the bucketed gmv_range shape. However, with 5 parameters at 0% schema coverage, the undocumented currency and seller_name leave the definition short of complete for a tool of this parameter count.

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 0%, so the description must compensate, and it does document date format (YYYY-MM-DD), time_slot values ('7D' default / '30D'), and author_type values (ALL/AFFILIATE/OFFICIAL) — enum-like detail the schema lacks. But it omits two of the five parameters entirely (currency and seller_name), leaving a clear gap.

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 resource with concrete scope and limit: 'Platform-wide TOP 100 bestselling creators.' An agent can immediately tell this apart from sibling resources like get_videos_bestselling_tool and get_products_bestselling_tool because the entity (creators) is named explicitly.

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?

'Use for BD outreach discovery' gives a clear intended context for the tool. However, it names no exclusions and does not point to the alternative bestseller tools (videos/products) when the agent wants a different entity, so it stops short of full routing guidance.

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