Server Quality Checklist

Tool Scores

• docgraph_tagsB
  3.2/5.0
  Behavior1/5

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

  The description describes read-only operations (list, find), yet the annotations set destructiveHint=true, indicating potential mutation. This contradiction is not addressed in the description, and no additional behavioral context is provided to explain the discrepancy.

  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?

  Single sentence efficiently captures both behaviors. No extraneous words, and the primary action (listing) is front-loaded.

  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 mentions document counts but does not specify the output format or address the destructive hypothesis from annotations. Given the lack of an output schema and the presence of a contradictory annotation, contextual completeness is insufficient for safe and correct tool 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?

  With 100% schema description coverage, the description does not add meaningful guidance beyond what the schema already provides. The description restates the schema's filtering behavior without further detail.

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

  Purpose5/5

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

  The description clearly states the tool's function: listing all tags with counts or finding documents by a specific tag. It uses specific verb-resource phrasing and distinguishes itself from sibling tools like docgraph_search or docgraph_status.

  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 when to use (when tag information is needed) but does not provide explicit guidance on when not to use or how it differs from alternatives. The sibling tools are not referenced for comparison, leaving the agent to infer distinctions.

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

• docgraph_filesB
  3.4/5.0
  Behavior1/5

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

  The description states 'List all indexed files' implying a read-only operation, but annotations declare destructiveHint: true. This creates a direct contradiction about whether the tool modifies state. The description does not resolve this or add any other behavioral traits beyond the conflicting annotation. Hence, it fails to provide accurate transparency.

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

  Conciseness5/5

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

  The description is two sentences, front-loaded with the core purpose ('List all indexed files'), followed by usage advice and alternative suggestions. Every sentence adds value with no redundancy or fluff. Highly 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 3 optional parameters and no output schema, the description covers usage context well but omits details about the output format, pagination, or default behavior for omitted parameters. The contradiction with annotations further undermines completeness. Score is average given these gaps.

  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 input schema already describes all three parameters with 100% coverage. The description adds practical context: for 'path' it clarifies 'bare directory name' and gives an example; for 'project' it explains workspace mode behavior and no-op in single-store mode. This goes beyond the schema's descriptions, earning a 4.

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

  Purpose4/5

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

  The description clearly states the tool lists all indexed files with specific extensions (.md, .docx, .html, .pdf). It also mentions filtering by path, which adds specificity. However, it does not differentiate from many siblings like docgraph_context or docgraph_graph, relying on a single sibling comparison (docgraph_node). This prevents a top score.

  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 advises using the path filter to narrow scope and directs users to docgraph_node for a single known document. This provides clear guidance for a common use case. However, no guidance is given for other scenarios or when to avoid this tool entirely, which would be needed for a 5.

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

• docgraph_graphA
  3.6/5.0
  Behavior3/5

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

  The description adds useful nuance for the trace operation (one-directional, ignores similarity/tag edges, 'no path' ≠ 'unrelated'), but fails to address the destructiveHint=true annotation, which implies side effects not mentioned. Annotations provide readonly/destructive flags, but the description does not clarify the destructive nature.

  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 paragraph with a clear bullet-like list. Every sentence serves a purpose, no redundancy, and it efficiently conveys the core functionality.

  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 6 parameters and no output schema, the description does not mention what the tool returns (documents, paths, counts?), nor does it explain the destructive side effects indicated by annotations. Critical information about output format and behavioral implications is missing.

  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% with parameter descriptions already present. The tool description does not add new information beyond what the schema provides; it merely restates the operation context. Baseline 3 applies due to high 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 is a document graph traversal facade and lists four specific operations (incoming, outgoing, impact, trace) with concise explanations, distinguishing it from sibling tools like docgraph_search or docgraph_similar.

  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?

  Each operation is described with when to use it (e.g., 'incoming — documents that cite/reference this document'), but there is no explicit guidance on when not to use this tool or alternatives among the many sibling tools. The context is implied rather than explicit.

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

