Server Quality Checklist

Tool Scores

• fs_inspectB
  3.2/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint and idempotentHint, but the description adds critical context beyond them: it explicitly states 'never content' and mentions a 'short-lived inspection token'. This is meaningful behavioral disclosure and doesn't contradict annotations.

  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 sentence that front-loads the primary action and key limitation. Every word earns its place, with no fluff or redundancy.

  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 is too sparse for a tool with 5 parameters. It doesn't explain what 'classify' means, what the reasons represent, how the token is used, or the significance of 'locally'. The complexity warrants more detail than a single sentence.

  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?

  With schema description coverage at 0%, the description must compensate, but it provides no direct explanation of any parameter. It hints at a 'bounded file range', which maps to line_start/line_end, but doesn't clarify platform/distro or other semantics, leaving agents to guess.

  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 verb 'classify' and resource 'bounded file range', with a specific output of reasons and an inspection token. It distinguishes from fs_read by emphasizing 'never content', but does not explicitly differentiate from other siblings like fs_stat or fs_list, so it's not a 5.

  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?

  The description provides no explicit guidance on when to use this tool versus alternatives. It implies usage for classification without returning content, but does not state scenarios, exclusions, or reference sibling tools. Agents have to infer when this is the right choice.

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

• fs_releaseB
  3.2/5.0
  Behavior2/5

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

  With all annotation hints false, the description carries the full burden for behavioral disclosure. It reveals that Exact mode requires local confirmation, but it does not explain what releasing a range does, whether the effect is reversible, or what happens when purpose verification fails.

  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 short sentences, front-loaded with the core action and condition, with no filler or redundant restatement of the name.

  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 state-changing tool with no useful annotations and zero parameter documentation, the description is under-specified: it lacks mode semantics, the relationship to fs_inspect, and the release workflow beyond the confirmation requirement. The presence of an output schema does not compensate for those gaps.

  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 add meaning for the parameters. It only hints at an 'Exact mode' concept for the mode parameter; 'purpose' and 'inspection_id' remain effectively unexplained, and 'redacted' is not described.

  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 uses a specific verb ('Release') with a clear resource ('an inspected range') and a precondition ('after model purpose verification'), which differentiates it from related fs_* inspection/read tools. It does not name the sibling tool explicitly, but the action is distinct.

  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?

  It states a clear timing/condition: use this after an inspection has been performed and the purpose has been verified. It also warns that Exact mode requires local confirmation, but it doesn't explicitly contrast with alternatives or explain when redacted mode is appropriate.

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

• fs_search_pathsB
  3.2/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds behavioral context by specifying that it searches only names, not content, and explicitly never returns secret-bearing snippets. This adds value beyond annotations. However, it does not describe other behaviors like recursion, performance characteristics, or case sensitivity, but given the annotations, this baseline is adequate.

  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, dense sentence that is front-loaded with the main action and includes a critical safety caveat. It wastes no words and has a clear structure. Perfect length for the information it conveys.

  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?

  The tool has six parameters, an output schema, and no parameter descriptions. The description is minimal and does not explain return format (though output schema exists), paging/limits, depth control, or platform/distro specifics. The description is adequate for basic selection but insufficient for correct invocation without additional inference. Sibling tools like fs_list or shell_run span a complex ecosystem, and this description does not provide enough guidance on how to use parameters effectively.

  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 for parameter meaning. The description mentions 'root', 'search file and directory names', and 'query', but does not explicitly tie these to specific parameters like 'path', 'query', 'platform', 'distro', 'max_depth', or 'limit'. With six parameters and zero schema descriptions, the tool clearly fails to help the agent understand parameter semantics. The description only implies a search term and root path, leaving the rest unexplained.

  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 uses a clear verb+resource structure ('Search file and directory names under a root'), specifies the scope ('names under a root'), and includes a crucial exclusion ('never searches or returns secret-bearing content snippets'). It distinguishes itself from sibling read tools like fs_read and fs_list by focusing on path-name search. However, it does not explicitly name a sibling alternative, so it doesn't fully differentiate from similar search-related tools.

  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 use cases for searching file/directory names without returning content, which is a clear context but not explicit guidance on when to use this tool versus alternatives like fs_list or fs_find. No when-not-to-use or alternative tool names are provided. The 'never searches content' clarification hints at a distinguishing use case but does not provide full usage guidance.

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

