ops_incident_update

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

With no annotations provided, the description carries the full burden of behavioral disclosure. While it hints at persistence ('persist the new operational status') and optional threading ('post a thread update'), it fails to disclose critical mutation safety details: dry_run behavior, side effects of severity changes, notification triggers, or whether updates are reversible. For a 10-parameter write operation, this is insufficient.

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 a single, front-loaded sentence with no redundant words. However, given the high parameter count and zero schema documentation, it may be overly terse rather than appropriately concise—leaving too much weight on the schema.

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 complex mutation tool with 10 parameters, 0% schema coverage, and no output schema or annotations, the description is incomplete. It fails to explain enum semantics (severity levels, status workflow), the purpose of dry_run, or what successful execution returns.

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%, requiring the description to compensate significantly. It only implicitly references 3 of 10 parameters (incident_id via 'tracked incident', post_update via 'post a thread update', status via 'operational status'). It completely omits semantics for critical fields like dry_run, token_override, next_update_minutes, and the distinction between summary vs details.

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 the core action ('Update a tracked incident') with specific verbs and resource. However, it does not explicitly differentiate from sibling tools like ops_incident_create or ops_incident_close, leaving the agent to infer the lifecycle distinction from the word 'Update' alone.

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?

No guidance is provided on when to use this tool versus ops_incident_close or ops_incident_create. There is no mention of prerequisites (e.g., that the incident must exist) or workflow conditions (e.g., whether closed incidents can be updated).

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