get_analytics_group_models

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

Annotations already cover the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the bar is lower. The description adds genuine value beyond annotations by disclosing pagination behavior and the enterprise entitlement constraint ('Enterprise-gated. Returns 403 on non-Enterprise Portkey plans'), which is critical operational context. No contradiction with annotations.

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?

Three sentences, each earning its place: the first states what it returns, the second provides when-to-use routing, and the third discloses the enterprise gating. The core purpose is front-loaded; the alternative routing and gating note follow in logical order with zero filler.

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?

Yes. With an output schema present, return values don't need explaining; with annotations covering idempotence and read-only safety, that burden is lifted; the description covers purpose, sibling routing, pagination, and the 403 failure mode. The two required time-range parameters are fully documented in the schema. Nothing an agent needs to call this correctly is missing despite the 31-parameter complexity.

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 description coverage is 100%, so the baseline of 3 applies. The description's mention of 'request count, cost, and token usage' in the output subtly echoes the filter dimensions (cost_min/max, token min/max params), but it doesn't add parameter-level meaning beyond what the schema already documents. The schema carries the heavy lifting here, and that's acceptable.

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 ('Get'), resource ('paginated per-model breakdown'), and the exact output shape (total_groups, group_count, models array with request count, cost, token usage). It also names the grouping dimension (per-model), which immediately distinguishes it from sibling group analytics tools like get_analytics_group_users, get_analytics_group_providers, and get_analytics_group_metadata.

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?

Explicitly states the use case ('compare model cost, popularity, and efficiency') and names the two sibling alternatives with the exact condition that should route the agent elsewhere ('use get_token_analytics or get_cost_analytics for time-series trends instead'). Nothing is left to inference.

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