Server Quality Checklist

Tool Scores

• list_notesB
  3.3/5.0
  Behavior3/5

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

  The annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds the filtering behavior but does not disclose result shape, ordering, pagination behavior, or whether note content is returned.

  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, compact, front-loaded sentence. It communicates the essential verb, resource, and optional filters with no unnecessary filler.

  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 simple read-only list tool with fully documented optional parameters, this is mostly adequate. However, it lacks guidance on sibling alternatives and does not clarify what the returned note list contains, which matters in the absence of an 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 the parameters are already fully documented. The description adds minimal semantic value beyond restating that folder and tag filtering exist.

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

  Purpose4/5

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

  The description states a specific verb and resource: 'List notes', with an optional filter by folder prefix or tag. It is distinguishable from single-note operations like read_note, but it does not explicitly differentiate itself from search or query_notes.

  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 about when to use list_notes versus search, query_notes, or list_tags. The description only states what the tool does, not when it should be preferred over alternatives.

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

• get_linksA
  3.8/5.0
  Behavior4/5

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

  With readOnlyHint true)Skip, the description adds behavioral details: marks links as resolved/unresolved, de-duplicates targets, sorts by line number. This goes beyond the annotation's safety hint, providing useful output behavior. No contradiction.

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

  Conciseness5/5

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

  The description is concise, two sentences, with key behaviors front-loaded (outgoing links) and additional details succinctly stated. No fluff.

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

  Completeness4/5

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

  For a simple read-only tool with a single required parameter and no output schema, the description covers what it returns and its behavior. It lacks explicit error cases or whether the note must exist, but given simplicity and annotations, it is largely complete.

  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 'path' is fully covered by the schema (100% coverage), so the description does not need to add much. It does not describe format or errors, but the schema requirement is clear. Baseline 3 is appropriate.

  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 it returns outgoing wikilinks and embeds from a note, which is specific and distinct from get_backlinks (incoming links). It mentions resolution, de-duplication, and sorting, but does not explicitly contrast with 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 description implies it is used to inspect outgoing links from a note, but provides no explicit when-to-use or when-not-to-use guidance. Given the sibling get_backlinks, a note on when each is appropriate would be helpful. The description does not mention the note must exist or prerequisites.

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

• patch_frontmatterA
  3.8/5.0
  Behavior4/5

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

  The description discloses important behavioral traits: it preserves key ordering and quote style, and explicitly explains that null values delete keys. These details go beyond the annotations (readOnlyHint=false, destructiveHint=true), which only indicate mutation and destructiveness. It adds useful context without contradiction.

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

  Conciseness5/5

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

  The description is a single, front-loaded sentence that states the core action, key guarantees, and deletion semantics. No filler or repetition; every clause adds 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 covers the essential behavior, deletion semantics, and safety guarantees. It does not mention error cases like hash_conflict, but those are captured in the schema. It also omits prerequisites (e.g., note must exist), but given the simple tool and existing schema, the description is near-complete.

  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 the schema already documents all three parameters. The description repeats the null-deletion behavior for the patch parameter, which is also stated in the schema, and adds no new semantic information beyond what is structured. Thus baseline 3 applies.

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

  Purpose5/5

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

  The description clearly states the tool's purpose: setting, updating, and deleting frontmatter keys. It specifies the resource (frontmatter keys) and includes a concrete behavioral guarantee (preserving key order and quote style), which distinguishes it from sibling tools like patch_note that modify note content.

  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 provided on when to use this tool versus alternatives such as patch_note or replace_in_note. The description gives no context on selection criteria, exclusions, or comparative advantages beyond the formatting guarantee.

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

