analytics_query

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety and external-service profile is covered. The description reinforces the external API target (YouTube Analytics API v2) but adds no detail about quotas, rate limits, or the shape of the returned rows. With annotations carrying the safety burden, a 3 is appropriate.

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?

It is a single front-loaded sentence with no filler, stating vendor, endpoint and scope. It is tight and appropriately sized, though the trailing clause about 'чего нет в готовых отчётах analytics' is slightly redundant with the purpose already stated.

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?

With an output schema present and annotations covering the read-only/open-world profile, the description only needs to establish purpose and routing, which it does. It could say more about when this raw-query escape hatch is preferable and any limits on it, but nothing essential for a correct call is missing.

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%, and each parameter (sort, filters, metrics, dimensions, dates, max_results) has a concrete example in the schema. The description adds nothing about parameter syntax or restrictions, so it sits at the baseline of 3 — the schema does all the work.

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 names a specific verb+resource combination — an arbitrary 'reports.query' against the YouTube Analytics API v2 for a channel — so the agent knows exactly what the tool does. It also positions itself against the sibling 'analytics' tool by scoping itself to what the ready-made reports don't cover, which helps differentiation.

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 states the selection condition clearly: use this for queries that the prepared 'analytics' reports cannot answer. That implicitly routes the agent away from the simpler sibling. It does not, however, name the 'analytics' tool explicitly or describe prerequisites/auth, so it falls short of a full 5.

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