update_incident

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

Annotations declare readOnlyHint=false and destructiveHint=false, and the description's 'record' implies mutation, consistent with those. However, the description does not disclose any additional behavioral traits such as side effects, notifications, or reversibility. It adds little beyond what the annotations already convey, so it meets the baseline but not more.

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?

One concise sentence with no wasted words. The essential purpose is front-loaded, and the description is appropriately sized for the tool's simplicity.

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 4 parameters and no output schema, the description is too sparse. It does not explain the relationship between intent and message, does not mention that allowed intents depend on current incident state (only in schema), and gives no examples of full usage. An agent would need to inspect the schema carefully to use it correctly, so the description alone is insufficient.

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 low (25%). The description mentions 'resolve, acknowledge, comment...' which partially maps to the intent parameter, and 'change severity' maps to severity. However, it does not explain the message or incident_id semantics, nor does it clarify when message is needed or how it relates to intent. It adds marginal value over the schema's existing descriptions and does not compensate for the coverage gap.

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 clear action (record an action) on incidents, with examples of actions and severity change. It distinguishes from create_incident by implying modification, though it does not explicitly say 'update existing', so it is clear but not perfectly specific.

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 no guidance on when to use this tool versus alternatives like create_incident or call_write. It does not mention that get_incident should be checked first for allowed actions (only in the schema), nor does it provide any exclusions or conditions. The usage context is entirely implied.

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