Update form recipients — nested

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

The description goes well beyond the annotations by warning that a Python sample incorrectly uses requests.post while the actual method is PUT, and explains that the call may notify recipients or change tenant data. It also clarifies preservation behavior and the operator write requirement, which complements destructiveHint=true and 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?

The description is front-loaded with the endpoint and the critical array-shape clarification, and nearly every sentence earns its place. It is slightly dense, especially the meta-note about the incorrect Python sample, but that caveat is operationally important.

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?

Given no output schema and a highly permissive body schema, the description covers the endpoint, array payload semantics, preservation expectations, auth requirements, and side effects. It still defers detailed recipients field structure to the official operation link, so the tool is not fully self-contained.

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 body parameter in the schema is an unconstrained recursive anyOf, so the description adds essential meaning by stating the body is a top-level JSON array and that field descriptions apply to array entries, not root object keys. It also names 'recipients' as the relevant body field and reinforces confirm must be true, significantly compensating for the schema's lack of structure.

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 the specific action 'Update form recipients', identifies the 'nested' variant, and gives the exact endpoint. The 'nested' qualifier and the top-level JSON array note distinguish it from the sibling xmatters_update_form_recipients, so an agent can tell them apart.

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 important conditions: operator write opt-in, confirm:true, and preserving entries that should not be replaced. However, it does not explicitly name alternative tools or state when to choose the nested version over the non-nested sibling, deferring some selection guidance to the 'nested' label and official documentation.

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