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

Annotations only state readOnly/open/destructive hints, and the description goes far beyond: token pricing (catalog free, 1 token per delivered profile), free-plan restricted totals with meta.plan_window_cutoff semantics, quota tiers (500 lifetime / 40k monthly with auto-refund), rate limits with structured error.code=rate_limit_exceeded, concurrency admission (one heavy analytical call at a time), and autonomous-agent auth requirements with refusal behavior. An agent literally knows the failure modes and costs before calling.

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 genuinely long (a dense wall of text), but it is front-loaded — the first two sentences carry purpose and call modal, and sections are clearly marked with caps headers. The tool is complex (13 optional params, two modes, auth, billing, rate-limit, concurrency, free-plan constraints), so the length is mostly earned. It loses a point for writing style: the crammed prose would read better as bullets; the token-cost and quota paragraphs are best with tight formatting.

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 13-parameter, 0-required, complex tool, the description covers everything an agent needs: both modes, which params apply to which mode, free/paid quotas, restricted-window semantics, rate limits, concurrency policy, auth refusal behavior, paging defaults, and even examples. The output schema exists, so not delineating return fields is acceptable. There is almost nothing left for an agent to discover through costly trial-and-error.

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% and the schema itself is unusually detailed, so the baseline is 3. The description adds strategic meaning beyond the schema: it connects parameters into usage recipes (country+relevance+exclude_cloaking to surface storefronts), explains the catalog-vs-profile split that determines which parameter groups apply, clarifies sort=active 'hot now' semantics, and explains the pricing consequence of limit. This is real additive value rather than schema restatement.

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+resource: 'Explore HUBS where ads send traffic, grouped by destination', enumerates the categories (Social Media, App Stores, Amazon, E-commerce, Popular, Platforms), and distinguishes the two call modes (catalog vs hub drill-in). It clearly separates this tool from sibling search tools like search_ads and search_advertisers by anchoring on destination grouping rather than ad/campaign or individual objects.

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 explicit when-to-call scenarios: 'Call WITHOUT hub to get the catalog', 'Call WITH hub set to a slug to drill into', an example recipe ('combine country + sort=relevance + exclude_cloaking for a per-geo ranking of real storefronts'), and clear when-not guidance ('window is a no-op', 'a category slug is rejected'). It stops short of naming sibling tools as alternatives or explicitly stating 'use search_ads instead when...', so it gets a 4 rather than 5.

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