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

Beyond the annotations (destructiveHint, readOnly false), the description discloses that the call may notify recipients and alter tenant data, and that operator write opt-in plus confirm:true are required. This is exactly the kind of side-effect context an agent needs.

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?

Three compact sentences: action/endpoint, body payload, and prerequisites/side effects. No filler; every line carries useful information.

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?

Covers endpoint, payload field, confirmation requirement, and side effects for a write operation with no output schema. It does not describe expected success/error response, but this is a minor gap given how much context is provided.

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?

Adds the critical body-field name 'comment', which the generic body schema does not specify. The eventId path parameter and confirm parameter are already documented in the schema, so the description fills an important 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?

States the action as a specific verb + resource ('Add a comment to an event') and reinforces it with the exact POST endpoint. This clearly differentiates from sibling getters like xmatters_get_event_annotations.

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?

Gives explicit operational context: operator write opt-in, confirm:true, and notification/tenant-data side effects. It doesn't name alternative tools for read-only annotation retrieval, but the usage context is clear enough to avoid misuse.

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

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

The description adds meaningful side-effect context beyond the annotations: it requires operator write opt-in, confirm:true, and warns that it may notify recipients or change tenant data. This aligns with destructiveHint=true and provides useful behavioral expectations.

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 compact and front-loaded with the core action, then supplies the endpoint, key body fields, requirements, and a reference link. It avoids unnecessary prose, though the opening sentence largely restates the tool title.

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?

The description gives enough to attempt the call: endpoint, path parameters, body field names, confirm requirement, and side-effect warnings. Still, it lacks details on required body fields, response shape, and error cases, which are important for a destructive, open-world mutation with no output schema.

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 description lists body fields (recipient, position, delay, escalationType, inRotation, onDuty), which adds value because the schema only defines body as an arbitrary JSON payload. However, it does not explain the meaning, types, or allowed values of these fields, leaving important semantics to the external reference.

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 operation as 'Add a member to a shift' and reinforces it with the exact REST endpoint POST /api/xm/1/groups/{groupID}/shifts/{shiftID}/members. This distinguishes it from siblings like xmatters_add_a_member_to_the_group and xmatters_get_members_in_a_shift.

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 given about when to choose this tool over alternatives, such as adding a member to a group or retrieving shift members first. The description focuses on how to invoke the API but not on the decision context.

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

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

Beyond the annotations, the description discloses important behavioral context: it requires operator write opt-in and confirm:true, and warns that it may notify recipients or change tenant data. This matches the destructiveHint and non-readOnly annotations and gives an agent a clearer risk picture.

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 compact and front-loaded: the action, endpoint, body fields, requirements, and side effects each get a short clause. There is slight redundancy with the title's first phrase, but no padding.

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 mutating tool without an output schema, the description covers the essential call context: endpoint, payload field names, prerequisites, and possible side effects. It lacks valid-value guidance for id/recipientType and any response/error hints, but the reference link and body-field listing are enough for a capable agent.

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 schema's body parameter is a generic JSON payload, so the description adds value by naming 'id' and 'recipientType' and placing groupID in the endpoint URL. It stops short of explaining valid values or relationships, but it meaningfully compensates for the schema's vagueness.

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 uses a specific verb and resource ('Add a member to the group') and confirms it with the exact endpoint, POST /api/xm/1/groups/{groupID}/members. This clearly distinguishes it from the sibling removal operation (xmatters_remove_a_member_from_the_group).

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?

Usage is implied by 'Add a member to the group' and the POST endpoint, but the description never explicitly states when to use this tool over alternatives or excludes other operations. An agent must infer from the sibling names.

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

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

Annotations already mark this as destructive and non-read-only, and the description adds meaningful side-effect context: it 'may notify recipients or change tenant data' and requires operator write opt-in plus confirm:true. This goes beyond the structured annotations by warning about notification and tenant-data mutation.

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 dense but well-structured: a one-line purpose, the endpoint, key body fields, a reference link, and the critical write/confirmation requirement. Every sentence earns its place, and the essential warning about tenant data is front-loaded enough.

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 destructive mutation with no output schema, the description covers the essential inputs (incidentID, body fields), the approval requirement, and side effects. It does not need to explain return values since none are defined, and the reference link supplements details on payload structure.

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 schema describes body only as a generic 'Complete API JSON payload,' so the description's mention of 'Body fields: entryType, text' adds real semantic value. It also names the path parameter via the endpoint and clarifies confirm's role, complementing the 75% schema coverage.

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 opens with 'Add a timeline note,' a specific verb plus resource, and reinforces it with the exact endpoint POST /api/xm/1/incidents/{incidentID}/timeline-entries. This clearly distinguishes it from sibling add/comment/event tools like xmatters_add_a_comment_to_an_event.

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 implies usage by naming the endpoint and body fields, but it does not explicitly state when to prefer this tool over alternatives or when not to use it. The write opt-in and confirm:true requirement gives operational context but no comparative guidance.

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

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

The description substantially expands on annotations: it explains that the request body is a top-level JSON array, warns that preserving existing entries matters, clarifies that PUT is the real method despite a Python sample using POST, and discloses side effects such as notifying recipients or changing tenant data. This is valuable beyond the raw annotations.

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 compact and front-loads the action and endpoint. Each sentence adds a relevant caveat or requirement, though the 'Body fields: recipients' fragment feels slightly abrupt and the official-operation note is redundant with the reference link.

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 the mutating nature, generic body schema, and lack of output schema, the description covers method, body shape, confirmation requirements, destructive side effects, and preservation behavior. It does not describe response format or recipient entry fields in detail, but the official reference and imperative to consult the operation close most of the gap.

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 schema is generic for body and high-level for confirm, but the description adds needed meaning: the body is a top-level array and the listed body fields describe array entries rather than root keys. It also names 'recipients' and links to official documentation. It leaves recipient field shapes somewhat vague, but it compensates beyond the schema baseline.

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 opens with 'Add subscribers' and pinpoints the exact REST operation: PUT /api/xm/1/subscriptions/{subscriptionId}/subscribers. This identifies the specific resource and action, and the endpoint distinguishes it from sibling tools such as get_subscribers, unsubscribe_a_user, and create_a_subscription.

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 clear context for when this tool is appropriate: adding subscribers to a subscription, with an explicit requirement for operator write opt-in and confirm:true. It does not explicitly name alternative tools or state when not to use it, but the operation and prerequisites are clear enough.

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

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

Annotations already indicate destructive behavior and non-read-only, but the description adds valuable side-effect context: it may notify recipients or change tenant data, and requires explicit write opt-in. This goes beyond the structured annotations.

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 compact and front-loaded: purpose, endpoint, body fields, reference, requirements, and side effects are each covered in short, scannable fragments. No unnecessary filler.

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?

Covers the essential call information: endpoint, required body fields, approval requirements, and side effects. However, it omits valid status values and response/error behavior, and the body schema remains generic enough that an agent may need the linked documentation.

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 schema's body parameter is a generic recursive anyOf, so the description's 'Body fields: id, status' provides real semantic meaning absent from the schema. It also clarifies query parameters are generic and pagination is explicit, though valid status values are not listed.

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 a specific verb and resource ('Change the status of an event'), identifies the HTTP endpoint, and lists body fields (id, status). This distinguishes it from related event tools like trigger_an_event or get_an_event.

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?

Provides prerequisites such as operator write opt-in and confirm:true, but gives no explicit guidance on when to use this tool versus alternatives like triggering an event or adding a comment. The intended context is implied rather than stated.

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

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

Annotations already mark the call as non-read-only and destructive, and the description adds meaningful behavioral context: 'may notify recipients or change tenant data' and the operator write opt-in requirement. This goes beyond the structured hints and helps the agent anticipate side effects.

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?

Three dense sentences cover the operation, endpoint, body fields, reference, and requirements without filler. The field list is a bit long but earns its place because the schema does not enumerate these fields.

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 with no output schema and a permissive body schema, the description provides endpoint, body fields, auth requirements, and side effects, plus a link to full API docs. It does not describe the expected response or error behavior, but the reference covers the remaining detail.

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 schema is a generic recursive anyOf with no named fields, so the description's enumeration of allowed body fields (changeType, source, summary, changedAt, changedBy, details, externalIdentifier, service) is essential. It also clarifies the confirm parameter's const true requirement and notes query pagination behavior.

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 specific action and resource: 'Create a change record' with the REST endpoint POST /api/xm/1/changes. The verb 'Create' and the resource 'change record' clearly separate it from sibling retrieval tools such as xmatters_get_changes and xmatters_get_a_change.

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 makes the operation clear and includes prerequisites ('Requires operator write opt-in and confirm:true'), but it does not explicitly state when to prefer this tool over its get_*/list_* siblings or when it should not be used. Usage context is implied by the verb rather than spelled out.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the description adds value by stating 'may notify recipients or change tenant data' and the confirmation requirement. It does not contradict annotations and provides context on side effects beyond the flags. No coverage of topics like idempotency or rate limits, but annotations cover idempotency hint.

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 concise and front-loaded with the primary action. It packs endpoint, body fields, a reference, and requirements into two sentences without excessive verbosity. Slight clutter from the HTTPS link, but it earns its place as an authoritative reference.

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 a mutation tool with a nested object and no output schema, the description covers the essential operational aspects: side effects, prerequisites, and field hints. It doesn't explain return values, but the absence of an output schema lowers that burden. The reference link and endpoint provide further context. Minor gaps like optional field meanings are not critical for invocation.

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 schema's body description is generic ('Complete API JSON payload'), so the description compensates by listing specific fields (name, description, enabled, accessibleByAll, position). This adds meaning beyond the schema, which only requires name and enabled. The confirm parameter semantics are also clarified in the schema, so the description's mention reinforces it.

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 a specific verb ('Create') and resource ('a communication plan'), and includes the HTTP method and endpoint. It distinguishes this from siblings by naming the action explicitly (create vs. get, modify, delete). The purpose is unambiguous.

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 specifies the action clearly and lists prerequisites (operator write opt-in, confirm:true), which implies when to use it (to create). It does not explicitly mention when not to use it or alternatives, but the create/resource pairing is obvious within the sibling set. Slight lack of explicit exclusions or alternative routing.

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

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

