Create Incident Action Item

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

Annotations already declare non-read-only, non-idempotent, non-destructive, open-world behavior, so the description only needed to add context such as validation rules or the custom-fields feature gate. It adds nothing: no mention that form_field_selections are silently ignored unless the org enables action-item custom fields, and no note that repeat calls create duplicates (idempotentHint=false).

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 short sentence is easy to scan, but "from provided data" is wasted space and the brevity here reflects under-specification rather than tight writing.

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 tool with a deeply nested JSON:API payload, ten-plus optional attribute groups (Jira linkage, assignees, custom fields), and no idempotency, the description omits nearly everything an agent needs to construct a valid call. The presence of an output schema and detailed nested property descriptions offset some of this, but the envelope and usage context are 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 only 50%, and the undocumented half is the critical JSON:API `data` envelope with its fixed `type: incident_action_items` value. The description does not explain this envelope or the relationship between incident_id and the nested payload, so it fails to compensate for the coverage gap even though the nested attribute descriptions are rich.

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?

"Creates a new action item" names a specific verb and resource, but "from provided data" is pure filler and the description never anchors the action item to the parent incident, which is the defining characteristic versus siblings like update_incident_action_item or create_incident. It is barely more than the title restated.

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?

There is no guidance on when to use this instead of update_incident_action_item or create_incident_event, and no stated prerequisite that the incident must already exist. The agent must infer usage entirely from the name and schema.

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