CDP MCP Server

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states 'Update an existing role,' implying a mutation operation, but does not disclose critical traits such as required permissions, whether the update is reversible, side effects (e.g., impact on users with this role), rate limits, or error handling. The JSON string formatting note adds minimal context, leaving significant gaps for a mutation tool.

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 extremely concise—two sentences—with zero wasted words. It is front-loaded with the core purpose ('Update an existing role.') and follows with specific parameter formatting advice. Every sentence earns its place, making it highly efficient in structure.

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?

Given the tool's complexity (mutation with 6 parameters, no annotations, schema coverage 0%), the description is incomplete. It lacks behavioral context, usage guidelines, and full parameter semantics. While an output schema exists (which mitigates the need to describe return values), the description does not address critical aspects like authentication needs, error conditions, or how partial updates (null parameters) are handled, making it inadequate for safe and effective 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?

Schema description coverage is 0%, so the description must compensate. It mentions 'whitelist/blacklist/included as JSON strings,' which adds semantic meaning for three parameters beyond their schema titles. However, it does not explain the other three parameters (role_id, tenant_id, name) or their relationships. With 6 parameters total and partial coverage, the description provides some value but falls short of fully compensating for the schema 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 description clearly states the tool's purpose: 'Update an existing role.' It specifies the verb ('Update') and resource ('role'), and distinguishes it from sibling tools like 'cdp_create_role' (creation) and 'cdp_delete_role' (deletion). However, it does not explicitly differentiate from other update tools (e.g., 'cdp_update_user'), which prevents a perfect score.

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 no guidance on when to use this tool versus alternatives. It mentions 'Pass whitelist/blacklist/included as JSON strings,' but this is parameter formatting advice, not usage context. There is no mention of prerequisites, when-not-to-use scenarios, or comparisons with sibling tools like 'cdp_get_role' or 'cdp_list_roles' for read operations.

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