• fs_statB
  3.2/5.0
  Behavior3/5

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

  Annotations cover safety (readOnlyHint=true, destructiveHint=false, idempotentHint=true) but description adds limited detail about metadata only, no filesystem side-effect details, permission/error behavior.

  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?

  Single sentence, concise, no redundant content.

  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?

  Output schema exists, but description does not explain return values; sibling tools of file listing/existence; contextual invocation for stat metadata may be sufficient. Missing content read vs lstat details.

  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 parameters have no descriptions; description adds no meaning. schema_description_coverage is 0%, so tool relies on parameter names 'platform', 'path', 'distro' only.

  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?

  Description uses specific action 'resolve' with target 'absolute Windows or WSL path without returning content'. Tool name 'fs_stat' suggests stat-like behavior. Distinguishes from siblings by stating no file content returned, but no explicit sibling comparison.

  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?

  Implied context: use to check path type/existence/metadata without reading content. No explicit when-vs alternatives, prerequisites, or exclusions.

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

• shell_runA
  3.5/5.0
  Behavior4/5

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

  Annotations already mark the tool as destructive and non-read-only. The description adds useful behavioral context by disclosing filesystem isolation and network availability, which is directly relevant for working with commands.

  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 convey purpose and key environment traits without any fluff. The most important information is front-loaded.

  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 command-execution tool with an output schema and robust annotations, the description captures core environment details (isolation, network) that affect command behavior. It doesn't discuss destructive potential, but annotations already signal that. Overall, sufficiently complete.

  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 explain the 'command' or 'timeout_seconds' parameters at all. The description adds no parameter-level meaning, even though it has the burden to do so.

  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 runs a command in the WSL bubblewrap snapshot, using a specific verb and resource. It distinguishes itself from siblings like windows_shell_run by specifying the WSL environment and notes key behaviors (host homes/windows mounts hidden, network enabled).

  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?

  The description does not provide explicit when-to-use or when-not-to-use guidance, nor does it mention alternatives like windows_shell_run. Usage is only implied by the tool name and environment description.

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

• windows_shell_openA
  3.5/5.0
  Behavior4/5

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

  Annotations only provide readOnlyHint=false, openWorldHint=false, etc., but no detailed behavioral traits. The description adds important behavior: the approval survives restarts until windows_shell_close, and notes that duration_seconds is legacy compatibility. This goes beyond the basic annotations and helps the agent understand persistence and parameter deprecation.

  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 sentence that conveys the core action, persistence, and a parameter caveat. It is front-loaded with the primary purpose, and every clause adds value. No filler words.

  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 that this tool has a clear purpose, an output schema (which likely documents the result), and only two simple parameters, the description covers the main behavioral points. However, the purpose parameter is left unexplained, and there is no mention of what constitutes 'approval' or how it is handled. The description is adequate but not fully complete for a tool that triggers a user-approval flow.

  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%, and the description provides only minimal parameter context: it mentions that duration_seconds is legacy compatibility, but does not explain the purpose parameter or its expected content. The purpose parameter is required but unexplained, leaving the agent to guess what information to provide. The description adds some value for duration_seconds but fails for purpose.

  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 ('Request one local approval for persistent Windows Shell authorization') and specifies the scope (persistent across restarts until closed). It distinguishes this from related tools like windows_shell_prepare, windows_shell_run, and windows_shell_close by focusing on the authorization/approval step.

  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 explains when the tool is used (to request approval before shell operations, and that it persists until close), but does not provide explicit guidance on when NOT to use it or which alternative (e.g., windows_shell_prepare) might be preferred. The context of 'one local approval' implies a prerequisite step, but comparisons are not explicit.

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

