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

With no annotations, the description carries the full burden. It does add useful behavioral context: outbound links are returned 'with resolution' and frontmatter links count as real references (with a concrete example). That is genuinely non-obvious. But it says nothing about pagination/limiting behavior or the cost of the 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?

Two short, front-loaded sentences with the core purpose stated first and a clarifying edge-case note second. Minimal waste, though the second sentence is a somewhat disjoint detail.

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?

An output schema exists, so return values need not be explained. Given no annotations and 0% schema coverage, the definition still leaves the `k` parameter, pagination, and when-to-use-versus-siblings unaddressed, making it adequate but incomplete.

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 0% and there are 2 parameters. The description never mentions `k` (the result limit) or clarifies `file_path`; only 'this note' loosely implies the target. With zero coverage in the schema, the description should compensate but does not.

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 purpose: it returns inbound links (who links to this note) and outbound links (where the note points). This clearly distinguishes it as a link-relationship tool versus a content reader. However, it does not explicitly differentiate itself from closely-related siblings like broken_links, find_related, or graph_overview.

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 clarifies scope and what the tool returns, so usage is implied, but there is no explicit when-to-use guidance and no named alternatives among the many link/graph-related siblings (broken_links, find_related, graph_overview). The agent must infer when this is preferable.

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 burden. It does disclose one behavioral trait beyond the schema: results are grouped by source note, which tells the agent the return shape. However, it says nothing about the index dependency (index_now exists as a sibling, implying staleness is possible) or the read-only/rate-limit profile.

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 with no wasted words, front-loading the defining characteristic (links that resolve to nothing) and the grouping in one clause.

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?

An output schema exists, so return values need not be explained, and the grouping is stated. Still missing for a link-integrity tool are the index-freshness caveat and the semantics/scope of limit, leaving an agent to guess about result truncation.

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 0% and the description never mentions the sole parameter. It is unclear whether limit caps broken links, source notes, or groups, nor what the default 200 means in context — the description does not compensate for the schema gap.

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 resource and scope: wiki-links that fail to resolve, resolved by stem or title. It is a noun phrase with no verb, but the intent (find broken links) is unambiguous and clearly distinct from the broader backlinks and graph_overview 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?

Usage is implied by the resource itself — an agent looking for dangling wiki-links would pick this up — but there is no explicit when-to-use statement, no mention of prerequisites such as a fresh index, and no comparison against the overlapping backlinks tool.

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

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

With no annotations, the description carries the full burden, and it does disclose the retrieval mechanism (semantic similarity plus 1-hop wiki-link expansion), which is genuinely useful behavioral context. However, it says nothing about result ordering, whether expansion can be large/expensive, or that this is a pure read operation beyond the implied 'Find'.

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; the mechanism clause sits immediately after the purpose and earns its place by defining the ambiguous term 'related'.

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 an output schema (so return values need no explanation), the definition supplies the one thing an agent must know: what 'related' means. The only gap, the meaning of k, is minor against that.

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 0%, so the description must compensate and does not: 'k' (default 10) is never mentioned, leaving the agent to guess whether it caps semantic neighbours, expanded links, or total results. 'file_path' is self-evident, but the one non-obvious parameter is entirely undocumented.

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 ('Find notes related to the given note') and adds scope detail ('semantic neighbours + 1-hop wiki-link expansion') that clarifies what 'related' means. It implicitly distinguishes itself from siblings semantic_search and backlinks by combining both signals, but never names 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 implied by the purpose: call it when you want related notes for a known file. There is no explicit when-to-use guidance versus semantic_search (semantic only) or backlinks (link only), which are the obvious alternatives, and no stated 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?

With no annotations, the description carries the full burden, and it does clarify what the operation yields by defining 'hub' and 'orphan' semantically. However, it says nothing about read-only behavior, cost, whether the graph is computed live, or pagination/limits on the returned results.

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 resource and immediately defines both returned categories. There is no filler and nothing that could be cut without losing meaning.

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?

Because an output schema exists, return values need not be described, and the qualitative category definitions are helpful. But the unexplained k parameter and the complete absence of usage guidance leave real gaps for an agent deciding whether and how to call this.

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 0% for the single parameter 'k', and the description never mentions it. An agent cannot tell from either source whether k controls the number of hubs, orphans, or both, nor how it interacts with the default of 15.

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 the specific resource (knowledge graph) and precisely defines its two output categories: hubs as notes with the most outgoing wiki-links and orphans as notes with no links. That makes it distinguishable in spirit from backlinks or broken_links, though it never names those siblings 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?

There is no statement of when to call this versus siblings like backlinks, broken_links, or list_notes, and no exclusions or prerequisites. The agent must infer the use case from the subject matter 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?

