Create plan endpoint

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.