• windows_shell_closeA
  3.6/5.0
  Behavior3/5

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

  Annotations indicate destructiveHint=false, but the description says 'Immediately revoke... invalidate... terminate', which suggests destructive actions. However, the description does not contradict the annotations directly; it adds context about what happens (revoke, invalidate, terminate). Since annotations are present, the description adds some value by specifying the exact effects, but it could be more explicit about side effects like whether it is reversible or requires confirmation.

  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 sentence, concise, and front-loaded with the action. It covers the key effects without unnecessary words. It earns a high score for efficiency.

  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 the tool has no parameters and an output schema exists, the description is fairly complete. However, it does not mention what the output or return value is, but the output schema likely covers that. It also does not mention any prerequisites or side effects beyond the listed actions, which could be important for a close operation. Overall, it is adequate but could be more complete.

  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 schema description coverage is 100% (vacuously). The description does not need to explain parameters, and the baseline for zero parameters is 4. The description adds no parameter info, but that is acceptable given no parameters exist.

  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 tool's purpose: revoke Windows Shell authorization, invalidate reviews, and terminate the active command tree. It uses specific verbs and resources, and it distinguishes from siblings like windows_shell_status and windows_shell_open by indicating a closing/termination action.

  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 the user wants to close the Windows Shell session, but it does not explicitly state when to use it versus alternatives like windows_shell_close vs workspace_close. It lacks explicit exclusions or alternative tool references, but the context of 'close' is clear enough.

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

• fs_readA
  3.7/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is clear. The description adds valuable context about sensitive ranges returning review_required and no content, which is beyond annotations. No contradiction.

  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, front-loaded with the core purpose, and every word earns its place. No fluff.

  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 has 5 parameters with 0% schema description coverage, but an output schema exists. The description explains the sensitive range behavior but does not cover parameter details or return format beyond that. Given the complexity, it is adequate but has gaps.

  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. It mentions 'bounded normal text range' implying line_start and line_end, but does not explain platform, path, or distro semantics. The description adds minimal value beyond the schema, so a baseline 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 the tool reads a bounded normal text range, which is a specific verb+resource. It distinguishes from siblings like fs_stat and fs_list by focusing on reading file content, though it doesn't explicitly name alternatives.

  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 for reading text files within a line range, but does not provide explicit when-to-use vs alternatives or exclusions. The mention of sensitive ranges returning review_required gives some context but not enough for clear guidance.

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

• windows_shell_prepareA
  3.8/5.0
  Behavior4/5

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

  Annotations already declare readOnly and non-destructive behavior. The description reinforces this by stating it does not execute, and adds that parsing is static, suggesting no side effects. This is sufficient given the existing annotations.

  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 that front-loads the core action (parse and bind) and its non-execution aspect. It is efficient and well-structured.

  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?

  While it explains the main purpose, it does not describe the output of the preparation, how the bound command is used later, or interactions with other tools. Given the tool's complexity and unknown output schema, the description is only partially complete.

  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?

  The description mentions several parameters (cwd, target, purpose, timeout) but omits others (shell, command, arguments, executable). It also references 'risk' and 'environment' which are not in the schema, causing ambiguity. Parameter meanings are not fully explained.

  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 function: it statically parses and binds a PowerShell or native command to specified parameters, and explicitly notes it does not execute. This distinguishes it from execution tools like shell_run.

  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 for preparation without execution, but does not explicitly state when to choose this tool over alternatives. It lacks direct guidance on scenarios where this tool is preferred.

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

