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

Annotations already declare readOnly and idempotent. The description adds that it parses only the ## Chat: block, ignores other content, and returns line ranges, which is helpful behavioral context beyond annotations.

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

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

Two sentences, no fluff, front-loaded with key information. Every sentence adds value.

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

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

For a simple tool with one parameter and no output schema, the description sufficiently covers purpose and behavior. Could hint at output structure, but not essential.

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

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

Single parameter note_path with full schema coverage. The description does not add new semantic meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool parses a specific chat block from a note into structured messages, distinguishing it from other note-reading tools. The verb 'Parse' and resource 'chat thread' are specific.

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

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

Implied usage: the tool is for reading chat threads, ignoring non-chat content. However, no explicit when-to-use or alternatives are provided among 33 sibling tools.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds significant context: token-budgeted, deduplication, hybrid search, and output format (markdown bundle). No contradictions.

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

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

Two sentences with key information front-loaded. Very concise, but could benefit from breaking into a short list for even better readability.

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

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

Given 5 parameters and no output schema, the description adequately explains the overall process and return format. It covers the main behavioral aspects but lacks details on error handling or edge cases.

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

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

Schema has 100% coverage with descriptions for all 5 parameters. The description adds minimal extra meaning: it mentions 'hybrid search' and 'token budget default 4000', but the schema already explains defaults and types. Baseline 3 is appropriate.

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

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

The description specifies a specific verb ('retrieve', 'gather', 'pack', 'return') and resource ('context pack for an AI question'). It clearly distinguishes from sibling tools like obsidian_search or obsidian_get_backlinks by describing it as a composite that replaces ~5 separate calls.

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

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

The description states when to use (when needing a ready-to-paste context blob) and implies it's an alternative to multiple manual calls. However, it does not explicitly list exclusions or when to avoid using it, leaving some ambiguity.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description does not need to repeat those. However, it does not disclose the return format or behavior beyond the query grammar, which would be helpful given no output schema.

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

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

The description is concise and well-structured: first sentence states purpose, then grammar, operators, special fields, and limitations. Every sentence adds value with no redundancy.

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

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

The description covers query syntax comprehensively but lacks information about the response format. Given the tool's complexity and no output schema, a brief note on what is returned would improve completeness.

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

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

The schema only has a minimal description for the query parameter. The tool description adds substantial meaning by detailing the exact grammar, operators, special fields, and limitations, fully compensating for the schema's brevity.

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

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

The description clearly states the tool's purpose: 'Run a Dataview-style query.' It provides the specific grammar and distinguishes itself from siblings like obsidian_search by focusing on Dataview syntax.

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

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

The description includes explicit syntax and limitations (no expressions, FLATTEN, GROUP BY, joins), and points to docs/api.md for unsupported features. It implies usage for basic queries but does not explicitly contrast with alternative tools.

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

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

Annotations already indicate read-only and idempotent behavior. The description adds details: BFS algorithm, max_depth limits, follow_embeds defaulting to true, and the return of path with wikilink text and alternative paths. No contradictions.

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

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

The description is concise (3 sentences), front-loaded with key information, and every sentence adds value. No wasted words.

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

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

Despite no output schema, the description adequately describes the return value (path with steps and wikilink text, alternative paths). It covers key behaviors for a graph traversal tool with 7 parameters.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context beyond schema: BFS algorithm, max_depth bounds (default 5, max 10), follow_embeds explains embed handling, include_alternatives explains result limits. This adds value.

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

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

The description clearly states the tool finds the shortest wikilink path between two notes using BFS, distinguishing it from siblings like obsidian_find_similar or obsidian_get_backlinks.

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

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

The description explains the BFS traversal, max_depth, and options like include_alternatives and follow_embeds, but doesn't explicitly state when to use this tool over others. However, the purpose is clear enough.

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

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

Annotations declare readOnly and idempotent, and the description adds performance details (O(N) over vault), internal scoring logic, and version 3.10 enhancements (age_days, stale flag), going well beyond 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.

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

The description is a concise paragraph of five sentences, front-loading the core purpose, then detailing signals, performance, and version updates without redundancy.

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

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

While no output schema exists, the description mentions individual signal scores and new fields (age_days, stale). It lacks explicit return format details but is sufficient for an agent to use the tool effectively.

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

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

Input schema has 100% coverage with clear descriptions. The description adds context about scoring and re-ranking but does not substantially extend parameter understanding beyond the schema.

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

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

The description explicitly states the tool finds similar notes using structural signals (tag overlap, title 3-gram, shared links, co-backlinks), distinguishing it from semantic search or graph traversal tools among siblings.

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

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

