Server Quality Checklist

Tool Scores

• module_graphC
  2.7/5.0
  Behavior2/5

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

  No annotations are provided, so the description carries full burden. It is silent about whether this operation is read-only, whether it can be expensive or require specific permissions. For a graph resolution tool, it would be helpful to mention that it may traverse large graphs or require workspace indexing.

  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, clear sentence that is concise and gets to the point. It could be slightly more structured by mentioning parameters, but as is, it is adequately sized and not verbose.

  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?

  With no output schema, no annotations, and no parameter detail, the description is insufficient for a complex graph-resolution tool. The agent cannot predict what the response contains, nor does it understand the impact of the 'transitive' flag. It needs more detail on the structure of the resolved graph and any potential side effects.

  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. It does not mention the 'name' parameter meaning or how 'transitive' affects the resolution. Users have to infer from the schema that 'name' is required and 'transitive' defaults to false, but the description adds no additional meaning.

  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 'Resolve' and specific resource 'module' and lists the outputs: interface units, imports, dependencies, and importing translation units. It clearly distinguishes from sibling tools like module_search and module_quality, which likely search or analyze modules rather than resolve their graph.

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

  Usage Guidelines2/5

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

  No guidance on when to use this tool vs alternatives. Sibling tools like module_search, module_quality, references, definitions might overlap in purpose, but the description does not clarify when to choose this tool over them. It does not mention any preconditions or consequences.

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

• referencesB
  3/5.0
  Behavior2/5

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

  With no annotations present, the description carries the full burden of behavioral disclosure but reveals little beyond the core function. The term 'indexed' hints that results depend on a pre-built index, which is useful context, but there's no mention of failure modes, permission needs, or index freshness. This is a modest but insufficient contribution given the absent 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?

  A single 16-word sentence that front-loads the verb and object, adds a valuable scope qualifier, and contains zero filler. This is exemplary conciseness—every word earns its place.

  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 6-parameter tool with no output schema and no annotations, a 16-word description is insufficient. It doesn't clarify the 'occurrence' parameter's role (which is non-obvious for a reference finder), the default behaviors, or what the response shape looks like. Given the complexity, this is under-specified.

  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 sits at 50%—three of six parameters (file, occurrence, includeDeclaration) lack inline descriptions, and the tool description offers zero parameter clarification. The rubric's baseline of 3 for >80% coverage doesn't apply here; with half the params undocumented, the description should compensate but doesn't.

  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 provides a specific verb ('Find') and resource ('indexed references to a declaration') with a meaningful scope qualifier ('across module units and translation units'). This differentiates it from siblings like 'definition' by implying cross-module reach, though it doesn't name an alternative tool explicitly as the top-tier examples do.

  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 is implied through the description's framing—an agent would know to use this when cross-unit references are needed—but there's no explicit when-to-use guidance, no exclusions, and no mention of prerequisites (e.g., an index needing to be built). This meets the 'implied usage' bar at exactly 3.

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

• workspace_symbolsB
  3/5.0
  Behavior2/5

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

  No annotations are provided, so the description alone must carry transparency. It only states the search action and combined scope, without mentioning result shape, grouping, pagination, read-only behavior, or workspace-scoping constraints, which an agent would need.

  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 front-loaded sentence with no filler or redundant restatement of the tool name. It could say more about behavior, but as a concise lead it earns its place.

  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 is structurally simple (one required parameter, no output schema), so the required context is small. Still, with no annotations and no return-value information, an agent cannot tell what a successful search returns or how modules are represented in results.

  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 schema has only a bare 'query' string at 0% description coverage; the tool description implies query is the search text for symbols/modules but adds no syntax, matching semantics, empty-query behavior, or examples. This does not compensate for the schema's silence.

  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 ('Search') and names concrete resources ('clangd symbols and named C++ modules'), plus the 'in one request' qualifier distinguishes it from separate module/symbol search siblings. It does not elaborate on what counts as a symbol, but the core purpose is unambiguous.

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

  Usage Guidelines3/5

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

  'In one request' hints that this tool is for combined symbol-and-module searches rather than using separate siblings, but it gives no explicit when-to-use/alternatives guidance. There are no exclusions or named fallback tools such as module_search.

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