• workspace_apply_backA
  3.8/5.0
  Behavior3/5

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

  Annotations declare destructiveHint=true, and the description aligns by stating 'apply ... to the original repository,' implying modifications. The description adds the 'conflict-check' step, which is useful behavioral context. However, it doesn't detail what happens on conflict or whether the operation is reversible. With destructiveHint already set, the description adds some value but not extensive detail.

  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 sentence, concise and front-loaded with the action. It provides the key context in a short string, which is efficient and to the point.

  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 tool has an output schema (though not provided in detail), and the annotations include destructiveHint. The description covers the main purpose and usage step. Given the simple parameters and clear purpose, it is mostly complete. However, it could benefit from explaining the output or side effects more, but with output schema present, that burden is reduced.

  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%, meaning the description must compensate. The description names 'review_id' and 'purpose' indirectly? Actually, it mentions 'reviewed paths' and 'diff review' but does not explicitly map to 'review_id' or 'purpose'. It doesn't explain how 'purpose' is used or what values it takes. Since there are only 2 params, a good description could easily explain them, but this one does not. Baseline is low because coverage is 0%, and the description adds minimal param semantics.

  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 ('apply back') and the resource ('reviewed paths to the original repository'). It specifies the operation is about applying previously reviewed changes after diff review and local confirmation, which distinguishes it from generic apply tools. However, it doesn't explicitly differentiate from sibling tools like workspace_diff or workspace_status, though the focus on applying back is distinct.

  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 usage context: 'After diff review and local confirmation, conflict-check and apply only reviewed paths to the original repository.' This indicates when to use the tool (after diff review) and what it does (conflict-check and apply). It doesn't explicitly mention alternatives or when not to use it, but the context is clear enough for an agent.

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

• system_healthA
  3.9/5.0
  Behavior4/5

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

  The annotations already indicate read-only, idempotent, non-destructive behavior, so the description's job is simpler. It adds specific context by mentioning 'enhanced post-secret protections', which indicates the health check includes security-related status. There is no contradiction, and it helps the agent understand the focus of the report.

  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, succinct sentence that front-loads the core purpose. It is concise with no redundant information, and every word adds value in communicating what the tool does.

  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?

  Given the tool's simplicity (zero parameters) and the richness of annotations, the description is sufficient. It explains the purpose and key focus areas. The output schema exists, so return values are documented separately. No significant gaps are present for this straightforward health check.

  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, so parameter semantics are not applicable. The description doesn't need to explain parameters, and with no parameters, a baseline of 4 is appropriate since there is no confusion about inputs.

  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 tool reports gateway capabilities and whether enhanced post-secret protections are active. It uses specific verbs ('report') and resources ('gateway capabilities'), and while it is not explicitly contrasted with siblings, the subject matter is distinct from the listed sibling tools which deal with files, workspaces, and shells.

  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 that this tool is for checking system health or status, but it does not provide explicit guidance on when to use it versus other tools like workspace_status or windows_shell_status. There is no mention of exclusions or alternatives, though the purpose is clear enough for an agent to infer usage in a health-check context.

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

• windows_shell_runA
  4/5.0
  Behavior4/5

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

  Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, which signals mutation and risk. The description adds that it runs standard-user commands and that non-safe commands require local confirmation, which is useful beyond annotations. It also implies a warning about consuming a token. No contradiction.

  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 that conveys purpose, constraints, and safety requirement. No wasted words.

  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 one parameter and an output schema, the description provides the essential context: it's a gated execution tool. It doesn't explain what the output looks like, but the output schema likely covers that. The description could mention what happens on failure or how to obtain a review_id, but that might be covered by sibling tools like 'windows_shell_prepare'.

  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?

  With schema description coverage of 0%, the description must explain the parameter. It mentions 'review token' and 'review_id' but doesn't explicitly map 'review_id' to the token. The connection is implied but could be clearer. The description adds meaning (what a valid review_id is), but not fully explicit.

  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 tool's function: consume a review token and run a reviewed standard-user command. It distinguishes itself from 'shell_run' by specifying it uses a prepared review token and requires confirmation for non-safe commands, though it doesn't explicitly name alternatives.

  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: use when you have a prepared review token and want to execute a reviewed command. It contrasts with 'windows_shell_prepare' (which produces the token) and 'shell_run' (likely a less safe variant), but doesn't explicitly say when not to use it or name alternatives.

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

