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

With no annotations, the description carries the full burden but only states the mutation. It doesn't say whether the daily note is created if missing, whether a nonexistent heading is created or errors out, whether the append is idempotent, or what is returned.

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

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

One short, front-loaded sentence with no filler. It is efficient, though the extreme brevity is part of why behavioral details are absent.

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 mutation tool with zero annotations and no output schema, the description is too thin: it omits fallback behavior for missing notes/headings, return information, and any hint of side effects. The schema covers inputs, but the behavior around the append is undocumented.

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 all three parameters are documented in the schema, including the optional vault_path override and heading examples. The description adds nothing beyond what the schema already provides, 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 (append), resource (daily note), and scope (today's note under a named heading). This distinguishes it implicitly from siblings like obsidian_append_note and obsidian_get_daily_note without the agent needing to open their 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?

No guidance on when to pick this over obsidian_append_note, obsidian_insert_at_heading, or obsidian_replace_section. Nothing about exclusions or prerequisites, leaving the agent to infer routing from 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?

No annotations are provided, so the description carries full behavioral burden. It doesn't disclose whether appended content adds a newline, how it handles missing files/paths, permission or vault requirements, or whether the operation is idempotent. Only the append-to-end semantics are covered.

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 tight sentence with the key scope constraint ('end of an existing note') front-loaded. No wasted words, though it is arguably terse given the missing guidance elsewhere.

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 mutation tool with zero annotation coverage and no output schema, the description is too thin. It omits failure behavior, permission requirements, newline/format handling, and any routing to sibling mutation tools.

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 content, file_path, and vault_path. The description adds no parameter detail beyond the schema, so 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 (append) and resource (note) with the constraint that the note must already exist. It distinguishes itself from create_note and insert_at_heading by implying end-of-file addition, though it doesn't explicitly name those 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?

No explicit when-to-use guidance or alternatives are given. The phrase 'an existing note' implies the note must pre-exist (versus create_note), but there is no routing to insert_at_heading, replace_in_note, or replace_section for other mutation needs.

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?

No annotations are provided, so the description carries the full burden. It does not say what happens if file_path already exists (overwrite, error, or merge), how vault_path resolves, or whether parent directories are created — all critical for a mutation tool with zero annotation coverage.

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

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

A single short, front-loaded sentence with no wasted words. It is efficient, though arguably under-specified rather than deliberately concise.

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

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

For a create/mutation tool with no annotations and no output schema, the description should cover existence/overwrite semantics and vault resolution behavior. None of that is present, leaving meaningful gaps an agent cannot resolve from structured fields.

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 all three parameters (content, file_path, vault_path) are already documented in the schema with examples. The description adds nothing beyond the schema, which is the expected baseline when 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 (Create) and resource (a new note) with the content source. The word 'new' implicitly separates it from siblings like obsidian_append_note and obsidian_replace_in_note, but no sibling is named explicitly, so an agent must 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?

No when-to-use guidance, no prerequisites, and no mention of the alternatives (append_note, insert_at_heading) that would be preferable when the note already exists. The agent gets no routing signal.

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?

No annotations are provided, so the description carries the full behavioral burden, and it does not state that this is a read-only lookup, what happens when the file_name does not exist, or whether a vault must be set first. It adds essentially nothing beyond the operation's surface meaning.

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 front-loaded sentence with no filler or redundancy. It is efficient, though it is thin enough that some would call it under-specified rather than purely concise.

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

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

With no output schema and no annotations, the description should ideally say what a backlink result looks like (note names, paths, counts) and how a missing target behaves. The 100% schema coverage covers inputs, but the output side is left entirely unexplained.

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 parameters (file_name, vault_path) are already fully documented in the schema, including the no-extension convention and the override semantics. The description adds no additional parameter detail; 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?

The description states a specific verb (Find) and resource (notes that link to a specific note), which maps unambiguously to backlinks. It does not, however, distinguish itself from the sibling obsidian_get_links (outgoing links) or obsidian_get_broken_links, so an agent must infer the direction of the relationship.

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?

There is no when-to-use guidance, no mention of prerequisites (does the note need to exist, must a vault be set?), and no reference to the closely related obsidian_get_links sibling. Usage is only implied by the tool name and description.

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?

No annotations are provided, so the description carries the full behavioral burden. It discloses the return shape ('broken links grouped by source file') and the read-only nature is evident from 'Find', but it says nothing about scan depth/recursion, cost on large vaults, or behavior when no broken links exist.

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 filler, with the core action and scope front-loaded and the return format following. Every clause earns its place.

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

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

With no output schema, the description usefully states what is returned and how it is grouped, which covers the main gap. Minor omissions remain, such as whether the scan recurses into nested folders, but nothing essential to invoking 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 description coverage is 100% for both parameters, so the schema already documents subfolder and vault_path. The description echoes the subfolder scoping concept but adds no syntax, format, or path-resolution detail 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?

Specific verb ('Find') plus resource ('wikilinks') plus a filter condition ('point to non-existent notes') and scope ('vault or a subfolder'). This is clearly distinct from siblings like obsidian_get_links and obsidian_get_backlinks without needing to open 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?

The scope phrase '(or a subfolder)' implies when to narrow the scan, but the description never states when to prefer this over obsidian_get_links, obsidian_get_backlinks, or other link tools, and offers no when-not guidance. Usage is inferable but not spelled out.

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

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

With no annotations, the description carries full behavioral burden. It usefully discloses a write side effect ('or create') for what reads like a getter, which is genuinely informative, but leaves unresolved what 'today' means (timezone/date), where the note lives, and whether a template is applied.

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 tight sentence with the key behavior (get-or-create) front-loaded and no filler. Every word earns its place.

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

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

No output schema or annotations exist, and the description does not say what is returned or how the daily note is resolved. It is minimally adequate for a one-parameter tool but stops short of the detail needed to call it with confidence.

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 optional parameter and schema description coverage is 100%, so the schema already explains vault_path. The description adds nothing about how the override interacts with the configured vault, 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?

The description gives a specific verb+resource ('Get ... today's daily note') and even flags the create-on-miss behavior. It is clear on its own, though it never names a sibling like obsidian_read_note or obsidian_append_daily_log to disambiguate when each is appropriate.

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?

There is no guidance on when to reach for this versus obsidian_read_note, obsidian_create_note, or obsidian_append_daily_log. The parenthetical hints at the create case but does not frame usage conditions or prerequisites.

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?

No annotations are provided, so the description carries the full behavioral burden, and it adds almost nothing beyond the verb. It does not say whether links are returned as raw wikilinks, resolved paths, or with line/context info, nor whether the note must exist. For a tool with zero annotation coverage this is a notable 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?

A single front-loaded sentence with no filler or redundancy. It is efficient, though arguably too thin for a tool that has no annotations or output schema to fall back on.

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?

Parameters are fully covered by the schema, but with no annotations and no output schema the description leaves the return shape of the links unspecified, which is the main thing an agent needs to plan around. Adequate but with a clear 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?

Both parameters (file_path, vault_path) are fully documented in the schema at 100% coverage, so the baseline is 3. The description adds no extra meaning about path resolution or when the vault_path override matters.

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 (get outgoing links from a note), and the word "outgoing" implicitly distinguishes it from the obsidian_get_backlinks and obsidian_get_broken_links siblings. It stops short of naming those alternatives explicitly, so it is clear but not fully differentiated.

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?

There is no when-to-use guidance, no exclusions, and no mention of the closely related obsidian_get_backlinks or obsidian_get_broken_links tools an agent might confuse it with. The only hint of usage is the implicit read-only framing of "Get".

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?

No annotations are provided, so the description carries the full burden. It usefully discloses a fallback behavior (creates a new '## section' if the heading is missing), which is real behavioral context. However it says nothing about permissions, whether existing content is preserved, or side effects.

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

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

Two tight sentences, front-loaded with the primary action followed immediately by the fallback rule. No wasted words.

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

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

For a 5-param tool with full schema coverage and no output schema, the description covers the key behavioral nuance an agent needs (the heading-not-found fallback). It is nearly complete, missing only permission or overwrite semantics.

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 all five parameters are already documented in the schema, including the position enum default. The description adds no additional parameter meaning 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 (insert) and resource (content under a specific heading), which is distinct from siblings like obsidian_append_note or obsidian_replace_section. It doesn't explicitly name those siblings, but the purpose is unambiguous.

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

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

The use case is implied by the heading-based insertion, but there is no explicit when-to-use versus obsidian_append_note, obsidian_replace_section, or obsidian_replace_in_note, and no stated prerequisites. Usage must be inferred.

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

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

With no annotations, the description carries the full behavioral burden, and it discloses little: no statement that this is a read-only listing, no recursion behavior for subfolders, no ordering, no hidden-file handling, and no indication of what the result contains.

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

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

One short sentence with the resource and scope front-loaded; nothing wasted. It is terse rather than padded, which is appropriate for a simple list 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?

A simple read-only tool with two optional params and no output schema, so the bar is low, but an agent still cannot tell whether the listing is recursive, what fields each entry carries, or whether it covers the whole vault by default.

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 optional parameters are already documented in the schema. The description's 'vault or a subdirectory' phrasing loosely maps to subfolder/vault_path but adds no format, default, or override-precedence detail. 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 ('List') plus resource ('markdown files') and scope ('in the vault or a subdirectory'). It implicitly differentiates from obsidian_search_notes (list vs. search), but does not name any sibling explicitly.

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

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

No when-to-use guidance and no alternatives named. An agent choosing between this and obsidian_search_notes or obsidian_get_backlinks gets no routing signal beyond the verb itself.

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?

No annotations provided, so the description must carry full behavioral burden. It doesn't disclose whether the operation overwrites existing files, how links are handled, whether it creates missing directories, or any error semantics. This leaves significant gaps for a file-mutating operation.

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, direct sentence that states the purpose immediately with no wasted words. It is appropriately sized for a simple 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?

For a file-move operation with no annotations, no output schema, and no parameter details in the description, this is incomplete. An agent needs to know about overwrite behavior, link updates, and directory creation. The description leaves these critical aspects unaddressed.

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 all three parameters with examples. The description adds no parameter-level meaning 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?

States a specific verb (move/rename) and resource (note), naming two related operations clearly. It doesn't distinguish from siblings like obsidian_update_frontmatter or obsidian_replace_section, but the verb-resource pairing is unambiguous.

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

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

No guidance on when to use move vs rename, no prerequisites, no mention of what happens to links or backlinks. The description only restates the tool's basic action without context about 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?

No annotations are provided, so the description carries the full behavioral burden. It does disclose useful traits — incremental by default, only changed files re-embedded, cached hashes honored unless force_reindex is set — but says nothing about cost/duration, whether it writes index files to disk, error behavior for a missing vault, or whether it blocks.

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 earning its place: purpose first, then scope control, then default behavior, then the override. No redundancy and no 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 no-annotation, no-output-schema indexing tool this covers invocation but not outcomes. An agent cannot tell whether a result is a summary of indexed files, how long the operation takes, or what happens on partial failure — all relevant because the tool mutates a persistent index.

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 goes beyond the schema by explaining the interaction between parameters — file_path narrows scope to one file, force_reindex ignores cached hashes for a full rebuild — giving the agent operational meaning the field descriptions alone do not convey.

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 ('Index the vault for semantic search (RAG)') and its effect is unambiguous versus the sibling obsidian_rag_query, which reads rather than builds the index. It stops short of naming the sibling explicitly, so an agent must infer the index/query pairing from names alone.

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 conditional usage for each mode: omit file_path for an incremental vault-wide run, pass file_path to re-index a single note, set force_reindex to rebuild from scratch. What is missing is guidance on *when* in a workflow to run it (e.g., after editing notes) and whether it must precede queries.

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?

No annotations are provided, so the description carries the full burden. It doesn't say the operation is read-only, that it requires a prior index build, what is returned (chunks/scores), or how 'limit' affects output – all relevant for a retrieval 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?

A single front-loaded sentence with no waste. It is efficient, though its brevity is also what leaves the gaps noted elsewhere.

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 retrieval tool with no annotations and no output schema, the description should explain what comes back and any index prerequisite. It says only that a search is performed, leaving the agent under-informed about results and preconditions.

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%: both 'query' and 'limit' (default 5) are documented in the schema. The description adds no additional parameter meaning, so the baseline of 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 (semantic search) and resource (indexed vault), which distinguishes it from obsidian_search_notes (keyword search) and obsidian_rag_index (indexing). It does not explicitly name those siblings, so it stops short of a 5, but the purpose is clear.

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?

There is no when-to-use guidance and no mention of the sibling obsidian_search_notes, which an agent must disambiguate against. The only implicit cue is the word 'semantic', and no prerequisites (e.g. that the vault must be indexed first) are stated.

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

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

With no annotations, the description carries the full behavioral burden. It discloses the return format (Markdown content), but says nothing about error behavior for a missing/invalid path, read-only/non-destructive nature, or how vault_path affects resolution.

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 short sentence that is front-loaded and wastes no words. It is appropriately sized, though the brevity edges toward under-specification for a tool with no 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?

For a two-param read tool with full schema coverage, the essentials are present and the return content type is stated (no output schema needed). Missing error/precondition context and vault-override behavior keep it only minimally adequate.

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 parameters are already documented, giving a baseline of 3. The description adds no path syntax, relative-path resolution, or vault-override semantics 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?

Specific verb ('Read') plus resource ('content of a specific note') with the format qualifier '(Markdown)'. It is distinguishable from list_notes/search_notes by targeting a single note by path, but it never names a sibling to sharpen 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?

The description gives no when-to-use versus alternatives such as obsidian_search_notes, obsidian_list_notes, or obsidian_get_daily_note. 'Specific note' weakly implies you already know the path, but no conditional guidance is stated.

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

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

With no annotations, the description carries the full behavioral burden. It helpfully discloses that only the FIRST occurrence is replaced, which is meaningful mutation behavior, but it omits what happens when old_text is not found (error vs no-op), whether the note is created if missing, and any permission requirements.

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 tightly written sentences with the core behavior front-loaded and an illustrative example second. Zero 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 an edit tool with no annotations and no output schema, the description covers the happy path but leaves edge cases unaddressed (match-not-found behavior, non-destructive guarantee). Schema fully covers parameters, but mutation semantics are only partially disclosed.

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 all four parameters (old_text, new_text, file_path, vault_path). The description references old_text/new_text conceptually 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 (replace) plus resource (text string in a note) and adds an important scope qualifier ('first occurrence'). It distinguishes itself reasonably from append/insert siblings, but does not explicitly contrast with the closely related obsidian_replace_section, so differentiation is implied 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?

'Use for surgical inline edits, e.g. adding a wikilink to existing text' gives a positive use case, so usage is implied rather than absent. However, it names no alternatives or exclusions despite siblings like obsidian_replace_section and obsidian_insert_at_heading covering overlapping edit 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?

With no annotations, the description carries full behavioral burden. It usefully discloses that the heading line is preserved and that replacement runs to the next same/higher-level heading or EOF, but it omits important mutation details: what happens if the heading is missing, if multiple headings match, whether the file must already exist, and whether the heading is created.

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 a single efficient sentence with the scope constraint front-loaded and the guaranteed preserved heading called out second. Every clause carries information and nothing is wasted.

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 mutation tool with no annotations and no output schema, the description covers core replacement semantics but leaves meaningful gaps around failure modes, heading-match uniqueness, and whether missing headings or files are handled. It is adequate but not complete for an agent to call it confidently in edge cases.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters, including vault_path as an optional override. The description adds no parameter-level detail beyond what the schema states, so the baseline of 3 is appropriate.

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

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

The description gives a specific verb ('Replace') and resource ('the body under a heading'), and defines the exact scope with the next same/higher-level heading or EOF boundary. It implicitly separates this from insertion/replacement siblings by defining what gets overwritten, but it never names or contrasts them explicitly, so an agent must infer the distinction from sibling names alone.

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?

There is no guidance on when to use this tool versus siblings such as obsidian_insert_at_heading, obsidian_replace_in_note, or obsidian_append_note. It states what the tool does but not the conditions or prerequisites that should select it over 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?

No annotations are provided, so the description carries the full behavioral burden. It discloses only that matching is simple/literal text, leaving case sensitivity, whether titles are searched, result limits, ordering, and vault scoping entirely unstated for a read operation.

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 short sentence with no wasted words, and the resource plus matching mode are front-loaded. Nothing is padded or redundant.

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

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

For a two-parameter read tool with full schema coverage and no output schema, the description is minimally adequate. It omits what the results look like (paths, snippets), the source vault default, and how it differs from the retrieval siblings, which an agent would need to choose correctly.

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

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

Schema description coverage is 100%, so both 'query' and 'vault_path' are already documented in the schema; baseline is 3. The description adds no syntax, escaping, or multi-term matching detail beyond that.

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 clear verb ('search') and resource ('notes') and clarifies the matching mode as a 'simple text match', which hints at literal substring matching rather than semantic retrieval. It does not, however, explicitly name the sibling obsidian_rag_query, so an agent must infer the distinction itself.

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?

There is no when-to-use guidance, no mention of alternatives (e.g. obsidian_rag_query for semantic search, obsidian_list_notes for enumeration), and no prerequisites or exclusions. The parenthetical 'simple text match' is the only implicit usage signal.

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?

No annotations are provided, so the description carries the full burden. It says the vault applies 'for this session,' which is useful scoping context, but never states whether the path must exist, whether invalid paths error, whether this persists across sessions, or what happens to previously listed notes.

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, front-loaded sentence with zero waste. The session-scoping constraint is stated immediately and nothing is redundant.

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

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

For a state-setting tool with no annotations and no output schema, the description should cover prerequisites (does the vault need to exist?) and side effects (does this affect all subsequent Obsidian calls?). It covers only the bare minimum.

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 sole 'path' parameter is fully documented as an absolute path in the schema. The description adds no syntax or format detail beyond that, 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?

States a specific verb (set) and resource (default Obsidian vault path) scoped to the session. It's clear what the tool configures, though it doesn't differentiate itself from other configuration siblings or explain how this state interacts with the rest of the Obsidian toolset.

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?

No guidance on when to call this versus alternatives. With a catalog of 17 sibling tools, the description doesn't tell the agent when this setup step is required or how the vault default affects subsequent operations.

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

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

With no annotations, the description carries the full burden, yet the only behavioral hint is the vague adverb 'safely' – it never explains what safety means, whether existing keys are preserved, permissions needed, or reversibility. For a mutation tool with zero structured behavioral coverage this is a significant 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 short sentences, front-loaded with the core action and followed by the mode support. No filler; every phrase contributes.

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 five-parameter mutation tool with no annotations and no output schema, the description is thin – the meaning of 'safely' and the interaction between single and batch modes are left to inference. It is minimally adequate given the rich schema but does not fully compensate for the missing behavioral detail.

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 defines all five parameters. The description's reference to 'single key/value or batch updates' loosely maps to the key/value versus updates parameters but adds no syntax or format 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?

The description names a specific verb and resource ('Update YAML frontmatter of a note') and clarifies the two operating modes (single key/value vs. batch). It distinguishes the tool's role from siblings like obsidian_replace_in_note or obsidian_insert_at_heading, though it doesn't name or contrast them explicitly.

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

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

Usage is only implied through the mention of 'single key/value or batch updates', which hints at mode selection but doesn't state when to use this over sibling mutation tools or what prerequisites apply. No explicit when-not or alternative routing is provided.

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