metrica.hf.report_devices

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds nothing beyond that: no mention of date-range semantics, pagination, default aggregation, or what 'device' dimension means. With annotations carrying the safety profile, the description contributes essentially zero extra behavioral context.

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 single fragment is brief but this is under-specification, not conciseness. Front-loading is moot when there is effectively no content to front-load, and the 'Human-friendly:' prefix carries no information.

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. However, for a tool with five parameters, a date-range reporting scope, and a device dimension, the description omits nearly everything an agent needs to call it correctly, leaving the definition incomplete relative to its 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 only 20% (only account_id is documented), so the description bears the burden of compensating and does not. It says nothing about limit, date_from/date_to formats, or counter_id, leaving four of five parameters undocumented in both places.

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 'device report' essentially restates the tool name metrica.hf.report_devices rather than stating a specific verb and resource. It gives no hint about what a 'device report' contains (device breakdown of traffic/sessions) or what it distinguishes from siblings like report_geo or report_landing_pages. This is a near-tautology.

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?

There is no when-to-use, when-not-to-use, or alternative guidance anywhere in the description. With many sibling report tools (metrica.hf.report_geo, report_landing_pages, report_utm_campaigns), an agent is given no cue about when this one is appropriate. This is misleading by omission for a family of near-identical report tools.

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