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

Annotations already establish that this is a non-read-only, non-destructive, non-idempotent mutation. The description adds useful behavioral context by specifying that both nodes must already exist and that the tool returns the generated edge UUID.

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 tight sentences, front-loading the core action and prerequisites before optional details and return value. There is no wasted language.

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 compensates by stating that the generated edge UUID is returned. Combined with the prerequisites and 100% schema coverage, an agent has enough information to invoke the tool 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 schema has 100% description coverage, so the schema already explains all six parameters. The description adds prerequisite meaning for fromNode/toNode and clarifies fromSide/toSide, but does not add much for label or canvasPath beyond what the schema provides.

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

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

The description states a specific action and resource: creating a directed edge between two existing canvas nodes. It clearly distinguishes this from sibling tools like add_canvas_node and read_canvas by focusing on edge creation and node prerequisites.

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 gives clear contextual guidance: both node IDs must already exist, and it names read_canvas and add_canvas_node as ways to obtain them. It does not explicitly describe when not to use the tool, but the usage context is sufficiently 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=false, destructiveHint=false, idempotentHint=false, so the safety profile is covered. The description adds real value beyond that: it discloses the persistence side effect ('persist the updated file'), the return value, and a non-obvious positioning heuristic that prevents origin stacking. It doesn't say what happens on invalid canvas paths or whether concurrent writes clobber, keeping it at 4.

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 the action and node types, then return value, then the positioning rule. Four sentences all earning their place, though the auto-position explanation is somewhat verbose and partially duplicates the schema wording.

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 an 8-parameter mutation tool with no output schema, the description covers the action, node-type branching, side effects, return value, and the key defaulting rule. An agent has everything needed to invoke it correctly and chain to add_canvas_edge.

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 every parameter is already documented, including the auto-stagger behavior on x/y and content interpretation per type. The description largely restates that schema content at the aggregate level rather than adding new syntax or format detail. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

States a specific verb and resource ('Add a new node to an Obsidian canvas') and enumerates the four node types with their semantics. It is clearly distinguished from the siblings read_canvas and add_canvas_edge, the latter of which is explicitly named as the follow-up consumer of the returned UUID.

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 operational context: the returned UUID is 'needed to connect nodes via add_canvas_edge', which routes the agent to the correct next tool. It also states explicitly when auto-positioning applies and that explicit coordinates win. It does not state exclusions (e.g. prefer read_canvas first to inspect existing nodes), so it falls short of a full usage contract.

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?

Adds real behavior beyond the annotations: the auto-inserted leading newline (a side effect on the file), the guarantee that prior content is preserved, and the fail-when-missing error mode. The safety profile (non-destructive, non-idempotent) is already carried by the hints, and the description doesn't explain what repeated appends accumulate to or what is returned, so it is strong but not exhaustive.

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 short sentences, each doing distinct work: core semantics, default newline behavior, then use cases and the failure/alternative. The critical non-destructive guarantee is front-loaded rather than buried.

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 two-parameter append tool with full schema coverage and safety annotations, this covers the essentials: what changes, what doesn't, the default newline, and the not-found failure. The only gap is that, with no output schema, it never says what the call returns (e.g., bytes written, resulting length), which an agent verifying the append might need.

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 both parameters are documented with examples and length limits, so the schema does the heavy lifting and the baseline of 3 applies. The description's newline note merely restates what the 'content' schema field already says; it adds no new path or content semantics.

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

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

States a specific verb and resource ('append text to the end of an existing note') and immediately pins down the distinguishing semantics: prior content is untouched. It also names the sibling it is often confused with ('use create_note to make a new note first'), so an agent can separate append semantics from creation.

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?

Gives concrete use cases (log entries, running lists, new sections) and the failure precondition with a redirect to create_note. It does not, however, distinguish against the other mutating siblings it most overlaps with — prepend_to_note, insert_at_section, update_section, replace_in_note — leaving that routing to inference.

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 the mutating, non-idempotent, non-destructive, closed-world profile, and the description adds substantive behavior: config-driven path/filename, template placeholder substitution semantics, and the failure condition when the note already exists. These are the non-obvious traits an agent needs before calling.

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 dense sentences, front-loaded with the operation and scope, and the failure condition is included where it matters. The placeholder enumeration is somewhat long and partly duplicates the schema, but it earns its place as the core behavioral nuance.

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

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

No output schema exists, yet the description never states what the tool returns (e.g., created note path/content) or whether parent folders are auto-created. For a creation tool with zero required params, the core behavior is covered but the return contract is a notable 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 description coverage is 100%, so the schema already documents date, content, and templatePath in depth. The description largely restates the placeholder rules already present in the templatePath schema description, adding little beyond the structured fields.

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

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

Specific verb+resource: creating a daily note in the vault's configured daily-note folder using its configured filename format. This clearly distinguishes it from the generic create_note and from get_daily_note by its config-driven placement, template seeding, and existence-failure 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?

Gives a clear context for use (today or a specific date, optional template) and surfaces the important 'fails if the note already exists' constraint, which implicitly steers the agent to check first. It does not explicitly name create_note or get_daily_note as alternatives, so no full when-not 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 declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false. The description adds valuable context beyond annotations: it fails rather than overwrites on conflict, creates missing directories automatically, and appends .md if omitted. This clarifies failure behavior and side effects, though it doesn't mention permissions or return values.

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 the core action, then failure behavior and alternatives, then automatic side effects. No wasted words, each sentence adds specific 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 complexity of a create operation with 3 parameters at 100% schema coverage and no output schema, the description covers usage, failure modes, and automatic behaviors completely. Nothing essential for correct invocation is missing.

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 input schema already documents all three parameters (path, content, frontmatter) with examples and constraints. The description adds no additional parameter-level semantics 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?

States a specific verb (Create) and resource (markdown note at given path) with body and optional frontmatter. Explicitly distinguishes from sibling tools for existing notes (append_to_note, prepend_to_note, update_frontmatter).

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

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

