Server Quality Checklist

Tool Scores

• editB
  3.3/5.0
  Behavior3/5

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

  Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false. The description adds 'Returns a unified diff,' which is a useful behavioral detail about the output. It does not contradict annotations, but it does not go beyond them significantly—no mention of failure modes, atomicity, or safety considerations.

  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 concise sentences with no filler. The primary action is front-loaded in the first sentence, and the return type is mentioned in the second. Every word earns its place.

  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 tool with 6 parameters and no output schema, the description covers the core operation and return format but omits usage context (when to prefer this over 'write'), edge-case behavior (e.g., what if old_text not found), and dependencies like workspace_id. The schema fills in some parameter details, but the description alone leaves an agent guessing about selection context.

  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 six parameters are already documented. The description adds no additional semantic context (e.g., typical values, relationships between parameters). It meets the baseline because the schema handles the parameters, but there is no extra value.

  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?

  Clear and specific: 'Apply a targeted exact text replacement inside a workspace text file.' The verb 'apply' and resource 'workspace text file' are explicit, and 'targeted exact text replacement' distinguishes it from siblings like 'write' (whole file) and 'search'/'read' (non-mutating).

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

  Usage Guidelines1/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 alternatives like 'write' or 'search'. The description does not mention exclusions, prerequisites, or typical scenarios. An agent has to infer that 'edit' is for small targeted changes, which is not explicitly stated.

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

• writeB
  3.4/5.0
  Behavior4/5

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

  destructiveHint: true and readOnlyHint: false already flag the mutation; the description adds value beyond annotations by disclosing that it 'Returns a unified diff' and requiring meaningful content. These details go beyond what structured annotations carry and do not contradict them.

  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 sentences with the core action front-loaded and no filler. The tail packs the return format and a usage rule into one compact clause, which is efficient though slightly dense; every sentence earns its place.

  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?

  Adequate for a write tool whose safety profile is covered by annotations, but the sibling edit is never addressed and 'unified diff' is left undefined. For a destructive tool with no output schema, it could clarify overwrite defaults and edge behavior more.

  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 documentation covers 100% of the 5 parameters (path, content, overwrite, create_dirs, workspace_id), so the baseline of 3 applies. The description adds no parameter-level meaning 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?

  States a specific verb and resource ('Create or overwrite a meaningful text file inside the workspace') with clear scope, and the title 'Write File' reinforces it. It clearly implies whole-file creation vs. incremental edits, but stops short of naming the edit sibling explicitly, so it earns a 4 rather than 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?

  Offers one behavioral rule ('do not create empty placeholder files') but gives no guidance on when to use this tool versus the sibling edit (or bash). The alternatives are not named and no conditions for choosing write over edit are provided, leaving the agent to infer.

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

• open_workspaceA
  3.5/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, signaling a non-mutating operation. The description adds return-value context (workspace_id, git status, skills) but no additional behavioral traits such as authentication needs, rate limits, or potential side effects beyond what annotations already cover. It neither contradicts annotations nor introduces new behavioral caveats.

  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, front-loaded with the action ('Open') and followed by a concise list of return items. It is free of filler, repetition, or unnecessary details, making it immediately scannable 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?

  For a tool with 8 parameters and no output schema, the description is minimal but adequate: it conveys the core purpose and return data. Parameter details are fully covered by the schema, so the description doesn't need to repeat them. However, it omits any guidance on parameter interactions or defaults, which could be useful for an agent deciding how to invoke the tool. A slightly richer description could mention that omitting root uses the current directory and that several flags control tree and skill inclusion.

  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?

  All 8 parameters are fully described in the input schema (100% coverage), and the description adds no parameter-specific meaning beyond that. The description simply names the operation; the schema already explains each parameter's purpose, defaults, and constraints. Baseline 3 applies because the schema carries the full semantic load.

  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 ('Open') and a precise resource ('a local project directory as a CodexPro workspace'), and lists the exact return content (workspace_id, git status, AGENTS.md, skills, compact file tree). This clearly distinguishes it from the sibling open_current_workspace, which targets the current directory rather than a specified path.

  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 explicitly state when to use this tool versus alternatives. While the sibling open_current_workspace suggests a complementary use case, the description provides no direct comparison, conditions, or when-not-to-use guidance. The intent is only implied by 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.