The description goes well beyond the annotations by stating the API method, the requirement for operator write opt-in, and the side effects that this mutation may notify recipients or change tenant data. Combined with destructiveHint=true and readOnlyHint=false, the agent gets a clear and accurate picture of the operation's impact.

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 dense but not bloated: it front-loads the core action and endpoint, states the key constraint about mobile push devices, lists the body fields, and points to the reference. The field list is long but earns its place given the open body schema and lack of detailed parameter documentation.

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 no output schema and a generic body schema, the description provides necessary context: endpoint, prerequisites, side effects, field names, and a documentation reference. It could add more detail about response behavior or device-type-specific requirements, but the reference and explicit caveats make it reasonably complete for an agent.

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 schema coverage is 100%, but for the body parameter the schema is a generic recursive open-world type. The description compensates by enumerating the relevant body field names and noting that device-type-specific fields are conditional and nested structures remain open. This adds real meaning beyond the schema's 'Complete API JSON payload' text.

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 specific verb and resource ('Create a device') and backs it with the exact REST endpoint. It also clarifies scope by noting device-type-specific fields and the mobile push device exception, which helps distinguish this create operation from get, modify, and delete device siblings.

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 includes an explicit use-vs-alternative cue: mobile push devices cannot be created via REST and existing push devices can be modified. It also states a prerequisite (operator write opt-in and confirm:true). It does not explicitly name sibling tools like modify_a_device, but the conditional guidance is sufficient for correct routing.

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

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

Annotations already indicate destructive=true, readOnly=false, and idempotent=false. The description adds meaningful behavioral context: it requires operator write opt-in and confirm:true, may notify recipients, and may change tenant data. This goes beyond the structured annotations without contradicting them.

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 first sentence and endpoint are clear, but the description includes confusing internal notes about JavaScript/Python requests, cURL examples, and 'C12' that do not help an agent invoke the tool correctly. These should be trimmed or clarified.

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 destructive mutation with a generic body schema, the description provides endpoint, reference, required approval fields, prerequisites, and side effects. There is no output schema, but for a mutation the description is otherwise complete enough for correct invocation.

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 schema's body parameter is a generic anyOf freeform blob, so the description compensates by naming the intended body fields: deviceType, name, description, privileged. It also clarifies the confirm parameter's purpose. Since schema coverage is effectively 100% but shallow, the description adds real value.

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 specific action and resource: 'Create a device name' via POST /api/xm/1/device-names. It is clearly distinct from siblings like xmatters_create_a_device, xmatters_modify_a_device_name, and xmatters_delete_a_device_name.

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 provides useful context—operator write opt-in, confirm:true, possible recipient notification—but it never explicitly says when to use this tool versus alternatives. Usage is strongly implied by the name and endpoint, but no direct routing guidance is given.

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

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

Annotations already mark this as destructive and non-read-only, and the description meaningfully adds detail: it warns that the operation 'may notify recipients or change tenant data', notes open fields in the body, and states the one-section-per-request constraint. This goes well beyond the structured annotation hints.

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 purpose and endpoint, then gives the essential body constraint, field list, reference, and prerequisites. Every sentence earns its place; the field enumeration is justified because the body schema is generic. No filler or redundancy is present.

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?

Despite having no output schema and a complex open body, the description provides enough to invoke the tool correctly: endpoint, required path parameter implied by the URL, body shape, field names, the confirm requirement, operator opt-in, side effects, and a documentation reference. Nothing essential for correct invocation is 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 coverage is 75%, so the baseline is 3, but the description adds value by enumerating the allowed body field names in a schema where body is otherwise a generic JSON payload. It also clarifies that section-specific and Incident Details fields remain open. It does not explain the meaning of each field, so it does not reach a 5.

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 specific verb ('Create') and resource ('a form section'), and reinforces it with the exact endpoint POST /api/xm/1/forms/{formId}/sections. This unambiguously differentiates it from sibling tools like xmatters_get_form_sections or xmatters_create_a_plan_form, even without explicitly naming them.

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 clear operational context: it targets a specific form, accepts one section per request, and requires confirm:true plus operator write opt-in. It does not explicitly name alternative tools or state when not to use it, so it misses the full 'when-not/exclusion' guidance but is otherwise clear.

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

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

Annotations already disclose destructiveHint=true, readOnlyHint=false, and idempotentHint=false. The description adds valuable context: requires operator write opt-in and confirm:true, and warns that it may notify recipients or change tenant data. This goes beyond annotation coverage and alerts the agent to side effects.

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 compact with two sentences. It front-loads the core action and endpoint, then provides a field list, reference link, and critical requirements. The field list is long but necessary given the generic schema. Structure is logical and efficient.

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 destructive, non-idempotent creation tool with nested objects and no output schema, the description covers essential aspects: endpoint, body fields, reference, permission requirements, side effects, and confirmation need. It does not detail each field's semantics, but the reference link fills that gap. Overall, an agent has sufficient information to invoke it correctly.

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 coverage is 100% with descriptions for each parameter, but the body schema is a generic recursive anyOf. The description compensates by listing the specific body fields (allowDuplicates, description, externalKey, etc.), providing meaning that the schema itself lacks. For query and confirm, the description largely restates schema info, but the field list adds genuine value.

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?

Description clearly states the action ('Create a group') and specifies the HTTP endpoint (POST /api/xm/1/groups). It distinguishes itself from sibling tools like modify/delete/get groups by explicitly indicating creation. The list of body fields further clarifies scope.

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 implies usage for creating a new group but does not explicitly contrast with alternatives like xmatters_modify_a_group or mention when not to use it. It does provide some usage conditions (requires operator write opt-in, confirm:true, may notify recipients), but lacks explicit 'use this when' guidance versus siblings.

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

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

Annotations already flag readOnlyHint=false and destructiveHint=true; the description adds meaningful context beyond that by disclosing it 'may notify recipients or change tenant data' and requires operator write opt-in. No contradictions with the annotations.

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?

Purpose is front-loaded in the first sentence, and the endpoint, field list, reference, and requirements each earn their place. The body-field enumeration is a slightly dense comma run-on but remains compact and directly useful.

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 destructive mutation with a nested body payload and no output schema, the description covers the endpoint, fields, prerequisites, and consequences, and provides a reference link. It doesn't describe the response format, but the supplied reference mitigates that gap.

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 100%, so the baseline is 3, but the description adds value beyond the schema by enumerating the concrete body fields (tollNumber, staticBridgeNumber, meetingLink, etc.) that the schema's generic 'Complete API JSON payload' leaves unspecified. This materially helps an agent construct the payload.

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 exact action and resource ('Create an external conference bridge. POST /api/xm/1/conference-bridges') and enumerates the body fields. The verb+resource pairing clearly distinguishes it from siblings like xmatters_get_a_conference_bridge, xmatters_modify_a_conference_bridge, and xmatters_delete_a_conference_bridge.

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?

Provides clear context for when the tool applies (creating a new external bridge) and states a prerequisite ('Requires operator write opt-in and confirm:true'). It does not explicitly name alternative tools or exclusion conditions, but the action/resource pairing is unambiguous against the sibling list.

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

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

Annotations already convey destructiveHint=true and readOnlyHint=false. The description adds valuable behavioral context: it explicitly warns that the operation 'may notify recipients or change tenant data' and requires operator write opt-in, which goes beyond the structured hints. It does not contradict the annotations and covers the key side-effect profile.

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 compact: three sentences covering purpose, endpoint, body fields, reference, prerequisites, and side effects. It is front-loaded with the action and includes no fluff. It is slightly dense but well-organized; a brief list format could improve scanability, so it does not earn a 5.

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 create tool with nested objects, no output schema, and several sibling alternatives, the description provides the essentials (endpoint, body fields, confirm requirement, side effects). However, it does not explain when to choose this over trigger_an_incident or modify_an_incident, nor does it mention response behavior or error handling. This is adequate but leaves clear gaps for an agent deciding between related operations.

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 coverage is 100%, so the baseline is 3, but the description adds meaning by listing 'summary, description, severity, status' as body fields, confirming the required fields and hinting at additional allowed ones. It also explains that confirm must be true and requires the XMATTERS_ALLOW_WRITES setting, which the schema already states but the description reinforces with operational context.

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 identifies the action ('Create an incident') and the resource (incidents), with the endpoint POST /api/xm/1/incidents. It is distinct from the sibling 'trigger_an_incident' in wording, though it does not explicitly contrast them, so it misses the top score for sibling differentiation.

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 states prerequisites (operator write opt-in and confirm:true) and side effects, but provides no guidance on when to use this tool versus alternatives like trigger_an_incident or modify_an_incident. There is no mention of conditions that would make this tool the right choice, leaving the agent to infer usage context.

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

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

Annotations already indicate destructive and non-read-only behavior, and the description adds meaningful context beyond them: it may notify recipients or change tenant data, and requires explicit confirmation and an operator write opt-in. This gives the agent a clearer risk profile without contradicting the annotations.

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 compact and front-loaded: it opens with the action, gives the endpoint, lists body fields, provides a reference, and states requirements and side effects. Every sentence earns its place with no filler or redundancy.

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 destructive create operation with no output schema, the description covers the endpoint, body fields, authentication prerequisite, confirmation requirement, and side effects. It stops short of describing the response shape or required subfields within the body, but the reference link and field list make it sufficiently complete for an agent to invoke it correctly.

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 coverage is 75%, and the description adds substantial value by enumerating the expected body fields (form, name, integrationType, environment, operation, triggeredBy, authenticationType, createdBy, deployed, script, endpoint, integrationService), which is critical because the body schema is a generic any-JSON type. It also reinforces the confirm:true requirement.

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 specific verb and resource ('Create an integration') and gives the exact endpoint, making the tool's function unambiguous. It is clearly distinct from sibling tools like xmatters_modify_an_integration, xmatters_delete_an_integration, and xmatters_get_integrations.

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 provides clear context for when to use this tool: creating a new integration via POST to the plans endpoint. It also gives important prerequisites ('Requires operator write opt-in and confirm:true') and warns about side effects, though it does not explicitly name alternatives or state when not to use it.

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

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

