Server Quality Checklist

Tool Scores

• configure_mcpC
  2.9/5.0
  Behavior2/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It does mention the merge behavior, which is useful, but it omits critical safety details such as the footgun refusal mechanisms (exposed via allow_footgun_* parameters), the fact that this operation mutates server configuration, and any side effects like requiring a restart. These are not covered by annotations, so the description is significantly under-informing 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.

  Conciseness4/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is two sentences and front-loads the core action ('Update the configuration'), then adds the merge detail. It is appropriately brief with no filler. It could benefit from a usage note, but the existing text is efficient and structured well.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness2/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a mutation tool with no annotations, no output schema, and multiple safety-related parameters, the description is incomplete. It does not explain when a configuration update is needed, the safety refusal behavior, or the relationship with sibling tools like restart_mcp_process. An agent may call this tool without understanding the risks or the merge semantics beyond a surface level.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 100%, so each parameter already has a description. The tool description adds no parameter-specific meaning beyond what the schema provides. The baseline of 3 is appropriate because the description does not introduce any additional context or clarify how the parameters interact (e.g., the purpose of the allow_footgun_* toggles).

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose4/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description states a clear action (update configuration) on a specific resource (existing MCP server), and mentions a distinguishing behavior (merging instead of overwriting). It is clearly distinct from siblings like add_mcp or remove_mcp, though it does not name them. The purpose is unambiguous for an agent.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines2/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  No guidance is given on when to use this tool versus alternatives such as add_mcp or restart_mcp_process. It is implied that it modifies existing servers, but there is no explicit context about when a config update is appropriate, whether a restart is needed afterward, or any prerequisites. The agent is left to infer usage context.

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

• add_mcpB
  3.1/5.0
  Behavior2/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It only states the raw action and destination, omitting critical behaviors such as the safety refusals for footgun flags (env, args, shell metacharacters) that are evident in the schema. It also doesn't mention whether existing configurations are overwritten, permission requirements, or failure modes.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness4/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is a single, front-loaded sentence with no wasted words. It is appropriately concise for the simple action it describes, though it omits important details that affect usability.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness2/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a tool with 10 parameters, nested objects, safety refusals, and no output schema, this description is severely incomplete. It doesn't cover return values, error handling, or the footgun override mechanism that an agent must understand to call the tool correctly.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 100%, so all 10 parameters are already documented with meaningful descriptions. The tool description adds no additional parameter semantics beyond what the schema provides, aligning with the baseline 3 for high coverage.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose4/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the action (add) and resource (new MCP server) with a specific destination (user configuration). While it distinguishes itself from 'remove_mcp' and 'list_all_mcps', it doesn't explicitly differentiate from 'configure_mcp' (which might modify existing servers), though 'new' implies that distinction.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines3/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description implies this is for creating new servers, but it doesn't explicitly state when to use this over 'configure_mcp' or provide exclusions/prerequisites. No alternative tools are mentioned, leaving usage context implicit rather than explicit.

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

• get_mcp_detailsB
  3.1/5.0
  Behavior2/5

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

  With no annotations, the description carries the full burden of behavioral disclosure. It labels the operation as 'Get', implying read-only, but does not state that it is safe or non-destructive. It also omits important behavioral context: that 'env' values are masked by default and that show_env_values can reveal raw secrets. The schema mentions this, but the description adds nothing beyond the basic operation.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is a single, tightly worded sentence with no filler. It goes straight to the purpose and does not waste tokens. This is optimal for a simple getter.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a straightforward retrieval tool with no output schema, the description provides the basic intent but leaves gaps. It fails to mention that the result includes environment variables, that they are masked by default, and that show_env_values toggles revelation. These details are only in the schema, so an agent unfamiliar with the tool might not realize the sensitive nature of the output. The description is adequate but not comprehensive.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 100%, so the parameters are fully documented in the schema. The description does not repeat or add anything about mcp_name or show_env_values. It passes the baseline threshold but does not enhance understanding of parameter usage beyond what the schema already provides.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose4/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description states a clear action ('Get') and a specific resource ('full configuration for a specific MCP server'). It implicitly distinguishes from siblings like list_all_mcps (which lists all) by focusing on 'specific'. It does not explicitly name an alternative, but the purpose is unambiguous.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines2/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  There is no guidance on when to use this tool versus alternatives such as list_all_mcps or check_mcp_health. The description does not mention prerequisites, expected context (e.g., when you already know the server name), or when not to use it. An agent must infer usage from the name and schema.

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

