Server Quality Checklist

Tool Scores

• audit_queryA
  3.8/5.0
  Behavior3/5

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

  The description adds that the operation is read-only and never changes the journal or vault, providing specificity beyond the readOnlyHint annotation. It does not disclose return behavior or error conditions, but the annotation already establishes safety.

  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 short sentences deliver the essential purpose and safety guarantee without redundancy.

  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 query tool with an output schema and annotations, the description covers purpose, filtering dimensions, and safety. It could mention the default limit or return format, but the output schema likely covers the latter.

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

  Parameters3/5

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

  The description maps the start/end parameters to 'time range' and mentions tool and note filters, but does not describe the 'limit' parameter or value formats. With 0% schema coverage, this partially compensates but leaves some parameters underspecified.

  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 queries committed operation metadata with filters for time range, tool, or note. It distinguishes itself from sibling note/search tools by focusing on the audit log.

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

  Usage Guidelines3/5

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

  The description implies usage for reviewing audit metadata but does not explicitly state when to prefer this over alternatives. No exclusions or alternative tool references are provided.

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

• get_healthA
  4.1/5.0
  Behavior4/5

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

  Annotations already declare read-only and non-destructive, and the description adds 'truthful' and a detailed list of health aspects, providing useful context beyond the structured hints. It does not contradict annotations, and the extra detail justifies a score above baseline.

  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 written sentence that front-loads the main verb and then lists specifics. Every word adds value, with no redundancy or filler.

  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 a zero-parameter interface and an output schema present, the description sufficiently covers the tool's purpose. The enumerated health dimensions give an agent a clear expectation of what the health check returns, and no critical information is missing.

  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, and schema coverage is 100% (vacuously). Per rubric, 0 parameters earns a baseline of 4, and the description correctly omits parameter details that would be irrelevant.

  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 'Return' and resource 'health', enumerating multiple concrete dimensions (freshness, integrity, checksum, durability, invariants). This distinguishes it from sibling tools focused on notes, searches, and audits.

  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?

  The description provides no guidance on when to use this tool versus alternatives. It does not mention use cases, prerequisites, or exclusions, leaving the agent to infer applicability from the tool name alone.

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

• get_note_historyA
  4.1/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and destructiveHint=false, so the bar is lower. The description adds value by specifying 'committed operation metadata' and 'without reading history content or modifying the journal', which clarifies that it does not expose content and only affects committed operations, providing useful behavioral context beyond 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?

  The description is a single, front-loaded sentence with a clear verb-first structure. It conveys the action, scope, and exclusions in just 14 words, with no superfluous 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?

  With an output schema available and annotations indicating a safe read operation, the description is largely complete. It covers the core action, scope, and non-modifying behavior. It could slightly benefit from mentioning the 'limit' parameter, but the output schema and simple nature make this a minor gap.

  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 clarifies the 'note' parameter through 'for one note', but it does not mention the 'limit' parameter or its behavior. The parameter names are somewhat self-explanatory, but the lack of description for 'limit' leaves a gap in semantics.

  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 'List committed operation metadata for one note' with a specific verb (List) and resource (operation metadata for one note). It distinguishes from siblings by explicitly clarifying it does not read history content or modify the journal, making it distinct from tools like get_note or revert_note.

  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 when to use: when you need operation metadata for a single note without content access or journal modification. It doesn't explicitly name alternative tools, but the scope is well-defined, and the 'without' clauses imply exclusions.

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

