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

It discloses important behaviors: 'Runs from compact rollups', 'Results expire after 24 hours', 'never exceed 100 rows', 'Effect: workspace-change', 'Retry with the same idempotency_key', 'Permission: analytics:read'. Annotations include readOnlyHint: false, but description contradicts? No, readOnlyHint=false means it might write, and effect workspace-change indicates mutation, so consistent. It adds value beyond annotations by specifying the workspace-change effect and permission requirement, and the expiration/results limits are useful. Only minor: doesn't mention details about queuing behavior (how to poll?), but overall good.

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 very concise, with 6 short sentences covering key aspects: data source, range limits, expiry, row limit, effect, retry, permission, and API reference. Every sentence adds value, no fluff. Front-loaded with the most important operational detail (rollups and range). Excellent structure.

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?

Given the tool complexity (has nested body schema, output schema, idempotency key), the description covers essential operational details but misses some aspects like what the output schema contains or how to handle queued results (e.g., polling a job ID). However, the output schema exists, so the description doesn't need to explain return values. The description covers expiration, row limit, permission, and retry. It's fairly complete for a creation tool, but doesn't mention that it can reuse existing reports if same parameters? The title says 'Create or reuse' but description doesn't explain when reuse happens. That could be a gap. But overall it's good.

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 schema already documents body and idempotency_key. The description adds 'Results expire after 24 hours' which indirectly relates to parameters? Not really. It doesn't add additional meaning about the parameters beyond what's in the schema, such as the meaning of 'from', 'to', 'group_by' etc. But the schema itself has descriptions for body and idempotency_key, and the nested object has field descriptions? Actually the schema doesn't include descriptions for individual fields like 'from' and 'to' (only format: date). So the description does not add semantic meaning for the date range or other fields. However, it mentions 'Ranges through 31 days complete inline' which gives context for the date range. That's a small addition. Baseline 3 because schema coverage is high, but the description could have elaborated on the meaning of group_by or source_ids, but it doesn't. So 3 is appropriate.

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 'Runs from compact rollups' and 'Effect: workspace-change', and the title says 'Create or reuse an analytics report', which is specific about the action and result. It distinguishes from sibling analytics_get_report by mentioning creation/reuse. However, it could be more explicit about the difference between creating and reusing, but overall purpose is clear.

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 mentions constraints like 'Ranges through 31 days complete inline; longer ranges are queued' and 'Results expire after 24 hours' which tells when to use it (for short ranges) and implies queuing for longer ones. It doesn't explicitly name alternatives, but the context of siblings like analytics_get_report implies retrieval vs creation. Additional guidance on when to reuse vs create would be helpful, but the description is decent.

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