• diagnosticsB
  3.2/5.0
  Behavior3/5

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

  No annotations are provided, so the description must carry the transparency burden. It reveals that module resolution happens before returning diagnostics, which is a useful process detail. However, it does not disclose potential side effects, error behavior, or whether the operation is read-only, leaving part of the behavioral contract implicit.

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

  Conciseness5/5

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

  The description is a single, concise sentence with no redundant words. It front-loads the core action ('Parse a file') and includes the key qualifier 'after module resolution' without digressing. Every word contributes to the meaning.

  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 tool with one parameter and no output schema, the description covers the essential behavior and a key context point (module resolution). It does not elaborate on return format, but since no output schema exists, this is not required. The description is sufficient for an agent to understand the tool's primary function.

  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 schema has only a 'file' string with no description, and the description does not clarify whether 'file' refers to a path, content, or identifier. With schema coverage at 0%, the description needed to explain the parameter's semantics but only says 'a file', which adds little beyond the schema itself.

  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 specific verbs and nouns: 'Parse a file', 'return clangd diagnostics', 'after module resolution'. It clearly conveys the tool's purpose and is distinct from siblings like 'document_symbols' or 'ast', though it does not explicitly differentiate itself. The inclusion of 'clangd' and 'module resolution' adds specificity beyond a generic statement.

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

  Usage Guidelines2/5

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

  There is no guidance on when to use this tool versus alternatives. It does not mention prerequisites, typical use cases, or when not to use it. The description is purely functional with no contextual or decision-making support for an agent.

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

• definitionB
  3.3/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the full burden. It explains position indexing (1-based) and suggests the needle parameter, but it does not describe return values, failure behavior, or path/workspace expectations.

  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 short, front-loaded, and contains no filler. Every sentence contributes either to purpose or to usage guidance, though a bit more context would not hurt.

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

  Completeness2/5

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

  For a tool with 6 parameters, no annotations, and no output schema, this description is too thin. It does not explain how file paths are resolved, why one might use line/character vs needle plus occurrence, or what the result contains, making full reliable invocation not fully supported.

  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 description adds some value by advising that needle is often easier for agents and noting that positions are 1-based, but the schema already covers 1-based line and character semantics. Several parameters such as occurrence and includeHover are still not semantically clarified enough for an agent to choose confidently.

  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 ('Find') and identifies the resource ('a declaration/definition across module BMIs'). It clearly separates this tool from references or document_symbols, though 'BMIs' is domain-specific and not fully explained.

  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 tool's general purpose is clear, and it gives a practical hint that needle is often easier for agents. However, it does not explicitly state when to prefer this tool over sibling tools such as references or workspace_symbols, and it provides no exclusionary criteria.

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

