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

Far exceeds the annotation bar: it discloses replace-style semantics, that an empty list removes everyone, role inheritance and admin visibility, the two-phase token lifecycle, token expiry/single-use, stale_revision behavior, and the replay (replayed:true) outcome that reinforces idempotentHint. It also flags CRM field values as untrusted data. No contradiction with the destructive/idempotent 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 and nearly every sentence carries operational weight (preview, approval, token reuse, stale handling). It is dense and delivered as one long block, with some safety boilerplate that could be tightened, so it is very good but not maximally economical.

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, multi-step tool with no output schema, the description supplies the missing return information — preview contents (summary, changes, warnings, confirmationToken) and the applied/replayed outcome — plus id source (get_pipeline_summary/get_pipeline_access). Nothing needed to call it correctly 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?

With 60% schema coverage, the description compensates well by explaining that roleIds replaces the role list, userIds replaces the people list, omitting one preserves it, and an empty list clears it — meaning the schema cannot express. confirmationToken semantics are fully covered. workspaceId is only documented in the schema, leaving a minor 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 opening sentence states a specific verb (replaces) and resource (roles/people who may see a pipeline), and the detailed semantics of roleIds/userIds make it unmistakable against sibling tools like get_pipeline_access, set_role_object_access, or update_pipeline. An agent can identify the operation without opening 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?

Explicit, prescriptive guidance on the preview-then-confirm flow: call first without confirmationToken, show the preview, get explicit approval, re-preview on any change, and handle stale_revision. It does not, however, name a specific sibling alternative (e.g., set_role_object_access vs. this pipeline-scoped tool), so it stops short of full alternative routing.

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