Annotations already indicate a destructive, non-read-only mutation, and the description adds meaningful behavioral context beyond that: 'may notify recipients or change tenant data' and the requirement for an explicit write opt-in. This sets accurate expectations about side effects and authorization without contradicting the annotations.

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 core action and endpoint, then provides the body field list, documentation link, and safety requirements in a compact format. The field list is somewhat long, but each part earns its place by informing the agent about payload, authorization, and side effects.

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 mutating API call with no output schema, the description provides the endpoint, key body fields, a reference link, and critical operational warnings. It could go further by noting required body subfields or a sample payload, but the included context is sufficient for a cautious agent to invoke the tool correctly.

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 coverage is high and the schema documents body, query, and confirm parameters. The description adds value by enumerating the accepted body field names (externalKey, firstName, roles, etc.) and explicitly restating the confirm:true requirement, which is useful because the body schema is a generic recursive JSON type rather than a detailed 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 an explicit action ('Create a person'), names the exact API endpoint, and clearly distinguishes this mutation tool from the many related person tools like get_a_person, modify_a_person, and delete_a_person. The resource and intent are unambiguous.

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 clear context that this tool is for creating a person and even specifies required preconditions: operator write opt-in and confirm:true. It does not explicitly discuss alternatives or exclusions, but the purpose is concrete enough that an agent can determine when to use it.

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

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

Annotations already indicate a write (readOnlyHint=false) and destructive side effects (destructiveHint=true). The description adds context beyond annotations: it requires operator write opt-in and confirm:true, and warns that it may notify recipients or change tenant data. This aligns with the annotations and provides actionable behavioral details.

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 concise and front-loaded: it starts with the action and endpoint, then lists body fields, prerequisites, and a reference link. Every sentence adds necessary information without redundancy. It is well-structured and easy to scan.

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 create operation, the description provides the endpoint, body fields, requirements, and a reference URL. It does not describe the response or error conditions, but the absence of an output schema makes that less critical. The inclusion of write opt-in and notification side effects adds operational completeness.

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 75% and the description compensates for the generic 'body' schema by explicitly listing expected fields (name, value, description). It does not elaborate on planId or confirm beyond what the schema already states, but the added body field information is valuable. The description enhances parameter understanding despite high schema coverage.

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 specific action ('Create a plan constant') with a clear verb and resource, and includes the HTTP method and endpoint. It lists the body fields (name, value, description), which distinguishes it from sibling operations like modify or delete. There is no ambiguity about the tool's purpose.

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 implies usage for creating new plan constants but does not explicitly contrast with sibling tools such as xmatters_modify_a_plan_constant or xmatters_delete_a_plan_constant. It provides prerequisites (operator write opt-in, confirm:true) but lacks explicit guidance on when to choose this over alternatives or when not to use it.

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

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

Annotations already indicate destructive and non-readonly behavior; the description adds that it 'may notify recipients or change tenant data,' which is important side-effect disclosure beyond the annotations. The confirm:true and operator opt-in requirements also clarify the authorization/safety bar. No contradiction with annotations.

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 packs the purpose, endpoint, body fields, a documentation link, and required operational flags into three sentences. Each clause adds distinct value, though the long reference URL adds noise. It is reasonably front-loaded ('Create a plan form' first).

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 destructive create operation with no output schema, the description covers the purpose, path variable, body field names, required confirm flag, authentication prerequisite, and side-effect warnings. It does not describe the response shape or error cases, but these are not essential for invoking the tool; the reference link covers details. It is complete enough for an agent to call correctly.

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 documents name (and allows arbitrary additional body properties); the description enumerates the other body fields (description, triggerType, mobileEnabled, uiEnabled, apiEnabled), compensating for the 75% schema coverage. It also reinforces that confirm must be true. This gives the agent substantial meaning beyond the raw schema.

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 specific action ('Create a plan form') and the HTTP endpoint, which clearly identifies the resource and operation. The verb 'create' distinguishes it from sibling tools like xmatters_modify_a_plan_form and the various get_* tools.

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?

It provides clear context: the endpoint, the required confirm flag, and the operator opt-in prerequisite. However, it does not explicitly compare to alternative tools (e.g., modify_a_plan_form) or state when not to use it, so it falls short of a full 5.

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

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

The description discloses important behavioral aspects beyond annotations: it requires operator write opt-in and confirm:true, and warns that it may notify recipients or change tenant data. This complements the annotations (destructiveHint=true, readOnlyHint=false) by adding specific side effects and prerequisites. No contradiction with annotations.

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 reasonably concise, stating the action, endpoint, body fields, reference, and requirements in a structured way. The list of body fields is necessary but adds length; it could be trimmed by linking to the reference. Overall it is front-loaded with the action and endpoint, making it easy to parse.

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 the complexity of the body (nested JSON with many fields), the description provides a reference link, a list of fields, and critical requirements (opt-in, confirm:true). It does not describe the response format, but for a mutation tool that is less critical. The description is sufficient for an agent to understand how to construct the request, though field semantics are left to the reference.

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 schema covers path (formId), body (generic JSON), query (empty), and confirm (boolean). The description lists the expected body fields (attachments, name, priority, etc.), which adds value over the generic body schema, but it does not explain the meaning or format of each field. The schema description for body already references the API docs, and the description adds the field list but not detailed semantics. Coverage is 75%, so the description partially compensates but does not fully explain parameters.

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 action ('Create a scenario'), the specific resource (scenario in a form), and the HTTP endpoint (POST /api/xm/1/forms/{formId}/scenarios). It is distinct from sibling tools like get_scenarios, modify_a_scenario, and delete_a_scenario, making the purpose unambiguous.

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 implies this tool is for creating a new scenario, but it does not explicitly contrast it with alternatives like modify_a_scenario or state when to prefer this tool. It does mention the prerequisite of operator write opt-in and confirm:true, which is a usage condition, but it lacks guidance on when not to use this tool or when to choose a sibling.

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

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

Annotations already mark this as destructive and non-idempotent; the description adds context by warning that it 'may notify recipients or change tenant data' and that operator write opt-in plus confirm:true are required. This meaningfully supplements the annotation signals without contradicting them.

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 compact and information-dense. The core action and endpoint are front-loaded, and each subsequent sentence adds a distinct piece of operational value: nested object guidance, body fields, reference link, and mutation prerequisites.

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 with no output schema, the description covers the endpoint, body shape, nested-object caveat, external reference, permissions, confirmation requirement, and downstream effects. It does not describe the response format, but the reference link and nested-object pointers make the tool sufficiently callable.

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 coverage is 100%, so the baseline is 3, but the description adds value by naming the body fields (name, event, attachments, recurrence) and explicitly flagging that event and recurrence objects remain open. This helps compensate for the schema's generic body payload definition.

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 precise verb and resource: 'Create a scheduled message' alongside the explicit POST endpoint. It is easy to distinguish from sibling tools like xmatters_get_a_scheduled_message, xmatters_modify_a_scheduled_message, and xmatters_delete_a_scheduled_message.

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 provides useful prerequisites and hints about nested objects, but it does not explicitly say when to choose this tool over alternatives or mention the sibling modify/get/delete tools. Usage context is implied rather than directly stated.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation risk is known. The description adds valuable context: requires operator write opt-in and confirm:true, may notify recipients or change tenant data. This goes beyond the annotations and warns the agent about side effects.

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 compact and front-loaded with the core action and endpoint. The body fields, reference link, and safety warnings are all included in a few sentences. Slight redundancy with the title ('Create a service') but the endpoint and field list earn their place.

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 create operation with no output schema, the description covers the endpoint, required body fields, the confirm requirement, and side-effect warnings. It doesn't describe the response format, but the reference link to the API docs fills that gap. The main missing piece is a note about what a successful response looks like, which is minor given the reference link.

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 100%, so the schema already documents the body and confirm parameters. The description lists the body fields (targetName, description, serviceTier, serviceType, ownedBy) which adds some meaning, but the body is a generic JSON payload reference and the description doesn't explain field formats or requirements beyond the schema.

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 specific verb and resource ('Create a service'), includes the exact API endpoint (POST /api/xm/1/services), and lists the key body fields. It clearly distinguishes this from sibling tools like xmatters_get_services, xmatters_modify_a_service, and xmatters_delete_a_service.

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 identifies the operation and endpoint, and the schema's confirm parameter explicitly states the operator must enable XMATTERS_ALLOW_WRITES. It doesn't explicitly name alternatives or when-not-to-use, but the context of a create operation with write opt-in requirements is clear.

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

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

Annotations already mark this as destructive and non-idempotent, and the description adds valuable behavior beyond that: it requires operator write opt-in, mandates confirm:true, and warns that the action may notify recipients or change tenant data. This gives an agent a good sense of the mutation's impact, though it doesn't detail reversibility or exact consequences.

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 compact and front-loaded: it states the action and endpoint, lists the body fields, gives a reference link, and then captures prerequisites and side effects. The opening sentence is somewhat redundant with the title, but every other sentence earns its place.

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 write operation with a generic nested body and no output schema, the description covers the endpoint, core body fields, authorization requirement, confirmation requirement, and side effects. It does not spell out response handling or validate the exact body shape, but the API reference link and annotations fill most of the gap.

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 schema covers all parameters, but the body parameter is a generic recursive JSON schema, so the description's explicit mention of serviceId and dependentServiceId adds real meaning. The confirm parameter's description also clarifies the require-true semantics. It stops short of specifying types or requiredness of the body fields, but the reference link and endpoint guidance compensate.

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 identifies a create operation on the service-dependencies resource via the POST endpoint and names the key body fields. It is unambiguous about what the tool does, though it doesn't explicitly contrast itself with the sibling modify/delete service-dependency tools beyond the verb 'create'.

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?