• append_periodic_noteA
  3.9/5.0
  Behavior3/5

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

  With all annotations false, the description carries the full behavioral burden. It adds genuinely useful guarantees ('Preserves existing frontmatter exactly') and creation-flow detail ('from template if configured'), which go beyond the raw annotations. However, it omits the most salient risk of an append operation — non-idempotency (duplicate calls duplicate content) — even though the prevHash parameter hints at concurrency concerns.

  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, zero filler. The primary action leads, the scoping list follows, and the creation behavior closes. Every clause serves a distinct purpose with no 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?

  For a moderate-complexity tool with 5 simple params and no output schema, the description covers the essentials well. Gaps remain: no mention of timezone handling for date-boundary behavior (critical for 'today' defaults), no duplicate-append warning, and no interaction with prevHash conflict recovery. These are real but not fatal omissions for an append operation.

  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 100%, establishing a baseline of 3. The description adds value by clarifying the createIfMissing parameter's effect ('Creates the note first (from template if configured)') and confirming its default, which is not fully obvious from the schema text alone. This is a small but genuine increment over 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?

  The description leads with a specific verb+resource: 'Append text to a periodic note' and immediately scopes it to '(daily, weekly, monthly, quarterly, or yearly)'. This clearly differentiates it from sibling 'append_note' (regular notes) and 'get_periodic_note' (read path) without needing to inspect either schema.

  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 'periodic note' qualifier implies the tool's niche, and the description notes the conditional creation behavior when createIfMissing is true. However, it never explicitly points to an alternative (e.g., 'use append_note for regular notes') or states when not to use this tool, despite siblings like append_note and patch_note existing. Usage context is implied rather than stated.

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

