generate_incident_summary

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

No annotations exist, so the description carries the full behavioral burden. It reveals the input domains but nothing about execution traits: an aggregation over three telemetry sources is presumably slow and possibly expensive, yet no latency or cost hint is given. It also leaves ambiguous whether "remediation runbooks" are generated text in the response or artifacts written somewhere - a meaningful safety question for a tool with no destructiveHint.

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?

A single dense sentence with no filler, and the deliverable is front-loaded alongside the action verb. Nothing is redundant, though it is compressed to the point where no structural element (usage cue, cost note) survives.

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?

This is a high-complexity tool - it fans out across three data sources and produces a multi-section report with runbooks - yet has no annotations and no output schema to describe the result. The description says nothing about the report's structure, severity classification, expected runtime, or whether generation has side effects. For this level of complexity and zero structured support, the one-line description is not sufficient.

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 all three parameters (serviceName, lookbackMinutes, incidentTimestampIso) are already documented, including the default window of 30 minutes. The description adds no new parameter meaning - it never mentions the lookback window or how the timestamp anchors the synthesized data. Baseline 3 applies when the schema does the heavy lifting.

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 ("Synthesize") and a concrete deliverable ("SRE incident diagnostic report with remediation runbooks"), and it enumerates the three input domains (metrics, OpenTelemetry error traces, Git commits). This is clearly more than a restatement of the name. It stops short of explicitly contrasting itself with the sibling tools that supply those same signals (fetch_error_traces, query_service_metrics, correlate_incident_with_git).

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?

Usage is only implied: the wording suggests this is the aggregating call you make when you want one consolidated report rather than individual data pulls. There is no explicit when-to-use statement, no prerequisite (e.g. call after you already know the affected service), and no exclusion or cost warning relative to the four sibling tools. An agent must infer the routing decision from the noun "report" alone.

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