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

Annotations already establish readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description goes beyond these by clarifying that this updates 'stored' server configuration and requires a specific permission scope. It does not detail partial-update or overwrite behavior, but the annotation coverage plus the 'stored' framing make the tool's core behavior clear.

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 four short sentences, front-loaded with the core purpose, then permission, alternatives, and target playbook context. Every sentence earns its place and supports either invocation or selection.

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 tool with 8 parameters, no output schema, and appropriate annotations, the description provides sufficient selection criteria, permissions, and payload scope. It does not cover update semantics such as whether partial fields replace or merge, or how nested arrays should be formatted, but these are partially inferable from the schema and do not prevent correct high-level use.

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 covers all 8 parameters with 100% description coverage, so the baseline is 3. The main description does not add much parameter-level detail beyond mapping broad categories like 'name, description, tools, resources, or transport' to the schema, and noting that playbook_id should be the target playbook. This is accurate but redundant with 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 action and resource: 'Update a connected MCP or OpenAPI server's stored name, description, tools, resources, or transport.' It clearly identifies which mutable fields are involved and distinguishes the tool from related server actions by naming call_connected_tool and delete_mcp_server.

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 explicit when-to-use guidance: updating server metadata versus invoking tools via call_connected_tool versus disconnecting via delete_mcp_server. It also states a clear permission precondition: 'Requires playbooks:write or full permission,' and tells the agent to pass a playbook_id.

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