update_incident

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

With no annotations, the description carries the behavioral burden. It clearly indicates this is a mutating operation and discloses the only supported status transition, which is the most likely side effect. It does not mention permissions, reversibility, or behavior on already-resolved incidents, but the basic safety profile of a state-changing update is evident.

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 front-loaded sentence with the verb and resource first; the status transition earns its place as key behavioral context. It is efficient, though it could have added a brief alternative-tool pointer without becoming bloated.

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 output schema exists and the input schema carries field constraints, the description offers enough for a basic call: edit an active incident, optionally move to in_progress, and rely on the schema for fields. It is incomplete around what 'active' means, whether resolved incidents are excluded, and how this relates to resolve_incident.

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 description needed to add meaning to the six parameters, but it adds none. The schema's self-explanatory names and constraints partially compensate; still, the description does not clarify distinctions like note vs description or how the optional fields interact.

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 uses the specific verb 'Edit' and names the resource, an incident, while constraining the action to active incidents and the status transition open to in_progress. It is clear enough to distinguish from create_incident and resolve_incident, though it does not explicitly name those siblings.

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 phrase 'active incident' and the open->in_progress transition communicate when the tool applies, but no alternative tools are named and no 'when not to use' guidance is provided. Usage must be inferred from the limited status transition rather than stated explicitly.

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