Usage is only implied by the word 'create'; there is no explicit guidance about when to choose this tool over xmatters_modify_a_service_dependency or xmatters_delete_a_service_dependency. The description does provide important preconditions (operator write opt-in and confirm:true) and a side-effect warning, which helps an agent decide whether it is allowed to run it, but not which tool to pick.

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

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

Beyond the annotations, it discloses that the operation can notify recipients or change tenant data and requires the operator write opt-in plus confirm. This is valuable context for a destructive, non-idempotent write, though it could be more specific about the nature of notifications or data changes.

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?

Three information-dense sentences front-load the action and endpoint, then add the fields, reference, and safety requirements. No filler or redundancy.

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 destructive create with no output schema, it covers the action, endpoint, body fields, auth/confirmation requirement, and side effects. It doesn't describe the response format or failure modes, but the reference link and schema cover much of the operational context.

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 coverage is 100%, but the body schema is a generic recursive anyOf, so the description's list of body fields (name, script, plan) adds real meaning. It does not add detail on query parameters, but the schema documents those as having no named parameters.

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 names a precise action and resource ('Create a shared library'), gives the exact HTTP endpoint, and lists the relevant body fields. This distinguishes it clearly from the sibling get/modify/delete shared-library tools.

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 clear preconditions (operator write opt-in, confirm:true), but it does not explicitly state when to use this tool rather than modify_a_shared_library when a shared library already exists. Usage is implied by the verb and resource rather than spelled out.

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

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

Adds meaningful side-effect disclosure: 'may notify recipients or change tenant data' and requires operator write opt-in plus confirm:true. These go beyond the raw annotations, which only flag mutating and destructive behavior. No contradiction with annotations.

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?

Though informative, the description mixes endpoint URL details, field lists, cross-references, and prerequisites in a single dense block. The trailing-slash clarification and cryptic 'See C04' add noise; a short structured list would be clearer.

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?

Covers the key operational facts: endpoint, required/conditional fields, authentication opt-in, and side effects. Because there is no output schema, a statement about the response (e.g., the created shift) would improve completeness, but overall it is sufficient for a create mutation.

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 schema has high coverage (75%) but only documents name, path, and a generic body object. The description supplements it by listing the full set of acceptable body fields and marking name as required and start/end/recurrence as conditional, enriching the otherwise permissive schema.

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 action and resource: 'Create a shift.' It specifies the exact HTTP endpoint, distinguishing it from other shift tools like update/delete/get. The difference from siblings is apparent from the verb and endpoint.

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?

Provides no explicit guidance on when to choose this tool over siblings such as xmatters_update_a_shift_by_id. The required/conditional field notes are parameter-level, not use-case selection. Usage must be inferred from the tool name.

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

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

Annotations already mark destructiveHint:true and readOnlyHint:false, but the description adds specific side effects: 'may notify recipients or change tenant data' and explicitly requires confirm:true. This is meaningful behavioral disclosure beyond the structured annotations.

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 compact and front-loaded: the primary action is stated first, followed by the endpoint, body fields, reference link, and important caveats. Every sentence contributes necessary operational information without redundancy or filler.

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 no output schema, the description covers the key operational aspects: endpoint, required fields, prerequisite confirm flag, and side effects. It could go further by describing the expected response format or an example payload, but it is sufficiently complete for an agent to invoke it correctly with the reference link.

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 coverage is 100%, but the body parameter is only generically described as a complete JSON payload. The description adds value by naming the four expected body fields (name, country, language, timezone). The confirm constraint is also reiterated. This goes beyond the schema's generic body reference.

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 'Create a site' with the exact REST endpoint (POST /api/xm/1/sites) and enumerates the body fields (name, country, language, timezone). This distinguishes it from sibling tools like modify_a_site and delete_a_site without requiring schema inspection.

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 an implied usage context (creating a new site) and lists a prerequisite (operator write opt-in and confirm:true), but it does not explicitly route the agent away from alternatives like modify_a_site or state when not to use this tool. No comparison with siblings is offered.

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

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

The annotations already indicate destructiveHint=true and idempotentHint=false. The description adds meaningful context beyond that by noting 'may notify recipients or change tenant data' and requiring 'operator write opt-in and confirm:true'. This gives the agent a clearer picture of the mutation's impact, surpassing what annotations alone provide.

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 compact and front-loads the action and endpoint, followed by the body fields, reference link, and requirements. It packs useful information without unnecessary verbosity, though the list of fields and caveats makes it slightly dense.

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 create operation, the description covers the endpoint, body fields, required confirm flag, permission requirement, and side effects. It also provides a reference link for deeper details. While it doesn't detail nested structures or response format, the provided information is sufficient for an agent to make a correct call in most cases.

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 schema descriptions are 100% coverage, but the description goes further by enumerating the key body fields (name, description, form, owner, notificationDelay, criteria, recipients, targetDeviceNames) that are not detailed in the generic 'Complete API JSON payload' schema description. This adds practical value for constructing the payload.

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 action ('Create a subscription') and the specific resource (subscriptions via POST /api/xm/1/subscriptions). It lists the body fields, making it unambiguous what the tool does and distinguishing it from other subscription operations like modify or delete.

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 provides some context (requires operator write opt-in and confirm:true) and warns about side effects, but it does not explicitly state when to use this tool versus alternatives (e.g., modify or delete subscription). The guidance is implied by the tool name and action but not spelled out.

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

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

Beyond the annotations (destructiveHint=true, readOnlyHint=false), the description explicitly warns that this operation 'may notify recipients or change tenant data' and requires 'operator write opt-in and confirm:true'. This is valuable behavioral context for a write endpoint that has side effects like notifications and tenant changes, exactly the kind of context an agent needs before invoking it.

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 compact and information-dense: it front-loads the core action, then gives the endpoint, body fields, reference link, and the critical operator/confirm requirement in two sentences. Every sentence contributes unique information without unnecessary fluff.

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?

The description provides the endpoint, body field list, reference URL, and required confirmation flag. There is no output schema, but for a create operation the most important context (side effects, auth requirement, confirm) is present. It doesn't describe the response shape or other behavioral details, but the reference link covers that and the essential invocation context is complete.

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 75%, and the description lists the body fields (name, description, scope, form, oneWay, etc.), which adds meaning beyond the schema's generic 'Complete API JSON payload' text. The schema already documents planId and confirm, and the description adds the endpoint and a reference URL for full field semantics. This compensates well for the remaining 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 clearly identifies the operation ('Create a subscription form'), specifies the HTTP method and endpoint (POST /api/xm/1/plans/{planId}/subscription-forms), and lists the body fields. It is distinguishable from sibling tools like xmatters_modify_a_subscription_form or xmatters_get_subscription_forms_in_a_plan because it explicitly says 'Create' and provides the exact target resource.

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 implies when to use this tool (when creating a subscription form) through the verb and resource, and the endpoint clarifies the plan-scoped context. It notes the operator write opt-in and confirm:true requirement, which is a key gate for use. It doesn't explicitly name sibling alternatives for modification or retrieval, but the 'Create' verb and the URL make the intended use clear enough.

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

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

Annotations already specify destructiveHint=true and readOnlyHint=false, so the mutation behavior is known. The description adds value by noting that it may notify recipients or change tenant data, and that it requires operator write opt-in and confirm:true, which are specific behavioral conditions beyond the generic annotation. It does not contradict annotations and provides useful extra detail.

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 compact paragraph that covers the essential points: purpose, endpoint, key conditional, body fields, reference, and requirements. It front-loads the action and includes critical constraints without excessive verbosity. It could be slightly more structured with bullets, but it's efficient and readable.

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 the tool has nested objects and requires a JSON payload, the description provides enough context for an agent to understand it must construct a body and confirm true, with a pointer to external docs. It doesn't explain return values, but there's no output schema and that may not be critical. The main gap is lack of explicit pagination or error handling info, but the reference is provided. Overall, it's sufficient for basic invocation.

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 coverage is 100% (as indicated), so the schema describes both body and confirm parameters. The description adds details about the body fields (id, absenceType, etc.) and the conditional nature of replacement, which goes beyond the schema's generic description. However, it doesn't fully elaborate on each field's meaning, so it adds moderate value but not exhaustive semantics.

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 it creates a temporary absence via a specific API endpoint, and the title reinforces the action. It includes the required HTTP method and path. It is distinct from sibling tools like get/delete temporary absences, and the description's reference to body fields adds specificity.

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 provides some context on when this tool is applicable, mentioning the conditional replacement field and the need for operator write opt-in and confirm:true. However, it does not explicitly state when to prefer this over other mutation tools or when not to use it, though the API-specific nature makes usage fairly clear. It lacks exclusions or alternatives.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds valuable side effects: 'may notify recipients or change tenant data' and the auth requirement. This goes beyond the structured data without contradicting it, enhancing the agent's understanding of impacts.

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 concise, front-loading the purpose, then providing the endpoint, key fields, and requirements in a compact manner. It includes a reference URL but stays within a few sentences, making it efficient without being verbose.

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?

While it covers essentials like endpoint, body fields, and auth requirements, it omits any information about the response format or behavior for a create operation. The query parameter is not explained (though schema suggests none are documented). The reference link partially compensates, but the lack of output schema and minimal body detail leaves some gaps.

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 coverage is 75%, and the description adds meaning by listing body fields (email, sms, voice) and confirming the confirm:true requirement, which the schema only states as a const. It also provides the exact endpoint and a reference link, adding value over the generic schema descriptions.

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 it creates form message templates, with a specific verb and resource. It distinguishes itself from sibling tools like modify or get templates by the verb and endpoint, making the purpose unambiguous.

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?

