Server Quality Checklist

Tool Scores

• similar_documentsA
  4.1/5.0
  Behavior4/5

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

  With no annotations, the description carries the burden, and it explains the core behavior: embedding-based similarity rather than explicit links, and what kinds of results to expect (near-duplicates, older notes). It does not mention edge cases like missing paths or limit semantics, but the main behavioral trait is clearly 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?

  Three tight sentences front-load the core purpose, then add usage context and a sibling comparison. Every sentence earns its place with no filler.

  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 two-parameter tool with an output schema, this is largely complete: you know what it does, why you would use it, and how it differs from a sibling. The only gap is explicit parameter guidance, which the input schema's defaults partially cover.

  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 refers to a 'given note' but never explicitly describes the required 'path' parameter or how 'limit' affects results; only the schema's minimal titles and default provide any information.

  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 opens with a specific verb and resource: 'Find notes covering similar ground to a given note'. It clearly distinguishes the tool from siblings by stating it uses 'embedding similarity rather than by explicit links', and explicitly contrasts it with entities_in_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?

  It gives concrete scenarios: 'surface related material the wikilinks miss — near-duplicates, or an older note on the same topic'. It names an alternative (entities_in_document) and explains the difference, though it does not discuss when not to use the tool relative to semantic_search.

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

• list_tagsA
  4.3/5.0
  Behavior4/5

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

  With no annotations, the description provides core behavioral information: it lists tags and their document counts, implying a read-only operation. However, it does not disclose the effect of the min_documents parameter or any other behavioral nuances, but for a simple list tool, the main behavior is adequately transparent.

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

  Conciseness5/5

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

  Two sentences, front-loaded with the main action, no redundant information. The structure is clean and efficient, earning a top score for 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 description covers the core purpose and usage context well. The output schema is present, so return values are defined. The main gap is the unexplained min_documents parameter, but overall the description is fairly complete for a simple 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 description coverage is 0%, and the description does not mention the min_documents parameter at all. The parameter's purpose is only inferable from its name, but the description adds no meaning beyond the schema, so the agent lacks clear semantic guidance.

  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 clear verb and resource: "List every tag in the corpus with how many documents use it." It specifically differentiates from the sibling tool documents_by_tag by positioning itself as a vocabulary discovery step, which is evident from the second sentence.

  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 directs when to use the tool: "Use to discover the corpus's own vocabulary before calling documents_by_tag." This gives a clear context and names a specific sibling alternative, fulfilling the requirement for usage guidance.

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

• entities_in_documentA
  4.5/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the transparency burden. It discloses that results include tags, wikilinks, and entities, and importantly notes the conditional dependency: entities appear 'once the semantic pass has run.' This goes beyond the name and schema, though it doesn't mention auth, side effects, or error behavior.

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

  Conciseness5/5

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

  The description is concise: two sentences deliver the core purpose, usage context, and parameter guidance. It is front-loaded with the action and outputs, 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.

  Completeness5/5

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

  Given the output schema exists (so return format is covered), the description provides all necessary context: what to use it for, when to use it, the conditional semantic pass, and path semantics. Sibling tool names further clarify boundaries. The description is complete for this simple, single-parameter tool.

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

  Parameters4/5

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

  The input schema has one parameter with no description (0% schema coverage), so the description compensates by explaining that `path` is 'relative to the knowledge base root' and gives a concrete example ('projects/my-project.md'). This adds meaningful semantic information, though it leaves minor details like extension requirements implied.

  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 with a specific verb: 'Show what a specific note is about' and lists the concrete outputs (tags, wikilinks in/out, entities). It distinguishes itself from siblings by focusing on a known note's neighborhood rather than search or global aggregation.

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

  Usage Guidelines4/5

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

  The description gives explicit guidance: 'Use when you already know which note you care about and want its neighbourhood.' It doesn't explicitly name alternative tools or say when not to use it, but the usage context is clear and distinct from sibling tools like semantic_search or similar_documents.

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