The description advises 'for vaults >5k notes prefer batching,' indicating when to use with caution. However, it does not explicitly state when not to use this tool versus siblings like obsidian_search or obsidian_get_note_neighbors.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the description's 'Read-only' confirms. It adds behavioral details: returns full frontmatter object without 'key' and just the field value with 'key'. This goes beyond annotations by clarifying conditional behavior.

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

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

The description is two concise sentences, front-loaded with the main purpose, and no redundant words. It efficiently conveys the core behavior and condition.

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

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

For a simple read tool with full annotations and 100% parameter documentation, the description is sufficient. It explains what is returned and the key behavior. No output schema exists, but the return type can be inferred. Could benefit from mentioning possible return types (object or scalar), but not a critical gap.

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

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

All three parameters (key, path, title) have descriptions in the schema, achieving 100% coverage. The description adds meaning by explaining how the 'key' parameter affects output (returns field value vs full object). This is extra value beyond the schema's basic descriptions.

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

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

The description clearly states the tool returns parsed YAML frontmatter for a note, with distinction between returning full object versus a single key. It uses specific verb 'Return' and identifies the resource 'frontmatter'. It implicitly differentiates from sibling tools like obsidian_frontmatter_search (search) and obsidian_read_note (full note), though not explicitly.

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

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

The description provides no explicit guidance on when to use this tool versus alternatives like obsidian_read_note for full note content or obsidian_frontmatter_search for searching. However, its behavior is intuitive for reading frontmatter, and the 'Read-only' annotation hints at safe usage. Implied usage is adequate.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, so the safety profile is clear. The description adds the exclusivity of predicates and a use case, but no additional behavioral traits beyond what annotations indicate.

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

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

Three sentences, each earning its place: purpose, use case, and predicate exclusivity. Front-loaded and no wasted words.

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

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

Lacks description of return format or pagination details, but the limit parameter handles max results. Overall sufficient for a search tool with good annotations.

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

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

Schema coverage is 100% with detailed parameter descriptions. The description adds meaningful context about predicate exclusivity and usage pattern, reinforcing and clarifying the schema.

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

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

The description clearly states 'Find every note where frontmatter.<key> matches a predicate', specifying a specific verb and resource. It distinguishes from siblings like obsidian_frontmatter_get (single note) and obsidian_search (general) by focusing on frontmatter predicates.

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

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

Provides a concrete use case example ('find all notes with status:draft and set their status to published') and explicitly states that predicates are exclusive, guiding correct parameter selection. However, it does not mention when not to use it or alternatives.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the description adds value by specifying that results are ranked and include snippets and link kind. No contradictions are present.

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

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

The description is two sentences with no wasted words. The first sentence states the core action, and the second provides key return details (ranked, snippets, link kind). It is front-loaded and concise.

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

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

Given no output schema, the description adequately covers what is returned (ranked hits, snippets, link kind) and implies ordering by rank. It does not address pagination or behavior with multiple target keys, but for a simple tool it is fairly complete.

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

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

Schema coverage is 100%, so baseline is 3. The description mentions 'target note' and 'ranked hits' but does not elaborate on individual parameters (e.g., how path vs title are used). It adds minimal extra meaning beyond the schema.

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

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

The description uses a specific verb ('List') and clearly identifies the resource ('every note in the vault that links or embeds the target note'). It distinguishes from sibling tools like obsidian_get_outbound_links and obsidian_search by focusing on incoming links.

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

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

The description implies usage when backlinks of a note are needed, but it does not provide explicit guidance on when not to use this tool or how it compares to siblings such as obsidian_search or obsidian_get_note_neighbors.

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

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

The description provides extensive behavioral details beyond the annotations (readOnlyHint, idempotentHint). It explains computational complexity, typical performance, caching policy (not cached, call once per session), output semantics (modularity range, convergence condition), and that it's pure structural. This adds significant value for agent decision-making.

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

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

The description is front-loaded with the core action and contains no wasted sentences; each sentence adds value. However, it is somewhat lengthy due to the inclusion of performance metrics and a promotional line ('First MCP server'), which could be trimmed slightly for conciseness without losing essential information.

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

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

The description fully covers the tool's functionality, input, output, behavior, and performance. Even without an output schema, it explains the return structure thoroughly. It addresses all relevant aspects for an agent to use the tool correctly and understand its constraints.

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

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

The parameter schema already covers both parameters with clear descriptions (100% coverage). The description adds extra context beyond the schema, such as describing min_size as useful for 'filtering dust' and clarifying default behavior. This provides additional semantic value.

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

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

The description clearly states the tool computes structural communities over the vault's wikilink graph using greedy modularity optimization (Louvain). It provides a specific verb ('computes') and resource ('communities'), and distinguishes itself from sibling tools by focusing on structural community detection without embeddings.

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

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