• codexpro_self_testA
  3.7/5.0
  Behavior4/5

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

  The description discloses key behavioral traits: it is local-only, does not touch source files, and can write/edit a single .ai-bridge file. It also mentions in-memory operations (Pro context bundle) without side effects. Annotations are all false, so the description carries the burden; it covers safety and side-effect boundaries well, though it omits exact return format 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 efficient sentence, front-loaded with the core verb and scope. It lists numerous checks without excessive detail, and every listed item adds informational value. Minor verbosity in the enumeration is acceptable given the tool's broad scope.

  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 description explains what the tool does but fails to mention what the tool returns — no output schema exists, so the description should hint at result format or interpretation. An agent has no guidance on how the diagnostic output is presented (e.g., JSON, plain text, exit codes) or how to handle failures. This is a notable gap for a diagnostic 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?

  Schema coverage is 100% — every parameter has a description in the schema. The tool description does not add significant parameter-specific meaning beyond what the schema already provides. It references the `.ai-bridge` write/edit generally, but that maps to the `write_probe` parameter which is already described. 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 tool runs a controlled, local-only diagnostic and enumerates the specific checks it performs (modes, tools, workspace, skills, git, bash policy, Pro context). This distinguishes it from siblings like read, bash, or open_workspace by presenting it as a comprehensive self-test rather than a single operation.

  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?

  Usage context is implied: it is a diagnostic to verify environment capabilities. The description notes it avoids source files but does not explicitly state when to use it versus alternatives, nor does it provide exclusions or conditions. Some guidance is present, but it is not explicit about when an agent should invoke this over other tools.

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

• searchA
  3.8/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 the 'targeted verification' nuance, implying a read-only investigative use case, but it does not disclose return format, performance characteristics, or any other behavioral details. With annotations covering safety, the added context is modest.

  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 with no filler. The primary purpose is front-loaded, followed by a direct usage preference. Every word earns its place, making it highly efficient and scannable for an agent.

  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 search tool with 7 well-documented parameters and no output schema, the description adequately covers usage context. It explains the scenario (verification) and an efficiency guideline. While it doesn't describe what the tool searches (files) explicitly, the title and schema imply it, and the description is sufficient for correct invocation.

  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 parameters (query, glob, path, regex, max_results, workspace_id, include_hidden) are already documented. The description does not add parameter-specific meaning beyond what the schema provides. Baseline 3 is appropriate when schema carries the full parameter documentation.

  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 purpose—'targeted verification or code lookup'—which indicates the tool searches for information. The title 'Search Files' reinforces the resource. However, it does not explicitly say 'searches files for text or regex,' leaving some implicit. It distinguishes itself from siblings by focusing on targeted searches.

  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 explicitly says when to use it ('targeted verification or code lookup') and provides a strong preference ('Prefer one specific final search instead of repeated broad verification searches'). It does not mention when not to use it or name alternatives, but the guidance is clear and actionable.

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

• treeA
  3.8/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 clear. The description adds the behavioral detail that blocked paths are excluded, which is useful. However, it does not mention output format, pagination, or limits, but these are partially covered by parameter descriptions. This is adequate given the 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 primary action ('List files and directories') and adds a meaningful qualifier ('excluding blocked paths'). There is no wasted text; every word 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?

  For a simple read-only listing tool with full schema coverage and annotations that specify safety, the description is sufficient. It states the scope and the key constraint. The absence of an output schema is not a concern because the tool's output is obvious from its purpose, and the description already clarifies the scope.

  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 100% coverage of parameter descriptions (each parameter has a description), so the baseline is 3. The tool description itself does not add any parameter-specific meaning beyond what the schema already documents. There is no need for compensation since coverage is high.

  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 ('List') and a clear resource ('files and directories inside the workspace'), and adds the constraint 'excluding blocked paths.' This clearly distinguishes it from siblings like 'read' and 'search' by defining its own scope and purpose.

  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 stating what it does, but does not explicitly specify when to use it over alternatives such as 'search' or 'read.' There is no mention of scenarios where it would be preferable or when not to use it, leaving the agent to infer from the tool name and description.

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