• workspace_openA
  4/5.0
  Behavior4/5

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

  The description adds crucial behavioral context beyond annotations: the original remains read-only until reviewed apply-back, indicating that opening a snapshot does not modify the original. This is not captured in annotations (readOnlyHint=false) and helps the agent understand side effects. It does not discuss other traits like auth or rate limits, but the added detail is significant.

  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, focused sentence that front-loads the verb and resource, then provides the executor qualification and the read-only note. No superfluous words.

  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?

  Given the presence of an output schema, the description need not explain return values. It conveys the core operation and an important workflow constraint. It could mention prerequisites or follow-up actions (e.g., apply-back or close), but it is sufficient for a well-scoped tool.

  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?

  With 0% schema description coverage, the description must compensate. It clarifies the executor parameter values ('wsl' or 'windows') and implies platform, but does not explain 'path' or 'distro'. This partial coverage of the four parameters is helpful but leaves gaps.

  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 (open one repository snapshot) and specifies two permitted executor values ('wsl' or 'windows'). It differentiates from siblings like workspace_apply_back and workspace_close by describing the snapshot-opening role in the workflow.

  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 by mentioning the snapshot execution context and the original's read-only status until apply-back, but it does not explicitly state when to use this tool vs. alternatives or when not to use it. The context is clear but not prescriptive.

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

• fs_listA
  4.1/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds useful behavioral context beyond annotations by specifying that the return includes entry names and metadata but never file snippets, helping agents avoid misusing the tool for content retrieval.

  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 short sentences, front-loaded with the core action and scoped by a clarifying negative. Every word adds value, and there is no redundant restatement of schema or annotation information.

  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 read-only listing tool with robust annotations and an output schema, the description is mostly sufficient. It captures the core purpose and the key behavioral boundary (no file snippets). It does not explain distro/platform context or limit behavior, but parameter names and the structured schema partially cover that 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%, and the description provides no parameter-level guidance. It only implies that the operation targets a directory via 'List directory entry names', leaving path, limit, distro, and platform semantics entirely to their names and schema types. The description must compensate for the lack of schema descriptions but does not.

  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 and resource ('List directory entry names and metadata') and clearly distinguishes this from sibling file tools by stating it never returns file snippets. This makes the tool's scope immediately clear and differentiates it from content-reading tools like fs_read or fs_inspect.

  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 that this is a directory-listing operation, and the explicit note 'never returns file snippets' gives an implicit exclusion when file content is needed. However, it does not explicitly name alternatives or provide a when-not-to-use directive, so it falls short of a perfect score.

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

• windows_shell_statusA
  4.1/5.0
  Behavior3/5

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

  Annotations already provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds the list of specific status categories and the fact it doesn't execute commands, which adds some behavioral context beyond annotations but doesn't elaborate on output format or side effects (none expected). With annotations covering the core behavioral traits, a 3 is appropriate.

  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, succinct sentence that front-loads the verb 'Report' and then lists the specific items. Every word contributes value, with no fluff or repetition, making it highly efficient.

  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?

  The tool is simple (0 params), has rich annotations covering safety, and an output schema exists. The description lists exactly what statuses are reported, covering all relevant aspects for such a status tool. No additional context is needed given the low complexity and structured annotations.

  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 takes zero parameters, so schema coverage is 100% by default. The description correctly omits parameter details. Baseline for 0-parameter tools is 4, and the description doesn't attempt to fabricate unnecessary parameter explanations.

  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 it reports status (PowerShell 7, standard-user, Job Object, authorization, workspace, policy) and explicitly says 'without executing a command', distinguishing it from siblings like shell_run or windows_shell_run. This is a specific verb-resource pair that 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 Guidelines3/5

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

  No explicit when-to-use guidance is given, but the phrase 'without executing a command' informs agents that this is a safe, non-executing status check. Siblings like shell_run and windows_shell_run imply alternatives, but no direct comparison or exclusions are stated. The usage context is inferred rather than explicit.

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