The description gives clear context on when to use: for analyzing wikilink graph structure, with a note that it's pure structural (no embeddings) and the server remains LLM-free. It advises calling once per session and reuse, but does not explicitly mention when not to use it or compare with alternatives like embedding-based clustering.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds behavioral detail: it returns three specific buckets (outbound resolved wikilinks, inbound backlinks with count, tag-cluster siblings excluding outbound/inbound). This goes beyond annotations, but does not disclose potential performance or error behavior.

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

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

Two sentences: first states functionality, second explains advantage and use case. No filler, front-loaded with key information.

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

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

No output schema exists, so the description must explain return values. It does so by naming the three buckets and their composition. It also mentions max_per_bucket parameter implicitly. However, it omits details like format of resolved wikilinks or count representation, but still sufficient for typical use.

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

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

Schema coverage is 100%, with descriptions for all three parameters (path, title, max_per_bucket). The description repeats the bucket structure but adds no new semantic detail beyond the schema. Baseline of 3 applies as the schema already does the heavy lifting.

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

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

The description clearly states it returns a note's immediate graph neighborhood (outbound wikilinks, inbound backlinks, tag-cluster siblings) in one call. It distinguishes itself from sibling tools by explicitly mentioning it replaces a chain of calls (read_note → backlinks → outbound → resolve_wikilink).

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

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

The description explicitly states it's designed for RAG-style 'give the LLM enough context to reason about THIS note', which implies when to use. It contrasts with the alternative chain of multiple calls, but does not explicitly state when not to use or list alternatives beyond the implied chain.

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

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

Annotations already indicate readOnlyHint and idempotentHint, so the safety profile is clear. The description adds useful behavioral details (lists embeds optionally, includes resolution status), which goes 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.

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

The description is two sentences, with the main purpose front-loaded. Every phrase adds value, and there is no redundancy.

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

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

Given the tool's simplicity (4 optional parameters, no output schema), the description covers the essential aspects: what it lists, types of links, and resolution status. It lacks details on behavior when both path and title are provided, but overall is sufficient.

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

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

Schema description coverage is 100%, with each parameter having a clear description. The tool description does not add additional meaning beyond what the schema already provides, so baseline score of 3 is appropriate.

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

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

The description clearly states the tool lists outbound links (wikilinks and embeds) with resolution status. It explicitly distinguishes itself as the symmetric counterpart to obsidian_get_backlinks, 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.

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

The description mentions it is the symmetric counterpart to obsidian_get_backlinks, providing a hint for when to use this tool (for outbound links) versus the sibling for inbound links. However, it does not provide explicit when-not or alternative guidance for other siblings.

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

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

Annotations already declare readOnlyHint and idempotentHint, so no contradiction. The description adds that results are ordered by modification, which is useful behavioral context beyond annotations.

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

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

Two short sentences with no unnecessary verbiage. Every word contributes to understanding.

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

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

For a simple read operation with no required parameters, the description is complete enough. It explains the output ordering and use case. No output schema exists, so the description could mention return format, but not strictly necessary.

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

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

Schema coverage is 100%, so the schema already describes all parameters adequately. The description does not add parameter-level meaning, which is acceptable given full schema coverage.

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

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

The description clearly states it lists notes ordered by most recent modification, with a specific use case ('picking up where work was left off'). This distinguishes it from sibling tools like obsidian_list_notes or obsidian_search.

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

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

The description provides a clear use case ('useful for picking up where work was left off'), implying when to use it. However, it does not explicitly mention when not to use it or suggest alternatives.

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

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

Annotations already declare readOnly and idempotent hints. Description adds scanning scope and default include_embeds behavior, consistent 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.

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

Two sentences: front-loaded purpose, then usage context. No wasted words, every sentence earns its place.

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

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

Covers purpose, usage, and parameter defaults. Missing output format details (e.g., list of link paths or texts) but adequate given no output schema and safe annotations.

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

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

Schema descriptions cover all parameters (100% coverage), so baseline 3 is appropriate. Main description adds only the vault-scanning context, not new parameter semantics.

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

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

Description clearly states the verb (Find), resource ([[wikilink]] and ![[embed]]), and scope (vault-wide, unresolved to file). Distinguishes from siblings like obsidian_resolve_wikilink.

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

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

Describes use case as 'vault-hygiene utility' for broken links, typos, intended notes. Does not explicitly exclude other uses or compare to alternatives like obsidian_lint_wiki, but provides sufficient context.

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

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

