Modify a scenario

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

Annotations already indicate destructive/not read-only, but the description adds meaningful context by warning that it 'may notify recipients or change tenant data.' It also specifies the write opt-in requirement and confirms the exact mutation approval mechanism, going beyond the generic annotation flags.

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 front-loads the core verb and resource, then provides the endpoint, field list, reference link, and safety requirements in a compact sequence. The long field list is necessary given the schema's generic body definition, and there is no filler or repetition.

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?

With no output schema, the description does not explain return values, which may be acceptable for a mutation but is still a gap. More importantly, the body field names are listed without semantics, and the only path to understanding them is the external reference link. The description is adequate but leaves an agent to consult external docs for field meanings and optionality.

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?

The input schema only explicitly defines path.formId, body.id, and confirm, with body as a generic object allowing arbitrary properties. The description compensates by enumerating the known body fields (attachments, escalationOverride, recipients, etc.), giving an agent a concrete starting point for constructing the payload even though per-field meanings are not detailed.

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?

States the operation explicitly as 'Modify a scenario' and reinforces it with the HTTP endpoint POST /api/xm/1/forms/{formId}/scenarios, which clearly targets an existing scenario resource. The list of body fields (id, name, priority, etc.) further distinguishes this from sibling create/get tools without ambiguity.

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 mentions prerequisites (operator write opt-in, confirm:true) and side effects but gives no explicit guidance on when to use this tool versus alternatives like xmatters_create_a_scenario or xmatters_get_a_scenario. Without naming the alternative for creating a new scenario, an agent must infer that modification requires an existing scenario id.

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