Clearly states when to use this tool (creating new notes) and when not to (existing notes), naming alternative tools for those cases. Provides explicit prerequisites like automatic directory creation and .md extension handling.

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 destructiveHint=true and readOnlyHint=false, but the description adds the crucial nuance that the default action is recoverable via the vault's .trash, and that the truly irreversible path requires an explicit flag. It further discloses the side effects of removeReferences (embeds deleted entirely, plain links degraded to visible text or basename) — behavior an agent cannot infer from annotations alone.

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 the action, then the default behavior, then the opt-in escalation path. Nothing is repeated and every sentence carries a decision-relevant fact.

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, four-parameter tool with no output schema, the description covers recoverability, irreversibility, and side effects of the reference-rewrite option, while the confirm safety latch is fully documented in the schema. An agent has everything needed to call it safely.

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%, and the schema's per-parameter text already explains permanent, confirm, and even the embed/link fallback semantics of removeReferences. The description largely restates that content rather than adding syntax, formats, or edge cases beyond it, so the baseline 3 applies.

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?

States a specific verb and resource ("Delete a note") and immediately scopes it into two distinct modes (trash-by-default vs. permanent unlink). No sibling tool in the list performs note deletion, so an agent can route here unambiguously without opening the schema.

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?

Gives explicit conditions for the optional behaviors: pass permanent=true only for immediate on-disk unlink, and removeReferences=true only in combination with permanent=true, with the rationale ("opt in explicitly because the rewrite is irreversible"). It also states the negative case (references are never rewritten when trashing). It stops short of naming an alternative tool (e.g. move_note) for relocating rather than deleting, which keeps it from 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?

Adds genuinely useful behavior beyond the annotations: the `^id` anchor is re-appended to the last line so existing `![[note#^id]]` transclusions keep working, which is the key side effect an agent must anticipate. Annotations already cover destructiveness and idempotency, so this extra context is what pushes it above baseline.

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

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

Three short sentences, front-loaded with the core action, followed by the non-obvious anchor-preservation behavior and then the use case. No redundancy or filler.

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?

All three parameters are documented in the schema, annotations cover safety profile, and the description covers the most critical behavior (anchor/transclusion preservation). It omits error behavior (e.g. what happens if the block id is not found), which is a minor but real 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 description coverage is 100% and the schema already documents the `^`-optional block id and the automatic anchor append for `newContent`. The description adds no syntax or edge-case detail (e.g. multi-line content behavior) beyond what the schema provides, so baseline 3 applies.

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?

States a specific verb and resource ('Replace the content of a block tagged with `^id`') and scopes it to anchored blocks, which separates it from sibling tools like `update_section` or `replace_in_note`. It does not name those siblings explicitly, so the differentiation is inferred from the resource qualifier rather than stated.

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 final sentence gives a clear use case: 'update a single paragraph or list item that other notes reference', implying this is the right tool when transclusions must survive. No explicit when-not guidance or named alternatives are given, keeping it out of 5 territory.

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 establish that this is a read-only, idempotent, closed-world operation. The description adds meaningful behavioral details beyond annotations: per-source grouping, broken link text and line numbers, total count, and the whole-vault resolution rule even when scanning a folder.

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 adds return format and usage timing without waste. Every sentence contributes useful information for invoking or interpreting the tool.

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?

There is no output schema, but the description sufficiently explains the return structure: a per-source report with broken link text, line numbers, and a total count. Together with the annotated safety profile and fully described parameters, it is complete enough for correct 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 description coverage is 100%, so both folder and maxResults are already well documented. The description reinforces the whole-vault resolution behavior for folder scanning but does not add syntax or constraints beyond what the schema provides, making the baseline 3 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 states a specific verb and resource: scanning notes for wikilinks whose targets do not resolve to existing notes. It also distinguishes the behavior from related tools by explaining that resolution uses the whole vault and that only truly unresolvable links are reported.

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 gives a clear usage situation: after renaming, moving, or deleting notes to catch dangling references. It does not explicitly name alternatives such as get_outlinks or find_orphans, nor does it state when not to use this tool, so it falls short of full alternative 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 declare readOnly, idempotent, closed-world, so the safety profile is covered. The description adds real behavioral context the annotations cannot: the three-way classification scheme and the return shape (counts per category plus capped example lists).

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-loads the core purpose, then the category definitions, then usage guidance, in three tight sentences. Every sentence carries distinct information with no repetition of name or title.

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 read-only, two-param tool with a fully documented schema, the description covers purpose, categories, return shape, and usage. Minor gap: it does not clarify interaction between includeOutlinksCheck=false and the reported categories beyond the schema text, but nothing essential is missing.

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 both parameters are fully described there, including the maxResults cap and the includeOutlinksCheck toggle. The description only echoes the maxResults cap ('capped by maxResults') without new syntax or edge-case detail, so baseline 3 applies.

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?

States a specific verb and resource (identify disconnected notes in the link graph) and enumerates the three sub-categories precisely. An agent can distinguish this from get_backlinks, get_outlinks, and find_broken_links without inspecting other schemas.

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 names the use cases: surfacing abandoned notes, missing hub pages, or archiving candidates. However, it never states when to prefer a sibling tool (e.g., get_backlinks for a single note) or any exclusions, leaving routing to inference.

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?

Adds real behavior beyond annotations: results exclude the source note, the tool reuses cached chunk embeddings rather than making a live API call, and is therefore 'fast and free.' That discloses cost/latency and an index-staleness dependency the annotations do not cover. It stops short of saying what happens when the index is missing or stale (error vs. empty result).

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 front-loaded sentences with no filler; the core behavior comes first and the prerequisite last. The middle sentence about chunk embeddings and opening-topic anchoring is somewhat implementation-heavy but does explain why results are cheap and how they are ranked.

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

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

No output schema exists, yet the description never says what a result looks like — paths only, paths plus similarity scores, snippets? For a ranked-retrieval tool that omission is a meaningful gap, though the input side and behavioral context are otherwise well covered.

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 both parameters are already documented in-schema with types, ranges, and defaults. The description maps 'note path' to path and 'K' to limit but adds no syntax, ranking, or scoring detail. Baseline 3 is appropriate when the schema carries the parameter burden.

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?