Discloses key behaviors: uses answer vector not query, typical performance improvement (+2-5 NDCG@10), fallback mechanism. Does not contradict annotations (readOnlyHint, idempotentHint). Lacks mention of rate limits or resource impact, but overall transparent.

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

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

Two short paragraphs, front-loaded with technique name and version, each sentence adding distinct value. No fluff, well-organized for agent parsing.

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

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

Given the tool's complexity (HyDE technique) and absence of output schema, the description covers all necessary aspects: purpose, usage, parameter semantics, prerequisites, fallback, and comparison to sibling. Complete for correct agent invocation.

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

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

Schema coverage is 100%, but description adds significant value: explains why query is used for audit trail, gives guidance on hypothetical_answer style and length, and notes fallback behavior. Enriches schema meaning effectively.

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

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

The description clearly states the tool performs HyDE-augmented embeddings search, explaining the technique and distinguishing it from sibling tools like obsidian_embeddings_search. The verb+resource is specific and unambiguous.

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

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

Explicit instructions on when to use this tool (under-specified queries), how to generate the hypothetical answer (no vault access, 1-3 sentences in note register), and what happens if hypothetical_answer is empty. Also mentions prerequisite setup requirement.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds that it is 'Read-only' and details the five buckets and their structure (path + suggestion), providing behavioral context beyond annotations. No contradictions.

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

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

The description is efficient and well-structured: opens with purpose, lists buckets concisely, explains output format, and ends with 'Read-only'. Every sentence adds value with no wasted words.

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

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

With no output schema, the description fully explains the return format: five buckets each with path and suggestion. It also explains the heuristics for stubs, stale pages, and concept candidates. References to sibling tools for fixing complete the picture.

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

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

All five parameters have good descriptions in the input schema (100% coverage). The description adds some context (e.g., how 'stub_word_threshold' relates to 'under N words') but does not significantly enhance beyond schema defaults.

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

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

The description clearly states 'Comprehensive vault-hygiene check' and lists five specific finding buckets (orphans, broken wikilinks, stubs, stale pages, concept candidates). This distinguishes it from sibling tools like obsidian_stale_notes which only handle one bucket.

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

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

The description implies use when performing a full audit before fixing, mentioning that findings are 'shaped so the agent can fix via existing tools.' It does not explicitly state when not to use it or list alternatives, but the context is clear.

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

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

Annotations already declare readOnlyHint and idempotentHint; description reinforces 'Read-only' and adds context about glob and read-paths honoring, and mtime sort. No contradictions.

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

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

Concise two-sentence description. First sentence states purpose and output, second gives usage guidance. No unnecessary words.

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

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

Description covers purpose, output content (view count and names), sorting, glob/read-paths honoring, and usage recommendation. Missing details on output format and error handling, but sufficient for a simple list tool.

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

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

Schema covers both parameters with descriptions. The tool description does not add additional parameter semantics beyond the schema. Baseline 3 is appropriate.

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

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

Clearly states that the tool lists `.base` files, describes what they are (YAML files for filters/views), and specifies output includes view count and view names. Explicitly distinguishes from sibling tools by recommending this tool for discovery before `obsidian_read_base` or `obsidian_query_base`.

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

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

Explicitly states the tool is for discovering which bases exist before using `obsidian_read_base` or `obsidian_query_base`. Provides context on sorting. Does not explicitly state when not to use, but the use case is well-defined.

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

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

Annotations already declare read-only and idempotent. The description adds detail about node/edge counts and confirms read-only. This is consistent and adds some context, but does not 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.

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

Two sentences with no wasted text. The first sentence conveys the core purpose and features; the second provides the use case. Very efficient.

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

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

Given simplicity (2 params, no output schema, clear annotations), the description is nearly complete. It could optionally mention the return format (e.g., path and counts), but this is not critical for a listing tool.

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

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

Schema coverage is 100%; both parameters have clear descriptions. The description adds no parameter-specific details beyond the schema. Baseline score of 3 is appropriate.

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

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

The description clearly states it lists .canvas files with node/edge counts, and it distinguishes from sibling tool 'obsidian_read_canvas' by positioning itself as a discovery step.

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

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

Explicitly advises using this tool before calling obsidian_read_canvas, providing a clear workflow. It also mentions honoring global flags, though it doesn't explicitly exclude other use cases. A minor improvement would be specifying 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.

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

Annotations already declare readOnlyHint=true, idempotentHint=true, so safety is clear. The description adds useful behavioral context: it returns specific fields (title, path, frontmatter, tags, mtime) and ordering (newest first), which helps the agent understand what to expect.

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

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

Two sentences, front-loaded with purpose and key features. Every sentence provides essential information with no redundancy.

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

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