• check_mcp_healthA
  3.5/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the full burden. It discloses what is checked (configured, wrapped, process running), implying a read-only operation, but does not disclose the return value format, error behavior (e.g., what happens if server is absent), or any side effects. There is no contradiction, but the behavior is only partially transparent.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is a single concise sentence with no filler. It is front-loaded with the primary action and enumerates the specific checks, making it efficient and easily parsed.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a simple one-parameter tool with no output schema, the description should explain return values or expected outcomes, which it does not. It also does not cover edge cases like missing servers or what constitutes a healthy vs. unhealthy response. The description is adequate for selecting the tool but not for expecting its output, so completeness is only partial.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 100% and the parameter 'mcp_name' is already described as 'The name of the MCP server to check.' The description adds no additional semantics beyond what the schema provides, so a baseline score of 3 is appropriate.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description uses a specific verb ('Check') and a clear resource ('health of an MCP server'), and enumerates three concrete aspects it examines (configured, wrapped, process running). This distinguishes it from sibling tools that list, detail, restart, or wrap servers.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines2/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  No guidance on when to use this tool versus siblings. It does not state, for example, to use it before calling other MCP operations, or to verify if a server is operational, or what to do based on results. The purpose is clear but there is no explicit or implicit usage context.

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

• remove_mcpA
  3.7/5.0
  Behavior2/5

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

  Annotations are absent, so the description carries the full burden of behavioral disclosure. 'Remove' implies a destructive mutation, but it does not specify whether the operation irreversibly deletes the server definition, whether it affects running processes, or whether any confirmation is required. Without these details, an agent cannot fully anticipate consequences.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  A single, well-formed sentence with no wasted words. The core action and target are front-loaded, and the file path provides necessary specificity without clutter.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a simple one-parameter mutation tool without an output schema, the description covers the essential action and target. However, it does not mention error handling (e.g., behavior if the server name does not exist) or any prerequisites (e.g., whether the MCP must be stopped first). Given no annotations, a bit more context on consequences would improve completeness.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 100% — the only parameter 'mcp_name' is described as 'The name of the MCP server to remove.' The description adds no extra information beyond the schema, so the baseline of 3 applies; the schema does the heavy lifting.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description states a specific verb ('Remove'), a clear resource ('MCP server'), and the exact configuration file path ('~/.claude/mcp.json'). This distinguishes it from siblings like add_mcp and configure_mcp, leaving no ambiguity about what the tool does.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description implies usage: to remove an MCP server from the user configuration. It does not explicitly name alternatives or when-not-to-use conditions, but the sibling set makes the purpose obvious. For a simple removal tool, this is sufficient context, though it lacks explicit routing guidance.

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

• restart_codex_mcp_processA
  3.8/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden. It discloses the reliability limitation, the mechanism (killing the wrapped child PID from its pidfile), and the typical failure mode for unwrapped MCPs. It does not detail side effects or whether the process is restarted synchronously, but the core behavior is transparent.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is two sentences with zero waste. The action is stated first, followed by the key caveat. Information density is high and every clause adds value, making it an exemplary concise definition.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a tool with a single well-documented parameter and no output schema, the description adequately covers purpose, limitations, and method. It could mention what the tool returns or whether it waits for restart, but these are minor omissions given the simplicity and the existing caveat.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The schema description for 'mcp_name' is clear and specific ('The mcp_servers.<name> entry in ~/.codex/config.toml to restart'), giving 100% coverage. The tool description adds no extra parameter details, but since the schema already explains it well, the baseline of 3 is appropriate.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose4/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description states a specific verb ('Restart') and resource ('Codex CLI MCP server process'), and implicitly differentiates from the sibling 'restart_mcp_process' by emphasizing the wrapped-MCP condition. It is not a tautology and clearly conveys the operation, though it could more explicitly name the generic sibling.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines3/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  It provides a clear condition for reliable use ('only for wrapped MCPs') and notes the fallback ('restart Codex CLI') for other cases. However, it does not explicitly compare against alternatives like 'restart_mcp_process' or state when to use that sibling instead, leaving some routing to inference.

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