• workspace_diffA
  4.3/5.0
  Behavior4/5

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

  Annotations already cover read-only, idempotent, and non-destructive aspects. The description adds behavioral details such as redaction and that Git-ignored outputs are listed but not reviewed or applied, which goes beyond the annotations. It could be more specific about what 'redacted' entailed, but it's still informative.

  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 that conveys all essential information without redundancy. It is well-structured and direct.

  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?

  Given the tool's simplicity (no parameters), the existing output schema, and comprehensive annotations, the description covers all required aspects. It explains the core functionality and key behaviors, making it complete for an agent to decide and invoke 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?

  Since the tool has zero parameters, the schema fully covers them (100% coverage). Per the guidelines, when coverage is high, the baseline score is 3 even without parameter-specific descriptions. No additional parameter info is needed.

  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 returns a diff of managed files, and specifies the redaction and handling of Git-ignored outputs. This distinguishes it from sibling tools like workspace_apply (which applies changes) and workspace_status (which shows status).

  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 by describing what the tool does and its limitations (lists but never applies Git-ignored outputs), but it does not explicitly contrast with alternatives or provide when-to-use scenarios. However, the conditions are reasonably clear from the context.

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

• workspace_statusA
  4.3/5.0
  Behavior4/5

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

  Annotations already cover read-only and idempotent behavior. The description adds meaningful detail by specifying that it excludes file content and separately lists ignored outputs, providing extra behavioral transparency beyond annotations.

  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, clear sentence with no unnecessary words. It efficiently conveys the tool's purpose and key limitation.

  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?

  Given that the tool has no parameters and an output schema exists, the description adequately explains the tool's function and output scope. It is complete for a status tool.

  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 no parameters, so the description need not explain them. The baseline of 4 applies, and no additional parameter information is required.

  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 reports managed changes and separately lists Git-ignored runtime outputs, providing a specific action and resource. This distinguishes it from sibling tools like workspace_diff or workspace_apply_back.

  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 for status checking but does not explicitly state when to use it over alternatives or mention sibling tools. It provides some context (excluding file content) but lacks explicit when-to-use/when-not-to-use guidance.

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

• workspace_closeA
  4.6/5.0
  Behavior4/5

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

  The annotations already mark the tool as destructive (destructiveHint: true), but the description adds valuable behavioral context by noting that unapplied changes require an explicit discard flag and local confirmation. This goes beyond what the annotations provide and helps the agent understand the safety mechanism and prerequisite for destructive action.

  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, front-loaded with the primary action. The second sentence adds essential conditional behavior without verbosity. Every word contributes to clarity, and it is appropriately sized for the tool's simplicity.

  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?

  Given the tool's simplicity (1 optional parameter, output schema exists), the description is complete. It covers the main action, the destructive nature, the parameter's purpose, and the confirmation requirement. There are no ambiguous aspects or missing behavioral details that the agent would need to infer.

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

  Parameters5/5

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

  The schema has only one parameter (discard_unapplied) with no coverage from the schema description (0%). The description fully compensates by explaining that unapplied changes need this flag, directly linking the parameter to its purpose. This gives the agent a clear understanding of when to set it to true.

  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 action: 'Remove the active local snapshot.' It uses a specific verb and resource, and it is easily distinguished from sibling tools like workspace_open, workspace_status, or workspace_diff, which have different purposes. The mention of unapplied changes and discard flags further clarifies the scope.

  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 the discard flag is required (for unapplied changes), which provides clear context on how to handle a common scenario. It does not explicitly name alternative tools or state when not to use it, but the purpose is evident from the tool name and description, and the guidance on unapplied changes covers the main usage nuance.

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