• create_note_aiA
  4.2/5.0
  Behavior5/5

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

  The description discloses rich behavioral details beyond the annotations: it is confined to DATACRON_WRITE_PATHS, never overwrites existing files, writes a durable operation record, and relies on human-in-the-loop approval. These specifics add significant value beyond the raw readOnly=false annotation.

  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 sentences, each earning its place: proactive trigger, core action with rejected format, and safety behavior. No redundancy or filler words.

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

  Completeness3/5

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

  The description covers usage, safety, and the rejected format, but for a tool with 10 parameters and 0% schema coverage, it leaves many parameter semantics unexplained. The presence of an output schema reduces the need to describe returns, but the agent still needs to understand parameters like supersedes or expected_hash to use the tool fully. The description is good overall but incomplete for full self-sufficiency.

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

  Parameters2/5

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

  The schema has 10 parameters with zero descriptions, and the tool description only explains the 'rejected' parameter format ('option -- reason'). Other important parameters like rel_path, supersedes, expected_hash, and last_verified are left entirely unexplained, leaving the agent to guess their meaning and usage.

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

  Purpose5/5

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

  The description clearly states the tool's action: 'Write a new typed _memory Markdown note.' This is a specific verb+resource that distinguishes it from read/search/patch tools. It also adds proactive context ('Call this proactively when a durable fact...'), making its purpose 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 explicitly says when to call ('when a durable fact, confirmed decision, or user preference emerges') and when not to ('Skip speculation and one-off chatter'). It does not explicitly name alternative tools, but the context imparts that this is for new notes rather than appending or patching, so it's clear but lacks direct alternatives.

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

• list_notesA
  4.3/5.0
  Behavior4/5

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

  Annotations already declare this as read-only and non-destructive. The description adds valuable behavioral context: pagination with offset/limit, optional scoping to a subfolder, filtering by tags or frontmatter, and the specific fields returned per entry. 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.

  Conciseness5/5

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

  The description is two sentences with no waste. It front-loads the primary use case, then concisely lists the key features (pagination, filters, entry fields), earning every word.

  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 and annotations provide safety context, the description is complete for selection and invocation. It covers the use case, filter options, result contents, and pagination behavior, leaving no significant gaps for an agent.

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

  Parameters3/5

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

  Schema description coverage is 0%, so the description must compensate. It explains the meaning of tags, folder, frontmatter, and pagination, with a useful frontmatter example. However, limit and offset are only implied by 'paginated' and lack explicit semantic detail beyond what the schema's defaults suggest.

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

  Purpose5/5

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

  The description clearly states the tool returns a paginated list of notes, with optional filters for subfolder, tags, and frontmatter. It uses a specific verb ('Return') and resource ('list of notes'), and distinguishes itself from siblings like get_note (deeper reads) by framing it as a discovery tool.

  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 first sentence explicitly instructs to use this tool for discovering vault structure before deeper reads, providing clear contextual guidance. It doesn't explicitly name alternatives or exclusions, but the contrast with 'deeper reads' implies when not to use it.

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

• search_regexA
  4.3/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint and destructiveHint, so the safety profile is known. The description adds valuable behavioral context: output is ranked, sandbox-wrapped, highlighted, resolved to indexed chunks, and depends on external binaries. It does not mention pagination or limit behavior, but the output schema exists to cover return details.

  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 concise sentences front-load the core purpose and then add essential details. Every phrase earns its place—output format, scoping, and prerequisites—without redundancy.

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

  Completeness5/5

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

  Given the presence of an output schema and read-only annotations, the description covers purpose, output characteristics, glob scoping, and external dependencies. It is sufficiently complete for an agent to correctly invoke and interpret results. The only minor gap is limit semantics, but the schema default mitigates that.

  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 explains glob ('Restrict file scope') and pattern implicitly via 'Regex search', but limit is not mentioned at all. The schema provides the default and type, but not the meaning. This partial coverage leaves limit semantics undocumented.

  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 'Regex search via ripgrep', a specific verb+resource statement that clearly differentiates this tool from sibling search_text. It further specifies the output format (ranked sandbox-wrapped match lines with term highlighting) and the prerequisite tools, leaving no doubt about what the tool does.

  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 provides clear usage context: it is for regex search, file scope can be restricted with glob, and it requires rg and datacron index. It does not explicitly name alternatives or state when not to use it, but the purpose is distinct enough that no exclusion is necessary.

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