• export_pro_contextA
  4/5.0
  Behavior3/5

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

  Annotations cover read-only/destructive safety (both false), so the description does not need to repeat that. It adds useful context by listing the bundle's components (repo tree, git state, selected files, handoff context), which goes beyond annotations. However, it does not disclose potential overwrite behavior if the file already exists, nor mention any I/O side effects beyond file creation, leaving a minor transparency gap.

  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 that fronts the action and purpose. It has zero waste and directly communicates the tool's function without tangential details.

  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 12 parameters and no output schema, the description succinctly covers the overall purpose, the file's contents, and the intended use case (offline ChatGPT planning). It does not explain return values or failure modes, but those are less critical for a file-generation tool. The mention of 'without live MCP tool calls' provides key context for selection. Overall, it is sufficiently complete for an agent to 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?

  Schema description coverage is 100%, so all 12 parameters are documented in the schema. The description does not add semantic detail beyond what the schema already provides (e.g., it mentions 'selected files' but that maps directly to selected_paths). With full schema coverage, 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 states a specific verb ('Create'), a specific resource ('.ai-bridge/pro-context.md'), and enumerates the contents (repo tree, git state, selected files, handoff context). It clearly distinguishes itself from generic write tools by focusing on the pro-context bundle for ChatGPT planning.

  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 explicitly frames when to use it: 'for high-context ChatGPT planning without live MCP tool calls.' This gives a clear use case and implies when it's appropriate (when you need offline context). It does not name specific alternatives or exclusions, but the context is strong enough to guide an agent.

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

• readA
  4.1/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, covering the safety profile. The description adds the 'line numbers' output detail and the 'avoid rereading' advice, which provides some context beyond the annotations. However, it does not disclose operational behavior such as pagination, handling of large files, or workspace-specific constraints. With annotations present, the description's additional context is useful but not rich, so 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 two sentences with zero filler. The core purpose ('Read a specific text file with line numbers') is front-loaded, and the usage guideline follows immediately. Every word adds value, making it an ideal length for an agent to parse quickly.

  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?

  Despite having no output schema, the description is complete for a tool of this simplicity. It covers the essential action (read a file), the output feature (line numbers), and a key efficiency guideline. The schema covers parameter details, and annotations cover safety. There is nothing an agent needs to know to invoke this correctly that is missing, especially given the presence of rich sibling context (e.g., read_handoff) which the description implicitly avoids.

  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 five parameters (path, start_line, end_line, max_bytes, workspace_id) are already documented in the schema. The description does not add any further parameter-level semantics, such as edge cases, default behaviors, or relationships between parameters. Baseline 3 is thus correct when the schema carries the full parameter documentation.

  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 ('Read') and resource ('a specific text file') with an explicit output feature ('with line numbers'). This distinguishes it from sibling tools like search, write, and edit without needing to open the schema. The wording 'specific text file' implies it is not for listing or searching contents, making its purpose unmistakable.

  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 an explicit when-not-to-use guideline: 'Avoid rereading files after write/edit unless exact final content is needed.' This gives the agent clear conditional logic for when to skip calling read. However, it does not explicitly name alternative tools (e.g., search, tree) or state when to prefer them, so it misses the full 'alternatives' part of the highest bar.

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

• read_handoffA
  4.1/5.0
  Behavior4/5

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

  Annotations (readOnlyHint, destructiveHint) already disclose that this is a safe read operation. The description adds context about the file type and coordination purpose, which is useful. However, it doesn't disclose the return format or error behavior, but with annotations covering the safety profile, this is acceptable.

  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, clear sentence that front-loads the key action and resource. There is no redundant wording or filler, making it concise and easily parseable.

  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?

  Since there is no output schema, the description should clarify what the agent receives when the tool succeeds. It doesn't mention return format, possible errors, or what happens if files are missing. The parameter is optional and uses a default, which is covered in the schema, but the read operation's output is left ambiguous. This is a moderate gap for a tool with no output schema.

  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 covers 100% of parameters with a description ('Workspace id from open_workspace. Omit to use default workspace.'), so the tool description adds no additional semantic weight. Baseline 3 is appropriate because the schema already documents the parameter well.

  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 ('read') and names a distinct resource ('.ai-bridge planning files'), while adding the purpose ('ChatGPT-to-agent coordination'). This clearly differentiates it from the generic 'read' sibling tool by specifying the exact file type and 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 conveys when to use the tool—when reading shared coordination files—but does not explicitly mention alternatives or when not to use it. The context is clear enough for an agent to infer its intended use, though it lacks explicit exclusions.

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