With no annotations present, the description carries the full burden and does disclose meaningful behavior: the lock-based concurrency model and that a competing run exits immediately, plus the fact that 'full=True' re-embeds everything (a costly, potentially long operation). It omits expected duration, whether the call blocks the caller, 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 short sentences, no filler. The primary action is front-loaded and the concurrency caveat follows, so the most important information comes first.

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?

An output schema exists, so return values need not be described, and the mutation/concurrency behavior is covered. What remains thin for a state-mutating indexer is the absence of any note on typical runtime, resource cost, or whether the caller is blocked while indexing runs.

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 0% and the 'full' property has no description, so the description must compensate — and it does, explaining that the default is incremental while 'full=True' re-embeds everything. Minor gap: no detail on cost/runtime tradeoffs of full mode.

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: 'Run the vault indexer now', with an explicit scope modifier ('incremental' by default). No sibling tool (vault_status, list_notes, semantic_search, etc.) performs indexing, so an agent can route to it unambiguously.

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

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

Implies use when the index needs refreshing, and the 'full=True' note hints at the choice between incremental and full runs. However, it never states when an agent should trigger re-indexing versus relying on existing state, nor any prerequisites before calling.

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 burden. It does disclose that this is a lightweight listing returning only metadata fields (implying no note bodies), but says nothing about permissions, pagination beyond the schema default, or whether results are ordered or truncated. Partial disclosure only.

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 terse sentences, front-loaded with what the tool returns, then how to filter. Every clause earns its place with 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?

An output schema exists, so return values need not be fully specified, and the description still summarizes them. For a simple zero-required-parameter read tool this is nearly sufficient; only the 'limit' behavior and result ordering are left to inference.

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 0%, so the description must compensate. It covers two of three parameters ('tag', 'folder prefix'), and 'prefix' adds matching semantics beyond the schema, which is genuinely useful. However, the 'limit' parameter is left unexplained in both schema and description.

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

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

The description names a specific action and resource ('inventory of notes') and enumerates the fields returned (file_path, title, type, status, tags), which tells an agent this is a metadata-only listing rather than a content read. It stops short of naming a sibling such as read_note or semantic_search 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?

The word 'cheap' implicitly signals when to prefer this over heavier tools like semantic_search or read_note, but there is no explicit when-to-use or when-not-to-use statement and no named alternative. Usage is inferable rather than 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 burden. It usefully discloses that this is a lightweight/cheap read that returns only headings rather than full content, but says nothing about failure modes (missing file), permissions, or size limits.

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 clause: what it returns, then why it is worth calling. Zero 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?

An output schema exists, so return-value detail is not required, and the description still summarizes the shape (headings + levels). For a one-parameter read tool this is essentially complete; only path-format guidance 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 0% for the single file_path parameter, so the description must compensate. 'of a note' weakly implies the path is a note identifier, but format/source (vault-relative vs absolute) is left entirely unstated.

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 precisely what is returned: a note's headings with their levels. Implicitly distinguishes itself from read_note via 'cheap context before reading the whole thing,' though it never names the 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?

'before reading the whole thing' implies the workflow position relative to read_note/read tools, giving usable but inferred guidance. There is no explicit when-not-to-use or named alternative.

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 burden. It does disclose real behavior — max_chars bounds output and truncation is explicitly marked — which is genuinely useful. It omits, however, what happens on a missing/invalid path or non-text file, and gives no hint about encoding or result metadata, leaving notable gaps 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?

Two short sentences, front-loaded with purpose, then the one behavioral nuance that matters (truncation). Nothing redundant or padded.

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?

An output schema exists, so return values need not be documented, and the description covers the path source and truncation behavior. The main residual gap is error/missing-file behavior, which keeps it from a 5 for a tool with zero annotation coverage.

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 0%, so the description must compensate, and it largely does: max_chars is explained (bounds the result, truncation is marked) and file_path is defined as a relative path sourced from semantic_search/list_notes. What's missing is what the path is relative to (vault root) and any default/limit semantics for max_chars beyond null.

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 (vault note) plus the lookup key (relative path), which cleanly separates it from write_note, update_note, and the snippet-returning semantic_search. An agent can tell what this returns (full text) versus a listing or search tool.

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 parenthetical '(path from semantic_search/list_notes)' tells the agent the intended workflow: obtain a path from a search or listing tool, then read here. It gives clear context but names no explicit exclusion or alternative condition, so it falls 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?

With no annotations the description carries the full burden, and it does well: it discloses the retrieval method (dense+BM25 fused with RRF), the return content (chunks with citations), and, notably, the semantics of the `index_stale` result field (0 = current, -1 = never run) so the agent can gauge trust. It stops short of 5 only because it omits things like result freshness implications of running a search against a stale index or whether an indexing step is required first.

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 capability, then a short paragraph on the one non-obvious parameter and the staleness signal. Every sentence earns its place; minor verbosity in the parenthetical '(default 1, the previous behaviour)'.

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?

