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

Adds real context beyond the annotations: credential is write-only and never seen by agents, reviewer/qa only ever receive read-only tools and cannot use sandbox-internal servers, and omitting fields preserves existing state while setting them re-points. It stops short of saying what happens to the previously stored credential on re-point or how failures (bad transport/credential combo) surface, which is why it isn't a 5.

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?

A single dense paragraph with no filler; the binding/update distinction is front-loaded and the transport and field-omission rules follow in a logical order. Every clause carries actionable 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 7-parameter mutation tool with no output schema, the description covers purpose, prerequisites, transport selection, and update semantics — enough to call it correctly. Gaps are minor: it does not touch approvedTools or the refresh_mcp_server_tools prerequisite, though the schema covers those.

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 semantics the schema lacks: the role-scoping rule for reviewer/qa, the intent behind each transport mode, and the keep-vs-replace behavior of transport/remoteUrl on update. It says nothing about approvedTools (left entirely to 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?

States a specific verb pairing ('Create or update') and a precise resource ('the binding for a server the repository declares'), which cleanly separates it from list_mcp_bindings and unbind_mcp_server. An agent can identify it as the write-side counterpart to the read siblings 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?

Gives explicit conditional guidance: omit transport/remoteUrl on an update to keep the pinned server and credential, set them only to bind or re-point. It also enumerates the three transport choices with the situation each serves (secret needed, no credential, proxied URL) and names the config:write capability prerequisite.

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