Server Quality Checklist

Tool Scores

• check_requestA
  3.5/5.0
  Behavior2/5

  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. Yet it never explains the polling semantics implied by wait_seconds — what happens on timeout, whether it blocks, what states the outcome can be in, or the return shape. For a polling-type tool this is a notable gap given there is no annotation coverage.

  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?

  Two tight sentences with the purpose front-loaded ahead of the usage trigger. No filler. It only loses a point because the second clause ('or to pick up a request the Claude Code hook raised') could arguably have been folded into the first, though it does add the sibling/hook context.

  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?

  Given it has an output schema and only two parameters (one with a meaningful default), the description covers the core purpose and when to call it competently. But it leaves out the wait_seconds timeout/blocking behavior and the possible outcome states — information an agent polling after a pending escalation would reasonably need before calling.

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

  Parameters2/5

  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, but it adds no parameter meaning at all. request_id and wait_seconds are never explained beyond their raw schema definition (an ID string and a defaulted integer). The description's mention of 'the request' hints at request_id but provides no semantics like what a valid ID looks like or what wait_seconds controls.

  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 names a specific verb and resource — 'Retrieve the outcome of an escalation' — with an explicit scope qualifier ('from MCP OR the hook'). It differentiates itself from its sibling run_privileged by the triggering mechanism it responds to, so an agent can tell exactly what this tool is for.

  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 gives explicit when-to-use context: 'after run_privileged returns pending, or to pick up a request the Claude Code hook raised.' This is clear and actionable, though it stops short of stating when-not-to-use or naming an alternative for older/unresolved requests.

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

• run_privilegedA
  3.5/5.0
  Behavior4/5

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

  No annotations are provided, so the description carries full responsibility. It discloses critical behaviors: human approval is required, the command runs outside the sandbox, the agent never receives root, and output is captured on approval. This is substantial transparency, though it omits what happens on rejection, timeouts, or any safety caveats—more than enough to earn a 4 but not 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.

  Conciseness5/5

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

  The description is two sentences with no filler. The core action is front-loaded ('Request a privileged shell command'), and the second sentence adds essential behavioral context. Every clause earns its place; it is a model of conciseness.

  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?

  Despite having an output schema, the description misses critical operational details an agent needs: what happens if approval is denied, is the request asynchronous (the term 'Request' implies a wait, but it is not stated), what is the expected latency, and how does the 'reason' parameter factor into approval. It also does not mention safety or restrictions on the command. These gaps are significant for a privileged, human-in-the-loop tool.

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

  Parameters1/5

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

  Schema description coverage is 0% and the description does not shed any light on the parameters. It never mentions 'command' or 'reason' by name, nor explains expected syntax, purpose of reason, or any parameter-specific guidance. With zero schema coverage, the description must compensate but fails entirely.

  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 verb ('Request') and resource ('a privileged shell command'), and the second sentence adds the key differentiator: it runs outside the sandbox. This distinguishes it from siblings like fetch_url (network) and request_path_access (file access), so an agent can tell it apart without opening any schema.

  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 is clear the tool is for running privileged shell commands that require human approval, but it does not explicitly state when to prefer it over alternatives or when not to use it. There is no mention of 'use this when sandbox is insufficient' or 'instead of sandbox_status'. The context is implied but not made explicit.

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

• sandbox_statusA
  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 behavioral burden. The verb 'Show' implies a non-mutating, read-only operation, which is useful implicit disclosure. However, it doesn't explicitly state that it has no side effects, requires no auth, or how escalations are represented. For a status tool this is acceptable but leaves room for more explicit guarantees.

  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, front-loaded sentence with zero waste. The verb leads, and each listed item (root, triggers, pending escalations) earns its place by describing distinct output facets. Nothing is redundant.

  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 zero-parameter status tool with an output schema present, the description is largely complete — it states exactly what the status covers. Minor gaps exist (e.g., no mention of when status is current or whether it reflects a snapshot), but these are not material for an agent deciding to invoke it.

  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?

  The tool has zero parameters and an empty input schema with 100% coverage, so there is nothing for the description to add. Per the baseline for a 0-param tool, a 4 is appropriate — no parameter documentation burden exists.

  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 and resource — 'Show the sandbox root, triggers, and any pending escalations.' The verb 'Show' signals a read-only status operation, and the listed content (root, triggers, escalations) is concrete. It does not explicitly contrast with siblings, but the domain is distinct enough from run_privileged, request_path_access, fetch_url, and check_request that an agent can infer the purpose.

  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 the siblings. It does not state prerequisites, conditions, or exclusions. For example, it doesn't clarify that this should be called before requesting access or that it's the safe inspection entry point. The agent must infer usage purely from the name and the sibling list.

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

• fetch_urlA
  3.8/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 that a human approves each request and that the sandbox performs the fetch outside the agent's context, providing key behavioral context. However, it does not cover all potential behaviors like failure scenarios or rejection handling.

  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 concise, with two short paragraphs that front-load the primary purpose and add key behavioral context without unnecessary words. Every sentence contributes value, making it well-structured and efficient.

  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?

  The tool is simple with only two parameters, and the description covers the main flow (fetch, approval, body). However, it omits the purpose of the 'reason' parameter, which is significant given zero schema descriptions. The output schema likely covers return format, but the missing parameter explanation creates a gap.

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

  Parameters2/5

  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, but it fails to explain the 'reason' parameter or any URL constraints. It implicitly mentions the URL but adds no meaningful detail beyond what the schema already shows (just types). The optional reason parameter is left unexplained.

  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 tool fetches a URL through the sandbox, specifying both the verb and resource. It is distinct from siblings like run_privileged and request_path_access, making its purpose unambiguous and easy to differentiate.

  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 usage when needing to fetch a URL and mentions human approval, but it does not explicitly state when to use this tool versus alternatives or specify exclusions. The guidance is implied rather than explicit, leaving some ambiguity.

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

• request_path_accessA
  4.2/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 behavioral disclosure. It discloses critical behavioral traits: a human must approve, the sandbox performs the read/write on the agent's behalf, and the agent never receives the capability. This covers the most important asynchronous and security implications. It does not mention whether the operation is blocking or how to check approval status, 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 no redundancy. The first sentence states the purpose upfront, and the second explains the approval process and parameter usage. Every word earns its place, and the structure is optimized for quick comprehension.

  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?

  Despite having an output schema, the description is fairly complete for a tool that requires human approval. It covers the main flow (request, approval, sandbox performs) and key parameters (mode, content). It does not mention that the operation is asynchronous or that the agent should poll check_request for status, but given the sibling tools and the output schema, this is a moderate gap. Overall, it's adequate but not exhaustive.

  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 0%, so the description must compensate for parameter meaning. It does explain 'mode' (valid values 'read' or 'write') and 'content' (used with write mode), which adds value. However, it does not clarify 'path' (though it's implied as the target file) or 'reason' (its purpose), leaving those parameters ambiguous. While partial compensation, the coverage gaps prevent a higher score.

  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 tool's purpose: requesting a file operation outside the sandbox folder. It specifies the verb 'Request' and the resource 'a file operation', and the scope 'OUTSIDE the sandbox folder' differentiates it from siblings like run_privileged, fetch_url, check_request, and sandbox_status, which have distinct purposes. The distinction is explicit and leaves no ambiguity.

  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: this tool is for file operations that need to happen outside the sandbox. It implies that for operations inside the sandbox, this tool is not needed. However, it does not explicitly name alternatives or state when not to use it; rather, it relies on the reader to infer that other tools like run_privileged or fetch_url are for different resource types. This is clear context but no exclusions are stated.

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