It provides usage context by noting the requirement for operator write opt-in and confirm:true, but does not explicitly mention when to use this over alternatives like modify or get templates. No exclusions or alternative routing are given, leaving the choice partially to inference.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false, but the description adds meaningful behavioral context: the requirement for operator write opt-in and the potential to notify recipients or change tenant data. It also specifies confirm:true as a gate, which aligns with the schema. These details go beyond the annotations and help the agent anticipate consequences.

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 compact and front-loaded: it starts with the core action and endpoint, then lists body fields, a reference link, and prerequisites. Every sentence contributes necessary information without verbosity. The structure is ideal for quick agent consumption.

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 destructive mutation with a nested body and confirmation gate, the description covers the endpoint, required parameters (path, confirm), body field outline, prerequisites, and side effects. It does not mention the return value or response format, but no output schema exists and the API reference is provided. This is sufficient for an agent to invoke the tool correctly, though a note on the expected response would be a minor enhancement.

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 75%, so the baseline is 3. The description adds value by enumerating the body fields (number, text, description, prompt, action, contribution, joinConference, allowComments, redirectUrl, translations), which the schema's body definition leaves generic ('Complete API JSON payload'). It also reinforces the confirm:true requirement. While not exhaustive, it meaningfully improves parameter understanding beyond the schema.

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 verb ('Create') and a specific resource ('form response options'), backed by the HTTP endpoint POST /api/xm/1/forms/{formId}/response-options. This unambiguously differentiates it from sibling tools like get or modify response options. The list of body fields further clarifies the tool's scope.

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 provides essential usage context: it requires operator write opt-in and confirm:true, and warns of side effects (may notify recipients or change tenant data). It does not explicitly contrast with alternative tools (e.g., 'use modify_a_form_response_option for updates'), but the name and endpoint make the intended use clear. It covers prerequisites and consequences well.

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

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

The description goes beyond the annotations by specifying that the operation may notify recipients or change tenant data and that confirm:true plus an operator write opt-in are required. This aligns with readOnlyHint=false and destructiveHint=true, so there is no contradiction. It adds useful behavioral context that the annotations alone do not provide.

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 compact and front-loaded: it states the operation, HTTP method, path, key body fields, reference, and required safety prerequisites in two sentences. Every clause contributes useful information, and the slight redundancy with the title is negligible.

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?

The description covers the essential invocation details: exact endpoint, required body fields, documentation reference, write opt-in/confirm requirement, and side-effect warning. There is no output schema, so a note about the return value could improve completeness, but the provided reference URL and operational prerequisites make the tool callable.

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 schema is unconstrained JSON with only a reference link, so the description adds real value by enumerating name, url, endpointType, authenticationType, and authentication. The POST URL also clarifies that path.planId is part of the endpoint path. Other parameters like confirm and query are already explained in the schema, so the description does not need to repeat them.

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 operation as 'Create plan endpoint' and gives the exact HTTP method and resource path (POST /api/xm/1/plans/{planId}/endpoints), which distinguishes it from get/modify/delete endpoint siblings. It could be a 5 if it explicitly named those alternatives, but the verb+resource is unambiguous.

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 provides important usage context by stating that operator write opt-in and confirm:true are required, and it warns of potential side effects. However, it never explicitly says when to use this tool versus creating, modifying, or deleting other resources, nor does it name the get/modify/delete endpoint siblings as alternatives.

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

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

Beyond the annotations, the description adds concrete behavioral detail: it requires operator write opt-in, may notify recipients, and may change tenant data. It also warns that the JSON body remains open, which helps the agent understand the flexible and potentially affecting nature of the call. No contradiction with the annotations exists.

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 action and endpoint, and nearly every clause adds operational context: path parameter clarification, open JSON warning, field list, authorization, and side effects. The unexplained 'See C07' and the duplicated reference URL add slight clutter, but overall the description remains dense and useful.

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 create operation with no output schema, the description provides the endpoint, required path identifier, body-field guidance, reference link, authorization requirement, and side effects. It omits response or error behavior, which is a minor gap, but an agent can still select and invoke the tool correctly from this definition.

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 schema's body parameter is a generic recursive 'any', so the description carries the main parameter burden by listing the known body fields and referring to Plan Property Objects and the API reference. It also clarifies that planId is the required path parameter despite the BODY PARAMETERS heading and notes confirm:true, all of which go well beyond the schema.

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 opens with 'Create plan properties' and gives the exact POST endpoint, so the verb, resource, and operation are unambiguous. It is clearly distinct from sibling tools like get_plan_properties and modify_plan_properties without requiring the agent to inspect their schemas.

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 clearly establishes that this is a create/mutation operation and gives important usage prerequisites: operator write opt-in and confirm:true, plus side-effect risk. It does not explicitly name alternatives or when-not-to-use conditions, but the create action and write requirements provide sufficient context.

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

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

Annotations already mark it destructive and non-readonly. The description adds valuable behavioral context: may notify recipients or change tenant data, and requires operator write opt-in. This goes beyond the annotations without contradicting them.

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 compact, front-loaded with the action, and every sentence carries useful information: endpoint, body, reference, requirements, side effects. No filler.

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 simple delete operation, the description covers prerequisites, side effects, and endpoint. With destructiveHint already set and no output schema, this is sufficient. It could mention response code or idempotency, but those are minor gaps given annotations.

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 covers 67% of parameters with descriptions; baseline is 3. The description adds 'Body fields: none' and restates confirm:true, which is already in schema. It does not explain bridgeID semantics or the query parameter beyond what schema offers. Slight additional value but not significant.

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 verb 'Delete' and resource 'conference bridge', and includes the exact REST endpoint. It is clearly distinct from sibling modify/create/get conference bridge tools, with no ambiguity about the action.

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?

Provides clear context for when the tool can be used: requires operator write opt-in and confirm:true. It does not explicitly list exclusions or alternatives, but the prerequisites and side-effect warning guide the agent. Missing explicit when-not-to-use or alternative suggestions, so not a 5.

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

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

The description discloses additional behavioral effects beyond the destructiveHint annotation: it may notify recipients or change tenant data, and requires operator write opt-in. This gives an agent useful side-effect awareness not present in the annotations.

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?

Three short sentences: action, endpoint, and key side-effect/requirement. Every sentence earns its place and the most important operational caveats are front-loaded.

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 simple delete tool, the description covers the endpoint, required confirm flag, operator opt-in, and side effects. No output schema exists, but the description and schema together give enough to invoke the tool correctly.

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 schema already describes confirm and query properties well, covering 67% of parameters. The description adds little beyond restating confirm:true and noting no body fields, which is not particularly necessary since no body parameter exists.

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 begins with 'Delete a device', a specific verb plus resource, and includes the exact REST endpoint. This clearly distinguishes it from sibling tools like get_a_device, create_a_device, and modify_a_device.

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 clearly states the prerequisite of an operator write opt-in and confirm:true, which is essential usage guidance. It does not explicitly name alternatives or when-not-to-use conditions, but the delete semantics are unambiguous enough for selection.

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

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

Annotations already mark this as destructive and non-read-only; the description adds meaningful context by noting it 'may notify recipients or change tenant data' and requires an operator write opt-in. It also flags an upstream API documentation error, which is valuable beyond the structured annotations.

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?

Front-loaded with the action, resource, and endpoint. The correction about the official definition and cURL typo is dense but purposeful because it prevents an agent from using a wrong URL. Some redundancy exists, but most sentences earn their place.

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 one-resource DELETE with no output schema, it covers the endpoint, required confirmation, side effects, and a known documentation discrepancy. It does not describe response or error formatting, but that is not essential for this mutation.

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 coverage is 67%, so the baseline is 3. The description adds 'Body fields: none' and confirms the confirm:true requirement, but it does not meaningfully expand on path.deviceID or query beyond what the schema already states.

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 exact action and resource: 'Delete a device name', and anchors it to the correct endpoint /api/xm/1/device-names/{deviceID}. It also explicitly separates this from deleting a device by naming the resource type, making sibling differentiation clear.

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?

Provides explicit preconditions for use: operator write opt-in and confirm:true, plus a warning about side effects. It does not name alternative tools, but the sibling set and resource name make the intended use case obvious.

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

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

Adds behavioral context beyond annotations: 'may notify recipients or change tenant data' and requires confirm:true. Annotations already flag destructiveHint=true, but the description elaborates on side effects and prerequisites.

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?

Concise single sentence with endpoint and reference link. However, it repeats 'Delete a group' from the title, and the reference link may be redundant. Still, it is front-loaded and efficient.

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?

Provides essential info: endpoint, requirements, and side effects. Lacks description of groupID meaning, but context from resource name implies it. Adequate for a delete tool.

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 covers confirm and query with descriptions, but the description does not clarify the groupID parameter beyond its presence in the path. 'Body fields: none' is unrelated to parameters, so no additional meaning is provided.

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 exact operation ('Delete a group') and specifies the HTTP endpoint (DELETE /api/xm/1/groups/{groupID}). This clearly distinguishes it from sibling tools like get, create, or modify group operations.

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 explicit guidance on when to use this tool versus alternatives. It does not mention sibling tools or conditions under which deletion is appropriate. It only lists prerequisites (operator write opt-in and confirm:true), which are requirements rather than usage guidelines.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false. The description adds meaningful behavioral context beyond annotations: 'may notify recipients or change tenant data' and the need for operator write opt-in and confirm:true. This explains real-world consequences and prerequisites that an agent would not infer from the schema alone.

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 compact and front-loaded with the purpose, then the endpoint, requirements, and side effects. The API reference URL is somewhat extraneous but does not bloat the text. Every sentence serves a clear function.

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 delete tool with annotations covering destructive behavior and schema covering parameters, the description provides the endpoint, prerequisites, and side effects. It does not mention the return value or explicitly state irreversibility, but those are fairly implied by destructiveHint and the delete action. Overall, an agent has enough to invoke it correctly.

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 67%, covering path and confirm. The description contributes little beyond the schema: 'Body fields: none' is redundant since no body property exists, and the confirm requirement is already described in the schema. It does not elaborate on planId or integrationId semantics, so it stays at the baseline for medium coverage.

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 begins with 'Delete an integration', a specific verb and resource, and repeats the REST endpoint that identifies the exact operation. This clearly distinguishes it from sibling tools that get, create, or modify integrations, and from deletes of other resource types.

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 states prerequisites ('Requires operator write opt-in and confirm:true') and hints at potential side effects, which gives some usage context. However, it does not explicitly say when to use this tool versus alternatives (e.g., modify instead of delete) or provide exclusion conditions, so usage guidance is only implied.

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

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