• restart_mcp_processA
  4/5.0
  Behavior3/5

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

  With no annotations, the description carries the full burden of behavioral disclosure. It states that the tool kills the process, and clarifies the respawn behavior for wrapped stdio MCPs. Yet it omits potential side effects (e.g., disrupted connections, unsaved state), prerequisites (such as permissions), or error scenarios if the process is not found. This is adequate but not rich.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Two sentences, no redundancy, and the core action is front-loaded. The explanation of wrap behavior and the fallback to Claude CLI is compact and directly relevant.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a single-parameter tool with no output schema, the description covers the main use case and the key behavioral difference between wrapped and non-wrapped processes. While it does not address edge cases like invalid names or failure handling, it is complete enough for an agent to know when to call it and what to expect, especially given the clarity of the parameter.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The schema provides full description coverage for the only parameter (mcp_name), and the tool description adds no further semantic details. At 100% coverage, the schema already carries the meaning, so the description does not need to compensate. Baseline 3 is appropriate.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the action (restart), the target (underlying process for an MCP server), and the method (find and kill its process). It implies a distinction from restart_codex_mcp_process by referencing Claude CLI and wrap_mcp_stdio, which orients the agent toward the standard MCP context.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description explains when this tool is appropriate: for wrapped stdio MCPs the wrapper respawns automatically, and otherwise the user typically needs to restart Claude CLI. It provides actionable context about when manual restart is unnecessary versus when it is needed. However, it does not explicitly name the alternative restart_codex_mcp_process for Codex-related MCPs, leaving a slight gap in sibling differentiation.

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

• unwrap_mcp_stdioA
  4/5.0
  Behavior3/5

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

  No annotations are provided, so the description bears full responsibility. It discloses a key behavioral trait: the need for a restart. However, it doesn't mention whether the operation is reversible, idempotent, or what happens if the server isn't actually wrapped. These are minor gaps for a simple tool but keep it at a mid level.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is a single, well-structured sentence that front-loads the primary action and immediately follows with the critical operational note. Every word earns its place with no redundancy.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a simple single-parameter operation with no output schema, the description covers the essential context: what it does, its effect (restoring original command), and the required follow-up action. It could mention expected return behavior, but that's a minor omission given the tool's simplicity and lack of complex output.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The input schema already provides a clear description for the single parameter (mcp_name). The tool description adds no new semantic detail about the parameter, and schema coverage is 100%, so the baseline of 3 is appropriate.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the action (unwrap), the target (previously wrapped stdio MCP server), and the outcome (restoring its original command). It implicitly contrasts with sibling wrap tools, making it easy to distinguish as the inverse operation.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description includes a clear prerequisite ('Requires restarting Claude Code to take effect') which informs the agent about the necessary post-step. It doesn't explicitly name alternatives, but the context of siblings like wrap_mcp_stdio makes the use case obvious. A brief note about when to use this versus unwrap_codex_mcp_stdio would push it to 5.

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