States a specific verb and resource with scope: 'Given a note path, return the K most semantically similar notes from the index (excluding the source note).' The note-to-note input form distinguishes it operationally from query-based siblings like search_semantic and search_notes, and the exclusion rule removes ambiguity about the result set.

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?

Gives an explicit prerequisite — 'Run index_vault first to populate embeddings for both the source and the candidates' — which tells the agent the ordering constraint. It does not explicitly name when to prefer search_semantic (query string) over this tool, leaving the alternative to inference.

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, and openWorldHint=false. The description adds key behavioral context beyond that: it deliberately does not unlink files and must be paired with external delete operations, which prevents destructive assumptions.

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 definition is three focused sentences with zero waste. The core purpose is front-loaded, followed by use cases and the important non-destructive behavioral caveat.

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 complete enough to call the tool correctly: it defines unused attachments, explains the intended workflow, and clarifies that deletion is external. It does not describe the return shape in detail, but the schema covers both parameters and no output schema exists.

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 both limit and includeBytes are already documented in the schema. The description adds no additional parameter semantics, so the 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 states a specific verb and resource: 'Locate attachments that no note references.' It also defines 'unused' precisely via two reference forms, which distinguishes this from sibling list_attachments, get_attachment, and find_broken_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 gives clear usage contexts ('vault hygiene before archiving or before running a sync') and explicitly routes deletion to shell operations rather than this tool. It lacks explicit when-not-to-use guidance, but the practical workflow 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?