• append_journalA
  4.4/5.0
  Behavior5/5

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

  Beyond the annotations, it discloses that the operation is confined to DATACRON_WRITE_PATHS, stores content-addressed history, writes atomically, and relies on human-in-the-loop approval. This provides critical safety and side-effect context not captured by the schema or 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?

  Three sentences only, with no fluff. The first sentence gives usage guidance, the second describes the action, and the third explains behavioral guarantees. Front-loaded and efficient.

  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?

  Covers path restrictions, atomicity, history, and approval, which is substantial for an append operation. Excludes explanation of expected_hash or error handling, but the presence of an output schema relieves some burden.

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

  Parameters3/5

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

  With 0% schema coverage, the description must compensate. It maps 'existing memory note' to rel_path, 'heading' to heading, and 'Markdown entry' to entry, but does not explain expected_hash. Partial compensation, but not full parameter semantics.

  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 'Append a Markdown entry under a heading in an existing memory note' – providing a specific verb, resource, and structural detail. Distinguishes from creating a duplicate note, aligning with sibling alternatives like create_note_ai.

  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?

  Explicitly says 'Use this when new information extends a topic that already has a note, instead of creating a duplicate,' offering clear context and an explicit alternative. It stops short of naming sibling tools like patch_note_section or create_note_ai, but the guidance is unambiguous.

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

• revert_noteA
  4.5/5.0
  Behavior5/5

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

  The description adds significant behavioral context beyond annotations: 'The revert is itself durable, reversible, indexed, and operation-logged.' It also mentions the CAS pattern via expected_hash, giving insight into concurrency control. These details complement the annotations (destructiveHint=true, idempotentHint=true) without contradicting them.

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

  Conciseness4/5

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

  The description is concise, three sentences that are information-dense but not bloated. The first sentence front-loads the core purpose, and the final sentence adds valuable behavioral context. There is minor redundancy between the first two sentences, but overall it is efficient and well-structured.

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

  Completeness4/5

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

  Given the annotations and output schema, the description is reasonably complete. It covers the undo use case, the CAS mechanism, and durability/reversibility. It does not mention prerequisites (e.g., obtaining a valid to_hash from history), but the sibling get_note_history implies that. The description is adequate 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.

  Parameters4/5

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

  Schema coverage is 0%, so the description must compensate. It explains expected_hash ('Pass the current content_hash as expected_hash for CAS') and implicitly defines to_hash as the target hash from history ('restore to exact content-addressed history bytes'). The 'note' parameter is obvious from the title and context. This adds meaningful meaning beyond the schema, though not all parameters are explicitly detailed.

  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: 'Use this to undo a bad write by restoring exact prior bytes.' It identifies the specific verb 'revert'/'restore' and the resource (note) with exact content-addressed history bytes. This distinguishes it from sibling tools like patch_note_section (partial edits) or append_journal (appends), providing clear differentiation.

  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 a clear when-to-use context: 'Use this to undo a bad write.' It also provides specific guidance for the expected_hash parameter ('Pass the current content_hash as expected_hash for CAS'). However, it does not explicitly mention when not to use it or alternatives, but the context is strong enough to imply it is for full reverts rather than partial edits.

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

• search_textA
  4.5/5.0
  Behavior5/5

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

  Beyond the annotations (readOnlyHint=true, destructiveHint=false), the description adds critical behavioral context: requires `datacron index` to have been run first, demotes superseded notes by default, and explains the include_superseded flag. It also discloses the output format (ranked sandbox-wrapped snippets with term highlighting). This goes well beyond what annotations alone 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 four sentences, front-loaded with the key usage directive ('First stop...'), and every sentence adds value. No redundant or filler content.

  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 is complete for a search tool: it covers the prerequisite (indexing), default behavior (superseded demotion), a key option (include_superseded), and output characteristics. An output schema exists to formalize the return structure, so detailed return values don't need to be in the description. It also provides enough context to differentiate from sibling search tools.

  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 carries the burden. It explains include_superseded and its default behavior, but does not explain `query` or `limit` beyond their existence in the schema. Since `query` is self-explanatory and `limit` has an obvious default, partial compensation is present, but it's not complete.

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

  Purpose5/5

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

  Description clearly states it performs full-text BM25 search over the user's notes, with a specific verb (search) and resource (FTS5 index). It also positions itself as the 'first stop' for questions, distinguishing it from siblings like search_regex by emphasizing it as the default search tool.

  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?

  Provides clear when-to-use guidance ('First stop for any question... search before saying you do not know'), indicating it should be the initial tool. However, it does not explicitly mention alternatives such as search_regex or specify when not to use it, so it lacks explicit exclusions.

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

