Server Quality Checklist

Tool Scores

• list_recentA
  3.6/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true and idempotentHint=true, covering the safety profile. The description adds useful context beyond annotations: the tool only covers markdown notes (important scope restriction) and sorts newest first. However, it doesn't disclose what data the output schema carries or any pagination/cutoff behavior given the ambiguous 'recently modified' window. With annotations covering safety, 3 is appropriate—adds scope and ordering but not richer 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?

  A single sentence, front-loaded with the verb and object, zero wasted words. It conveys scope (markdown notes), ordering (newest first), and cardinality (n) compactly. This is near-ideal conciseness for a tool with this simplicity level.

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

  Completeness4/5

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

  For a read-only, idempotent tool with a single optional parameter, an output schema present, and simple semantics, the description adequately covers what's needed. The scope (markdown notes), ordering, and count are all stated. The only gap is not clarifying the ambiguous 'recently modified' window or return shape, but the output schema likely handles return format. Given low complexity and good annotations, this is complete enough.

  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 0%, and there's exactly one parameter (n, default 10). The description says 'n most recently modified' which adds meaning to the parameter (it's the count limit), but with a default of 10 and a zero-required-parameter signature, the description's mention of 'n' does map to the schema parameter. The description adds limited semantics beyond the schema—it conveys the limit semantics but doesn't discuss valid ranges or edge cases (e.g., large n). Baseline 3 is appropriate for a low-sidebar effort on a single simple param.

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

  Purpose4/5

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

  The description uses a clear verb+object structure: 'list' the n recently modified markdown notes, with an explicit scope (markdown notes only) and ordering (newest first). It distinguishes from siblings reasonably well—read_note is singular, search_wiki is search, write_note is write, get_links gets links—though it doesn't explicitly name any alternative. Slightly penalized for not explicitly positioning against search_wiki, which is the closest alternative.

  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 the use case (list recent markdown notes) but doesn't explicitly state when to prefer this over search_wiki or other siblings, nor when not to use it. There's no exclusions or alternative differentiation. The ordering and scope are clear, giving minimal context, but no explicit when/when-not guidance is provided.

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

• search_wikiA
  3.6/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is established. The description adds that the search is case-insensitive and covers both full-text and filename, which is useful behavioral context beyond the annotations. However, it doesn't clarify return format, ranking, or sorting despite an output schema existing. A 3 is appropriate since annotations carry the safety disclosure and the description adds modest context.

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

  Conciseness5/5

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

  The description is a single, tightly-worded sentence with zero waste. It conveys the scope (vault's markdown notes), behavior (case-insensitive), and coverage (full-text + filename) economically. This is appropriately concise for front-loading key information.

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

  Completeness4/5

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

  For a search tool with a clear query param, an output schema, and read-only annotations, the description is reasonably complete. Though it doesn't mention pagination, ranking, or wildcard support, an output schema exists and the annotations cover safety. The description defines the search scope (markdown notes in the vault) which is the key differentiator. Missing some search-behavior detail but adequate for a simple tool.

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

  Parameters3/5

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

  Schema description coverage is 0%, meaning the schema provides no descriptive text for parameters. The description compensates somewhat by explaining the query operates on markdown note content and filenames case-insensitively, which gives the agent a meaningful sense of what 'query' means. However, 'limit' semantics are not elaborated beyond its default value of 20, which is self-explanatory. The description adds moderate value over the bare schema.

  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') with a clear resource ('the vault's markdown notes') and clearly differentiates scope from siblings like read_note and write_note. The case-insensitive and full-text/filename detail adds precision. It's clearly distinguished from list_recent (which lists without query), the closest sibling.

  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 it (to find content in markdown notes via full-text or filename), and given siblings like write_note and read_note are operationally different, the usage context is intuitive. However, there's no explicit guidance on when not to use it or alternatives, such as list_recent for browsing without a query. Implied usage only, no explicit exclusion or alternative naming.

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

