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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the read-only safety profile. The description adds meaningful behavioral context: CSV output format, per-day bucketing, DAY resolution with the 'to must be at least 1 day in the past' constraint, and the default ranking behavior. Slightly below 5 because page/limit behavior is only partially described.

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?

Dense, information-rich single paragraph that front-loads the purpose, then covers format, ranking options, bucketing guidance, and constraints. Every sentence earns its place — no filler, tautology, or repetition of schema-restated content.

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?

Output schema exists, so return-value explanation isn't needed. The description covers ranking behavior, CSV columns, per-day bucketing, variant scoping, and time constraints — quite complete. Minor gap: limit behavior and pagination are not described, and graphId semantics are left to the schema definition (which just names the field with no type detail).

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 covers 6 params but only describes from/to/limit/orderBy semantics; graphId and variantName are minimally described in schema. The description compensates by explaining variantName ('optionally scopes to one or more variants (omit for all)') and orderBy default semantics including the exact enum values. However, graphId still has no description and the limit default/maximum is only partially explained in schema.

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+resource: 'Top operations by usage/health for a graph over a time window.' It clearly distinguishes from siblings like GetSubgraphMetrics (subgraph-level) and GetTopOperations by emphasizing the time-window + per-day CSV bucket format and CSV output.

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 explains when to use: it names the ranking options (orderBy) and when each is appropriate — REQUEST_COUNT for busiest, REQUEST_WITH_ERROR_COUNT for error-prone, REQUEST_LATENCY_P99_MS for slowest. It also notes the exclusion: 'to must be at least 1 day in the past' and DAY resolution as a constraint. The per-day bucket guidance on summing columns for window totals provides practical usage direction.

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