• graph_overviewA
  4.5/5.0
  Behavior4/5

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

  No annotations are provided, so the description carries the burden. It conveys a read-only reporting action and adds interpretive value by explaining the counts indicate which extraction stages have run. Although it does not explicitly state 'no side effects', the verb 'Report' strongly implies a non-mutating operation.

  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 and front-loaded: the first sentence states the core function, and the second provides usage context. Every word earns its place with no 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?

  For a zero-parameter overview tool with an output schema, the description is complete. It tells the user what to expect (node/edge counts per type), why to use it (checking extraction stages), and this is sufficient for an agent to select and invoke it correctly.

  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 baseline is 4. The description adds no parameter-specific details, which is appropriate since there is nothing to document.

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

  Purpose5/5

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

  The description clearly states the tool reports the current graph contents with node and edge counts per type. The verb 'Report' with the specific resource ('graph') and what it returns makes the purpose unambiguous, and it is distinct from sibling tools like semantic_search or list_tags.

  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 when to use it: 'Use to check which extraction stages have run before trusting a query that depends on them.' It does not explicitly mention when not to use it or name alternatives, but the context is sufficiently clear.

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

• semantic_searchA
  4.5/5.0
  Behavior4/5

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

  With no annotations, the description carries the transparency burden. It discloses the method (semantic matching), the return contents (document path, section breadcrumb, similarity score), and the recommended follow-up. It does not explicitly state non-destructiveness or error/limit behavior, but for a read-only search tool the provided behavioral context is strong.

  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 well-structured and concise: it opens with the core purpose, follows with usage guidance, names an alternative, and closes with return details and a follow-up action. Every sentence contributes necessary information without wasted words.

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

  Completeness5/5

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

  Given the tool's moderate complexity, the description covers purpose, use cases, exclusions, return contents, and a follow-up workflow. An output schema exists, so return type details are not needed in the description. The description is complete for an agent to select and invoke the tool 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 0%, so the description must compensate. It clarifies that the 'query' is meant to be a natural-language conceptual phrase, but it does not describe the 'limit' parameter beyond what the schema's default value implies. The description adds partial value for query semantics but under-explains limit.

  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 'Find passages in the knowledge base by meaning rather than keywords' — a specific verb and resource. It also distinguishes itself from keyword-based search by naming search_knowledge as the alternative, which helps an agent understand the tool's specific role even among sibling tools.

  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?

  Explicit usage guidance is provided: 'Use when the question is conceptual or the user's wording is unlikely to match the note's wording verbatim' and 'For exact strings, literal identifiers, or filenames, prefer knowledge-mcp's search_knowledge instead.' This clearly states when to use and when not to use, plus a follow-up call to read_knowledge.

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

• documents_by_tagA
  4.8/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden. It discloses that the output is paths (not content) and directs the user to read_knowledge for content, adding meaningful behavioral context. However, it does not mention error handling, case sensitivity, or explicitly state that it is a read-only operation beyond the listing verb.

  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 front-load the core purpose, then add usage context and return-value guidance without any fluff. 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?

  The tool is simple (one parameter) and an output schema exists, so the description does not need to explain return values in detail. It covers purpose, usage, parameters, and even the next step (read_knowledge), making it complete for the tool's complexity.

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

  Parameters5/5

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

  The schema has 0% description coverage, but the description explains the 'tag' parameter as a 'frontmatter tag' and gives examples, which is exactly what the schema lacks. It also connects the parameter to list_tags, effectively compensating for the schema gap.

  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 opens with a specific action 'List documents carrying a frontmatter tag' with concrete examples, clearly distinguishing it from siblings like list_tags and semantic_search. The verb+resource+condition structure makes the tool's purpose immediately obvious.

  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 states the intended use case ('tag-based navigation') and provides an actionable prerequisite ('Call list_tags first if unsure which tags exist'). This gives the agent clear when-to-use guidance and points to an alternative tool, satisfying the highest bar.

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