Add an endpoint to an endpoint group

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

Usefully discloses the underlying call (POST to /endpoints/groups/{org}/{group}/contents) and the membership semantics ("Re-adding an existing member is a no-op"), which is real context beyond annotations. However, it says nothing about the confirm="YES" gate or dry_run defaulting to true, which are the two behavioral facts that most affect a destructive-flagged mutation; the no-op claim also sits in mild tension with idempotentHint=false without being a direct 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?

Two tight sentences, purpose front-loaded, mechanics second, zero filler. The raw URL path is arguably the only expendable 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?

Output schema and rich annotations are supplied, so the description need not explain return values. Still, for a destructive, open-world mutation with a confirmation gate, it should at minimum note the dry_run/confirm execution model and that the group must pre-exist.

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. The description adds the request body shape and, notably, mentions a `type` field in the payload that has no corresponding top-level schema property, but it does not explain the confirm/dry_run/response_format 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?

A concrete verb-plus-resource statement ("Add a single endpoint to an endpoint group") that is unambiguous and clearly distinct from the sibling action1_remove_endpoint_from_group. It never names a sibling or scoping rule explicitly, so it falls just short of a 5.

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 intent is implied cleanly by the verb, but there is no explicit when-to-use guidance, no prerequisite stating the group and endpoint must already exist, and no routing away from nearby tools (move_endpoint, list_group_contents, remove_endpoint_from_group). An agent can infer the case but gets no confirmation.

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