• contradiction_scanA
  4.6/5.0
  Behavior5/5

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

  The description disclosed that the tool never writes, even after elicitation or confirmation, which directly reinforces the readOnlyHint annotation and adds important context about the confirm mode's behavior. It also explains that scan mode returns deterministic candidates and read-only proposal tokens, and clarifies the difference between summary and full detail. These details go 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?

  The description is two sentences, front-loads the usage condition, and packs essential information about modes, detail levels, and safety without redundancy. 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?

  The description covers the tool's core behavior, modes, and read-only guarantee. Since an output schema exists, return values are not the description's responsibility. However, it could be slightly more complete by explicitly tying proposal_token to confirm mode, but this is a minor gap. Overall it is sufficient for an agent to use the tool 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?

  With 0% schema description coverage, the description must compensate, and it does. It explains the 'mode' parameter (scan vs confirm), the 'detail' parameter (summary vs full), and implies the 'proposal_token' parameter through 'confirm mode validates one token.' However, it does not explicitly name the proposal_token parameter or state that it is required for confirm mode, leaving some inference to the reader.

  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 scans for contradiction candidates between indexed sections that may conflict or refine each other. It distinguishes itself from sibling tools by describing its specific analytical purpose and the two modes (scan/confirm). The verb 'scan' and explicit resource 'contradiction candidates' make the purpose 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 provides explicit usage context: 'Use this when indexed sections may conflict or refine one another.' It distinguishes between scan and confirm modes and explains when each is appropriate. However, it does not explicitly mention when not to use this tool or name alternative sibling tools, so it lacks explicit exclusions or alternatives.

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

• get_backlinksA
  4.6/5.0
  Behavior5/5

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

  The description significantly adds behavioral context beyond the annotations. It explains the target resolution order ('title -> filename -> aliases') and the empty list behavior for unresolved targets or no incoming links. This gives the agent a precise understanding of edge cases and resolution logic, which is valuable given the annotations only declare read-only safety.

  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 four concise sentences, each earning its place. It is front-loaded with the primary use case, then provides technical resolution details, and ends with the edge-case empty list behavior. There is no fluff or repetition, making it highly efficient for an agent to parse.

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

  Completeness4/5

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

  Given the tool's moderate complexity and the presence of an output schema (which negates the need to describe return values), the description covers the core aspects: use case, target resolution, and empty behavior. It does not explicitly address the limit parameter behavior, but that is a minor omission given the schema provides the default. Overall, it is sufficiently complete for an agent to use the tool 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?

  With 0% schema description coverage, the description carries the burden for parameter semantics. It thoroughly explains the 'target' parameter, including acceptable formats (ULID or wikilink alias) and resolution precedence. The 'limit' parameter is not mentioned, but its meaning is conventional and its default (20) is in the schema. The description adds significant meaning for the key parameter, so a 4 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 identifies the tool's function: 'Return chunks whose wikilinks point at the given target.' It also adds a specific use case ('find related context the user did not mention') that distinguishes it from general search tools like search_text or search_regex. The verb 'Return' and resource 'chunks with wikilinks' make the purpose 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 opening phrase 'Use this to find related context the user did not mention' provides a clear scenario for when the tool is appropriate. However, it does not explicitly mention alternatives or state when not to use it, so it lacks exclusion guidance. This earns a 4 for clear context without full differentiation.

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