Beyond the annotations' destructiveHint, the description adds concrete behavioral context: operator write opt-in is required, confirm must be true, and the action may notify recipients or change tenant data. It also states the HTTP verb and body expectations, which helps an agent anticipate side effects and authorization needs.

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 compact and front-loaded with 'Delete a person' before the endpoint and constraints. Each piece adds information, though the trailing reference and requirement section could use line breaks or punctuation for easier scanning.

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 destructive call with two required parameters and no output schema, the description supplies the key invocation facts: how to target the person, what body/query expectations are, and what authorization and side-effect caveats exist. It does not detail error cases or how the operator opt-in is granted, but the annotations and schema cover the remainder.

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 endpoint template 'DELETE /api/xm/1/people/{personID}' clarifies the required path parameter, and 'Body fields: none' removes guesswork about a request body. The confirm requirement is reinforced, though query parameters are left generic by the schema's own description; this is reasonable for a delete operation.

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 opens with the explicit verb-object pair 'Delete a person' and grounds it in the exact HTTP endpoint. This clearly distinguishes it from sibling tools like get_a_person_by_id, create_a_person, and modify_a_person.

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 states necessary preconditions ('Requires operator write opt-in and confirm:true') and the resource to target, so the intended use is clear. However, it gives no explicit guidance about when to prefer deletion over alternatives such as modify_a_person, or any when-not-to-use scenarios.

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

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

Beyond the annotations (destructiveHint:true), the description adds specifics: 'may notify recipients or change tenant data' and 'Requires operator write opt-in and confirm:true'. These disclose side effects and prerequisites not fully captured by annotations or schema, enhancing transparency.

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 concise, front-loading the purpose, then providing the endpoint, reference, and critical prerequisites in a single sentence. Every element adds value with no redundancy.

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 simple delete operation with no output schema, the description includes essential context: endpoint, reference, prerequisites, and side effects. It does not specify the response on success (e.g., 204), but this is minor given the absence of an output schema and the simplicity of the operation.

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 schema covers path.planId and confirm with descriptions, but the description adds 'Body fields: none' and the operator write opt-in requirement, which are not in the schema. With 67% schema coverage, this additional context helps agents understand the call parameters, though the query parameter remains generic.

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 'Delete a plan' clearly, specifying the verb and resource. It distinguishes from sibling delete tools (e.g., delete_a_device, delete_a_group) by targeting the 'plan' resource, so an agent can select it unambiguously.

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 provides clear context for use: it is a delete operation for a specific plan, includes the endpoint, and notes prerequisites (operator write opt-in and confirm:true). It does not explicitly mention exclusions or alternatives, but the resource-based clarity makes when-to-use evident.

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

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

The description adds substantial context beyond the destructiveHint and readOnlyHint annotations: it requires operator write opt-in and confirm:true, and warns that the action may notify recipients or change tenant data. This meaningfully signals side effects an agent should consider before calling the tool.

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 compact, front-loaded with the core action, and each sentence carries useful information: endpoint, body expectations, reference, and required safeguards. There is no filler or repetition of the obvious.

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 destructive mutation with no output schema, the description covers the critical operational details: HTTP method, path, confirmation requirement, opt-in, and potential side effects. It could be slightly more complete by stating what a successful response looks like or explicitly contrasting with the modify and create siblings, but it is not missing essential safety information.

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 endpoint template adds some meaning by showing planId and constantId as path variables, and the description restates the confirm:true requirement, but the schema already documents confirm and query. The planId and constantId properties themselves remain undocumented in both schema and description, so the description only partially compensates.

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 opens with the exact operation, 'Delete a plan constant', and reinforces it with the full DELETE endpoint, so the verb and resource are unmistakable. It is also clearly distinct from sibling tools like create/modify/get plan constants.

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?

Use is implied by the operation name and description, but no explicit guidance is given about when to choose this tool over related tools such as modify_a_plan_constant or get_plan_constants. The confirmation and opt-in requirements are operational constraints, not usage comparisons.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation risk is known. The description adds valuable behavioral context beyond annotations: it requires operator write opt-in and confirm:true, may notify recipients or change tenant data, and notes the plural/singular discrepancy in the API definition. This goes beyond what annotations alone provide.

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 compact and front-loaded with the core action and endpoint. The additional notes about plural/singular, body fields, reference link, and requirements are each useful and not redundant. It is slightly dense with multiple clauses in one sentence, but every sentence earns its place.

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 destructive mutation with no output schema, the description covers the key operational facts: the HTTP method and path, the required confirm flag, the write opt-in requirement, and potential side effects. It does not describe the response format, but no output schema exists and the reference link is provided. The main missing piece is a clearer statement of what happens on success or failure, but the description is largely complete for an agent to invoke it correctly.

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 67%, and the description adds meaning for the confirm parameter by explaining it is 'Explicit approval of this exact mutation' and that the operator must enable XMATTERS_ALLOW_WRITES. The path parameters (planId, endpointId) are self-explanatory from the schema and the endpoint URL. The description does not add much for the query parameter, but the schema already documents it as having no documented names and explicit pagination.

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 specific verb ('Delete'), a specific resource ('a plan endpoint'), and the exact HTTP endpoint. It also distinguishes itself from sibling tools like xmatters_get_plan_endpoints, xmatters_create_plan_endpoint, and xmatters_modify_a_plan_endpoint by naming the delete operation explicitly. The plural/singular note adds precision.

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 clear context: it requires operator write opt-in and confirm:true, and warns that it may notify recipients or change tenant data. It does not explicitly name alternative tools for when not to use it, but the delete-specific wording and the sibling list make the usage context clear. A small gap is not stating when to prefer a different endpoint (e.g., modify instead of delete).

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

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

Annotations already mark this as destructive and non-idempotent; the description adds meaningful context by stating that deletion may notify recipients or change tenant data and by calling out the operator write opt-in requirement. This goes beyond the structured annotations without contradicting them.

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 compact and front-loads the core purpose before side effects and prerequisites. The reference URL is mildly redundant for an agent, but the overall length is appropriate and every major sentence adds useful information.

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 destructive delete operation with no output schema, the description covers the essential operational caveats: required confirmation, operator write opt-in, potential recipient notification, and tenant data changes. It does not describe response codes, but that is a minor gap for a simple DELETE endpoint.

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 67%, so the schema carries most of the parameter meaning for `path` and `confirm`. The description adds the endpoint template and "Body fields: none," but it does not explain the scheduledMessageId format or add much semantic value beyond what the schema already provides.

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 opens with the specific action and resource: "Delete a scheduled message," then reinforces it with the exact REST endpoint. This clearly distinguishes it from the scheduled-message create, modify, and get siblings.

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 prerequisites (operator write opt-in and confirm:true) but provides no guidance about when to choose this tool instead of an alternative, nor any "when not to use" exclusions. There is no comparison to sibling tools such as modifying or getting a scheduled message.

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

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

Annotations already mark the tool as destructive and non-idempotent; the description adds that it may notify recipients or change tenant data and that operator write opt-in is required, which are not present in the structured hints. It does not fully describe irreversibility, but destructiveHint covers that core aspect.

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 compact: two sentences plus endpoint and reference link. Every clause adds useful information—purpose, endpoint, body requirement, prerequisites, and side effects—with no filler or redundancy.

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 destructive delete tool with no output schema, the description covers the essential context: endpoint, body constraints, prerequisites, and potential side effects. It omits response details and error scenarios, but those are less critical given the annotations and simple parameter structure.

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 schema already provides rich descriptions for query and confirm, covering 67% of parameters. The description adds 'Body fields: none' and the URL path clarifies serviceId, but it does not explain the meaning of serviceId or add detail beyond what the schema already has. Adequate but not exceptional.

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 operation directly ('Delete a service') and gives the exact REST endpoint (DELETE /api/xm/1/services/{serviceId}), which clearly differentiates it from sibling tools like xmatters_get_a_service, xmatters_create_a_service, and xmatters_modify_a_service. An agent can immediately identify what this tool does.

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 ('Requires operator write opt-in and confirm:true') but gives no guidance on when to choose this tool over alternatives such as xmatters_modify_a_service or when deletion is appropriate. It does not contrast with sibling operations, so the agent must infer usage purely from the name.

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

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

Annotations already mark this as destructive and not read-only. The description adds meaningful behavioral context beyond them: it requires operator write opt-in and confirm:true, and warns that the operation may notify recipients or change tenant data. This is exactly the kind of side-effect disclosure an agent needs.

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 dense but well-ordered: purpose, method/path, body clarification, reference, then required authorization and side effects. Every sentence earns its place and there is no filler.

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 destructive mutation with no output schema, it covers the identifier, authentication prerequisite, confirmation requirement, and side effects. It does not describe response codes or failure semantics, but that is not essential for correctly selecting and invoking this DELETE operation.

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 schema already documents confirm and query well, and the description clarifies that body fields are none. The endpoint template adds meaning for path.id. The only minor gap is not stating where confirm is transmitted, but the schema's required const true is sufficient for correct MCP invocation.

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 a specific verb and resource: 'Delete a service dependency', reinforced by the exact DELETE endpoint. This unambiguously distinguishes it from sibling tools like create/modify_a_service_dependency and delete_a_service.

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 preconditions such as operator write opt-in and confirm:true, which is useful operational guidance. However, it does not explicitly say when to use this tool versus modifying or deleting other resources; the appropriate usage is only implied by the name and endpoint.

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

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