• wrap_codex_mcp_stdioA
  4/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden of disclosing behavioral traits. It states that it rewrites the MCP entry, launches a wrapper that respawns the original command, and explicitly notes that a Codex CLI restart is required for the change to take effect. This covers the mutation, the new process behavior, and the required follow-up action. It could mention reversibility or impact on existing config, but the core side effects are disclosed.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is three sentences with no filler. The first sentence states the purpose and scope, the second explains how it works, and the third gives the required post-action. Everything is front-loaded and earns its place.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  The description covers the configuration file, the wrapper mechanic, and the restart requirement. It does not describe error handling or what happens if the mcp_name does not exist, but given the single parameter is fully documented and there is no output schema, the essential context for a successful call is present. Slight gap is the absence of any warning about config modification potentially needing backup, which would be nice but is not critical.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The input schema documents the single parameter mcp_name with a clear description (the mcp_servers.<name> entry). Since schema coverage is 100%, the parameter is fully self-documenting; the description adds no additional semantic detail beyond what is already in the schema. Baseline 3 is appropriate.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the specific verb and resource: it wraps a Codex CLI stdio MCP server (from ~/.codex/config.toml). It names the target file and describes the mechanism (rewrites the entry to launch mcpgo's Node wrapper). This distinguishes it from the generic sibling wrap_mcp_stdio by scoping to Codex CLI stdio servers.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines3/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description implies the tool is for making Codex CLI stdio MCP servers restartable, which provides context. However, it does not explicitly state when to use this tool over the sibling wrap_mcp_stdio, nor any exclusions or prerequisites (e.g., that the server must already be configured in config.toml). Not misleading, but guidance is implicit rather than explicit.

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

• wrap_mcp_stdioA
  4.2/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden. It discloses the side effect on ~/.claude.json, the mechanism (Node wrapper that respawns when killed), and the restart prerequisite. It does not mention potential overwriting of existing config values or failure modes, but the disclosed behaviors are accurate and useful.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is exactly two sentences: the first front-loads the purpose, the second explains the mechanism and requirement. Every clause adds value, with no fluff or repetition. Efficient and well-structured.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a single-parameter tool with no output schema, the description covers the essentials: what it does, how it works, and the required restart. It could add caveats about config overwrites or error conditions, but these are minor given the tool's simplicity and the provided fact that it modifies ~/.claude.json.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 100% (mcp_name is documented as 'The name of the MCP server to wrap'). The description adds no additional meaning beyond this – it doesn't explain how the name maps to config entries or any constraints. Baseline 3 is appropriate since the schema already fully describes the parameter.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the action ('wrap') and the resource ('stdio MCP server'), and explains the purpose ('so it can be restarted reliably'). It differentiates from the sibling wrap_codex_mcp_stdio by explicitly targeting stdio servers, and implicitly contrasts with unwrap_mcp_stdio. The agent can tell exactly what this tool accomplishes.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description implies when to use it (when restart reliability is needed) and includes a key operational requirement ('Requires restarting Claude CLI to take effect'). However, it does not explicitly name alternative tools (e.g., unwrap_mcp_stdio, restart_mcp_process) or state when not to use it, which would strengthen guidance but is not essential given the clear purpose.

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

• list_all_mcpsA
  4.5/5.0
  Behavior4/5

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

  With no annotations, the description carries the behavioral disclosure burden. It explicitly reveals that env values are redacted by default, explains the security rationale (preventing exfiltration), and notes the behavior when show_env_values=true is passed. This goes beyond a simple 'list' operation and gives the agent important safety context. However, it does not mention output format or any other side effects, which are minor for a read-only list tool.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is two concise sentences with no fluff. The main action is front-loaded, and the second sentence adds essential detail (redaction and parameter usage) without redundancy. Every word earns its place.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a simple list tool with one optional boolean parameter and no output schema, the description covers the purpose, source file, security behavior, and parameter semantics. It is complete enough for an agent to call the tool correctly without further clarification. The sibling tools are sufficiently differentiated by the 'all' scope.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 100%, so the parameter is well-documented. The description adds value beyond the schema by explaining the default redaction behavior and the legitimate use case for revealing values ('when you legitimately need them'). This contextualizes the parameter's purpose and security implications, earning a score above the baseline.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states a specific verb ('List') and resource ('all configured MCP servers from ~/.claude.json') and distinguishes from siblings by scope: it covers all servers, while siblings target individual servers (get_mcp_details), health checks, restarts, etc. This makes the purpose unambiguous.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description provides clear context for when to use this tool: to enumerate all configured MCP servers. It does not explicitly mention alternatives or when not to use it, but the purpose is self-evident given the name and description. The redaction note adds usage context for the parameter but not for alternatives, so it stops short of a full when/when-not explanation.

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