Modify an incident

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

Annotations already indicate readOnlyHint=false, destructiveHint=true, and idempotentHint=false, and the description adds meaningful side-effect context: 'may notify recipients or change tenant data' and the requirement for write opt-in and confirm:true. It also notes the body is open JSON, which is useful. This goes beyond the annotations to describe consequences and prerequisites.

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 compact, about three sentences, and front-loads the main action with the endpoint. It includes a reference link and key constraints without verbosity. Some information is densely packed but still efficient; a slight reorganization could improve scannability.

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 mutation tool with no output schema, the description provides essential operational details: endpoint, required confirm, lookup options, allowed body fields, and side effects. It does not describe the response format or error handling, which is a minor gap given the open-world and destructive nature, but the core information needed to invoke the tool is present.

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 descriptions cover all three parameters (body, query, confirm) with detailed notes. The tool description adds extra semantics by enumerating allowed body fields (id, incidentIdentifier, summary, description, severity, status) and clarifying that only one of id or incidentIdentifier is needed. This supplements the schema's generic 'open JSON' description.

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 'Modify an incident' and provides the HTTP method and endpoint, distinguishing it from create/get/trigger incident tools. It lists specific body fields and lookup options, making the tool's purpose unambiguous and distinct from siblings like create_an_incident or trigger_an_incident.

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 gives practical guidance on lookup (id vs incidentIdentifier) and prerequisites (operator write opt-in, confirm:true), but does not explicitly state when to use this tool over alternatives like create_an_incident or trigger_an_incident. The usage context is implied rather than explicit, so it lacks clear when-not-to-use guidance.

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