• server_configA
  4.1/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and destructiveHint=false, so the safe read-only nature is known. The description adds concrete behavioral detail: it lists what is shown (safety modes, limits, blocked paths) and explicitly states 'Does not reveal auth tokens,' which supplements the annotations with useful security context.

  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, crisp sentence that front-loads the primary action and resource. It lists the key content categories and the one exclusion, with no filler or 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 zero-parameter, read-only tool with annotations covering its safety profile and no output schema, the description provides all necessary context: what it shows, what it omits, and that it is a non-destructive lookup. An agent can invoke it correctly without further information.

  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 the schema coverage is effectively complete (100% of 0 parameters are described). Per the rubric, a 0-parameter tool gets a baseline of 4. The description does not discuss parameters, but none exist, so no additional clarification 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 states a specific verb ('Show') and resource ('CodexPro server configuration'), and enumerates the content (safety modes, limits, blocked paths). It also clarifies what is intentionally excluded (auth tokens), which makes the tool's scope unmistakable and distinguishes it from generic read tools.

  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 explicit guidance is given about when to use this tool versus siblings such as `read`, `search`, or `server_config` itself. Context implies it is for configuration lookup, but no alternatives or exclusions are mentioned. The description provides no usage context beyond its own purpose.

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

• handoff_to_agentA
  4.2/5.0
  Behavior4/5

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

  Annotations already establish it's a write operation (readOnlyHint=false), but the description adds valuable context: it only creates handoff files and does not execute local agent commands. This is a key behavioral clarification beyond what annotations provide, preventing an agent from expecting side effects like running commands. It does not 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?

  Two sentences, zero fluff. The first sentence states the core action and target, the second clarifies the scope limitation (no command execution). Information is front-loaded and every word earns its place. Excellent conciseness.

  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 7 parameters (1 required) and no output schema, but it's a straightforward write operation. The description covers the purpose, target file, and a critical limitation. It doesn't explain the return value or error behavior, but for a file-creation tool this is typically obvious and not essential. One could argue it might mention that the plan should be comprehensive since the local agent will read it, but that's a minor omission.

  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 input schema fully documents all 7 parameters. The tool description adds no additional parameter-specific guidance. Baseline of 3 is appropriate because the schema carries the semantic weight; the description doesn't enhance or clarify parameters beyond what is already structured.

  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 ('Write'), a concrete resource ('.ai-bridge/current-plan.md'), and the intended audience (local agents like Codex, OpenCode, Pi). It clearly distinguishes this from generic write/edit tools by specifying the file and purpose, and even clarifies it does not execute commands. This leaves no ambiguity about the tool's function.

  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 context is clear: use this to create a handoff plan for a local agent. It implies the primary use case without explicitly naming alternatives or exclusions. While it doesn't say 'use this instead of write when creating a handoff file,' the purpose is distinct enough that an agent can infer when to call it. A missing explicit 'when not to use' keeps it at 4 rather than 5.

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

• load_skillA
  4.2/5.0
  Behavior4/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 valuable context: the tool returns a 'bounded' body (not the full file), and it only works with discovered skills, not arbitrary paths. This clarifies what happens beyond the annotation's implied read-only nature. No contradiction detected.

  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 filler. The core purpose is stated first, followed by the key usage prerequisite. Every word contributes value.

  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 6 parameters (only 1 required), the description covers the primary usage context (after opening workspace, referencing inventory) and the key constraint (no arbitrary paths). Since the output is simply the SKILL.md content, no output schema is needed. The only minor gap is not explicitly stating that the return value is the raw SKILL.md text, but it's implied by the name and context.

  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 every parameter is already documented in the schema (e.g., 'name', 'path', 'source', 'max_bytes'). The description does not add additional parameter-specific meaning beyond the general usage note that it operates on inventory. 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 ('load'), the resource ('bounded SKILL.md body'), and the scope ('discovered workspace, user, or plugin skill by name'). It explicitly contrasts with arbitrary path access and references the discovery flow (open_current_workspace/open_workspace + skill_inventory), effectively distinguishing it from sibling tools like 'read' and 'search'.

  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 a clear when-to-use instruction: 'use after open_current_workspace/open_workspace shows skill_inventory.' It also states a constraint ('Does not accept arbitrary paths'), implying the proper flow. However, it doesn't explicitly name which sibling tools are alternatives or when not to use it beyond the path restriction, so it's not a full 5.

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