The description covers return fields and ordering. Since no output schema exists, this is valuable. It could be slightly improved by noting default limit (50) or behavior with no filters, but overall it is sufficiently complete for a list tool with 4 parameters.

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

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

Schema description coverage is 100% (all 4 parameters have descriptions). The description mentions the filtering options but does not add new semantic meaning beyond what the schema already provides. Baseline of 3 is appropriate.

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

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

Description clearly states the verb 'List', resource 'notes in the vault', and specifies filtering options and return fields. It distinguishes from siblings like obsidian_search or obsidian_frontmatter_search by focusing on listing with filters.

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

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

The description implies usage for listing notes with optional filters, but does not explicitly state when to use this tool versus alternatives (e.g., when to use search vs list). No exclusions or when-not guidance is provided.

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

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

Description adds sorting order (newest first) beyond the annotations that already declare readOnlyHint and idempotentHint. No contradictions; the 'Read-only' statement aligns with annotations. Slight redundancy but adds value.

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

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

Extremely concise, with key info front-loaded: what it lists, key facts, and usage guidance. Every sentence is valuable and non-redundant.

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

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 well-covered schema and annotations, the description is complete. It covers purpose, usage context, sorting, and relationship to sibling tools. No gaps.

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

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

Schema coverage is 100% and parameter descriptions are already informative. Description does not add substantive new meaning beyond what the schema provides (e.g., default value for limit is in schema). Baseline 3 is appropriate.

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

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

Description clearly states it lists .pdf files with specific metadata (size, timestamp), distinguishes from siblings like obsidian_read_pdf and obsidian_list_notes, and positions itself as the discovery entry point.

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

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

Explicitly tells when to use this tool ('discover which PDFs exist') and when to use the alternative ('before calling obsidian_read_pdf'). Also mentions configuration options (--exclude-glob, --read-paths) and sorting behavior.

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

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

Discloses behavioral traits beyond annotations: returns tags with usage counts broken down by frontmatter vs inline, sorted by count descending. Annotations already indicate read-only and idempotent nature. No contradictions.

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

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

One sentence, front-loaded with key information, no wasted words. Clearly structured with purpose and output format.

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

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

Given no output schema, description covers essential aspects: what the tool returns (unique tags with counts, sorting). Could mention default behavior for optional parameters, but schema provides defaults.

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

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

Schema coverage is 100%, so description adds minimal value beyond schema. Description implies filtering by folder and min_count, but does not provide additional semantic details beyond what the schema already provides.

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

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

Clearly states verb 'List', resource 'every unique tag', and provides specifics about usage counts (frontmatter vs inline) and sorting (by count descending). Distinguishes from sibling tools like obsidian_search or obsidian_frontmatter_search.

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

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

Implies usage for listing tags with filtering options, but lacks explicit guidance on when to use this tool versus alternatives like obsidian_search or obsidian_frontmatter_search. No when-not-to-use or prerequisite information.

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

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

The description adds significant behavioral context beyond annotations: read-only nature, ~1-2s per page performance, optional dependencies for zero-cost markdown path, Tesseract.js license and pre-installation requirement, no outbound network calls. Annotations already declare readOnlyHint and idempotentHint, and description reinforces 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.

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

The description is detailed and informative, but somewhat dense. It front-loads the main purpose, which is good, but could be more structured (e.g., bullet points). However, every sentence adds value, so it earns a 4 rather than 5 for slight verbosity.

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

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

Given 4 parameters and no output schema, the description is thorough. It explains the tool's role, performance, dependencies, installation, and fallback behavior. It describes return shape ('per-page text + per-page confidence + mean confidence + same shape as `obsidian_read_pdf`'), which compensates for lack of output schema.

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

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

Schema coverage is 100% with descriptions. The description adds extra meaning: default `lang` is 'eng', multi-lang via '+' with max 8 packs; `pages` is 1-indexed inclusive range; `scale` default 2 (~150 DPI), capped at 4, with performance trade-off. This enriches the schema significantly.

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

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

The description clearly states the tool runs OCR on image-only/scanned PDFs, with specific verb 'OCR' and resource 'image-only/scanned PDF'. It distinguishes from sibling `obsidian_read_pdf` by referencing the `has_text: false` return case, ensuring no ambiguity.

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

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

Explicitly says 'Use this when `obsidian_read_pdf` returns `has_text: false`', providing clear context. Also mentions multilingual setup via `lang`, optional `pages` and `scale`, and fallback for missing language data, guiding proper invocation.

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

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

The description adds value beyond annotations by stating no filesystem or network side effects and explaining the URI emission mechanism. It does not contradict annotations, which already declare readOnly and idempotent hints.

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

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

The description is three sentences, to the point, and front-loaded with the core purpose. No unnecessary words.

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

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

