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

Annotations provide no behavioral hints (all false), so the description carries full burden. It discloses creation, default behavior for sides, and the return value (edge UUID). 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?

Three sentences with zero filler. Each sentence serves a distinct purpose: stating the action and prerequisite, detailing optional parameters, and specifying the return value. 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?

For a 6-parameter tool with no output schema, the description covers the essential aspects: purpose, prerequisites, optional parameters, and return value. Could mention error cases but not required for basic 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?

Schema description coverage is 100%, so baseline is 3. The description adds value by reinforcing prerequisite conditions, explaining how to obtain node IDs, and stating the return value—all 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 clearly states the verb ('Create a directed edge') and the resource ('connecting two existing canvas nodes'), and it distinguishes from sibling tools like add_canvas_node by specifying that nodes must already exist and suggesting read_canvas for IDs.

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 prerequisite ('fromNode and toNode must already exist on the canvas') and provides specific guidance on how to obtain those IDs (use read_canvas or capture from add_canvas_node). Also explains optional parameters and their defaults.

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 (which are minimal), the description discloses that the file is persisted (write operation), returns a UUID, and includes auto-stagger logic for coordinates. It does not cover error conditions or permissions, but the key behaviors are 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?

The description is two well-structured sentences, front-loading the core purpose and then detailing node types, return value, and coordinate behavior. Every word earns its place with no redundancy.

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

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

Given 8 parameters and no output schema, the description covers node types, return value, auto-stagger, and content interpretation. It omits prerequisites (canvas file must exist) and error cases, but overall is sufficiently complete for a creation 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?

With 100% schema coverage, the description still adds value by explaining auto-stagger for x and y coordinates, summarizing node type interpretations, and noting default widths/heights already in schema. The added context goes beyond raw schema details.

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 adds a node to an Obsidian canvas and persists the file, using a specific verb+resource. It distinguishes from sibling add_canvas_edge by mentioning the returned UUID is needed to connect nodes.

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 context for when to use this tool (adding nodes) and hints at its relationship with add_canvas_edge via the UUID return. However, it does not explicitly exclude alternatives or state prerequisites like canvas file existence.

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 indicate readOnlyHint=false, consistent with a write operation. The description adds context beyond annotations: the leading newline insertion, failure condition if note doesn't exist, and use cases. No contradictions exist, and the description provides meaningful 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 four sentences, each serving a distinct purpose: purpose, newline behavior, use cases, failure condition and alternative. No extraneous information, well-structured, and front-loaded with the core function.

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 covers key aspects: behavior, newline insertion, failure, and alternative. It could mention the return value or success confirmation, but it's fairly complete for a simple mutation tool. Siblings include both append and prepend variants, but the description only references 'create_note' as alternative.

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 adequate descriptions for both 'path' and 'content'. The overall description restates some info (e.g., newline behavior) but doesn't add significant new meaning beyond the schema. 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?