• docgraph_historyA
  3.6/5.0
  Behavior1/5

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

  The description contradicts the annotations: it states a read-only 'show' operation, but annotations have destructiveHint: true and readOnlyHint: false. This is a clear contradiction, forcing the score to 1 per rules.

  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 that front-loads the purpose and includes key details. Every part is necessary and well-structured.

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

  Completeness4/5

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

  For a simple tool with one parameter and no output schema, the description covers what is returned (commits count, authors, dates, message) and edge cases (empty for untracked). It is mostly complete, though lacks info on output format or ordering.

  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 single parameter 'document' is described in the input schema with 'Document name or path', achieving 100% schema coverage. The description adds no further semantic detail about the parameter, meeting the baseline but not exceeding it.

  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 shows git commit history for a document, listing specific details like number of amendments, authors, dates, and last commit message. This distinguishes it from sibling tools like docgraph_status or docgraph_context, which handle other aspects.

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

  Usage Guidelines4/5

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

  The description provides clear context for when to use the tool (to see history) and includes a condition for empty results (files not tracked by git). However, it does not explicitly mention when not to use it or suggest alternative tools, which could be helpful given the sibling list.

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

• docgraph_exploreA
  3.7/5.0
  Behavior1/5

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

  The description uses 'survey' implying a read-only operation, but annotations set destructiveHint=true, indicating destructive behavior. This is a direct 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?

  Three sentences that are front-loaded with purpose, then efficiency, then guidelines. No wasted words.

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

  Completeness3/5

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

  While purpose and guidelines are clear, the description lacks context about the destructive behavior and does not hint at the response format (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?

  Schema description coverage is 100%, so baseline is 3. The description does not add additional meaning beyond the schema's parameter descriptions.

  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 surveys several related documents and cross-references, and distinguishes it from siblings docgraph_node and docgraph_context.

  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?

  Explicitly says when to use (multiple documents) and when not to (single doc: use docgraph_node; governance/context: use docgraph_context).

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

• docgraph_nodeA
  3.8/5.0
  Behavior1/5

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

  Description says 'Get' (read-only) but annotations have destructiveHint: true, indicating mutation. This is a severe contradiction; no side effects or behavioral traits disclosed.

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

  Conciseness5/5

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

  Two sentences, no wasted words, front-loaded with purpose and usage guidance.

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

  Completeness2/5

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

  Despite strong parameter details, missing behavioral context (destructive nature due to annotation contradiction) and no output schema described, leaving significant gap for an agent.

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

  Parameters4/5

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

  Schema covers 100% of parameter descriptions. Description adds value with examples for 'section' (heading text or anchor slug) and cleaning instructions for 'document' (strip suffixes).

  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 clearly states verb 'Get' and resource 'single document or heading's full details', and distinguishes from sibling docgraph_explore for multiple documents.

  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?

  Explicitly says when to use (single doc/heading) and when not (multiple docs: use docgraph_explore), and explains the 'section' parameter for full content.

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

• docgraph_statusA
  4/5.0
  Behavior1/5

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

  Annotations declare destructiveHint=true, but the description describes a read-only health check with no mention of destructive actions. This is a clear contradiction, severely undermining transparency.

  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 well-structured sentences that front-load the primary purpose and add secondary use cases without redundancy.

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

  Completeness5/5

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

  Given no parameters, no output schema, and a rich set of sibling tools, the description covers the tool's output, usage scenarios, and important clarifications (e.g., metadata score deductions) completely.

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

  Parameters5/5

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

  With zero parameters and 100% schema coverage, the description adds significant meaning by enumerating the health metrics and metadata quality scores returned, which the schema cannot 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 clearly states it reports index health metrics (file count, node count, edge count, etc.) and additional state details, which is specific and distinguishes it from sibling tools like docgraph_context or docgraph_graph.

  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?

  Explicit guidance is given: 'Use to verify the index is ready before other operations, or to inspect embedding model state, LLM callout tool state... domain packs, and drift findings.' It provides clear context but does not mention when not to use or alternatives.

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

• docgraph_contextA
  4.1/5.0
  Behavior4/5

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

  Annotations already indicate destructiveHint=true and openWorldHint=true. The description adds behavioral context by warning about potential large responses and suggesting parameter adjustments (includeContent, maxContentBytes) to manage output size. 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?

  The description is concise with two sentences. The first sentence clearly states the primary purpose. The second sentence provides essential usage guidance and a warning about response sizes. No redundant information.

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

  Completeness3/5

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

  Given the tool's complexity (17 parameters, no output schema), the description provides a high-level overview but lacks detail on governance-awareness, cross-references, and output formats (covered in the schema but not reiterated). Some gaps remain for fully informing the agent.

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

  Parameters3/5

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

  Schema coverage is 100%, so all parameters have descriptions. The tool description adds limited new parameter information beyond the schema, only implicitly referencing includeContent and maxContentBytes in the size warning. Baseline is 3 for high 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 explicitly states 'PRIMARY TOOL. Build relevant documentation context for a task or topic.' It uses a specific verb ('build') and resource ('documentation context'), and distinguishes itself from the sibling tool docgraph_node by advising to use that for a single known document.

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

  Usage Guidelines4/5

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

  The description gives clear guidance on when to use an alternative ('For a single known document, use docgraph_node instead') and provides advice on configuring parameters to avoid large responses. However, it does not explicitly exclude other sibling tools or mention when not to use this tool beyond that specific case.

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

• docgraph_searchA
  4.1/5.0
  Behavior2/5

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

  Annotations indicate destructiveHint=true and idempotentHint=false, which are unusual for a search tool, but the description does not address these traits. The description focuses on result path handling but omits behavioral side effects.

  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?

  Description is a single paragraph that front-loads the core purpose and provides essential details in a compact form. A bit dense but no wasted sentences.

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

  Completeness4/5

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

  Given 16 parameters and no output schema, the description covers search function, sibling differentiation, filters, and result handling. Lacks explanation of destructive behavior, but otherwise adequate for the complexity.

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

  Parameters4/5

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

  Schema coverage is 100%, but description adds value by explaining filter usage and result path format (suffix stripping, parent document path). This helps agents use parameters correctly beyond the schema.

  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?

  Clearly states it performs full-text search across indexed Markdown documents and returns matching documents with headings and snippets. Differentiates from sibling docgraph_context by specifying it combines search with structure.

  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?

  Explicitly advises when to use this tool vs docgraph_context, and instructs to use governance and research filters. Also provides specific guidance on stripping path suffixes for downstream tools.

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

• docgraph_similarA
  4.4/5.0
  Behavior3/5

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

  The description is very transparent about limitations (no per-term breakdown, scores are corpus-relative, 0 results meaning). However, annotations indicate destructiveHint=true, implying the tool might modify state, but the description suggests a purely read-only operation (find similar documents). This contradiction reduces the score.

  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?

  Description is long but efficiently packed with necessary details. Front-loaded with main purpose, then edge cases and caveats. Minor redundancy (e.g., repeated '0 does NOT mean'), but every sentence 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?

  Given the complexity (multiple engines, scoring formula, edge cases like 0 results), the description is thorough. Explains weighted blend, what results contain, and limitations. No output schema, but the description covers return format sufficiently.

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

  Parameters4/5

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

  Schema coverage is 100% with descriptions, but the description adds significant value: explains engine defaults (auto/tfidf always on, no flags), document path restrictions, limit default, and project scope behavior. Exceeds baseline.

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

  Purpose5/5

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

  Clearly states it finds topically similar documents using TF-IDF, shared references, and tag overlap. Distinguishes from sibling tools like docgraph_graph for explicit link tracking and mentions docgraph_embeddings for neural similarity. Specific verb and resource, no ambiguity.

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

  Usage Guidelines5/5

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

  Explicitly tells when to use alternatives (e.g., docgraph_graph for explicit link tracking). Warns that heading anchors return empty, explains 0 results do not indicate engine failure, and advises checking docgraph_status for neural availability. Comprehensive guidance.

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