The description covers the main output, side effects, and optional parameter behavior. Missing details like vault parameter handling or path/title exclusivity are minor gaps for a simple tool without output schema.

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

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

Schema coverage is 100% with clear parameter descriptions. The main description mentions path and new_pane but not title, and does not explain the relationship between path and title (e.g., exclusivity, fallback). Thus, it adds minimal value over the schema.

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

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

The description clearly states it returns an obsidian://open URI for opening notes in the Obsidian desktop app. It is specific about the action and resource, but does not explicitly differentiate from sibling tools, such as other open or launch tools, though the purpose is distinguishable.

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

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

The description implies usage for handing off to the desktop app without coordination, providing context. It does not explicitly state when not to use or list alternatives, but the context is clear enough for the agent.

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

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

Annotations already declare readOnlyHint and idempotentHint as true. The description adds valuable behavioral details: it scans all notes (walks every note), returns results sorted oldest-first, and mentions ReDoS protection for custom patterns. These details are beyond what annotations provide and are accurate.

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

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

The description is concise (three sentences) and front-loaded with the main action. Every sentence provides essential information: what it does, what it returns, sorting, and a common usage pattern. No wasted words.

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

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

Despite lacking an output schema, the description fully explains the return value structure (source, heading, line number, age) and sorting order. It covers edge cases like ReDoS safety and optional prefixes. Given the tool's simplicity and the thorough description, it is complete for an agent to invoke correctly.

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

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

Schema description coverage is 100% with clear parameter descriptions. The description adds meaning by explaining the default pattern (matching Open question:/Q:/TODO?/?? with optional prefixes) and the ReDoS rejection for pattern overrides. This additional context helps the agent understand parameter usage beyond schema alone.

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

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

The description clearly states the tool's action ('Walks every note for lines matching deferred-thinking markers') and specifies the output format ('Returns each hit with source, the heading it lives under, line number, and age in days'). This distinguishes it from sibling search tools like obsidian_search, which do general text search, and obsidian_frontmatter_search, which targets frontmatter.

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

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

The description provides context for when to use this tool (research-PKM pattern for surfacing open questions) and implies it is not for general search. However, it does not explicitly state when not to use it or list alternative tools. The sibling list is large, so a clearer exclusion would improve the score.

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

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

Read-only declared in text matching annotation. Adds details on scanning body for mismatches and proposing patches. 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.

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

Single paragraph with clear front-loading of purpose. Every sentence adds necessary detail. Not overly verbose.

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

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

No output schema, but description fully explains return structure (flagged notes with identifiers and patches). Covers inputs, logic, and output sufficiently for agent use.

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

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

Schema coverage 100%, description adds default value for 'tag' (paper) and clarifies folder/limit usage. Adds value beyond schema.

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

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

Specific verb 'audit' with clear resource 'paper notes' and criteria for missing citations. Distinguishes from sibling tools that read/search notes without this audit logic.

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

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

Describes what to use it for (auditing paper notes for identifiers) and mentions post-processing steps. No exclusion criteria but context makes usage clear.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds significant behavioral details: version history, supported DSL syntax, fail-closed behavior for unsupported expressions, return of unevaluated_predicates, and the change in behavior permissiveness. No contradictions 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.

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

The description is front-loaded with purpose but includes extensive version history and DSL details that, while useful, may be more than necessary. Could be slightly more concise, but provides valuable detail for correct usage.

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

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

Given the complexity of the DSL and multiple parameters, the description covers return values (matching paths + frontmatter), error handling (unevaluated_predicates), and version changes. No output schema exists, so the description adequately explains what the tool returns.

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

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

Schema coverage is 100% with good descriptions. The tool description adds context about parameter interactions (AND combination of view and global filter, folder as extra scope), but this does not significantly exceed the schema's own descriptions.

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

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

The description clearly states the tool runs a .base file's filter against markdown notes, returning matching paths and frontmatter. It distinguishes itself from sibling obsidian_search by noting this is for explicit saved queries, not retrieval-quality search.

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

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

Provides clear context for when to use this tool (explicit saved queries) and contrasts with obsidian_search. However, it does not explicitly state when not to use or list prerequisites beyond having a .base file.

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

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

Annotations already indicate readOnlyHint=true and idempotentHint=true. The description reinforces the read-only nature and adds that it does not execute queries, providing context beyond annotations. No contradictions.

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

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

Two sentences: first states core functionality, second clarifies what it does not do and provides usage context. No wasted words, front-loaded with key action.

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

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

Given one well-documented parameter, no output schema, and annotations covering safety, the description is complete. It lists the structural components returned but could optionally add more detail about the JSON keys. Still sufficient.

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

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