• read_noteA
  3.9/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and idempotentHint=true, so the agent knows this is a safe read. The description adds valuable context about the return format: it returns parsed YAML frontmatter plus markdown body, which helps the agent know what to expect. Could add more (e.g., what happens if path doesn't exist), but with strong annotations this is well covered.

  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?

  Extremely concise single sentence with zero wasted words. Front-loads the verb+resource and delivers the key behavioral detail (parsed YAML + markdown body) efficiently.

  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?

  With a single self-evident parameter, strong annotations (readOnlyHint, idempotentHint), and an output schema explaining return shape, the description is largely sufficient. The only gap is error behavior (missing path, invalid YAML), but for a low-complexity tool this is acceptable. Sibling tools are well differentiated.

  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 0%, so the description bears the burden for the single 'path' parameter. The description implies path is a note path to read but doesn't explicitly define it beyond the tool's purpose. With only one self-evident parameter ('path' strongly implies a file location given the tool name and description), the implied semantics are sufficient; a baseline of 3 is surpassed by the clear frontmatter/body context.

  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?

  Clear verb+resource: 'Read one note' with specific detail on output format (parsed YAML frontmatter plus markdown body). Distinguishes from siblings like write_note (writing) and list_recent/search_wiki (searching/listing). Slightly loses a point for not explicitly contrasting with get_links, but purpose is specific and readable.

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

  Usage Guidelines3/5

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

  The description implies use when you need the content of a single note, and the 'one note' phrase contrasts with list_recent (listing notes). However, it doesn't explicitly state when not to use it or what alternatives to prefer (e.g., when you want only metadata vs content, or when the path is unknown and search_wiki would be better).

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

• get_linksA
  4.4/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds meaningful behavioral detail on how backlinks are resolved (filename stem, frontmatter title, aliases, case-insensitive, mirroring Obsidian). This is genuinely useful context that explains non-obvious linking semantics and goes beyond what the annotations and schema provide.

  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 compact—two short sentences. The first sentence states the tool's dual function (outbound links + backlinks), and the second efficiently details backlink matching semantics. Every sentence earns its place with zero 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?

  The tool has an output schema (which presumably documents the return shape), one clear parameter (path), and good annotations. The description covers behavior adequately: it names outbound links and backlinks and explains matching logic. For a relatively simple read-only tool, this is complete.

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

  Parameters4/5

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

  The schema has only one parameter (path), which is self-explanatory as a file path. The description doesn't need to add much, though it could mention what kind of path (absolute vs relative), but for a single obvious parameter, the schema baseline covers 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?

  Clear verb+resource: 'get' links for a note, with an explicit scope covering both outbound wiki-links and inbound backlinks. This is specific and distinguishes a graph/linking tool from the sibling read_note (content reading) and search_wiki (content search). The description states precisely what is retrieved.

  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 clearly specifies what the tool returns (outbound links + backlinks) and the exact matching criteria for backlinks. However, it doesn't explicitly contrast with siblings like search_wiki or list_recent, nor state when to choose this over them. Usage context is implied by the link-focused content, but no explicit when/when-not guidance is given.

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

• write_noteA
  4.4/5.0
  Behavior4/5

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

  The description meaningfully supplements the annotations. Annotations declare not readOnly, not idempotent, not destructive — but the description adds key behavioral guarantees: gated write (create vs append only), never overwrites, never deletes, and protection of immutable raw/ source directories. This is valuable context beyond what annotations provide.

  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 tightly-scoped sentences, zero wasted words. Front-loaded with the primary action ('Gated write'), then safety guarantees, then the dry_run tip. Every sentence earns its place.

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

  Completeness4/5

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

  A 4-parameter write tool with an output schema and good annotations — the description covers the critical behavioral constraints (gating, safety, dry_run). The main omission is not describing idempotency behavior for repeated append operations or what the output schema returns, but the output schema exists so return-value documentation isn't the description's job. Overall sufficient for a moderately complex mutation 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?

  Schema description coverage is 0%, yet the description compensates well by explaining the mode parameter ('create' vs 'append'), the safe-write behavior, and the dry_run preview capability. The content and path parameters are self-explanatory from their names, and the description covers the semantics that needed clarification. A small gap remains for dry_run's exact output format, but the core semantics are covered.

  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 verb+resource action: 'write' a note with distinct 'create' and 'append' modes, targeting '.md' notes. It explicitly distinguishes from the sibling read_note by framing this as 'Gated write', so the purpose is specific and differentiated.

  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 constraints on usage: never overwrites, never deletes, and never writes into raw/ directories. The dry_run=true preview guidance adds practical usage context. However, it doesn't explicitly state when to choose this vs a specific alternative (e.g., when to use search_wiki or read_note), though the write/read distinction is implicit.

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