• open_current_workspaceA
  4.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 clear. The description adds that it targets the 'configured default workspace' without a path, but does not cover return behavior or side effects. Given annotation coverage, the description carries sufficient but not extra-rich behavioral context.

  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 with zero wasted words. The critical usage direction is front-loaded, and the sibling exclusion is clearly stated. Very efficient.

  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?

  Complete for a simple, parameterless-required tool with annotations covering safety and schema covering all optional parameters. The description covers usage timing and sibling differentiation. A minor gap is that 'configured default workspace' is not elaborated, but that is not essential for correct invocation.

  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?

  All four parameters have schema descriptions (100% coverage), so the description does not need to explain them. The baseline of 3 applies because the schema fully documents parameters; the description adds no additional parameter context, which is acceptable.

  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 the specific action (open the configured default workspace) and explicitly distinguishes it from the sibling `open_workspace` by noting it does not accept a path. This makes the purpose unmistakable.

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

  Usage Guidelines5/5

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

  It provides explicit timing ('once at the start') and an exclusion ('Do not call open_workspace after this unless switching roots'), directly guiding the agent on when and when not to use it relative to an alternative.

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

• show_changesA
  4.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 agent knows this is a safe read operation. The description adds behavioral context by specifying that it combines git status and diff stats with an optional diff, and that it's 'review-oriented.' However, it doesn't disclose potential edge cases (e.g., empty workspace, invalid path) or any authentication nuances. Given the annotations cover the safety profile, 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?

  Two sentences with no fluff. The first sentence states the purpose and content of the result, and the second gives direct usage guidance. The key information is front-loaded, making it easy for an agent to parse quickly.

  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 explains what the tool returns and when to use it. The schema covers all parameter semantics. It does not mention behavior for edge cases like no changes or when the workspace is not open, but those are minor gaps given the tool's simplicity and the annotations. Overall, it's complete enough for an agent to call 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% for all four parameters, each with a clear description (path, staged, include_diff, workspace_id). The tool description adds no parameter-specific meaning beyond what the schema already provides, so the baseline of 3 applies.

  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 (summarize) and resource (current workspace changes) with explicit details on what the result contains: git status, diff stats, and optional diff. It also differentiates from alternatives like bash git status and git_diff by naming them.

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

  Usage Guidelines5/5

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

  It explicitly says 'Use this instead of bash git status, bash git diff, git_status, or git_diff when reviewing work.' This gives clear when-to-use guidance and names the alternatives to avoid, leaving no room for ambiguity.

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

• bashA
  4.5/5.0
  Behavior4/5

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

  Annotations already declare destructiveHint=true, readOnlyHint=false, openWorldHint=true, and idempotentHint=false. The description adds useful behavioral constraints beyond annotations: it restricts to a single allowlisted command and bans command chaining. It does not explicitly mention that commands may modify the workspace, but the destructiveHint annotation already covers that, so the description adds value without 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 three sentences, each earning its place. The first sentence states the core purpose, the second gives exclusions with alternatives, and the third imposes a critical safety constraint. It is front-loaded with the primary action and uses no filler or redundant phrasing.

  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 command execution tool with no output schema, this description is complete. It tells the agent what can be run, what cannot, names alternatives, and sets boundaries on command composition. The workspace context is implied via open_workspace and cwd parameters. An agent can call this tool correctly without further information.

  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 four parameters are already documented with clear descriptions (command, cwd, timeout_ms, workspace_id). The description provides example command types (tests, build, lint) but does not add meaning beyond the schema's 'Command to run.' The schema carries the burden, so a 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 states a specific verb ('Run') and resource ('allowlisted verification command'), and explicitly distinguishes from siblings by naming alternatives for other operations. It is clear that this tool is for executing verification commands like tests, build, lint, typecheck, or project scripts, not for general file operations or git inspection.

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

  Usage Guidelines5/5

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

  The description explicitly states when to use the tool (verification commands), gives concrete examples, and provides direct exclusions with named alternatives ('use show_changes, tree, search, and read instead'). It also prohibits chaining commands with &&, pipes, redirects, or shell file readers, which is a precise usage constraint.

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