Single parameter 'path' has schema description coverage of 100%. The description does not add additional meaning beyond what the schema already provides, so baseline score of 3 is appropriate.

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

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

The description explicitly states it parses a .base file into structured JSON, listing the components (filters, formulas, etc.). It distinguishes from sibling obsidian_query_base by clarifying it does not execute queries.

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

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

The description provides clear when-to-use scenarios (introspect structure, surface saved queries) and explicitly warns not to use for query execution, naming the alternative sibling tool.

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

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

Description adds useful behavioral details beyond annotations: output structure with nodes, edges, file_resolved, summary, broken_file_refs. Annotations already declare readonly and idempotent, so description complements well.

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

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

Very concise, front-loaded with main purpose, followed by structured details. Every sentence adds value. No fluff.

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

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

For a tool with 1 parameter and no output schema, the description completely covers inputs and outputs. Includes summary and broken refs info. No gaps.

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

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

Schema has 100% coverage for path parameter. Description adds value by clarifying path is vault-relative and accepts with or without .canvas extension, which is not in schema description.

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

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

Clearly states it parses .canvas files into typed nodes and edges. Specific verb (read) and resource (Obsidian Canvas). Distinguishes from siblings like obsidian_read_note and obsidian_read_pdf.

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

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

Implies use for reading canvas structure, but no explicit when-not or alternatives mentioned. Sibling tools exist for other file types, but description does not guide selection.

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

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

Annotations already indicate readOnly and idempotent. The description adds value by detailing return contents (content, frontmatter, links, etc.), format variants, alias resolution, and error handling with 'Did you mean' suggestions, 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.

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

The description is concise (3 sentences), well-structured with front-loaded main purpose, and each sentence adds necessary detail without redundancy.

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

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

Given the tool is read-only with full schema coverage and no output schema, the description adequately explains all input options and output details, including edge cases like aliases and error suggestions.

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

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

Schema has 100% coverage with descriptions for all 3 parameters. The description adds meaning beyond schema by explaining default format, the semantic difference between 'full' and 'map', and alias usage for titles.

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

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

Description clearly states 'Read a note by relative path or by title', specifying the verb and resource. It also distinguishes output formats and alias resolution, differentiating from sibling tools like search or frontmatter get.

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

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

The description explains when to use 'full' vs 'map' format and mentions periodic-note aliases, but does not explicitly state when not to use the tool or list alternatives. However, context from siblings implies it's for reading a single note, not searching.

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

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

Beyond annotations (readOnlyHint, idempotentHint), description adds that it's read-only, has same path-safety and privacy filter as obsidian_read_note, and is powered by Mozilla's PDF.js. 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.

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

Three concise sentences, front-loaded with main action, then edge case, then implementation details. No redundant words.

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

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

Despite no output schema, description adequately describes return structure (per-page, full_text, metadata, has_text flag). All 3 parameters are clarified. Tool context is complete.

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

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

Schema coverage is 100% but description adds meaning: pages parameter explained as 1-indexed inclusive range for partial reads; path parameter implied to follow safety filter. Adds value beyond schema.

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

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

The description explicitly states it extracts plain text from one PDF, returning per-page text, full_text, and doc-level metadata. It distinguishes from sibling obsidian_ocr_pdf for scanned PDFs.

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

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

Describes when to use obsidian_ocr_pdf for scanned PDFs (has_text: false). Mentions optional pages for partial reads. Does not explicitly state when not to use, but provides clear alternative context.

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

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

Annotations already indicate readOnlyHint and idempotentHint, so the description carries a lower burden. It adds context about handling various link formats, but does not disclose what happens on broken links, return value format, or behavior of include_content. Missing some behavioral details.

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

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

The description is a single sentence that efficiently conveys the core purpose with no wasted words. It is front-loaded with the main action and lists key features compactly.

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

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

Given the tool has no output schema, the description should ideally mention the return value (e.g., file path or content). It says 'resolve to a vault file' but does not specify what is returned. The include_content parameter's effect is not explained. Sibling tools list suggests it's a utility tool, but more detail on output would complete the picture.

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

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

All parameters have schema descriptions (100% coverage), so baseline is 3. The description adds value by explaining the supported link syntax (aliases, sections, block refs, relative paths) beyond the schema examples, helping users understand format variants.

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

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

The description clearly states the tool resolves [[wikilink]] or ![[embed]] to a vault file, listing supported formats like aliases, sections, block refs, and relative paths. It distinguishes itself from sibling tools like obsidian_read_note which read by path rather than resolving links.

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

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

The description implies usage when you have a wikilink string and need to find its file, but does not explicitly mention when not to use it or alternatives like obsidian_read_note for reading content after resolution. No exclusion criteria are provided.

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

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