• patch_note_sectionA
  4.6/5.0
  Behavior5/5

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

  Annotations already flag destructiveHint=true, and the description elaborates by stating the heading line and non-target sections are preserved, prior history is stored exactly, and writes are atomic. It also explains the expected_hash CAS check, adding significant behavioral 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 three sentences, front-loaded with the core action, and every sentence contributes meaningful operational detail without redundancy.

  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 key operational guarantees (atomicity, history preservation, CAS) and what is preserved, which is sufficient given the presence of an output schema. It omits edge cases like hash mismatch behavior, but overall is complete enough for a tool of this scope.

  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 0% schema coverage, the description compensates for expected_hash (explains its CAS role) and indirectly for heading and new_content by describing the replacement action. It does not mention heading_level or rel_path, but these are relatively clear from context.

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

  Purpose5/5

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

  The description uses specific verbs ('rewrite', 'replace') and clearly identifies the resource ('an outdated section in place', 'content under one existing Markdown heading'). It differentiates from siblings by noting this is for existing notes/sections, not new ones.

  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 states the primary use case: 'rewrite an outdated section in place when the topic already has a note.' This gives a clear context and implies avoiding use for new notes, though it does not explicitly name alternate tools or exclusions.

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

• get_noteA
  4.8/5.0
  Behavior5/5

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

  Annotations already mark this as read-only (readOnlyHint=true), but the description adds substantial behavioral detail: chunk_id returns format='chunk' with sandbox-wrapped body, parent-hash mismatch returns a stale-chunk error, chunk reads ignore offset/limit, and format='full' paginates by character range. This goes far beyond 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?

  The description is dense but well-structured: purpose, id forms, chunk behavior, then full/map behavior. Every sentence earns its place, and semicolons keep related ideas together. It is appropriately sized for the tool's complexity.

  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 complexity and the presence of an output schema, the description covers all necessary aspects: input types, format behaviors, pagination, and error conditions. It leaves no ambiguity about what to expect, making it complete for effective tool use.

  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?

  Schema description coverage is 0%, but the description compensates fully. It explains the meaning of id_or_path (ULID, chunk_id, path), the format enum values (full, map, chunk), and clarifies that offset/limit page by character range in full format and are ignored for chunk reads. This adds significant meaning beyond the raw 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: 'Fetch the full context behind a search hit' and 'Fetch a single note by its ULID, indexed chunk_id, or vault-relative path.' This is a specific verb+resource that distinguishes it from siblings like search_text or get_note_history.

  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 opening sentence gives clear usage context: use this before answering from a snippet alone. It also provides guidance within the tool, such as using format='map' as a 'cheap to scan' option. However, it does not explicitly name sibling alternatives or state when not to use this tool, so it misses the full 'when/when-not' explicit guidance.

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

• set_frontmatterA
  4.9/5.0
  Behavior5/5

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

  Beyond the destructiveHint annotation, the description discloses that this write operation only changes a fixed set of fields, preserves the Markdown body, and automatically updates a timestamp. It also clarifies the invalidation pattern (invalid_at + invalidated_by) and rejected format, providing substantial behavioral context not present in annotations.

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

  Conciseness5/5

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

  The description is one dense paragraph but every sentence adds value: use case, invalidation preference, rejected format, and explicit list of changed fields. It is front-loaded with 'Use this when' making the primary trigger immediately clear. No 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 complexity (10 params, destructive write), the description covers when to use, what changes, what is preserved, and how to format specific fields. With an output schema present, the lack of return-value descriptions is acceptable. The description is comprehensive enough 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.

  Parameters4/5

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

  Despite 0% schema description coverage, the description names the key parameters (origin, confidence, last_verified, supersedes, rejected, valid_from, invalid_at, invalidated_by) and explains the value format for rejected ('option -- reason'). It does not explain expected_hash or rel_path, but the lifecycle semantics give enough meaning for most parameters.

  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 identifies the tool as updating frontmatter fields on an existing memory note, with a specific focus on lifecycle changes (verified, superseded, confidence changes). It distinguishes itself from siblings by explicitly noting it only changes specific fields and preserves the Markdown body, which differentiates it from body-editing tools like patch_note_section.

  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?

  Provides explicit 'when to use' guidance: lifecycle changes such as verification, supersession, or confidence adjustments. It also gives a strong preference guideline (invalidate over delete/rewrite) and explains the rejected entries format, telling the agent when and how to record discarded options.

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