Incident postmortem (pydantic-ai + sampling)

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

No annotations are present, so the description carries the full disclosure burden, and it does real work: it reveals that generation is delegated to a pydantic-ai agent and that the LLM is supplied client-side via MCP sampling — a genuinely useful trait because the call may depend on client sampling capability and latency. It stops short of full transparency by not stating whether the draft is persisted back to the incident or how unknown incident IDs are handled, but for a zero-annotation tool this is substantive behavioral disclosure.

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 22-word sentence with the essential verb-object ('drafts a short blameless postmortem from an incident's facts') front-loaded and the mechanism clause second. No filler, and every clause adds information rather than restating the tool's name or title.

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 one-parameter tool with an output schema present, the description is close to sufficient: it explains the input's purpose and the output's nature. Remaining gaps — side effects and invalid-input behavior — are minor at this complexity, and the output schema covers return semantics, so nothing critical is missing.

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 0%, so the property block offers only a type and title for incident_id; the description compensates only partially by mapping the parameter to 'an incident's facts'. It does not state the id's format, how it is obtained (e.g., via list_incidents), or what an invalid id produces — the added meaning is real but minimal.

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 ('drafts') and a specific resource: a short blameless postmortem produced from an incident's facts. This cleanly separates it from the operational incident-management siblings (list_incidents, open_incident, update_incident), which manage incident state rather than produce documents. The output's kind, length, and tone are all named up front, so an agent can predict the artifact without opening the schema.

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 intended use is implied — call when you want a postmortem for a given incident_id — but there is no explicit when-to-use or when-not-to-use guidance, and no alternatives are named. Given LLM-driven siblings like summarize and poet, the description does not tell an agent what distinguishes this from those, beyond the output being a postmortem rather than a summary.

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