Goes well beyond the readOnly/idempotent annotations by disclosing the return shape per media type (image blocks, audio blocks, base64 resource with vault:// URI), the 5 MB default and 50 MB hard ceiling, and the vault-containment restriction. These are exactly the traits that determine token cost and whether a call will fail.

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 dense sentences, front-loaded with the return behavior, then limits, then constraints, then sibling routing. No sentence is filler; each carries either behavioral or routing 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?

With no output schema, the description fully carries the burden of describing return values by content type, plus size limits and path restrictions. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds rationale the schema lacks: maxBytes exists to keep token usage sane and can be raised to 50 MB, and path must resolve inside the vault. It stops short of any path-format examples, though the schema supplies one.

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?

States a specific verb and resource ('Read an attachment file and return its bytes') and immediately distinguishes itself from the text-format siblings get_note / read_canvas / read_base. An agent can identify the tool and its domain without opening the schema.

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 routes callers: text-format files (.md, .canvas, .base) are rejected here and must go through get_note / read_canvas / read_base instead. It also gives the condition for raising the size cap via maxBytes, so both the when-to-use and when-not-to-use cases are covered.

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 annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false, so the safety profile is covered. The description adds valuable behavioral detail beyond annotations: result contents (source path, line number, surrounding text) and a fallback matching strategy ('falls back to basename matching if exact match fails'). It does not mention pagination or ordering, but the added context is substantial.

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, front-loads the core purpose, and each sentence contributes useful information: result fields, use cases, and path handling. There is little waste, though the use-case sentence could arguably be slightly tightened.

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 appropriately explains the return shape (source note path, line number, surrounding text). Combined with annotations covering safety and idempotency, it gives an agent enough to call the tool correctly. Minor gaps like result ordering or pagination are not critical for a read-only 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 the baseline is 3. The description adds meaningful semantics beyond the schema by explaining that paths are accepted with or without the .md extension and that basename matching is used as a fallback. This clarifies runtime behavior for the single path parameter, which the schema does not specify.

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 states a specific verb and resource: 'List all notes that contain a wikilink pointing to the target note.' It precisely defines the direction of the relationship, distinguishing this from the sibling get_outlinks tool without needing to name it. An agent can confidently identify this as the inbound-link lookup.

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 gives clear use cases: 'Use to understand which notes reference a topic, or to assess the impact of renaming or deleting a note.' This provides strong context for when to call the tool. However, it does not explicitly mention alternatives such as get_outlinks for outgoing links or find_broken_links for broken links, so it falls short of 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?

Goes beyond the annotations (which already declare readOnly/idempotent/openWorld=false) by disclosing the resolution mechanism, the return shape (path, parsed frontmatter as a labeled header block, body), and the error condition when no note exists. That is substantive behavioral context an agent cannot infer from the flags.

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 the action and scope, then resolution mechanics, then error handling. Every sentence carries information the agent needs; nothing is restated from the name or schema.

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?

There is no output schema, but the description covers the return contents (path, frontmatter, body) and the failure mode, so an agent knows what to expect on both success and error. Nothing material is missing for a single optional-parameter read 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% and already documents YYYY-MM-DD format and the local-today default, so the baseline is 3. The description adds value by explaining how the date is interpreted (resolved through the vault's configured folder/filename format) rather than being a raw path lookup.

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?

States a specific verb and resource (read the daily note) plus scope (today or a specific date), and immediately distinguishes it from the generic get_note by explaining that the path is resolved via the vault's daily-note folder and filename format. An agent can tell this apart from get_note and create_daily_note without opening any schema.

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 names the fallback: 'Errors if no daily note exists for that date — use create_daily_note to create one.' That is real when-to-use-something-else guidance. It doesn't explicitly contrast against get_note for the read case, but the resolution semantics imply the distinction.

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

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

Annotations already declare readOnly/idempotent/openWorld=false, so safety is covered; the description adds genuine behavioral detail beyond them — results are grouped by depth into an indented tree and each neighbor carries hop distance and direction. It does not discuss cost or the truncation behavior of maxResults (that lives only in the schema), keeping it from a 5.

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 the core traversal semantics, then return format, then use cases, then the path note — four tight sentences. The final sentence about .md extension mildly duplicates the schema, a small redundancy rather than 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?

There is no output schema, so describing the returned structure (depth-grouped tree with hop tags) is exactly what's needed and it is present. Nothing essential is missing, though a word on truncation or graph-size limits would round it out.

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 depth/direction/maxResults are already fully documented. The description reinforces path extension flexibility, but that same fact is in the schema, so it adds little beyond restating structured data — baseline 3 applies.

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?

States a specific verb ('traverse the wikilink graph outward') plus the resource (notes reachable within N hops) and the return shape. It also implicitly distinguishes itself from the direct-link siblings by promising neighbors 'beyond direct links', so get_backlinks/get_outlinks are clearly not substitutes.

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?

Names three concrete use cases (explore a topic cluster, map a local neighborhood, find related notes beyond direct links), which is clear usage context. It stops short of explicit when-not guidance or naming get_backlinks/get_outlinks as the bounded alternative, so it is strong but not complete.

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

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

Annotations already declare readOnly/idempotent/closed-world, and the description adds real value on the return shape: parsed frontmatter as a labeled header, a flat inline tag list, and body; fragment modes skip the header and return raw text. It does not describe failure behavior (missing note, nonexistent section or block id), which is the remaining gap.

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 the default behavior, then one clause per mode, ending with a practical recommendation about token usage. Dense but every sentence earns its place; slightly long in its enumeration.

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

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

No output schema exists, and the description does carry that burden by explaining exactly what each mode returns. For a read-only, four-parameter tool with full schema coverage that is nearly sufficient; error/edge-case behavior is the only missing piece.

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, but the description adds semantic detail beyond the schema: section supports path-form headings ('Tasks/Today'), block targets the paragraph tagged with that id, and lines are inclusive 1-indexed. These clarify how parameters compose with the output modes, not just their types.

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?

States a specific verb and resource ('Read a note') and immediately enumerates the four retrieval modes. It is clearly separable from siblings like search_notes, list_notes, and read_base without opening the schema.

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?

Each mode is tied to a condition ('With section...', 'With block...', 'With lines...') and it explicitly recommends fragment modes for token efficiency on long notes. It lacks an explicit exclusion against sibling tools (e.g., use search_notes to locate a note first), so not 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 readOnly/idempotent/closed-world, so safety is covered; the description adds genuinely new behavior by disclosing the three-way result partitioning and that raw link text plus resolved paths are returned. It says nothing about ordering, limits, or whether nested/transcluded links are followed.

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 tight sentences: the first front-loads the operation and the exact result shape, the second front-loads the use cases. No redundant restatement of the title or annotations.

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

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

No output schema exists, and the description compensates well by describing the partition and returned fields; safety comes from annotations and the single param is fully covered by the schema. Minor gaps remain on edge behavior (missing source note, link ordering, non-wikilink URLs).

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 on a single 'path' parameter, the schema carries the semantics (vault-relative path, extension optional). The description adds no further meaning about how path is interpreted or what happens if the note does not exist — baseline 3 applies.

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?

States a specific verb ('List') and resource ('every outgoing wikilink from a note') and even describes the output partitioning into valid/broken/embeds. The word 'outgoing' implicitly separates it from get_backlinks, but the overlap with find_broken_links (also named as a use case here) is never resolved.

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?

Gives three concrete use cases (audit references, detect broken links, follow downstream dependencies), which is clear context for invocation. It stops short of exclusions or naming alternatives such as find_broken_links or get_backlinks when those would be the better choice.

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, idempotentHint and closed-world, so the safety profile is covered; the description adds the default sort order and the inclusive 'modified at or after' filter semantics. It says nothing about what a returned note contains or how limit interacts with result ordering, leaving gaps the annotations don't fill.

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 the single most important fact (recency ordering) and then the filter syntax, then use cases. The final clause ('pick targets for review') is slightly filler but does reinforce intent.

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

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

No output schema exists, so the description carries the burden of describing return shape, and it never says whether notes come back as titles, paths, or full content — a real gap for a listing tool. Filtering and ordering are adequately covered.

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% and the description largely restates the `since` documentation, including the same relative-span examples ('7d', '24h', '2w'). `limit` and `folder` are not mentioned at all, so the description adds essentially no parameter meaning beyond the schema.

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

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

States a specific verb and resource plus the ordering guarantee ("List notes ordered by most-recently-modified first"), which meaningfully separates it from the unordered list_notes / search_notes siblings. It does not explicitly name or contrast with those siblings, so an agent still has to infer the boundary.

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?

Gives three concrete usage contexts (surfacing recent work, a 'what changed this week' digest, picking review targets), which is stronger than implied usage. It offers no exclusions or 'use X instead when…' routing, so the choice against search_notes or list_notes remains unstated.

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

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

Annotations already declare readOnly, idempotent, and non-openWorld, so safety is covered. The description adds genuinely new behavioral context beyond them: reads flow through the mtime cache, so repeated calls are cheap — a performance trait an agent can plan around. It also implicitly discloses the return shape by listing the metrics, which matters since there is no output schema.

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

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

Three short sentences: what it returns, when to use it, and the cost profile. The key content (the metric list) is front-loaded and no sentence is filler.

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 one optional parameter, rich read-only annotations, and no output schema, the description does exactly the extra work needed by enumerating the returned fields and noting cache behavior. Nothing an agent needs to call this correctly is missing.

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 single 'folder' parameter is fully documented in the schema, including the omit-for-whole-vault semantics. The description adds nothing on top of that, so the baseline 3 applies.

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?

States a specific verb and resource ('Return a quick health snapshot of the vault') and then enumerates the exact metrics returned, so the tool is unmistakable. It never names a sibling to contrast against, which keeps it out of 5 territory, but the metric list does the disambiguating work implicitly.

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?

Gives real usage context ('useful for dashboards and is-this-vault-healthy checks'), which tells the agent when this is the right call. It offers no explicit exclusions or alternatives among siblings like read_base or query_base, so it stops short of full when-not 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?

Goes well beyond annotations: discloses the exact cache file written, that vault text is sent to an external embedding provider, the required `confirm` safety latch for data leaving the tool boundary, hash-based skipping behavior, and progress notifications. These details let an agent reason about privacy, cost, and idempotency.

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-loads the core purpose, then layers in privacy, persistence, incrementality, and progress behavior. Sentences are dense with useful facts rather than filler, though the description is longer than strictly necessary for an expert agent.

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

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

Covers the important risks for a complex indexing tool: external data transmission, required confirmation, cache location, incremental behavior, and force re-embedding. It does not cover failure modes or the role of the `folder` scoping parameter, but the annotations and schema fill in the remaining structure.

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

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

Schema coverage is 100%, so the schema already documents all three parameters thoroughly. The description reinforces the purpose of `confirm` and gives an example for `force`, but the `folder` parameter is not mentioned and no syntax or format details are added 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?

States a specific verb and resource ('Build or refresh the embedding index') and explicitly names the sibling tools that consume it (`search_semantic` and `find_similar_notes`). An agent can immediately distinguish this maintenance operation from the search tools themselves.

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: it is the index-builder behind the semantic search siblings, is incremental by design, and `force: true` is for re-embedding after switching models. It does not state explicit when-not-to-use conditions or concurrency caveats, but the intended usage is clear.

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

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

Annotations already declare non-destructive, non-readonly and non-idempotent behavior, so the safety profile is covered. The description adds that content is inserted without replacement, which is useful context, but says nothing about failure modes (missing section) or repeated-insert behavior that the non-idempotent hint implies.

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-loads the core action, then the position semantics, then the use case. Every sentence contributes and there is no redundancy.

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

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

No output schema exists, but the description covers action, positioning, and use context adequately. It omits what happens when the section is not found, a minor gap for an insertion 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%, so baseline is 3, but the description meaningfully elaborates the `position` enum in plain terms ('above the heading', 'top of the section body', 'just before the next heading'), adding clarity beyond the schema's own enum 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?

States a specific verb+resource ('Insert content into a specific section') and immediately clarifies it does not replace the section, distinguishing it from update_section and append_to_note in the sibling list.

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?

'Use to add a new bullet or paragraph without rewriting the section' gives a clear use context and implicitly contrasts with update_section. It does not explicitly name an alternative tool or exclusions, keeping it just short of 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 readOnly/idempotent/closed-world, so the bar is lower; the description still adds real value by disclosing the return shape (sorted relative paths plus per-extension count summary) and the non-markdown filter scope. It does not discuss ordering key or behavior in very large vaults, keeping it at 4.

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, zero filler: scope first, return value second, usage third. Each sentence carries distinct information an agent needs.

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 steps in to describe the return payload (sorted relative paths + per-extension counts), which is the main gap it needed to cover for a two-param read tool. Minor omissions like path root semantics and pagination interplay are handled by the schema.

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

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

Schema coverage is 100% — both 'limit' (including that counts are still reported when truncated) and 'extension' (with/without dot) are fully documented in the schema. The description adds no parameter-level detail beyond that, so baseline 3 applies.

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

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

Specific verb ('Enumerate') plus precisely delimited resource ('every non-markdown file in the vault — images, PDFs, audio/video clips'), explicitly excluding notes/canvases/Bases. That exclusion is what separates it from list_notes and read_canvas without inspecting schemas.

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?

Gives three concrete use cases (audit assets, find duplicates by name, pick targets for find_unused_attachments) and explicitly hands off to a sibling for the follow-up action. It lacks an explicit 'use get_attachment instead if you want to read one file' exclusion, so it falls short of 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 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 cover read-only, idempotent, closed-world behavior, so the bar is lower; the description still adds real value by disclosing sort order and, importantly, that output is truncated at `limit` while the total count is still reported. The one gap is that no offset/pagination cursor exists, so truncated results cannot be resumed — that limitation is implied but not spelled out.

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 tight sentences: the first covers scope and return shape, the second covers truncation semantics and intended uses. The most decision-relevant fact (what it enumerates) is front-loaded, and nothing is padding.

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 carries the burden of describing return values and does so (sorted relative paths, total count). For a two-parameter, zero-required listing tool with full annotation coverage, nothing an agent needs to call it correctly is missing.

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 both parameters are fully documented in the schema, including the 1-10000 range, default of 50, and the note that the total is still reported. The description's mentions of `limit` and folder scoping essentially restate the schema, so baseline 3 applies.

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?

States a specific verb (enumerate), resource (markdown notes), scope (whole vault or one folder), and even the return shape (sorted relative paths plus total count). This is clearly distinguishable from siblings like search_notes or get_note, which retrieve by query or by identity rather than enumerating the vault.

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?

Gives three concrete use cases: browsing vault structure, building a file picker, and enumerating targets for batch processing. It stops short of naming an alternative and the condition that selects it (e.g., 'for query-based retrieval use search_notes instead'), so it is clear context without 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 declare readOnlyHint, idempotentHint, and openWorldHint=false, so safety is covered; the description adds the output shape (tree of paths with depth) that annotations cannot convey. It omits edge behavior such as what happens for a missing path or a note with no headings.

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, with the core capability front-loaded and the usage hint following immediately.

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 adequately covers the return shape (tree of paths with depth) and the tool's role in the workflow. Only minor gaps remain around error or empty-result behavior for a nonexistent path.

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 single `path` parameter is documented there as a vault-relative note path. The description's 'in a note' reinforces the target but adds no syntax or format detail beyond the schema, so baseline 3 applies.

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?

States a specific verb (list) and resource (headings in a note) and even specifies the return shape: a tree of paths with depth. This is clearly distinguishable from siblings like get_note or list_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?

Explicitly frames the tool as a discovery step before calling get_note, update_section, or insert_at_section, naming the exact alternatives and the condition that selects them.

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 cover the safety profile (readOnly, idempotent, closed-world), yet the description still adds substantive behavior: tags come from both inline #hashtags and YAML frontmatter, names are case-normalized, and the result includes a total unique count. It does not mention edge cases (empty vault, duplicate tag spellings after normalization), which keeps it from a 5.

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 the core action and return content, followed by usage routing. No filler and nothing repeated from the title or schema.

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 carries the burden of describing return values and does so (sorted list plus total unique tag count), and it explains tag sourcing and normalization. Minor gaps remain around empty-result behavior and sort defaults, but nothing an agent needs in order to call it correctly is missing.

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 single enum parameter is fully documented in the schema, so the schema does the heavy lifting. The description's reference to 'a sorted list' hints at ordering but does not explain the count-vs-name sort choice, so it adds little beyond the schema — the baseline 3 applies.

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?

States a specific verb and resource ('Enumerate every unique tag used across the vault') plus what is returned ('the number of notes each tag appears in'). It also distinguishes itself from the sibling search_by_tag by positioning itself as the discovery step before tag-based search.

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

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

Names concrete use cases (tag cloud, category picking, taxonomy audit) and explicitly routes the agent to search_by_tag for the follow-up step. The complementary relationship with the sibling is unambiguous, so an agent can pick this tool without inspecting either schema.

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 substantial behavior beyond the annotations: parent folders are created, internal links are rewritten by default, confirmPath must match the normalized destination, updateLinks:false skips the rewrite scan, and .md extensions are auto-added. These are meaningful side effects for a destructive mutation tool, and the description does not contradict the destructiveHint annotation.

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

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

The description is front-loaded with the core action and follows with the most important behavioral details in a compact sequence. Every sentence adds operational value, including folder creation, link rewriting, confirmPath requirements, and the updateLinks tradeoff.

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 move/rename tool with full schema coverage and no output schema, the description covers the main behavioral concerns: link rewriting, folder creation, confirmPath, extension normalization, and an audit alternative. It omits what happens if the destination already exists, such as overwrite or collision behavior, which is important for a destructive move operation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds valuable meaning beyond the schema: confirmPath must match the destination after .md normalization, updateLinks:false is faster on large vaults, and the agent may pair it with find_broken_links afterward. It also notes that .md extensions are added automatically if omitted, which the schema does not explicitly state for either path.

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 opens with a specific verb and resource: 'Move or rename a note within the vault, preserving its full content.' This is unambiguous and inherently distinct from sibling operations such as create_note, delete_note, or update_section. An agent can identify exactly what the tool does without reading the schema.

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?

Usage guidance is implied by 'Move or rename a note', and the description gives useful guidance for the updateLinks option, including pairing with find_broken_links for audits. However, it does not explicitly state when to use move_note versus alternatives or when not to use it, so selection guidance remains implied rather than explicit.

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=false, destructiveHint=false, idempotentHint=false, so the safety profile is covered. The description contributes the non-obvious behaviors: frontmatter is preserved at the top and the call errors when the note is missing. It does not state whether repeated calls duplicate content (relevant given idempotentHint=false) or whether the vault index is updated.

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 short sentences, front-loaded with the operation and its placement rule, followed by use cases and the failure condition. No redundancy or filler.

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 two-parameter mutation tool with full annotation coverage and no output schema, this covers placement, when to use it, and the failure mode. It could go further on idempotency/duplication behavior given idempotentHint=false, but nothing needed to invoke it correctly is absent.

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 schema already documents both path and content, including the 'after any frontmatter' wording the description repeats. The description adds no format, size, or encoding detail beyond the schema, so the baseline 3 applies.

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?

States a specific verb and resource ('Insert content at the top of an existing note's body') plus the placement rule relative to YAML frontmatter, which is the exact semantic that separates it from append_to_note and insert_at_section. An agent can identify the operation without opening the schema.

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?

Gives concrete use cases (prepending to a running list, pinning context, TL;DR sections) and a precondition ('Fails if the note does not exist'). It stops short of naming the sibling alternatives append_to_note or insert_at_section that an agent should consider instead when the target position differs.

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 cover the safety profile (readOnly, idempotent, closed-world), so extra credit goes to the substantive disclosure that unsupported clauses are reported as warnings and treated as no-match — a non-obvious failure mode that would otherwise cause an agent to silently misread an empty result as 'no matches exist'. It does not, however, say where those warnings appear in the response or whether results are truncated when `limit` is hit.

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 purpose is front-loaded correctly in the first two sentences. However, roughly two-thirds of the text is an exhaustive enumeration of filter DSL syntax, and there is no filter parameter in the schema — the filters live inside the .base file — so this bulk does not help the agent construct a call. It is organized and scannable, but it is reference material occupying a tool description.

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 read-only query tool with four fully documented parameters, the description covers what it does, the optional view layering, and partial return semantics (note paths, plus warnings). The main gap, given there is no output schema, is the response shape: where warnings surface and whether truncation at `limit` is signalled.

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 earns more by explaining that `view` applies both the view's filters AND its ordering on top of base-level filters — semantics the schema's one-liner does not convey. `limit` and `includeFrontmatter` are left entirely to the schema, which is acceptable given full 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 opening sentence gives a specific verb and resource: run a Base file's filters against the vault and return matching note paths. That distinguishes it from read_base (which returns the file itself) and from search_notes, though the description never names those siblings explicitly, so the differentiation is inferable rather than stated.

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 second sentence clarifies an optional mode (apply a named view on top of base-level filters), which tells the agent when to supply `view`. However, there is no guidance on when to prefer this tool over read_base, search_notes, or search_by_frontmatter, and no stated prerequisites for what a valid .base file is.

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, so safety is covered. The description adds valuable context beyond that: what the return payload contains, including unrecognized fields, which prepares the agent for pass-through data. It doesn't mention failure modes for missing/invalid files, but with annotations carrying the safety profile this is solid.

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 the return payload, followed by the routing hint. Zero 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?

No output schema exists, so the description carries return-value disclosure and does so by enumerating the parsed sections. Complete enough for a single-param read tool, though it could note error behavior for malformed or missing .base files.

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?

Only one parameter at 100% schema coverage, so the schema fully documents 'path' including pattern and length constraints. The description adds no syntax or path-format guidance beyond what structured fields already provide, making the baseline 3 correct.

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

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

Specific verb+resource ('Return the parsed contents of a Base file') with enumerated contents (filters, properties, view definitions, unrecognized fields). It also implicitly distinguishes itself from query_base via the recommended sequencing, so an agent can tell it apart from 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?

Explicitly states when to use it ('Use to discover what queries a Base supports') and names the downstream alternative (query_base). Clear context, but no explicit when-not conditions or mention of list_bases as an alternative for discovery.

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, and openWorldHint=false, so safety is covered. The description adds valuable behavior beyond that: it is a bounded summary with hard caps (up to 200 nodes, up to 200 edges) and content is 'preview' rather than full, which tells the agent to expect truncation. That truncation disclosure is the kind of trait annotations cannot convey.

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?

A single dense sentence that front-loads the core action and file format, then enumerates the returned payload. Every clause earns its place (counts, caps, field lists, workflow guidance), though the enumeration is lengthy enough to read as a spec rather than a quick summary.

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

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

No output schema exists, so the description must carry return-value semantics — and it does: counts, capped node/edge lists, exact fields included, and the 'content preview' caveat. Combined with full annotation coverage and a fully documented single parameter, an agent has everything needed to call and interpret it 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?

There is a single required 'path' parameter, and schema coverage is 100% with an example and .canvas pattern constraint. The description adds no syntax or format detail beyond the schema, so this is the baseline-3 case where structured data does the heavy lifting.

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

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

States a specific verb (Read) and resource (Obsidian .canvas file) and precisely describes the returned structure: counts, capped nodes with id/type/position/size/content preview, and edges with source/target. This is clearly differentiated from mutation siblings like add_canvas_node/add_canvas_edge by naming them as downstream consumers.

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?

Gives explicit context: 'Use to inspect or navigate a canvas before calling add_canvas_node or add_canvas_edge.' This ties usage to a workflow and names alternatives. It lacks an explicit when-not statement, but the intended occasion is unambiguous.

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 destructiveHint annotation, the description discloses vault-wide rewriting scope, both inline and frontmatter targets, the confirmation guard, hierarchical rebasing behavior with an example, and the dry-run read-only mode. This is substantial behavioral context for a destructive mutation tool.

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 dense and front-loaded, moving from scope to confirmation requirement, hierarchical behavior, dry-run behavior, and tag-name formatting. Every sentence adds actionable information without 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?

For a destructive 5-parameter mutation tool with no output schema, the description covers the critical safety mechanism, dry-run alternative, hierarchical default, and naming format. An agent has enough context to invoke it correctly and safely.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds useful meaning: confirmTag must match the new tag name, hierarchical rebasing is illustrated with project/alpha → client/alpha, and oldName/newName should omit the leading #. It goes beyond the schema descriptions, though some details are still schema-owned.

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 states a specific verb and resource, 'Rename a tag', and clarifies vault-wide scope across inline #tags and frontmatter tags:. It is clearly distinct from sibling tag-listing/searching 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?

It explains key usage conditions: non-dry-run rewrites require confirmTag, dryRun returns planned counts without writing, and hierarchical defaults to true. No sibling alternative is named, but no direct rename alternative exists in the sibling list.

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 destructiveHint=true and idempotentHint=false, so safety profile is carried by structured data. The description adds real value beyond that: it discloses the fail-closed abort behavior with `expectedCount`, and states that the tool returns a replacement count — behavior an agent could not infer from 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 doing distinct work: core operation, mode support, safety guard plus return value. Front-loaded with the verb and resource, with no filler or restatement of the name.

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 destructive mutation with full schema coverage and rich annotations, the description covers the operation, modes, guard, and return value. Minor gaps remain — e.g. behavior on zero matches, or what happens if `path` doesn't exist — but nothing critical to correct invocation is missing.

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 goes beyond the schema by explaining the *rationale* for `expectedCount` ('guarding against accidental over-replacement when an LLM drafts a pattern that's too broad') and by framing the literal-vs-regex tradeoff, which clarifies the interaction between `find` and `regex` better than the schema's per-field notes.

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?

States a specific verb+resource combination ('Search-and-replace within a single note') that immediately distinguishes it from sibling mutation tools like update_section, edit_block, or append_to_note. It also names the two modes of operation (literal strings vs regex) in the same breath.

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?

Explains the purpose of `expectedCount` as a guard against over-broad patterns, which is genuinely useful usage guidance. However, it never explicitly states when to prefer this over update_section or edit_block, nor any when-not conditions, so the agent must infer routing from sibling names alone.

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 cover safety (readOnlyHint, idempotentHint, openWorldHint=false), yet the description adds real behavior: matching is case-insensitive, includeBasename mirrors Obsidian's own resolution fallback, and 'every note' signals multiple results are possible. It omits what the result looks like (paths vs. note objects), which with no output schema is the remaining gap.

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 matching rule and followed by the option and the recommended workflow. Every clause carries 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 two-parameter, read-only lookup with full schema coverage and annotations, this covers purpose, option semantics, and workflow. The one missing piece is return shape (list of matching paths, ordering), which matters given there is no output schema.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning beyond the schema: case-insensitivity is not documented in the schema, and the 'Obsidian's resolution fallback when no alias matches' framing explains why includeBasename defaults to true and when it fires.

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?

States a specific verb and resource ('Find every note whose frontmatter aliases: field contains the given name') plus matching semantics (case-insensitive). This is clearly distinct from siblings like search_notes or search_by_frontmatter, which search content or other fields.

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?

Gives explicit usage context: 'Use to translate a human-friendly title like My Project into the actual note path before calling get_note,' which names the downstream tool. It stops short of stating when not to use it (e.g., when the path is already known, or when a content search is needed), so a 4 rather than 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 read-only, idempotent, and closed-world behavior. The description adds useful matching semantics beyond annotations: case-insensitive matching, array-element matching, and that results include note paths with full frontmatter.

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 efficient sentences and front-loads the core matching behavior. Every sentence contributes useful information without 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?

For a simple read-only search tool with full schema coverage and annotations covering safety, the description is complete enough. It explains matching rules and return content, which is especially important because there is no output schema.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema. The description reinforces property/value matching semantics but adds no details for folder or maxResults beyond what the schema provides.

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

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

The description states a specific verb and resource: find notes by YAML frontmatter property/value pair. It is clear what the tool does, but it does not explicitly distinguish itself from the sibling search_by_tag, especially since it mentions tags stored in frontmatter.

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

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

It gives clear usage context: filter notes by metadata like status, type, or tags. However, it does not explicitly say when to prefer search_by_tag or search_notes, nor does it state 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 declare readOnly, idempotent, closed-world behavior, so the safety profile is covered. The description adds real value on top: prefix optionality implied by matching 'project' vs '#project', sub-tag recursion, dual tag sources, and the return shape (paths plus optional previews).

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 the core matching rule followed by edge-case behavior and then usage intent. No filler and nothing redundant.

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

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

With no output schema, the description correctly states it returns matching note paths with optional content previews, and annotations cover safety. Ordering and pagination beyond maxResults are unaddressed, which is a minor gap 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%, including the default for maxResults and the 200-char preview detail, so the schema carries parameter meaning. The description reinforces tag format and nested matching but adds little beyond what the schema already documents; 3 is the baseline.

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?

States a specific verb (find) plus resource (notes tagged with a tag) and goes further by explaining the matching mechanism: nested sub-tags, inline hashtags, and YAML frontmatter. This distinguishes it operationally from full-text search_notes and search_by_frontmatter even without naming them.

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?

'Use to collect notes belonging to a topic, area, or workflow stage' gives an implied usage context, but there is no explicit when-not guidance and no alternatives (e.g., search_by_frontmatter or search_notes) are named for the agent to route between.

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 cover the safety profile (readOnly, idempotent, closed-world), and the description adds real behavioral content: ranking signals (title/path focus, repeated-line dampening) and the shape of results (paths grouped with line numbers and query-centered snippets). It omits truncation/empty-result behavior and how the maxResults cap interacts with ranking.

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 front-loaded sentences with no filler: what it does, how results come back, when to use it. The ranking sentence is dense but earns its place by explaining result ordering.

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 carries the return-value burden and does describe result structure (grouped paths, line numbers, snippets). Missing is what happens with zero matches, result cap/truncation, and whether ordering vs. maxResults is deterministic.

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 every parameter is already documented, and the description only echoes the 'literal, not regex' point already in the schema. It adds nothing on folder scoping, case sensitivity, or result limits. Baseline 3 for a fully described 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?

States a specific verb+resource ('full-text search across all notes') and pins the matching model as literal/full-text, which implicitly separates it from search_semantic, search_by_tag, and search_by_frontmatter. An agent can pick this tool without opening the schema.

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?

Gives clear context ('locate notes containing a phrase, keyword, or code fragment') and a follow-up path ('pair with get_note to retrieve full bodies'). It never explicitly excludes or names the sibling alternatives (search_semantic, search_by_frontmatter), so routing between them is left partly to inference.

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

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

Annotations already declare readOnly/idempotent/openWorld, and the description adds genuinely useful context: the index is persisted, no implicit re-indexing happens, and the embedding cost is deliberate. It does not cover failure modes such as an empty or stale index, which is the main residual behavioral gap.

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?

Purpose and the key constraint are front-loaded, and every sentence carries information. The scoring-internals clause ('cosine similarity', 'top-chunk focus signal') is slightly more implementation detail than an agent needs to select or call the tool.

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 still tells the agent what a result is (one per note, best chunk as snippet), the indexing prerequisite, and the natural next step. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns extra by clarifying that ranking yields one result per note (so 'limit' counts notes, not chunks) and that the snippet comes from the best chunk. It still says nothing extra about 'folder' scope 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?

States a specific verb and resource ('Search notes by meaning rather than keywords') and immediately contrasts with the keyword sibling search_notes, so the agent can pick correctly without opening a schema. The ranking model (best chunk per note) further pins down what comes back.

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

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

Explicit prerequisites and follow-ups: run index_vault first, no auto-indexing because of embedding cost, and pair with get_note for full bodies. Together with the 'by meaning rather than keywords' framing, the when-to-use vs search_notes is unambiguous.

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 the annotations by disclosing merge-vs-overwrite semantics, creation of a block when absent, and — critically — that the YAML block is regenerated so comments, quoting, multi-line style, blank lines, and key ordering are normalized. This explains exactly what the destructiveHint=true means in practice, which is the single most decision-relevant fact here.

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?

Core behavior is front-loaded in the first two sentences, with the formatting-loss caveat isolated in a clearly marked note. Every sentence carries distinct information; nothing is redundant with the name or title.

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 two-parameter mutation tool with no output schema, the description covers the mutation semantics, the preservation guarantee, the destructive side effect, and the return value (a count of properties written). Nothing an agent needs to invoke it safely is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds value by clarifying that payload keys overwrite while unmentioned keys persist, and that the properties argument is a payload rather than a path. It does not add format or edge-case detail (e.g., null values to delete a key) 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?

States a specific verb (merge) and resource (YAML frontmatter of a note), and immediately delimits scope: body content untouched, keys not mentioned preserved. This clearly separates it from siblings like update_section, replace_in_note, and append_to_note, which act on body content rather than 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?

Provides a concrete usage context ("Use to set status fields, tags arrays, or other metadata without rewriting the body"), which gives the agent a clear selection criterion against body-editing siblings. It does not, however, name specific alternatives or state when not to use it (e.g., removing keys, which this tool apparently cannot do).

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 destructiveHint=true, idempotentHint=true and readOnlyHint=false. The description adds real value on top: it defines precisely what is destroyed (the body span between headings) and what survives (the heading line itself), which is exactly the context an agent needs before an overwrite. It does not cover error behavior when the section is absent or any confirmation/undo semantics.

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: what is replaced, what is preserved, how to specify the section, and why not to use the alternative. The core destructive scope is front-loaded in the first sentence.

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 three-parameter destructive mutation with annotations and no output schema, this covers scope, parameter format, and the main alternative. Minor gap: no indication of what happens if the heading path doesn't resolve to an existing section, which matters for an overwrite 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%, so the schema already documents all three parameters, making 3 the baseline. The description does add one useful detail beyond the schema: 'section' paths are case-insensitive and whitespace-tolerant, plus concrete path examples. The newBody explanation largely restates the schema's own note that the heading line is kept intact.

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?

States a specific verb and resource ('Replace the body of a specific section') and pins down the exact boundary: everything between a heading and the next heading at any level, with the heading line preserved. It clearly separates itself from whole-file rewriting but does not name closer siblings such as insert_at_section or replace_in_note, leaving the agent to infer the difference.

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 it: 'Use this instead of rewriting the whole file when you only need to update one section.' That gives a clear selection rule against full-file rewrite. It stops short of stating the inverse conditions (e.g., to add content use append_to_note/insert_at_section, or what to do when the section is missing).

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