overview_tag_distribution

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

With no annotations supplied, the description carries the full burden. It does disclose the required permission scope and that this is a GET read against /api/v1/reports/overview/tags, which is real behavioral context the schema cannot convey. It says nothing about rate limits, response shape, or whether results are aggregated across the whole workspace.

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 short and front-loads the tool identity, but two of the four lines (the raw endpoint path and the 'Tags: Reports' label) are administrative noise for an agent, while the one sentence that would matter — what the report returns — is absent.

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 reporting tool with no output schema and no annotations, the description needs to describe the returned data and its aggregation semantics. It instead provides only permission and endpoint metadata, leaving the agent unable to predict the response.

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?

There is a single optional parameter (`days`) and the schema already documents it at 100% coverage, including default, 0-365 clamping, and query-parameter placement. The description adds no extra meaning, so the baseline of 3 applies.

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 restates the name ('Get Overview Tag Distribution') and adds only the endpoint path. It signals a reporting read but never defines what 'distribution' means (tag counts? per-conversation tags? over time?), and it does nothing to separate it from the sibling overview_counts, overview_charts, or overview_csat tools.

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 only precondition given is the `reports:manage` permission, which is genuinely useful. There is no guidance on when an agent should pick this overview report over the other overview_* siblings, and no exclusions or alternative routing.

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