get_metric_report

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

Since no annotations are provided, the description carries the full burden. It discloses two behavioral traits: metrics with no data return an error field instead of failing the report, and the performance pack only retains 28 days of history. These are useful but not comprehensive; it does not mention auth, rate limits, or other edge cases. This is adequate but not rich.

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 somewhat long due to the extensive metric lists, but it is well-structured with bullet points for each pack, making it easy to scan. The core purpose and usage guidelines are front-loaded. Every sentence contributes: the purpose, the pack list, the use case, and the retention note. It is appropriately concise for the information it must convey.

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's complexity (10 parameters) and the presence of a complete schema, the description focuses on the high-level concept of packs, usage guidance, and key behavioral notes. It does not detail every parameter's behavior (e.g., filter semantics) but those are in the schema. The absence of an output schema is acceptable as the tool likely returns straightforward results. The description covers enough for an agent to decide when to use it and what to expect.

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 coverage is 100%, so the baseline is 3. The description adds substantial semantic value for the 'pack' parameter by enumerating all metrics in each pack, which is essential for correct selection. It also adds context about the tool's purpose. Other parameters are adequately described in the schema, so the description meaningfully supplements the pack parameter.

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 clearly states a specific verb and resource: 'Query a themed group of related metrics in one call.' It lists the available packs and even distinguishes its scope from single-number queries by including 'Use this when a question is about an area rather than a single number.' This differentiates it from sibling tools like query_metric or query_metrics.

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 description explicitly says when to use ('Use this when a question is about an area rather than a single number') and provides concrete examples. It does not explicitly name alternative tools or state 'when not to use,' but the guidance is clear enough that an agent could infer the appropriate context. It also mentions optional breakdown and comparison features.

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