The description adds valuable behavioral context beyond the annotations: it notes the operation 'may notify recipients or change tenant data' and requires confirm:true plus operator write opt-in. This meaningfully expands on the destructiveHint, idempotentHint, and readOnlyHint annotations. No contradiction with annotations exists.

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 compact and front-loaded: it states the action, endpoint, body requirement, prerequisites, and side effects in two sentences. No filler or redundant wording is present. The reference link is useful and does not bloat the description.

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 destructive tool with no output schema, the description covers the essential context: endpoint, required confirmation, permission prerequisite, and potential side effects. It does not state the return behavior, but that is not critical for a delete operation. Overall, it provides enough information for an agent to call the tool correctly.

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 schema already documents path.libraryID and confirm, including confirm's const true requirement and operator opt-in. The description adds 'Body fields: none' and restates confirm:true, but does not substantially enrich parameter meaning beyond the schema. With 67% schema coverage, this is adequate but not exceptional.

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 specific verb and resource: 'Delete a shared library' and gives the exact endpoint. This clearly distinguishes it from sibling tools like get, create, or modify a shared library. No ambiguity remains about what operation is being invoked.

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 actionable prerequisites: 'Requires operator write opt-in and confirm:true,' which tells the agent when it is permitted to use this tool. However, it does not explicitly compare with alternatives or state when not to use this tool, leaving some usage guidance implicit.

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

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

Annotations already mark destructive/write. The description adds the specific gate (operator write opt-in + confirm:true) and concrete side effects ('may notify recipients or change tenant data'), which are not present in the annotations. No contradiction.

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?

Compact presentation front-loads purpose, endpoint, and no-body, then adds auth and side-effect warnings. The reference link is extra but useful; there is no filler.

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 destructive, auth-gated delete, the description includes endpoint, body requirement, confirmation gate, and side effects. It does not describe response/status codes, but no output schema exists and the reference URL covers deeper API details, so the core invocation context is complete.

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 covers 67% of properties; query and confirm have schema descriptions, path does not. The description reinforces confirm:true and clarifies the request has no body, and the endpoint template gives path-parameter meaning, but it does not independently explain groupID/shiftID beyond their names.

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 names the action ('Delete a shift') and gives the exact REST endpoint with groupID/shiftID, making the target resource unambiguous. It does not explicitly contrast with sibling update/shift tools, but the delete verb and endpoint are sufficient to identify the operation.

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 statement of when to use this versus update/create/get shift tools; the agent must infer from operation name. It gives prerequisites (write opt-in, confirm:true) but not selection criteria relative to alternatives.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, idempotentHint=false, and openWorldHint=true; the description adds genuine context beyond those by disclosing that deletion 'may notify recipients or change tenant data' and requires an operator write opt-in. This gives the agent a real sense of blast radius without contradicting the annotations.

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 compact and front-loaded: purpose, endpoint, body, reference, then side effects. Every fragment earns its place; the only minor flaw is the reference URL running into the next clause without clear separation.

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 destructive tool with no output schema, the description covers purpose, endpoint, body absence, authorization prerequisite, and user-visible side effects, and links to full API docs. It does not describe the success response or reversibility, which are modest gaps for a delete operation.

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 coverage is 67%, with confirm and path.siteID described in the schema (confirm via const:true, siteID via minLength). The description adds 'Body fields: none,' confirming agents need not send a body, but it does not elaborate on siteID semantics beyond the schema.

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 opens with a specific verb and resource ('Delete a site') and adds the exact REST endpoint (DELETE /api/xm/1/sites/{siteID}), making the operation unambiguous against siblings like get_a_site, create_a_site, and modify_a_site. However, it does not explicitly contrast with those sibling tools.

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?

Usage is implied by the name and purpose, and the description adds important preconditions ('Requires operator write opt-in and confirm:true') that tell an agent when the call will be permitted. It never names sibling alternatives (e.g., modify_a_site) or says when not to delete, so routing guidance is left to inference.

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

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

Annotations already mark destructiveHint true and readOnlyHint false, and the description adds important consequences: 'may notify recipients or change tenant data.' It also states the auth requirement and the need for confirm:true, going well beyond the annotations.

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 compact and front-loaded with the action and endpoint. Every sentence adds value: endpoint, body requirement, reference, permissions, and side effects. No filler.

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 simple delete operation, the description covers the endpoint, required confirmation, permissions, and potential side effects. With destructiveHint in annotations and no output schema, nothing essential is missing for an agent to invoke this correctly.

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 coverage is 67%, and the description adds 'Body fields: none' and restates the confirm:true requirement, which reinforces the schema's confirm description. It doesn't elaborate subscriptionId, but the schema already documents it; overall it adds meaningful context beyond the schema.

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?

Description states the specific verb 'Delete' and resource 'a subscription', and includes the exact HTTP endpoint. It clearly distinguishes from sibling tools like get/modify/create subscription by naming the destructive action.

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 prerequisites (operator write opt-in and confirm:true) but does not explicitly say when to use this tool over alternative subscription operations (e.g., unsubscribe_a_user or modify_a_subscription). Usage is implied rather than explicitly contrasted with siblings.

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

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

Annotations already mark this as destructive and non-read-only, so the description's added value is the side-effect warning that recipients may be notified and tenant data may change, plus the write-opt-in requirement. This goes beyond the structured annotations without contradicting them.

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?

Three short sentences convey endpoint, body expectation, reference, prerequisites, and side effects with little waste. Minor double spacing and a reference URL are acceptable; info is front-loaded and scannable.

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 two-required-parameter delete with no output schema, the description covers the endpoint, required confirmation, opt-in, body expectation, and side effects. A response/status-code note would be a small improvement, but nothing essential to invoking it correctly is 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?

The schema already documents query and confirm in detail, and the description adds only 'Body fields: none' and the path variable name through the endpoint. The temporaryAbsenceId parameter has no explicit prose description but is self-explanatory from the endpoint; the added value over the schema is modest.

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 specific action ('Delete a temporary absence') and gives the exact REST endpoint, which unambiguously identifies the resource and operation. This distinguishes it from the sibling create/get temporary-absence tools even without inspecting the schema.

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?

It provides clear invocation context by stating the DELETE verb, that no body fields are needed, and that operator write opt-in plus confirm:true are required. It doesn't name alternatives or exclusions, but for a deletion operation the trigger condition ('delete a temporary absence') is sufficiently clear.

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

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

Annotations already establish readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is clear. The description adds the HTTP GET method and 'Body fields: none' but does not disclose potential behaviors like authentication requirements, error cases, or response characteristics. It does not contradict the annotations.

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 extremely concise and front-loaded: the core action comes first, then the exact endpoint, then the body constraint, then a reference link. Every sentence earns its place 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?