• append_noteA
  4/5.0
  Behavior4/5

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

  Annotations already indicate it's a write operation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds valuable behavioral detail: it preserves frontmatter and is safe for 'append-only workflows,' which provides context beyond the annotations. No contradiction exists.

  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 concise sentences with no filler. The core purpose is stated first, and the additional safety/use-case context is provided in a second sentence. Every phrase adds value, making it appropriately sized and front-loaded.

  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 append operation with three parameters, the description covers the key points: it appends, preserves frontmatter, and indicates safe workflows. However, it does not mention error behaviors (e.g., what happens if the path doesn't exist) or whether it creates a note if missing. Given the low complexity and existing annotations, this is a minor gap.

  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%, with each parameter (path, content, prevHash) already documented in the schema. The description does not add any additional parameter-specific semantics, so it remains at the baseline score of 3 given the complete 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?

  The description clearly states the tool's function: 'Append text to a note body without touching the frontmatter.' This is a specific verb (append) and resource (note body), and it explicitly distinguishes itself from other mutation tools by mentioning the frontmatter preservation, which differentiates it from patch_note or replace_in_note.

  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 provides context on when the tool is appropriate ('Safe for meeting notes, daily logs, and append-only workflows'), but does not explicitly mention when NOT to use it or point to alternative tools. It implies usage scenarios but lacks explicit exclusions or sibling comparisons, leaving the agent to infer the boundary.

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

• create_noteA
  4/5.0
  Behavior4/5

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

  Beyond the destructiveHint:true annotation, the description discloses three concrete behaviors: automatic parent-directory creation, the fail-on-existing-note rule, and the prevHash compare-and-swap guard that can gate the overwrite. These are non-obvious side effects and failure modes the annotations alone do not convey. The description is consistent with readOnlyHint:false and destructiveHint:true.

  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, each earning its place: the core action first, then the optional parameters, then the critical existence-failure and CAS-guard behavior. No filler and no repetition of schema content.

  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 5-parameter destructive write with no output schema, the description covers creation, optional fields, directory auto-creation, the existence failure mode, and the overwrite/CAS guard. The one notable gap is the return contract on success — the CAS workflow implied by prevHash would benefit from knowing whether the note's contentHash is returned — but the invocation semantics are fully specified.

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

  Parameters3/5

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

  Schema description coverage is 100%, so every parameter (path, content, prevHash, overwrite, frontmatter) is already documented in the input schema. The description's only added semantic is the coupling between prevHash and overwrite ('prevHash may guard the overwrite'), a small increment over the schema's per-parameter text.

  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 opening sentence 'Create a new note at a vault-relative path' names a specific verb, resource, and scope qualifier. This cleanly distinguishes it from sibling mutators like append_note, patch_note, replace_in_note, and move_note, which all act on existing notes, and from delete_note.

  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 fail-if-exists clause ('Fails if the note already exists unless overwrite is true') gives the agent a clear condition for choosing the overwrite path. However, it does not explicitly route to alternatives — e.g., checking existence with list_notes first or selecting patch_note/append_note for modifying an existing note — so cross-tool selection is left implied.

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

• get_periodic_noteA
  4/5.0
  Behavior4/5

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

  Annotations declare readOnlyHint=false and destructiveHint=false, so the description correctly adds that the tool may create a note when createIfMissing is true – a behavioral detail beyond the annotations. It also discloses the config file locations (.obsidian/daily-notes.json and plugin data.json). No contradictions. However, it does not describe the exact return shape or failure modes, which are minor gaps given the side‑effect disclosure.

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

  Conciseness5/5

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

  Two sentences with no filler. The primary purpose ('Get the path and existence status') is front‑loaded, followed by config sources and the optional creation behavior. 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?

  Since there is no output schema, the description conveys that the return includes 'path and existence status', and it explains the config‑reading logic and optional creation. This is sufficient for an agent to call correctly. It lacks explicit error cases or what happens after creation (e.g., returns path or just status), but the core information is present.

  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?

  Parameter schema coverage is 100% – all three parameters (date, period, createIfMissing) already have descriptions in the schema, including defaults. The description adds no new semantic meaning beyond restating the defaults ('Defaults to today', 'Default: daily', 'Default false') which are already present. Baseline 3 applies because the schema carries the weight.

  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: 'Get the path and existence status of a periodic note' and enumerates the period types (daily, weekly, monthly, quarterly, yearly). This clearly distinguishes it from sibling tools like create_note or append_periodic_note, even though it never names them. The 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?

  The description explains what the tool does and mentions the optional creation side‑effect, but never explicitly states when to use this tool versus a sibling like create_note or append_periodic_note. It gives context (reads config from specific files) but no when‑to‑use or when‑not‑to‑use guidance, leaving the agent to infer suitability.

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

• replace_in_noteA
  4.1/5.0
  Behavior4/5

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

  Annotations already flag destructiveHint=true and readOnlyHint=false, so the write nature is known. The description adds valuable behavioral context beyond that: it clarifies that frontmatter is never affected (scope of mutation) and recommends dryRun for previewing. It does not discuss failure modes like hash_conflict, but the schema documents that, and the bar is lower given the annotation coverage.

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

  Conciseness5/5

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

  The description is two sentences with no fluff. The core purpose is front-loaded, and the supporting details (feature list, frontmatter exclusion, dryRun tip) follow in a logical order. Every sentence earns its place, and nothing is redundant with the schema.

  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?

  With 9 parameters and no output schema, the description could do more to explain return values or error conditions. It does not mention what the tool returns on success (e.g., count of replacements, updated content) or how it reports failures like hash_conflict or note-not-found. The schema and annotations cover some aspects, but the lack of output guidance leaves a gap for a mutation tool of this complexity.

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

  Parameters3/5

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

  Schema description coverage is 100%, so all 9 parameters are individually documented. The description adds only a high-level summary of capabilities ('Supports literal and regex search, case sensitivity, whole-word matching, and a replacement limit') and a tip about dryRun, but this does not meaningfully augment the schema, which already explains each parameter's semantics. Thus, baseline 3 is appropriate.

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

  Purpose5/5

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

  The description clearly states the resource and action: 'Find and replace text within a note body.' It goes beyond a simple verb by listing supported features (literal/regex, case sensitivity, whole-word, limit) and explicitly excludes frontmatter, which distinguishes it from sibling tools like patch_frontmatter or append_note. An agent can immediately understand what it does without needing to inspect the schema.

  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 for body text replacement, and explicitly states 'Frontmatter is never touched,' which serves as a when-not-to-use boundary. It also advises using dryRun to preview before writing, which is a concrete usage tip. However, it does not name any alternative sibling tools, so it stops short of a full 5.

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

• get_backlinksA
  4.2/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is known. The description adds the performance characteristic ('fast, pure index lookup') and the sort order. It does not describe pagination behavior, ownership, or failure modes. With annotations covering the read-only nature, a 3 is fair – it adds a bit but not extensive behavioral depth.

  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, each earning its place: purpose, performance characteristic, and sort order. Front-loaded with the core function. 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 read operation with fully documented parameters (schema coverage 100%) and a clear description, the agent has everything needed to invoke it. Missing an explicit output structure, but no output schema exists impossible to know exactly, but the description mentions source line and optional excerpt, which is adequate. Could mention pagination but not critical. Score 4 because it covers the essentials.

  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 each parameter described. The description adds context on the 'excerpt' (optional, ~200 chars) and the sort order, which enriches understanding of 'limit' and 'includeExcerpt'. It goes slightly beyond pure schema repetition, earning a 4.

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

  Purpose5/5

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

  The description states a specific verb ('Return'), a precise resource ('every note that links to the target note'), and the result shape (source line, optional excerpt). It implicitly distinguishes itself from sibling tools like get_links (which likely returns outgoing links) and search, making the operation unmistakable.

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

  Usage Guidelines4/5

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

  The description gives contextual signals for when to use this tool: it is a reverse-link lookup backed by a pre-built index, implying it is the fast, intended path for finding inbound references. It does not explicitly name alternatives or exclusions, but the 'pure index lookup' phrasing signals it is not for full-text search or outgoing links. Slight gap: no explicit 'use X instead' guidance.

  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?

  The readOnlyHint annotation already signals a safe read operation. The description adds useful behavioral details—that all tags are returned, filtering behaviors, and that nested tags include a parent field—which goes beyond the annotation's minimal information.

  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 concise sentences deliver the purpose, options, and a notable output feature with zero redundancy. Front-loaded with the primary action and immediately informative.

  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 read-only list tool with no output schema, the description covers the return contents (usage counts, parent field for nested tags) and behavioral parameters fully. No gaps are apparent for an agent to invoke it 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?

  The schema covers all parameters with descriptions (100% coverage), so the description adds no significant new meaning about inputs. It merely reiterates what the schema already specifies, 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?

  Describes a specific action ('List all tags in the vault') with clear scope and distinguishes itself from siblings by focusing solely on tags. The mention of usage counts and nested tags further specifies the tool's unique function.

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

  Usage Guidelines4/5

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

  While it doesn't explicitly contrast with alternatives, there is no other tag-listing tool among siblings, making the purpose self-evident. It provides clear context but omits explicit exclusions or when-to-use guidance beyond its self-description.

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

• searchA
  4.3/5.0
  Behavior5/5

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

  The description goes well beyond the annotations (readOnlyHint=true) by describing output trim (excerpts of ~120 chars), a tunable excerptLength, fuzzy matching and prefix search support, and the nuance that semantic/hybrid modes delegate to a local embedding model gated on SEEKSTONE_SEMANTIC=1. These details materially shape an agent's expectation of what the tool actually does when called.

  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, none wasted: purpose, the essential behavior (excerpts-not-notes), and mode/gating semantics. The most important constraint is front-loaded, and the rest earns its place by explaining mode behavior that the agent needs before calling.

  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 complex search tool with no output schema, the description does enough heavy lifting: it tells the agent what the result looks like (exerpts), what modes exist, and how the mode-related feature gates work. The main gap is that it doesn't address result ranking, the absence of paging, or whether there is a structured query language — minor for the purpose, since the important return shape is specified.

  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 already covers all six parameters at 100%, which sets a baseline of 3. The description adds meaning beyond the schema by explaining the query's inherent capabilities (fuzzy matching, prefix search), and by tying excerpt length tuning (~120 chars) to the excerptLength parameter's default. It doesn't restate schema field-by-field, so it earns the elevated score.

  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 identifies the tool's action ('Full-text search across the vault') and adds a distinctive behavioral cue ('Returns ranked excerpts — not full notes'), which separates it from retrieval siblings like read_note without opening any schema. It stops short of explicitly naming a sibling to differentiate from, but the 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 Guidelines4/5

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

  The description gives clear context for when this tool fits: it's a read-side discovery tool designed to minimize context usage, and it explains the mode trade-off (lexical vs semantic/hybrid, plus the SEEKSTONE_SEMANTIC=1 requirement). There is no instruction on when to use an alternative (e.g., query_notes or list_notes) and no explicit exclusions, so it earns a 4 rather than a 5.

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

• query_notesA
  4.4/5.0
  Behavior4/5

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

  Annotations already carry readOnlyHint=true, so the description correctly adds no mutation warnings and instead discloses a non-obvious behavioral contract: results are compact rows (path + title by default, extensible via select) and never the note content itself. This materially changes what an agent expects to receive and is not stated in the annotations. The only missing behavioral context would be pagination/size caps beyond the schema limit parameter, but the schema already covers that.

  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 short sentences, each earning its place: scope definition, return-format contract, and sibling routing. The most distinguishing trait (metadata vs content) is front-loaded, and nothing is wasted restating annotations or schema defaults. It is unusually economical for a tool with 11 parameters.

  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 an 11-parameter read-only tool with a 100%-covered schema, the description covers purpose, filter dimensions, result shape, and the main sibling alternative; the output-schema absence is compensated for by the explicit 'returns compact rows, not note content' statement. The only marginal gap is that it doesn't mention distinguishing siblings like list_notes or get_tags, and the sort/select defaults are left to the schema. An example 'where' predicate would be nice but is not a genuine completeness gap.

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

  Parameters3/5

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

  Schema documentation covers 100% of the 11 parameters, each with a meaningful description, including defaults for select and sort and the AND semantics of where. The description only echoes the filter axes (tag, folder, modified time, size) and the select default, with no syntax or format details that the schema lacks. Per the high-coverage baseline, the description adds no real param-value meaning, so a 3 is appropriate.

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

  Purpose5/5

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

  The description opens with a specific verb and resource ('Structured metadata query') and enumerates the exact filter dimensions: frontmatter key/value predicates, tag, folder, modified time, and size. It also distinguishes itself by declaring that it returns compact rows rather than note content, which clearly separates it from content-returning siblings like read_note and search. An agent can tell what this does and is not without reading any schema.

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

  Usage Guidelines5/5

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

  The final sentence explicitly routes usage: 'Use this instead of search when filtering by properties rather than text.' It names the alternative sibling and gives the classification condition, effectively covering both the when (property-based filtering) and the when-not (text-based filtering). This is explicit routing guidance, not just implied context.

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

• delete_noteA
  4.5/5.0
  Behavior5/5

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

  Beyond the destructiveHint annotation, the description reveals critical behavior: the default action is non-permanent (trash) and reversible, and only permanent deletion requires an explicit flag. It also discloses recoverability. This transparency is essential for an agent deciding whether to call this tool and mitigates risk, going well beyond what the annotation already provides.

  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 at two sentences, with the action verb first and the most important behavioral nuance immediately following. Every word contributes value, and the sentence structure flows from the core action to the key conditional. No fluff or repetition.

  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 tool with three parameters and one required field, the description covers the essential behavior (delete, default trash, permanent override) and confirms reversibility. It does not mention error handling for missing paths or concurrency, but given the schema and annotations, the definition is complete for an agent to call it correctly. Nothing critical 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?

  The schema already documents all three parameters with 100% coverage, so the description needn't add parameter details. The description's mention of 'pass permanent: true' restates the schema without adding new meaning. This meets the baseline of 3 but does not elevate it further.

  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 'Delete a note', which is a specific verb and resource, and immediately clarifies the default trash behavior and the permanent deletion option. This distinguishes it from siblings like move_note or patch_note, which are about modifying instead of removing. The tool's purpose is unambiguous and immediately scoped.

  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 on how deletion works by default (to trash) and how to override it, which implicitly tells the agent when this tool is appropriate. However, it does not explicitly mention alternatives like move_note or state when NOT to use it (e.g., for reorganization). This is a slight gap in otherwise clear guidance.

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

• move_noteA
  4.5/5.0
  Behavior5/5

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

  Beyond the destructiveHint annotation, the description discloses concrete behavioral traits: it rewrites wikilinks and markdown links in other notes while leaving fenced code blocks untouched, auto-creates parent directories, and fails if the destination exists unless overwrite is true. This is rich, actionable context that goes well beyond the annotation and helps an agent anticipate 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.

  Conciseness5/5

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

  Three concise sentences, front-loaded with the primary purpose, followed by critical behaviors (link rewriting, directory creation, overwrite failure). No filler — 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?

  For a mutation tool with 5 parameters and no output schema, the description covers the main side effects (link rewriting, directory creation, failure conditions) and explains the overwrite and rewriteLinks parameters behaviorally. The prevHash guard is documented in the schema but not in the description; however, the agent can infer it from the parameter description. Given the complexity, this is complete enough for correct invocation.

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

  Parameters3/5

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

  Schema description coverage is 100%, so each parameter already has a clear meaning. The description adds context around rewriteLinks (rewriting links in other notes) and overwrite (failure behavior) but does not add new information for from, to, or prevHash beyond the schema. It sits at the baseline of 3 because the schema carries the parameter explanation.

  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 'Move or rename a note to a new vault-relative path' — a clear verb, resource, and target location. It explicitly describes the link-rewriting side effect, distinguishing it from destructive delete_note and heading-renaming rename_heading.

  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 conveys when to use the tool (moving/renaming notes) and details the overwrite and link-rewriting behavior. It does not explicitly name alternative tools, but the purpose is unambiguous given the sibling list; this falls short of a perfect 5 that requires explicit when-not/alternatives.

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

• patch_noteA
  4.5/5.0
  Behavior4/5

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

  Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds operational semantics — exact behavior of append, prepend, replace — and the frontmatter constraint, which is useful. It does not mention the prevHash concurrency guard or hash_conflict failure, but those are fully documented in the schema, and there is no contradiction.

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

  Conciseness5/5

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

  The description is three compact segments: the main purpose, the operations list, and the frontmatter constraint. It is front-loaded with the core purpose, contains zero fluff, and 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?

  For a mutation tool with 6 parameters, the description covers the operational model and key constraints (frontmatter untouched). It omits details like prevHash and createIfMissing, but these are fully specified in the schema, so the description plus schema together provide a complete picture. A small addition like mentioning the concurrency guard would push it higher.

  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?

  Although schema coverage is 100%, the description adds significant meaning beyond the schema by defining what each operation does (append after section, prepend after heading line, replace section content) and clarifying the targeting mechanism (heading or block without ^ prefix). This goes well beyond the schema's individual 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?

  Clearly states the tool surgically edits a specific section of a note, targeted by heading or block reference, without rewriting the whole file. It identifies three operations (append, prepend, replace) and explicitly notes frontmatter is untouched, distinguishing it from siblings like append_note and patch_frontmatter.

  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?

  Conveys that it is for targeted, non-rewriting edits and excludes frontmatter, which gives helpful context for choosing this tool. However, it does not name specific alternatives or provide explicit when-to-use/when-not-to-use guidance beyond these implications.

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

• rename_headingA
  4.5/5.0
  Behavior4/5

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

  Despite having annotations, it adds valuable context about case-insensitivity, first-match-wins on duplicates, and skipping code blocks. It doesn't contradict the annotations.

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

  Conciseness5/5

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

  Two dense sentences pack a lot of precise information: what it does, how it works (warm backlink index), and key edge-case behaviors. No fluff.

  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 rename operation, it covers the mutation, the link rewriting, the index source, and important resolution semantics. It could elaborate on return values, but the description is comprehensive for typical usage.

  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?

  With 100% schema coverage, the schema already documents each parameter. The description adds value by explaining the exact behavior of heading matching and what happens with the prevHash guard.

  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 renames a heading and rewrites links and embeds across the vault, which distinguishes it from simple rename or edit tools. It mentions specific behavioral nuances like alias preservation and ignoring fenced code blocks.

  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 implies this tool is for renaming headings specifically, not for other edits, and mentions how it handles duplicate headings. It doesn't explicitly mention alternative tools, but the context is clear for when to use this over a generic edit tool.

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

• context_packA
  4.6/5.0
  Behavior5/5

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

  Beyond the readOnlyHint=true annotation, the description adds critical behavioral disclosure: the byte-budget mechanism, the three output components, and especially the empty-result semantics ("Empty excerpts with confidence 'none' or 'low' means the vault lacks coverage — do not infer content"), which prevents an agent from hallucinating answers. No contradiction with annotations.

  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?

  Three dense sentences, each with a distinct job: what it returns, when to use it, and how to interpret empty results. Purpose is front-loaded and there's no fluff, though the middle sentence could arguably be split for skimmability. Minor polish would push this to 5.

  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?

  With no output schema, the description carries full responsibility for explaining return values and edge cases, which it does thoroughly: outputs (ranked excerpts, summaries, source paths), budget behavior, and the empty-coverage case are all disclosed. An agent has everything needed to call this tool correctly, so nothing critical 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 description coverage is 100%, and the description's parameter-related details (byte budget default, natural-language query) are already present in the input schema's field descriptions. The description reinforces but does not extend the schema, so it sits at the baseline of 3 for high 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?

  Description opens with a specific verb and resource: "Assemble everything needed to ANSWER a natural-language question in one call," then enumerates exact outputs (ranked excerpts, linked neighbor notes with one-line summaries, follow-up source paths). This differentiates it from siblings by promising answer-ready context "without multiple round-trips," which no sibling claims.

  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 routes to alternatives: "Use search to locate notes and query_notes for metadata filters; use context_pack when you want answer-ready context without multiple round-trips." Names two siblings and the precise condition that selects this tool, making the when-versus-when-not distinction unambiguous.

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

• outline_noteA
  4.7/5.0
  Behavior5/5

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

  Annotations already declare readOnlyHint=true, and the description adds meaningful behavioral context: it returns only structural data (headings, offsets, anchors, frontmatter keys) and explicitly excludes prose. It also signals a performance advantage ('fraction of the cost'), which is not in the annotations. No 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?

  Two sentences with zero wasted words. The most critical information (what it returns and what it excludes) is front-loaded, and the usage guidance is packed efficiently into the second sentence.

  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 description fully covers the return value (heading tree, offsets, anchors, frontmatter keys), the exclusions (no prose), and the usage context (before reads/patches). With only 3 well-documented parameters and read-only annotations, nothing essential is missing for an agent to call it correctly.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the baseline is 3. The description doesn't add extra semantics to the parameters beyond what the schema already states, but it does clarify the overall output context (e.g., 'frontmatter key list' implies what includeFrontmatter might do). No compensation needed.

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

  Purpose5/5

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

  The description states a specific verb ('Return') with a precise resource ('a note's structure') and enumerates the components (heading tree, offsets, block-reference anchors, frontmatter key list). It clearly distinguishes from siblings like read_note by explicitly saying 'without returning any prose,' so an agent knows exactly what it gets.

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

  Usage Guidelines5/5

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

  The description provides explicit when-to-use guidance: 'Use this before section reads or patches to discover what sections exist at a fraction of the cost of reading the full note.' This tells the agent the ideal scenario and why it's preferable to full reads, effectively excluding alternatives like read_note.

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

• read_noteA
  4.7/5.0
  Behavior5/5

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

  Beyond the readOnlyHint annotation, the description discloses the exact JSON return shape (content, bytes returned, total note size, contentHash) and the hash's purpose for compare-and-swap with edit tools. This behavioral context is not captured in annotations and is valuable for the agent.

  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: first states the operation and modes, second the return value, third the usage context. It is front-loaded with the core purpose and contains zero wasted words, making it efficiently structured.

  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 5 parameters, a nested object, and no output schema, the description covers the return structure, the purpose of contentHash, and the prerequisite discovery steps. An agent has everything needed to call the tool correctly and understand its output without ambiguity.

  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 fully describes all five parameters (100% coverage), so the description adds no extra parameter meaning. The mention of block reference and line range merely echoes schema descriptions; no new semantics are introduced, so the baseline of 3 applies.

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

  Purpose5/5

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

  States a specific verb (read) and resource (note or span), enumerates three selection modes (heading section, block reference, line range), and distinguishes it from siblings like outline_note and search by its read-only content-return focus. The purpose is unambiguous and the description clearly differentiates the tool.

  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 the agent to use search or outline_note first to find the path and section names, and explains the contentHash is to pass as prevHash to edit tools for compare-and-swap. This provides clear when-to-use guidance and ordering, effectively routing the agent to the correct prerequisite tools.

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