Annotations provide readOnlyHint and idempotentHint. Description adds extensive behavioral details: auto-detection of signals, degradation paths, RRF fusion with k=60, per-signal observability, PDF inclusion with kind flag, forgetting-awareness (age_days, stale), recency-weight option, graph_boost, and filter_frontmatter. No contradictions.

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

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

Well-structured with bold headings and version markers. Front-loaded with main purpose. However, somewhat verbose with version history details (v2.2.0, v2.3.0, v2.8.0, v3.10) that could be summarized more concisely for an AI agent.

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

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

Comprehensive for a complex tool with 8 parameters, no output schema. Covers retrieval behavior, degradation, observability, graph boost, filtering, forgetting-awareness. Explains return format elements like per_signal, kind, age_days, stale. All necessary context for correct invocation.

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

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

Schema coverage is 100% with descriptions, but description adds significant value: explains default for limit, granularity usage ('block' vs 'note'), graph_boost's unique feature, min_signals for precision, filter_frontmatter with AND logic and array membership. Goes far beyond schema definitions.

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

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

The description clearly states it is 'The default search tool for v2.0' performing hybrid retrieval (BM25, TF-IDF, embeddings). It distinguishes itself from sibling tools like individual _search tools by being the recommended unified search.

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

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

Explicitly says 'Use this instead of the individual _search_text / _full_text_search / _semantic_search / _embeddings_search tools unless you specifically need single-ranker output for diagnostics.' Also discusses graceful degradation and when to use specific parameters like folder and granularity.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. Description adds behavioral context: 'cheap mtime-only scan', 'returns path / title / mtime / age_days'. Mentions 'forgetting-aware staleness' but could elaborate more. No contradictions.

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

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

Two concise sentences front-loaded with the main action and utility. No wasted words, every sentence adds value.

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

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

Without output schema, the description lists returned fields. Covers purpose, usage, behavior, and output. Implicitly references stale_days via 'N days'. Could mention limit/folder defaults explicitly, but overall complete.

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

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

Schema coverage is 100% with clear descriptions for all 3 parameters. Description does not add parameter-specific details beyond the schema, which is acceptable given full coverage. Baseline 3 is appropriate.

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

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

Clearly states it lists stale notes based on age threshold, with a specific verb and resource. Distinguishes from siblings like obsidian_list_notes by focusing on staleness.

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

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

Explicitly says 'Use to surface facts that may be outdated' and 'pick notes to refresh', giving clear context. Does not mention when not to use or contrast with siblings, but the guidance is sufficient.

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

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

Annotations already declare readOnlyHint and idempotentHint, covering safety. The description adds valuable context about performance (one pass over cached parse), which goes 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.

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

Two concise sentences: the first lists all returned metrics, the second provides usage guidance and cost. No wasted words, well front-loaded.

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

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

For a simple tool with one optional parameter, no output schema, but strong annotations, the description provides everything needed: what is returned, when to use it, and its performance characteristics.

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

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

Schema coverage is 100% with a clear description for the single parameter. The description does not add extra meaning beyond the schema, so baseline score of 3 is appropriate.

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

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

The description clearly specifies that the tool returns a vault-wide summary including specific metrics (total notes, total bytes, etc.), and it distinguishes itself from sibling tools by being a one-shot orientation call.

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

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

The description explicitly states it is useful as the first call in a session to provide structural context, and notes that it is cheap (one pass over cached parse), guiding the agent to use it before targeted reads.

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

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

Discloses read-only and idempotent behavior aligning with annotations. Adds details: parses YAML, resolves wikilinks, checks tags/path collisions, returns errors/warnings/diagnostics. Clarifies always available without --enable-write.

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

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

Description is front-loaded with purpose and contains informative sentences without fluff. Each sentence adds value, though could be slightly more concise.

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

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

Covers what the tool does, returns, and prerequisites. Since no output schema exists, the description explains return types (errors/warnings/diagnostics). Lacks details on diagnostics structure but sufficient for an AI agent.

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

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

Schema has 100% coverage, but description adds value by explaining default mode behavior ('create errors if path exists, overwrite/append allow existing') and tying parameters to workflow. Provides context beyond schema's basic descriptions.

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

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

Clearly states 'Lint a draft note BEFORE writing' with specific verb and resource. Distinguishes from siblings by addressing the 'LLM-write pain' and listing specific checks (YAML, wikilinks, tags, collisions).

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

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

Explicitly recommends when to use ('before writing') and provides 'Recommended workflow: validate → fix → obsidian_create_note.' Notes that it does not require --enable-write, but does not explicitly state when not to use or name alternatives.

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