For a simple single-resource GET with strong annotations, the description provides the essential invocation information: the endpoint and required changeID. However, it does not describe what a 'change' is, what response to expect, how errors are surfaced, or how this tool relates to the sibling listing tool xmatters_get_changes. The reference link partially compensates, and the complexity is low, so a 3 is appropriate.

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 endpoint path /changes/{changeID} makes the meaning and location of the required changeID parameter clear, even though the schema's path object lacks a description. The query object is already described in the schema, including pagination behavior. The description's only additional parameter-related note is 'Body fields: none,' which is useful but minimal.

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 verb and resource: 'Get a change' and identifies the exact endpoint GET /api/xm/1/changes/{changeID}. It is obviously a single-resource retrieval operation, but it does not explicitly contrast with the sibling xmatters_get_changes or otherwise name alternatives, so it stops short of full sibling differentiation.

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 provides no guidance on when to use this tool versus the many related tools in the sibling list, such as xmatters_get_changes or xmatters_create_a_change_record. The endpoint implies it should be used when you have a specific changeID, but no explicit when-to-use, when-not-to-use, or alternative routing is given.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the API endpoint and notes that body fields are none, which is useful but not extensive. It does not disclose behaviors like authentication, rate limits, or return format, but given the annotations cover the safety aspects, a 3 is appropriate.

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 extremely concise, consisting of a clear purpose statement, the endpoint, a note about body fields, and a reference link. There is no fluff or unnecessary detail, and the core purpose is front-loaded in the first sentence.

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 simple get-by-ID operation with read-only annotations and a schema that covers the query parameters, the description is mostly complete. It lacks any mention of what a communication plan is or what the response contains, but the output schema is absent and the reference link provides additional context. The note about body fields and the endpoint are sufficient for an agent to make the call correctly.

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 coverage is 50%: the path parameter planId is required but not described, while the query parameter has a detailed description in the schema. The tool description does not add any additional meaning to the parameters beyond what the schema already provides. The endpoint mentions {planId} but does not elaborate on its format or purpose, so the description adds minimal value over the schema.

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 'Get a communication plan' with a specific verb and resource, and the endpoint includes {planId} indicating a single plan lookup. However, it does not explicitly distinguish this from the sibling xmatters_get_communication_plans (plural) for listing all plans, relying on the name and endpoint to convey the distinction.

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 alternatives. It does not mention that this is for retrieving a single plan by ID, nor does it suggest when the plural list version would be appropriate. The endpoint implies a planId is required, but there is no explicit usage context or exclusion.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safe read-only behavior is covered. The description adds the endpoint and 'Body fields: none,' which gives minor request-shape clarity, but it does not disclose response format, error cases, or authentication requirements. With annotations present, this is adequate but not rich.

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 short, but the first sentence 'Get a conference bridge' is redundant with the tool name. The endpoint line and reference link add value, but the structure could be tighter by dropping the tautological opener.

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 simple GET-by-ID tool, the endpoint and body-fields note provide the core calling context, and annotations cover the safety profile. However, there is no output schema, no description of the returned conference bridge object, and no guidance on finding bridgeId, leaving moderate gaps for an agent.

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 description shows bridgeId appearing in the path via the endpoint template, and says body fields are none, but it does not explain what bridgeId represents or how to obtain it. Schema coverage is only 50% because query parameters have no documented names, and the description does not compensate for this gap beyond restating the placeholder.

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 specific verb and resource: 'Get a conference bridge' and includes the exact endpoint GET /api/xm/1/conference-bridges/{bridgeId}. This clearly identifies a single-resource read operation and distinguishes it from the sibling list tool xmatters_get_conference_bridges, though it does not explicitly name that sibling.

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 about when to use this tool versus alternatives such as xmatters_get_conference_bridges for listing bridges or xmatters_create_an_external_conference_bridge for creating one. The endpoint implies fetching by ID, but the description offers no explicit context or exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, fully covering the safety profile. The description adds a minor behavioral note that 'Body fields: none' (pertaining to the request) and provides a reference link. It does not mention response format or any edge cases, but given strong annotation coverage, this is acceptable. No contradiction with annotations.

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 compact and front-loaded with the essential action and endpoint, followed by a body-fields note and a reference. Every sentence adds value: the endpoint clarifies the API call, the body note prevents unnecessary payload, and the reference offers deeper docs. It is concise with no fluff, though the structure is a bit fragmented into three short clauses.

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 straightforward GET-by-ID operation with no output schema and strong safety annotations, the description is mostly adequate. It includes the endpoint, body requirement, and a link for detail. However, it does not mention error handling, response structure (though none is specified), or how to use the query parameters (only the schema covers that). An agent could call it correctly, but more context on potential failures or usage notes would improve completeness.

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 schema description coverage is 50%: the query parameter is well documented (embed, pagination, comma joining), but the deviceID within the path object has no description. The tool description adds no parameter-specific meaning, so it relies entirely on the schema. The deviceID is self-explanatory from the endpoint, but the description does not compensate for the missing schema intent. Overall, it meets the baseline but does not enhance understanding beyond the schema.

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 action ('Get a device') and provides the exact API endpoint (GET /api/xm/1/devices/{deviceID}), which unambiguously identifies the resource and operation. It is distinct from siblings like xmatters_get_devices (list) and create/modify/delete tools, though it does not explicitly point out these differences. The endpoint format implies a single device lookup by ID.

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 explicit guidance is given on when to use this tool versus alternatives such as xmatters_get_devices or xmatters_get_a_person_39_s_devices. The description only states the endpoint and does not provide context for selection, prerequisites, or conditions that favor this tool. The agent must infer from the name and API path, which is insufficient given the large sibling list.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds the HTTP method and 'Body fields: none', but does not describe response contents, error cases, or other operational behavior. No contradiction with annotations.

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 extremely compact: a clear verb/resource clause, the endpoint, a note that the body is empty, and a reference link. Every element earns its place, and there is no repetition of information already present in the schema or annotations.

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 state what a successful response contains, and it gives no guidance on plan context or failure modes. The reference link and schema-side query documentation compensate partially, making this adequate but not complete for an agent that must interpret the result.

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 schema documents the query parameters (recipients, embed, offset, limit), comma-joining of arrays, and explicit pagination behavior, covering much of the optional surface. The description itself adds little beyond embedding {formId} in the endpoint; formId is not semantically explained, though its meaning is reasonably inferable from the name.

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 specific verb and resource ('Get a form in a plan') and pins it to the exact endpoint GET /api/xm/1/forms/{formId}. It clearly identifies a single-item retrieval, but it does not explicitly contrast with sibling list tools such as xmatters_get_forms_in_a_plan.

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 singular 'a form' and the {formId} path parameter imply use when you have a specific form ID and need one form, but the description provides no explicit when-to-use versus alternatives guidance. It neither states exclusions nor names sibling tools that should be used instead.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the HTTP method (GET), the endpoint, and "Body fields: none," which are mildly useful, but it does not disclose response behavior or open-world caveats beyond what annotations already imply.

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 compact and front-loaded: operation, endpoint, body requirement, and reference are each in one short line. There is no filler or redundant elaboration.

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 nested variant in a dense family of form/plan tools with no output schema, the description is missing the most important context: what "nested" changes about the response and when to select this tool over its siblings. The schema covers pagination mechanics, but selection-critical information is absent.

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 schema documents the query parameters with helpful detail (including comma-joining and explicit pagination), but the required path parameters have no descriptions. The description only restates planId and formId in the URL template without adding semantics beyond their names, so it only partially compensates for the schema's gaps.

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 operation: retrieving a form in a plan, reinforced by an explicit REST endpoint. It is unambiguous about the resource acted on, but it does not explain what "nested" means or how this tool differs from closely related siblings like xmatters_get_a_form_in_a_plan.

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 variant instead of the many related form/plan tools. It does not mention scenarios, exclusions, or alternatives; the reference link is a documentation pointer, not usage guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the description doesn't need to cover safety. It adds 'Body fields: none' and the endpoint, which are minor but useful context. No additional behavioral details (e.g., pagination, response format) are disclosed, but the annotation coverage lowers the bar.

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 brief and front-loaded with the purpose and endpoint. It includes a reference link for additional context. There is no wasted text, though it could benefit from a bit more detail without becoming verbose.

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?

The description provides a reference link and the endpoint, but does not clarify the meaning of 'nested recipients' or how it differs from the non-nested variant. It also omits any mention of output structure, though the lack of an output schema lessens that need. Given the dense sibling set, more context about when this variant is appropriate would improve completeness.

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 description only mentions 'Body fields: none', which is not a parameter. It does not explain planId or formId, though they are self-explanatory from the endpoint. The query object has a schema description, but the overall schema coverage is 50%, and the description does not compensate by detailing the path parameters or query semantics.

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 action (get a form in a plan) and the specific resource (nested recipients) and gives the endpoint. It distinguishes from the non-nested sibling by name, but doesn't explain what 'nested' means, leaving some ambiguity about the exact scope.

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 its siblings such as xmatters_get_a_form_in_a_plan_recipients or xmatters_get_a_form_in_a_plan_nested. There are no explicit when-to-use or alternative recommendations, leaving the agent to infer the distinction from the name alone.

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds the endpoint and notes that body fields are none, which is useful. However, it does not describe what 'nested' means behaviorally, nor does it explain the query parameters or response format. It is consistent with the annotations and adds some context, but not rich behavioral detail.

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 concise—two sentences plus a URL and reference—and the core purpose is front-loaded. It includes the HTTP method and endpoint in the first sentence, making it easy to scan. There is no extraneous content.

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 the tool's complexity (nested objects, no output schema, and many closely related siblings), the description is too sparse. It does not clarify when to choose the nested variant over the non-nested one, does not explain query parameters, and does not describe the return structure. The reference link provides external documentation but is not inline, so the description alone is insufficient for correct selection and invocation.

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 description does not explain any parameters. The schema defines path parameters (planId, formId) without descriptions, and the query parameter is a generic object with a description that lists names but no meanings. With schema description coverage at 50%, the description should compensate for the undocumented path parameters, but it does not. It merely repeats the endpoint pattern.

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 operation (get), the resource (a form in a plan), and the specific subresource (nested sender permissions). It includes the exact HTTP endpoint, which disambiguates it from the many similar sibling tools. However, it does not explicitly contrast it with the non-nested sender-permissions variant, so it stops short of a perfect score.

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 tool versus alternatives like xmatters_get_a_form_in_a_plan_sender_permissions or xmatters_get_a_form_in_a_plan_nested. The description simply provides the endpoint and a reference link, leaving the agent to infer the difference from the name alone. No exclusions or conditions are given.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds only the endpoint and body fields, but no behavioral details like return format, pagination defaults, or error conditions. It doesn't contradict annotations, but adds minimal value beyond them.

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?

Very short and direct, front-loading the purpose. Includes the endpoint and a reference link, both useful, with no wasted words. It's concise without being under-specified.

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 simple GET with read-only annotations and no output schema, it covers the core action but lacks details on the response structure or pagination behavior (though the schema's query description covers offset/limit). It's adequate for a basic retrieval but not fully comprehensive.

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 description does not mention parameters. The schema provides a description for the 'query' object (pagination, offset/limit) but the 'path.formId' is only typed as string. With 50% schema coverage, the description should compensate for the undocumented formId semantics but does not.

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 a clear verb and resource: 'Get a form in a plan — recipients' with the explicit endpoint. It distinguishes from sibling tools like xmatters_get_a_form_in_a_plan and xmatters_get_a_form_in_a_plan_sender_permissions by focusing on recipients, though it doesn't contrast with the nested recipients variant.

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 on when to use this tool versus alternatives such as xmatters_get_a_form_in_a_plan_nested_recipients or xmatters_get_forms_in_a_plan. The description only states what it does, leaving selection to the agent.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the endpoint path and a reference link, but does not disclose behavior such as pagination, default limits, or what the response contains. The query schema does mention pagination explicitly, so the description itself adds little beyond the annotations and schema.

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 compact: one sentence, the endpoint, body fields, and a reference link. It is front-loaded with the resource name and HTTP method. The reference link is useful but could be considered extra; overall it is efficient and scannable.

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 simple read tool with annotations covering safety and a schema covering the query parameters, the description is mostly adequate. However, it lacks any mention of what the response contains, pagination behavior (though the schema mentions it), or how this differs from the nested sender-permissions sibling. Given the large sibling list and no output schema, a bit more context would help an agent select and invoke it correctly.

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 50%: the path.formId parameter is documented only by name/type in the schema, and the query parameter description is provided in the schema. The tool description does not add any parameter-level meaning beyond the endpoint path. With 50% coverage, the description partially compensates by showing the endpoint, but it does not explain formId semantics or query parameter usage.

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 specific verb ('Get'), a resource ('a form in a plan — sender permissions'), and the exact endpoint path. It is clearly a read operation for sender permissions of a form, which distinguishes it from sibling tools like xmatters_get_a_form_in_a_plan_recipients and xmatters_get_a_form_in_a_plan_nested_sender_permissions, though it does not explicitly name those siblings.

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 implies usage by naming the endpoint and resource, and the readOnly/idempotent annotations signal safe retrieval. However, it does not explicitly state when to use this tool versus alternatives such as the nested sender-permissions variant or the recipients variant, nor does it mention any prerequisites like needing a formId from a plan.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the HTTP method and 'Body fields: none', but does not disclose response shape, authentication needs, or query behavior beyond what the schema provides. No contradiction with annotations.

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 compact and front-loaded with the action and endpoint. The body-fields note and reference URL add useful context without excessive verbosity. It earns a high score for efficiency, though it is somewhat fragmentary.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.