An output schema exists, so return values need not be explained, yet the description usefully clarifies the subtle `index_stale` field. However, for a 5-parameter tool with 0% schema coverage it leaves `k`, `tag`, and `folder` entirely unexplained, which is a real gap for correct invocation.

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

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

Schema description coverage is 0% across 5 parameters. The description explains `chunks_per_note` well and implies `query`, but `k`, `tag`, and `folder` receive no meaning, syntax, or filtering guidance in either the schema or the description, leaving half the surface undocumented.

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?

Names a specific verb+resource: hybrid (dense+BM25, RRF) semantic search over the Obsidian vault, and states the return shape (chunks with file_path citations). It does not explicitly differentiate itself from near siblings like find_related or list_notes, so it stops short of a 5.

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 routing to alternatives such as find_related, read_note, or a keyword search. The reader must infer that this is the tool for semantic retrieval over the vault, and nothing tells them when a different sibling is preferable.

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 does add real value: partial-patch semantics ('Only the arguments you pass are changed'), the `updated` bump, and a validation constraint (at least one resolvable [[wiki-link]] must remain). However, it omits auth/permission needs, what happens on a nonexistent file, and the effect of auto_index/retracted, leaving meaningful gaps for a 14-param mutation.

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 tight sentences, front-loaded with the core action and constraint; each sentence conveys distinct information about mutation scope, body handling, and validation. 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 14-parameter, unannotated mutation with 0% schema coverage, the description leaves most parameters and failure modes undocumented, even though the presence of an output schema excuses it from explaining return values. It is not complete enough for an agent to invoke confidently across the full parameter set.

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 0%, so the description must compensate for 14 undocumented parameters. It only clarifies `content` (replaces body) and `append` (appends instead), plus a vague reference to 'frontmatter fields'; the remaining ~11 params (moc, tags, type, title, status, aliases, auto_index, supersedes, etc.) get no semantic help from either source.

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 ('Patch an existing note in place') and clarifies that it touches frontmatter fields and/or body while bumping `updated`. This makes the patch-vs-full-write distinction against write_note inferable, though the sibling is never named explicitly.

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

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

The description explains mechanics but never states when to choose update_note over write_note or other siblings, nor any prerequisites (e.g. the note must already exist). No when/when-not guidance is present.

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 the index-refresh behavior (writes auto-refresh, external edits leave it stale), which is genuine context beyond the tool's output. It does not state read-only/safety profile or any permission/rate constraints, keeping it out of 5 territory.

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 definition ('Index health: ...') followed by tightly relevant usage context. Two short blocks with no padding, though the second paragraph blends usage guidance with behavioral detail.

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?

An output schema exists, so return values need no elaboration, and with zero parameters the schema gap is nil. The description supplies purpose and the key staleness caveat, making it complete enough to call 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 takes zero parameters, so the schema cannot carry semantic weight; baseline is 4. Nothing in the description misrepresents the empty argument set.

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 resource and scope: reports index health, specifically notes on disk vs indexed, last run time, and which notes changed. This clearly distinguishes it from search/read siblings, though it does not name a specific sibling it differs from (e.g. index_now) to reach a 5.

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 condition for use: 'Call this before trusting a search result,' tied to the trigger of an external manual file edit leaving the index stale. Lacks an explicit pointer to the remediation sibling (index_now) for when the index is stale, so it stops 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?

With no annotations, the description carries the full behavioral burden. It usefully discloses that unresolved links are reported rather than rejected and that the index refreshes automatically, which is non-obvious context. But it omits a critical write-tool behavior: what happens if file_path already exists (overwrite vs. error), and any permission/conflict 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?

Front-loaded with the core purpose, then layered with format and behavioral detail; every sentence carries information and nothing is padded. The one blemish is the misplaced '`description` is required' claim, which is both incorrect against the schema and interrupts the otherwise tight structure.

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 12-parameter mutation tool with 0% schema coverage and no annotations, the description covers the trickiest params and two key behaviors, which is meaningful. But it leaves most parameters undocumented and never resolves the overwrite/conflict question, so an agent could still call it incorrectly. The existing output schema relieves the description of return-value duty.

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 0%, so the description must compensate, and it does add real meaning for a few params (file_path kebab-case EN in vault root, moc accepts 'Rust MOC' or '[[Rust MOC]]', auto_index batching). However, 8 of 12 params (tags, type, status, aliases, retracted, supersedes, content, title) get no semantic treatment. It also asserts 'description is required' while the schema marks it optional with default null — a factual conflict.

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 first sentence gives a specific verb+resource: 'Create a new vault note.' The word 'new' distinguishes it implicitly from the sibling update_note, but that contrast is never made explicit. An agent can identify the operation, but the sibling differentiation is left to inference.

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 supplies workflow context (a hub may be written before its spokes, use auto_index=False to batch) which implies how the tool fits into a flow. However, it never states when to reach for write_note versus update_note, nor any prerequisites such as whether the target file must not already exist. Usage is implied, not directed.

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