• document_symbolsB
  3.3/5.0
  Behavior3/5

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

  With no annotations, the description carries the behavioral burden. It discloses that the result comes from clangd's hierarchical symbol view and the operation is a read-only list, but it does not mention prerequisites such as an open/indexed file or what happens for unparseable inputs.

  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, front-loaded sentence with no filler or repetition. Every phrase adds useful information: action, scope, and method.

  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 one-parameter, no-output-schema tool, this is minimally viable: it states what is returned (declarations) and the hierarchical organization. But without annotations or an output schema, it leaves gaps around return shape details and any practical constraints (e.g., requiring clangd to be ready).

  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 coverage is 0%, so the description must clarify the 'file' parameter. It adds that the file is a C++ source or module unit, but it does not specify path format, accepted extensions, or URI/absolute-path expectations, leaving much of the parameter semantics 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 names a specific action ('List declarations') and resource ('C++ source or module unit'), and clarifies the method ('clangd's hierarchical symbol view'). It is clear enough to distinguish from workspace_symbols by scope, though it does not explicitly reference siblings.

  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 intended use is implied: call it when you need declarations from a single C++ source/module unit rather than workspace-wide search. However, it provides no explicit when-to-use/when-not-to-use guidance or alternative tool names.

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

• workspace_refreshB
  3.4/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden and does well: it discloses reloading, rebuilding, restarting clangd, and preserving unchanged cache files. It could mention potential disruption to open sessions, but the core side effects are clearly stated.

  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 dense sentence with no filler. The 'rebuilt' phrasing is slightly awkward, but the sentence conveys multiple key behaviors efficiently.

  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 description is adequate for a single-action tool but leaves gaps: no usage guidance, no parameter explanation, and no indication of return or failure behavior. Given the simple schema, it is minimally viable rather than 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?

  Schema description coverage is 0% and the description does not mention the optional 'reason' parameter. The schema only provides a type and default, so the description adds no semantic value beyond the schema for this parameter.

  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 specific verbs and objects: 'Reload compile commands and rebuilt PCM/modmap artifacts, restarting clangd'. It clearly identifies the tool's primary action and scope, though it does not explicitly differentiate from sibling tools like workspace_warm.

  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 behavior implies use when compile commands or generated artifacts are stale and clangd needs restarting, but there is no explicit guidance on when to prefer this over sibling tools or when not to use it.

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

• astA
  3.5/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the full burden. It discloses that the output includes the AST and synthetic module context, which is useful, but does not detail output format, size limits, performance implications, or error conditions. It adds some transparency but is not comprehensive.

  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, concise sentence that is front-loaded with the core purpose. It has no filler and directly states what the tool returns, though it could be slightly more structured by adding a note about parameter usage.

  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 complexity of returning a detailed AST, the description is somewhat minimal. It mentions synthetic module context, which is helpful, but lacks details on output structure or how range parameters affect the result. With no output schema and no annotations, it does not fully cover the context needed for an agent to use it correctly.

  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 schema has 5 parameters with 0% description coverage, and the description does not explain any parameters. It mentions the file and module context but does not clarify the role of startLine, endLine, startCharacter, or endCharacter beyond their names. The description fails to compensate for the low schema coverage.

  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 clangd's detailed AST and adds synthetic module context for module declarations/imports. It uses a specific verb ('Return') and distinguishes from sibling tools like document_symbols and module_graph, which serve different purposes.

  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 inspecting AST and module context, but does not explicitly state when to use this tool versus alternatives like document_symbols or module_search. There are no exclusions or explicit context provided, so guidance is mostly implied.

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

• module_qualityA
  3.5/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries full burden. It mentions using clangd AST and the analysis nature, but does not disclose side effects, limitations, or return format. The description is not misleading but leaves behavioral details unspecified.

  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, efficient sentence with no redundancy or filler. It clearly front-loads the core action and purpose, making it easy to parse quickly.

  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?

  Given the lack of output schema and annotations, the description should explain what the tool returns and how to invoke it effectively. It only states what it does, not the result format, thresholds usage, or any prerequisites, leaving significant gaps for a complex analysis tool.

  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 coverage is 0% and the description provides no explanation of the four parameters (file, concurrency, minBodyLines, minStatements). Although parameter names hint at meaning, the agent gains no explicit semantic guidance, requiring inference or external knowledge.

  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 'find' and 'verify' on a clear resource: module interfaces matched to .cpp implementations. It clearly distinguishes this from sibling tools like module_search or module_graph, which focus on different aspects.

  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 purpose implies usage for checking module definition-implementation consistency, but it does not explicitly state when to use it over alternatives or any exclusions. The context is inferable but not clearly articulated.

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

• workspace_openA
  3.5/5.0
  Behavior3/5

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

  With no annotations, the description carries the full transparency burden. It usefully discloses the persistent clangd process and module awareness, but it does not explain idempotency, blocking behavior, failure conditions, or what happens if the workspace is already open.

  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 front-loaded sentence with no filler. Every part adds meaning: the action, the target, and the key side effect.

  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 stateful 7-parameter setup command with no annotations or output schema, the description plus schema is adequate but not complete. It lacks lifecycle guidance, prerequisites like compile_commands.json, and verification/return details, yet the core invocation path is clear.

  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 high (86%), so the schema already documents most parameters. The description adds only the general 'module-aware' concept and does not explain parameter tradeoffs beyond what the schema provides; 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?

  Description uses a specific verb/resource pair ('Open a C++ workspace') and adds a distinctive behavioral outcome ('start one persistent module-aware clangd process'), clearly separating it from siblings like workspace_warm or workspace_status.

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

  Usage Guidelines2/5

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

  No guidance is given on when to call this versus alternatives such as workspace_status or workspace_refresh, nor whether it should be called once before other workspace commands. The implied use case is not stated explicitly.

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

• workspace_warmA
  3.8/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the full burden. It accurately discloses that the operation is non-blocking and that status should be polled, which is valuable. However, it does not explain side effects, preconditions (e.g., whether a workspace must be open), or any resource implications, leaving some behavioral aspects opaque.

  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, both essential. The first states the core action, the second gives the follow-up instruction and reassures about availability. No fluff or repetition.

  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 simple tool (no output schema, two optional params), the description covers the core start-and-poll behavior but omits important context: what 'AST warmup' involves, preconditions, the meaning of 'limit', and the exact effect on the workspace. It is adequate but not fully self-sufficient.

  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 does not mention parameters at all. The schema describes 'files' but 'limit' lacks a semantic description, and overall schema coverage is only 50%. The description fails to compensate for the missing limit explanation, leaving its meaning ambiguous beyond the default/max/min constraints.

  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: 'Start non-blocking AST warmup.' It specifies a concrete verb and resource, and the follow-up instruction 'Poll workspace_status' clarifies the intended workflow. This distinguishes it from siblings like workspace_refresh or workspace_open by emphasizing its non-blocking warmup nature.

  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: it is non-blocking, so the agent should use workspace_status to check progress, and other MCP tools remain usable in the meantime. It does not explicitly name alternatives or exclusions, but the 'poll workspace_status' instruction effectively guides when to use this tool and what to do next.

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

• module_searchA
  3.9/5.0
  Behavior3/5

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

  There are no annotations provided, so the description carries the burden. It mentions 'entities clangd does not expose as symbols,' which clarifies its scope. However, it doesn't disclose return behavior, whether it performs a read-only operation, or any side effects. It's a search tool, so it's intuitively non-destructive, but that's not explicit.

  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 one sentence, concise, and front-loads the core action. Every word adds value; no fluff or redundancy.

  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 simplicity of the tool (one parameter, no output schema, no annotations), the description is adequate but not comprehensive. It covers purpose and scope, but lacks details on result formatting, potential empty results, or how this complements the sibling tools. A bit more explanation of what 'entities' means would enhance completeness.

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

  Parameters3/5

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

  The schema has a single parameter 'query' with 0% description coverage in the schema. The description mentions 'Search named...' implying the query parameter is a name pattern. This adds some meaning, but it could be more explicit about format (e.g., exact name vs. substring, wildcards). Baseline is 3 given only one parameter and minimal schema info, slight credit for implying a name-based search.

  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 purpose is clear: it searches named C++ modules and partitions, specifically targeting entities not exposed by clangd's symbol search. The verb 'Search' is concrete, the resource is specified ('C++ modules and partitions'), and it distinguishes itself from sibling tools like `workspace_symbols` and `document_symbols` by including module/partition entities.

  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 a specific use case: when you need to find C++ modules and partitions, which are not covered by standard symbol searches. However, it doesn't explicitly state 'use this instead of workspace_symbols' or provide exclusions, but the distinction is clear enough for an agent to infer when to use it.

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

• formatA
  4/5.0
  Behavior4/5

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

  With no annotations present, the description carries the full burden of disclosing side effects. It clearly states that preview is the default and that apply=true explicitly writes the file and updates clangd, which is critical safety information for an agent deciding whether invocation may mutate state.

  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 deliver the core purpose, the engine, the default mode, and the explicit mutation mode. There is no filler or redundancy, and the most important safety detail is placed in the second sentence.

  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 description covers the key purpose and preview/apply distinction, which is essential for safe invocation. However, it does not explain what the preview output looks like, what happens if the file is not part of the current workspace, or how `tabSize` and `insertSpaces` affect the result, leaving noticeable gaps for a 4-parameter tool with no annotations.

  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 schema has no parameter descriptions and the description only explains the `apply` parameter semantics. `file` is only implied by 'source,' while `tabSize` and `insertSpaces` are not explained at all despite being meaningful formatting controls.

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

  Purpose5/5

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

  The description clearly states a specific action ('Format') applied to a specific resource ('C++/module source') and names the engine ('clangd'). It also distinguishes itself from the sibling workspace, module, and diagnostics tools by identifying the formatting operation.

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

  Usage Guidelines4/5

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

  The description provides clear guidance on default behavior versus opt-in mutation: preview by default, apply=true to write. While it does not explicitly name excluded alternatives, the sibling list contains no competing format tool, so the usage context is reasonably clear.

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

• workspace_statusA
  4.2/5.0
  Behavior3/5

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

  With no annotations, the description carries the burden of behavioral disclosure. The verb 'Return' suggests a read-only operation, but it does not explicitly state that there are no side effects, nor does it describe potential latency or dependencies (e.g., whether it triggers warmup). This is adequate but not thorough.

  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 is front-loaded with the main action ('Return') and lists all output categories. There is zero fluff, and 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?

  The description enumerates what the agent can expect, and given the absence of an output schema, this is necessary. It lacks detailed explanations of domain terms (e.g., 'readiness', 'coverage'), but for a focused status tool in a clangd context, these are likely understood.

  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 the schema trivially covers all (100%). Per rubric, baseline for 0 params is 4, and there is no additional parameter meaning to convey.

  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 explicitly states the tool returns specific status information (clangd readiness, warmup progress, module counts, PCM/modmap coverage, recent errors), which clearly distinguishes it from sibling tools like workspace_open or workspace_refresh. It uses a specific verb (Return) and a concrete resource.

  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 its usage as a status-check tool, and the context (sibling tools being actions rather than queries) makes it clear why an agent would call it. However, it does not explicitly state when not to use it or mention alternative tools for similar purposes.

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