The description clearly states 'Append text to the end of an existing note' with a specific verb and resource. It distinguishes from siblings like 'prepend_to_note' and 'replace_in_note' by emphasizing appending without altering prior content, and provides use cases (log entries, running lists, new sections).

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 (append to existing notes) and when not (fails if note doesn't exist, recommending 'create_note' instead). It also clarifies the newline insertion behavior. However, it doesn't explicitly contrast with 'prepend_to_note' or 'insert_at_section', which would further 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?

Description explains placeholder substitution behavior in detail and failure condition on duplicate. Annotations are minimal (no readOnly/destructive hints), so description carries burden well, adding useful context beyond 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?

Three sentences with no redundancy. First sentence states core purpose, second details template, third states failure condition. Each sentence earns its place. Perfectly 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 all essential aspects: purpose, optional date, template substitution, failure on duplicate. No output schema needed for a create tool; the description is sufficient. Could mention whether note is opened after creation, but not critical.

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 value by explaining template placeholder behavior and interaction between content and templatePath (content ignored if templatePath provided). This enriches the parameter meaning 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 action (create), resource (daily note), and context (today/specific date, configured folder/format). It distinguishes from siblings like create_note (generic note) and get_daily_note (retrieval) by specifying the daily-note folder and failure on duplicate.

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: can be used for today or specific date, optionally with template. States failure condition (if daily note already exists), implicitly guiding against calling when note exists. Could be more explicit about when to use over create_note, but still strong.

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?

Describes key behaviors: fails on existing note (no overwrite), auto-creates directories, appends .md extension. Annotations are minimal, so description provides essential transparency.

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 main purpose. Every sentence adds 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?

For a tool with 3 parameters and no output schema, the description covers purpose, constraints, usage guidelines, and parameter context completely.

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. Description adds value by clarifying 'body content', 'optional YAML frontmatter', and path behavior beyond schema 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 it creates a new markdown note at a given path with body and optional frontmatter. It distinguishes from siblings by specifying when to use other tools like append_to_note.

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 fails if a note exists and directs to alternatives (append_to_note, prepend_to_note, update_frontmatter). Also notes automatic directory creation and .md extension addition.

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?

Goes well beyond annotations by detailing trash folder behavior, recovery, reference removal conditions, and the confirm safety latch. No contradiction with destructiveHint=true.

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

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

Three sentences, front-loaded with main purpose, then details. No wasted words; every sentence is informative and necessary.

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 destructive nature and 4 parameters, the description fully covers behavior, safety, and edge cases (reference removal ignored when trashing). No output schema needed.

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 all parameters (100% coverage). The description adds value by explaining interactions (e.g., permanent+confirm, removeReferences only works with permanent), though schema already provides 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 'Delete a note' and distinguishes between trashing (recoverable) and permanent deletion, making the purpose unambiguous and differentiating it from sibling tools like move_note.

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 permanent vs non-permanent deletion and the safety confirm flag. It lacks explicit guidance on when not to use this tool versus alternatives like archive or move, 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?

Discloses that the trailing ^id anchor is preserved, which is key behavioral info beyond annotations. No contradiction with annotations. Does not mention error cases (e.g., missing block or note), but annotations already indicate destructive 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, front-loaded with purpose, every word earns its place. 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?

No output schema, but description does not need to explain return values for a mutation tool. Adequate for the tool's simplicity; could mention success confirmation or error handling, 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?

Schema coverage is 100%, and description adds valuable semantic detail: clarifies that block can include or omit leading ^, and that ^id is appended automatically to newContent.

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 explicitly states 'Replace the content of a block tagged with ^id', includes the use case 'update a single paragraph or list item that other notes reference', and distinguishes from sibling tools like replace_in_note and append_to_note.

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 ('update a single paragraph or list item that other notes reference') and explains the anchor preservation benefit, but could explicitly mention when not to use (e.g., for larger edits use replace_in_note).

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 show readOnlyHint and idempotentHint, consistent with scanning. Description adds behavioral context: returns per-source report, total count, only truly unresolvable links reported, uses whole vault for resolution, and groups entries by source note.

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?

Four sentences, each essential. Front-loaded with purpose. No filler or redundancy. Efficiently provides all necessary context without excess.

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?

Even without output schema, description explains return format (per-source report with broken link text, line numbers, total count). Covers scanning scope and resolution behavior. Contextually complete for a scan 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 100% of parameters. Description adds meaning beyond schema: folder restricts scan but resolution uses whole vault; maxResults groups by source and summarizes remaining entries. This helps agent understand behavior beyond parameter limits.

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 tool scans for wikilinks whose target does not resolve, returns per-source report with broken link text and line numbers, and total count. It distinguishes from sibling tools like find_orphans or find_unused_attachments by focusing on dangling references after renaming/moving/deleting.

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 to use after renaming, moving, or deleting notes to catch dangling references. Also clarifies that resolution uses whole vault even when scanning a single folder. No explicit when-not, but context is clear and helpful.

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 mark it as read-only/idempotent. Description adds detail on three classification groups, return structure (counts always full, examples capped), and parameter behavior (includeOutlinksCheck).

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, efficient and well-structured. Front-loaded with purpose, followed by detailed classification and usage. 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?

Given no output schema, description adequately explains return structure (counts per category, example list capped by maxResults). Covers main behavioral aspects for effective 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 covers parameters with descriptions. Description adds meaning by explaining how maxResults caps examples per category and how includeOutlinksCheck affects reporting groups, 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?

Clearly identifies the tool's function: finding disconnected notes in the link graph with three specific categories. Distinguishes itself from siblings like find_broken_links by focusing on orphan detection.

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 use cases: surface abandoned notes, missing hub pages, or archiving candidates. Provides good context but lacks explicit when-not-to-use or alternative tool references.

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 discloses key behavioral traits beyond annotations: it uses existing chunk embeddings from the source note, makes no live API call, and is fast and free. It also notes the exclusion of the source note. No contradictions with readOnlyHint and idempotentHint.

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 with two focused sentences: the first states the core purpose, the second adds behavioral context and a prerequisite. No redundant or extraneous 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 is mostly complete given the tool's simplicity and available annotations. However, it does not specify the return format (e.g., list of note paths or scores). With no output schema, a brief mention of the return structure would enhance 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 input schema already covers both parameters with full descriptions (100% coverage). The description adds marginal value by explaining that 'K' corresponds to the limit and that the source note is excluded, but these are largely implicit in 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 the action: given a note path, return semantically similar notes from the index. It specifies the resource (notes) and distinguishes from sibling tools like search_semantic by highlighting the use of existing embeddings without live API 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 provides a clear prerequisite (run index_vault first) but does not explicitly state when not to use this tool or compare it directly to alternatives. The context implies use cases but lacks explicit exclusions.

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 mark readOnlyHint and idempotentHint; description adds that it deliberately avoids unlinking files. This extra behavioral detail helps the agent understand tool's limitations 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?

Two sentences, each serving a purpose: first explains what the tool does, second gives usage context. No fluff, front-loaded, easy to scan.

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, so description should convey return format. It mentions 'unused-attachment paths' and 'total reclaimable bytes' but doesn't specify exact structure (e.g., array of strings vs objects). Otherwise covers purpose, parameters, and usage well.

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 (limit, includeBytes) with descriptions. Description adds nuance: for includeBytes, it mentions reporting total reclaimable bytes, and for limit, it notes total counts are still reported even when truncated. This 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?

Clearly states the tool locates attachments unreferenced by any note, specifying two reference types (`![[file]]` and `[text](file)`). Distinguishes itself from siblings like `find_broken_links` and `find_orphans` by focusing on attachments and explicit exclusion of unlinking.

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?

Specifies when to use (before archiving or sync) and what not to expect (tool doesn't delete/unlink, suggests pairing with shell deletes). Could explicitly compare to siblings but current guidance 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?

Beyond the annotations (readOnlyHint, idempotentHint), the description discloses that images return as `image` blocks, audio as `audio` blocks, others as base64 `resource`, and that attachments must be inside the vault. It also specifies the 5 MB default cap with maxBytes up to 50 MB. 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?

Three sentences, each serving a distinct purpose: purpose, return types and size limit, and exclusions with alternatives. No redundancy, 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?

Given the tool's binary file reading nature, the description covers return formats, size limits, vault scope, and file type restrictions. With no output schema, the description sufficiently explains what to expect. It also cross-references sibling tools for 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?

Schema description coverage is 100%, so baseline is 3. The description adds context about maxBytes' default (5,242,880 bytes) and hard cap, and explains that path is vault-relative. While it doesn't add much for path, the description of how maxBytes affects the behavior (raising cap) provides marginal added value, justifying a 4.

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 reads and returns attachment bytes, specifies the return types (image, audio, resource), and explicitly distinguishes itself from siblings by noting that .md, .canvas, and .base files are rejected and should use get_note, read_canvas, or read_base instead.

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 explicit when-to-use and when-not-to-use guidance: for binary attachments, not for text-format files. It mentions the default 5 MB cap and how to raise it via maxBytes, and suggests alternative tools for rejected file types.

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 show readOnlyHint and idempotentHint. Description adds valuable behavioral details beyond annotations: accepts paths with/without .md extension and fallback to basename matching. 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?

Three sentences, no wasted words. Front-loaded with purpose, then output details, then usage context, then edge cases. Perfectly sized.

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 lists output fields (source path, line, context). Covers purpose, output, usage, and fallback behavior. Complete for a read-only 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% with description on path. Description adds meaning: relative path, extension optional, and fallback behavior. Goes beyond schema to provide practical usage guidance.

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 notes with wikilinks to the target, with specific output details (source path, line number, context). Distinguishes from sibling get_outlinks 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?

Explicitly says when to use (understand references, assess rename/delete impact). Does not mention when not to use or compare to siblings like find_broken_links, but context is clear enough for typical use.

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, but the description adds value beyond these by stating that the tool errors if no note exists and describing the return structure (path, frontmatter, body). 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 two sentences long, front-loads the core functionality, and contains no filler. Every sentence adds 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?

For a simple read tool with one optional parameter and no output schema, the description is complete: it covers purpose, error case, return values, and ties to related tool. Could mention that the frontmatter is parsed, but it's already implied.

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?

With 100% schema description coverage (the single 'date' parameter is well-documented with pattern, format, and default), the description does not add new semantic meaning beyond what the schema provides. 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 reads the daily note for today or a specific date, resolved via the vault's configured folder and filename format. It specifies the return values (path, frontmatter, body) and distinguishes itself from create_daily_note by mentioning error case and alternative.

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 says to use create_daily_note if no note exists, providing a clear when-not-to-use guideline. However, it doesn't contrast with other read tools like get_note for non-daily notes, which could help an agent decide between 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 readOnlyHint and idempotentHint. Description adds specific behaviors: early truncation at maxResults with a notice, neighbor tagging with hop distance and direction, and traversal stopping at depth cap. 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 plus a bullet list of use cases. Front-loaded with main action. 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?

Despite no output schema, the description explains return format (grouped by depth, tree visualization, tagging with hop distance and direction). Covers all necessary aspects for a complex graph traversal 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% with descriptions for all 4 parameters. Description adds extra meaning: path accepts .md extension or not, depth range and exponential growth warning, direction clarification, maxResults early stop behavior.

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 traverses the wikilink graph outward from a starting note, returning reachable notes grouped by depth with visualization and tagging. This distinguishes it from siblings like get_backlinks or get_outlinks which handle single-hop 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?

It explicitly mentions use cases: exploring topic clusters, mapping neighborhoods, finding related notes beyond direct links. It also clarifies path handling with or without .md extension. Lacks explicit when-not-to-use 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?

Goes beyond annotations (readOnlyHint, idempotentHint) by detailing behavior: fragment modes skip frontmatter/tag header, return raw text; full mode returns parsed frontmatter, tags, and body. 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?

Front-loaded with main action, followed by concise mode explanations. Every sentence adds value; no redundancy. Well-structured for quick 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?

Completes the picture for a tool without output schema by describing return format per mode. Covers all parameters and usage scenarios adequately.

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?

Adds significant meaning beyond schema: for 'section' explains path-form support, for 'block' clarifies block id format, for 'lines' specifies 1-indexed inclusive range. Complements 100% schema coverage with contextual details.

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 'Read a note in full or as a fragment' and distinguishes four modes (full, section, block, lines). Differentiates from sibling tools like get_backlinks or get_recent_notes by focusing on note content retrieval.

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 describes when to use each fragment mode ('keep token usage tight on long notes') and what each returns. Provides clear context for selection without needing 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=true and idempotentHint=true. The description adds value by specifying that links are partitioned into categories and that raw text and resolved paths are returned. No contradictions; it supplements the annotations with functional 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 sentences with no wasted words. Key information is front-loaded: what it does, then the partitioning details, then usage guidance.

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 one parameter, full schema coverage, no output schema, and clear annotations, the description is complete. It explains the output categories and usage. Minor omission: no mention of how aliases or transclusions are handled, but this is acceptable for a focused 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?

The single parameter 'path' is already well-documented in the schema (100% coverage), including an example. The description mentions return values but does not add new semantic meaning to the parameter 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 clearly states the tool lists outgoing wikilinks from a note, partitioning them into valid, broken, and file embeds. It uses specific verbs ('List') and resources ('outgoing wikilinks'), and distinguishes from siblings like get_backlinks which handles 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 provides explicit usage scenarios: 'audit a note's references, detect broken links, or follow downstream dependencies.' However, it does not explicitly contrast with find_broken_links, which is a sibling tool for broader link checking.

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 agent knows it's safe and repeatable. The description adds ordering behavior and the optional `since` filter syntax (ISO date or relative span), going beyond what annotations provide. 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 two sentences, front-loading the core purpose and then explaining the filter. 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?

Given the simple tool (3 parameters, no output schema), the description covers the main functionality, ordering, filter options, and use cases. It doesn't detail pagination or error handling, but those are implicit from the schema (limit param) and annotations. Adequate for the complexity level.

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. The description adds value by giving concrete examples for `since` (e.g., '7d', '24h', '2w'), which clarifies usage beyond the schema's generic text. For limit and folder, the description doesn't repeat schema details, 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 'List notes ordered by most-recently-modified first', specifying the verb (list), resource (notes), and ordering. It distinguishes from related tools like list_notes (which likely has no ordering) and search_notes (query-based) by focusing on recency and offering a time filter.

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 concrete use cases: 'surfaces what you've been working on', 'what changed this week digest', or 'pick targets for review'. While it doesn't explicitly exclude alternatives like search_notes or get_note, the use cases implicitly guide when to use this 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?

Annotations already provide readOnlyHint and idempotentHint. The description adds value by revealing the mtime cache mechanism, explaining performance behavior for repeated calls.

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 output description and use case. Every sentence adds value 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?

Despite no output schema, the description explicitly lists all return fields and explains caching behavior. For a simple read tool with one optional parameter, this 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 description covers the single parameter (folder) 100%. The description does not add new semantic information beyond stating 'restrict stats to this folder', which aligns with 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 the tool returns a health snapshot with specific fields (note count, bytes, words, etc.) and explicitly distinguishes it from siblings by its aggregate nature. No sibling offers vault-wide stats.

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?

Description advises use for dashboards and health checks, and notes cheap repeat calls via cache. While it doesn't mention when not to use, the purpose is self-explanatory and unique among 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?

The description adds context beyond annotations: it splits notes into heading-aware chunks, embeds via configured provider, persists to a specific file, and emits progress notifications. Annotations already indicate idempotent and non-destructive, which align with description.

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?

Four sentences front-loaded with purpose, then process, incremental behavior, force usage, and progress notifications. 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 tool's behavior, side effects, and progress notifications. Annotations cover safety. Complete for the tool's complexity.

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

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

Schema covers 100% of parameters with descriptions. The description adds minimal additional meaning beyond incremental behavior related to force. 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 builds or refreshes the embedding index used by search_semantic and find_similar_notes. It specifies the verb (build/refresh) and resource (embedding index) and distinguishes it from sibling tools that consume the index.

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 incremental behavior and when to use force (re-embed everything after model changes). The folder parameter restricts indexing. However, it does not explicitly mention when not to use this tool or alternatives beyond referencing search_semantic and find_similar_notes.

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?

With all annotation hints set to false (readOnly, openWorld, idempotent, destructive), the description compensates by stating the tool is non-destructive ('without replacing it'). It also details the three position behaviors, adding context about insertion points. 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?

Two sentences, no superfluous words. The first sentence states the core purpose, the second explains position options and a concrete use case. Every part 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?

For a tool with no output schema and straightforward input, the description covers what it does, the position variants, and a typical use scenario. It does not mention error handling or prerequisites, but given the context, it is sufficiently complete for an agent to select and 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%, providing a baseline of 3. The description adds value by explaining the 'position' enum in plain language ('before', 'after-heading', 'append') and the trailing newline normalization hint for 'content', which goes beyond the schema's brief 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 uses the specific verb 'Insert' and identifies the resource as 'content into a specific section'. It clearly differentiates from siblings like append_to_note (which appends to entire note) and update_section (which replaces), by stating 'without replacing it'. The explanation of position values further clarifies the exact insertion behavior.

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: 'add a new bullet or paragraph without rewriting the section.' It implicitly distinguishes from replace_in_note by emphasizing non-replacement. However, it does not explicitly state when not to use or list alternative tools, leaving some inference to 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 declare readOnlyHint, idempotentHint, openWorldHint. Description adds behavioral context: returns sorted list of relative paths and per-extension count summary. It clarifies scope ('beyond notes/canvases/Bases'). 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?

Three sentences: first states action, second output, third use cases. No wasted words. Front-loaded with core purpose.

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 adequately describes return format (sorted list + count summary). Lacks mention of limit's effect on count or pagination, but is sufficient for a 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 description coverage is 100%, so baseline is 3. The description does not add meaning beyond schema for limit and extension. It mentions output structure but not parameter details.

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 enumerates every non-markdown file in the vault, listing specific file types (images, PDFs, audio/video clips). It uses specific verb 'enumerate' and resource 'non-markdown file', distinguishing it from siblings like list_notes or list_bases.

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 explicit use cases: 'audit assets, find duplicates by name, or pick targets for find_unused_attachments.' This guides when to use, though it doesn't explicitly state when not to use it or mention alternatives beyond the sibling reference.

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 details: returns sorted list, relative paths, and count. It does not contradict 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?

Three sentences, each adding unique value: enumerates, defines bases, describes output, suggests next steps. No wasted words, 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?

With no parameters and no output schema, the description fully explains the tool's operation and output. It is self-contained and sufficient for an agent to use 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?

The tool has no parameters, and schema coverage is 100%. The description does not need to add parameter details, and the baseline score for 0 params is 4.

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 enumerates every .base file in the vault, defines what a base is, and specifies the output (sorted relative paths and count). It clearly distinguishes the tool's purpose from siblings by focusing specifically on .base files.

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 pairing with read_base or query_base, indicating a typical workflow. While it doesn't explicitly contrast with sibling list tools like list_notes or list_attachments, the context and tool name make its 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=true, idempotentHint=true, openWorldHint=false. The description adds that it scans entire vault and takes no parameters, but no new behavioral traits 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, efficient, front-loaded with key information, no waste.

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 parameters and no output schema, the description is complete: it specifies scope, return type, and usage context.

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?

No parameters, baseline 4 per guidelines. The description correctly states 'Takes no parameters'.

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 enumerates Obsidian canvas files, returns a numbered list of relative paths and total count, and distinguishes from sibling tools by noting it scans the entire vault and takes no parameters.

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 to use to discover available canvases before calling read_canvas, add_canvas_node, or add_canvas_edge, providing clear context and 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 signal readOnly and idempotent. Description adds truncation behavior (limit truncates output but full count reported) and that the list is sorted, which are helpful 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, zero fluff. First sentence defines core action and output, second sentence provides usage guidance. 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?

Despite lacking an output schema, the description fully explains return format (sorted relative paths and total count) and detailed behavior around limit. Sufficient for an agent to correctly invoke.

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. Description adds value by clarifying truncation semantics and that folder restricts scope. This goes beyond schema 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?

Description uses specific verb 'enumerate' and resource 'markdown notes', specifies scope (vault or folder), and lists use cases (browse, file picker, batch processing) that distinguish it from sibling search or retrieval tools.

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 when to use (browse structure, file picker, batch processing) and, by contrast, implies not for content search. While no direct exclusion of alternatives, the context is sufficient for an agent to decide.

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. Description adds behavioral detail by stating it returns a tree of paths with depth, which goes beyond annotations 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?

Two sentences that convey essential information without any fluff. Each 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 listing tool with one parameter and no output schema, the description sufficiently explains what the tool does and the nature of its output (tree with depth).

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 'path' parameter. The description does not add additional meaning beyond what the schema provides, so 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 explicitly states it lists headings as a tree of paths with depth, which is specific. It also mentions its utility for discovering section arguments, distinguishing it from related tools like get_note or update_section.

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?

Directly states that the tool is useful for discovering valid section arguments before calling other tools (get_note, update_section, insert_at_section), providing clear guidance on when 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?

Beyond annotations (readOnlyHint, idempotentHint), description adds detection sources (inline, YAML), case-insensitive normalization, and output details (sorted list, total count). 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?

Two sentences, front-loaded with purpose, no extraneous words. Highly concise and well-structured.

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 simple tool (1 param, read-only, no output schema), the description fully covers functionality, usage, and output. Complete for its complexity.

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 the only parameter (sortBy) with enum and default. Description adds no new parameter-specific info beyond mentioning 'sorted list', which is sufficient given high 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?

Clearly states it enumerates unique tags, detects from inline and YAML, normalizes case-insensitively, and returns sorted list with total count. Differentiates from sibling tools like search_by_tag and rename_tag.

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 provides use cases: build tag cloud, pick categories, audit taxonomy, and discover tags before calling search_by_tag. Also implies when to use it before other operations.

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 indicate destructiveHint: true. Description adds specifics: content preserved, parent folders created, links updated by default, and .md extension auto-added. 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?

Three sentences with no wasted words. Each sentence adds meaningful information: action, parent folder behavior, link update trade-off, and automatic extension.

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 covers key effects. Missing explicit mention of what happens if destination already exists or error cases, but overall sufficient for common 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 each parameter. Description adds value by noting automatic .md extension addition and explaining updateLinks default behavior, but schema already conveys basics.

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 'Move or rename a note within the vault, preserving its full content.' This is a specific verb (move/rename) and resource (note), and it distinguishes from related tools like create_note or delete_note.

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 explains when to use default updateLinks behavior vs. setting false for speed, and suggests pairing with find_broken_links for auditing. Also mentions parent folder creation as needed.

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 indicate write operation (readOnlyHint=false), and description adds specifics: inserts after frontmatter, fails if missing. 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?

Three focused sentences front-loading the main action and key constraint (frontmatter placement), with no superfluous 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?

Complete for a simple 2-parameter tool with no output schema; covers behavior, constraints, and use cases adequately.

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?

100% schema coverage with descriptions; description adds context about placement after frontmatter but no extra parameter details 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 clearly states the tool inserts content at the top after frontmatter, distinguishing it from 'append_to_note' and other 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?

Provides clear use cases (front of lists, pinning context, TL;DR) and notes failure if note doesn't exist, but lacks explicit alternatives for similar 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 mark it as read-only, idempotent, and not open-world. The description adds critical behavioral context: unsupported clauses are reported as warnings and treated as match-all, and it enumerates supported filter syntax and recognized file properties. This goes well 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?

The description is front-loaded with the core purpose and then expands on syntax and behavior. While it is somewhat lengthy, every sentence adds value (syntax details, unsupported clause handling). It could be slightly more concise, but it remains well-structured and informative.

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 4 parameters, no output schema, and moderate complexity, the description covers purpose, parameters (via schema and description), filter syntax, and edge cases (unsupported clauses). It lacks an explicit description of the output structure beyond 'matching note paths', but the overall completeness is high.

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 significant meaning by detailing the filter syntax and recognized properties, which is not present in the schema. However, the description does not elaborate on the 'view' parameter's expected format or behavior beyond 'apply view filters and ordering'. This prevents a 5.

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 filters against the vault and returns matching note paths. It specifies the action ('Run'), the resource ('Base file's filters'), and the output ('matching note paths'). It also distinguishes itself from siblings like search_notes by focusing on Base file-driven 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 explicitly explains when to use this tool (to apply Base file filters with optional view) and provides detailed filter syntax, which serves as usage guidance. It does not explicitly state when not to use it, but the context of siblings and the specificity of the Base file mechanism imply the appropriate scenarios.

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 value by detailing what is returned (filters, properties, view definitions, unrecognized fields), which gives a clear picture of the tool's output 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, perfectly concise. First sentence describes what it returns, second gives usage advice. 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?

Given the tool's simplicity (one parameter, read-only, no output schema), the description covers the purpose, return content, and usage context adequately. Missing error handling details but standard for such a 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% with a well-described single parameter. The description does not add extra semantics beyond the schema's parameter description, 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?

Clearly states it returns parsed contents of a Base file, listing exactly what is returned (filters, properties, view definitions, etc.). Distinguishes from sibling tool query_base by noting its use as a discovery step before querying.

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 to use tool to discover queries that a Base supports before calling query_base. Provides clear context for when to use, though does not mention when not to use or alternatives like list_bases.

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 (readOnlyHint, idempotentHint) already declare safety; description adds specific output details (node properties, edges). 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?

Two sentences, no fluff, front-loaded with purpose. 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?

Single simple parameter fully covered, no output schema needed, description explains return format. Complete for this low-complexity 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% with a well-described 'path' parameter. Description does not add additional meaning beyond the schema, warranting baseline 3.

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 reads a .canvas file and returns a structured summary of nodes and edges. Distinguishes from siblings by mentioning usage before add_canvas_node/add_canvas_edge.

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 inspect or navigate a canvas before calling add_canvas_node or add_canvas_edge', providing clear when-to-use and naming 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?

The description adds important behavioral context beyond annotations: it explains hierarchical rebasing, dry-run mode, and the requirement to strip leading '#'. The annotations indicate destructive behavior, and the description confirms and elaborates 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 (three sentences), front-loaded with the main purpose, and each sentence adds necessary detail. No fluff or repetition.

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, no output schema, and annotations, the description adequately covers all behavioral aspects: scope, hierarchical behavior, dryRun, and parameter formatting. It is complete for the tool's complexity.

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

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

The input schema has 100% description coverage, so baseline is 3. The description provides additional meaning by explaining the leading '#' removal and the effect of hierarchical=true, which adds value 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 clearly states the tool renames a tag everywhere in the vault, including inline #tags and frontmatter fields. It provides specific scope and distinguishes itself from sibling tools (no other rename tool exists).

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 implicitly makes the usage clear by stating the tool's purpose. While it does not explicitly mention when to use alternatives, the naming and context make it obvious; however, no explicit when-not-to-use or alternatives 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 indicate destructiveHint=true and readOnlyHint=false. The description adds valuable behavioral context: the expectedCount guard prevents accidental over-replacement, and it returns the replacement count. This 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?

The description is three sentences, each adding critical information. It is front-loaded with the core purpose, then explains the regex option and safety guard, and finally the return 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?

For a destructive tool with 6 parameters and no output schema, the description covers the operation, the guard, and return value. It does not explain error handling for expectedCount mismatch (e.g., what happens if count doesn't match), but the phrase 'refuses to commit' implies an abort. Adequate but has a minor 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?

Schema coverage is 100%, so parameters are documented. The description adds meaning by explaining the distinction between literal and regex, the purpose of expectedCount (guard against over-replacement), and that backreferences work with regex. This is useful context beyond schema 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 it performs a search-and-replace within a single note, supporting literal strings and regex. This distinguishes it from sibling tools like append_to_note or edit_block, which are not find-and-replace operations.

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 specifies it operates on a single note, implying when to use it. It does not explicitly mention when not to use it or provide alternatives, but the context is clear enough. The expectedCount guard adds usage guidance.

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. Description adds case-insensitive matching and fallback behavior for basename, which supplements the structured data 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?

Three sentences, each earning its place: first explains core function, second details optional behavior, third provides usage guidance. No fluff, well-structured.

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 implies return type (list of note paths) but doesn't specify format. However, with 2 simple parameters and clear annotations, it adequately completes the context.

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 enriches both parameters: explains 'name' is case-insensitive and 'includeBasename' defaults to true with matching logic. Adds useful behavioral nuance 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 clearly states the tool's action: find notes whose frontmatter aliases field contains a given name case-insensitively. It also distinguishes from sibling tools by specifying it translates human-friendly titles to actual note paths before calling get_note.

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 explicit usage context: 'Use to translate a human-friendly title... before calling get_note.' This tells the agent when to use this tool and references a sibling tool, guiding correct 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 detailing case-insensitive comparison, array matching, and that results include full frontmatter. Annotations only indicate readOnly and idempotent, so this extra context is beneficial.

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, front-loaded with purpose, then providing matching behavior and usage hints. It is concise and well-structured, with 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 purpose, matching logic, return value, and usage context. It is complete for the tool's complexity, especially given the high schema coverage and 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 description coverage is 100%. The description reiterates case-insensitivity and array matching, which are already in the schema, so no significant new semantics are added. 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's purpose: 'Find notes whose YAML frontmatter contains a given property/value pair.' It specifies a specific verb and resource, and the function is distinct from sibling tools like search_by_tag or search_notes.

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 suggests use cases: 'Use to filter notes by metadata like status, type, or tags stored in frontmatter.' It provides clear context but lacks explicit when-not-to-use guidance or comparisons to 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?

The description discloses key behavioral traits beyond the annotations: it explains nested sub-tag matching, detection from both inline and YAML frontmatter, and the return format (note paths with optional content previews). This adds significant context on top of the readOnlyHint and idempotentHint 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 concise at three sentences, each serving a distinct purpose: stating the main function with a key feature, adding a detail on tag sources, and providing a use case. It is front-loaded with the verb and resource, 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?

For a simple search tool with three parameters and no output schema, the description covers the primary functionality, tag matching behavior, and return type. It is mostly complete, though it does not mention result ordering or pagination limits; however, these are covered in the schema for maxResults.

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 input schema has 100% coverage and already contains detailed descriptions for all three parameters (e.g., tag, maxResults, includeContent). The tool description does not add new parameter-level meaning beyond what the schema provides, so it meets the baseline of 3.

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 verb 'Find' and resource 'all notes tagged with a specific tag', and distinguishes itself from siblings by explicitly mentioning nested sub-tags and detection from inline #hashtags and YAML frontmatter. It also provides a concrete use case: 'collect notes belonging to a topic, area, or workflow stage'.

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 when to use the tool ('Use to collect notes belonging to a topic, area, or workflow stage'), and its mention of nested sub-tags implicitly differentiates it from other search tools. However, it does not explicitly state when not to use it or compare to specific alternatives, which would elevate it to a 5.

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 details on return format (paths with line numbers and snippet content) which is consistent and valuable. 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, zero waste. Front-loaded with the core functionality and return format. Efficient and easy to parse.

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 explains return format. Suggests pairing with get_note for completeness. Covers behavior adequately; minor omission of what happens on no results, but overall complete for a search 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 description coverage is 100%, so baseline is 3. The description does not add new meaning beyond what the schema already provides (e.g., query is literal, folder restricts, etc.)

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?

Clear verb+resource: 'full-text search across all notes'. Distinguishes from siblings like search_by_tag and search_semantic by specifying full-text and return format (paths with line numbers and snippets).

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 when to use: 'locate notes containing a phrase, keyword, or code fragment'. Provides a recommended pairing with get_note for full bodies, implicitly guiding against using it when tag-based or semantic search would be more appropriate.

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?

Above and beyond annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses that the tool embeds queries, scores all chunks, deduplicates results, and does not auto-index due to cost. This equips the agent with operational understanding of the tool's 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?

Three sentences, each serving a distinct purpose: definition of functionality, explanation of internal process, and actionable usage guidance (prerequisites and pairing with get_note). No wasted words; front-loaded with critical 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?

Covers prerequisites, mechanism, and output structure (deduplicated best-matching note). However, lacks explicit mention of output format (e.g., list of notes with scores) and behavior for empty results. Given no output schema, these details would enhance 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?

Schema description coverage is 100%, so the baseline is 3. The description adds high-level context but does not significantly enhance the parameter descriptions beyond what the schema already provides. For example, the query parameter is already well-described in 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 'Search notes by meaning rather than keywords', clearly distinguishing it from keyword-based search tools like search_notes. It also details the mechanism (embedding, scoring, deduplication), making the specific purpose unmistakable.

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?

It instructs to run index_vault first and explains why auto-indexing is disabled (embedding cost). It pairs with get_note for retrieval, providing a clear workflow. However, it does not explicitly list when not to use it or mention alternative sibling tools like search_by_tag.

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 the annotations (destructive, idempotent), the description details that the YAML block is regenerated, normalizing comments, quoting, multi-line scalars, blank lines, and key ordering. It also notes that it creates a frontmatter block if none exists. This fully discloses side effects.

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

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

Two paragraphs: first states purpose and return value, second warns about formatting normalization. Front-loaded with key information, 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?

Given no output schema, the description includes the return value (count of properties written). It covers all necessary aspects: merge semantics, behavior on missing frontmatter, and formatting caveats. Sibling context is naturally handled, and the definition is self-contained.

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 both parameters. The description adds value by explaining the merge behavior: 'Keys in the payload overwrite existing values' and 'Existing keys not in the payload are preserved,' which is not fully captured in 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 merges key-value pairs into YAML frontmatter, preserving existing keys and body content. It distinguishes itself from siblings like replace_in_note or update_section by focusing solely on frontmatter metadata.

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?

It explicitly says 'Use to set status fields, tags arrays, or other metadata without rewriting the body.' This provides clear guidance on when to use the tool, though it does not explicitly mention alternatives for body changes.

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 indicate destructiveHint=true and idempotentHint=true, consistent with a replacement operation. The description adds behavior beyond annotations by stating the heading line is preserved and defining the section scope as 'everything between a heading and the next heading at any level'.

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 with two sentences plus a parenthetical detail about the section parameter. It is front-loaded with the primary action and efficiently provides necessary usage instructions 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's mutative nature and no output schema, the description adequately covers input behavior and constraints. It clarifies what is replaced and preserved. However, it does not address edge cases like missing sections, which could be inferred but not explicit.

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 the description adds meaningful context: 'section' is a heading path with case-insensitive and whitespace-tolerant matching, 'newBody' is replacement content without the heading, and 'path' explicitly requires extension. This supplements the schema well.

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 replaces the body of a specific section, preserving the heading line. It distinguishes itself from sibling tools like 'insert_at_section' by specifying it replaces content rather than inserts, and from 'replace_in_note' by targeting a section instead of the whole note.

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 advises using this tool 'instead of rewriting the whole file when you only need to update one section', giving clear context for when to choose it over alternatives. It also explains the 'section' parameter format with details on case-insensitivity and whitespace tolerance.

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