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

Even though annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, the description goes well beyond that. It reveals the return shape (`{total, items}` with item fields), the session-vault behavior with the `vaultPath` override rule, and the language-specific scanning restrictions. None of this is available in the annotations, and it contradicts nothing.

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 efficiently structured across two paragraphs, front-loading the purpose and usage in the first sentence. Every sentence adds distinct value—scope, usage trigger, parameter behavior, return format, and vault context—with no filler. It is long but information-dense, and the structure makes it easy to scan.

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

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

For a list tool with three optional parameters, the description is comprehensive. It covers scoping (single note vs vault), language filtering, vault selection, return shape (though the output schema presumably details it further), and language-specific requirements. There is no missing information that would prevent a correct call, and the output schema handles return-field specifics.

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 each parameter has a description, but the explanation text adds critical interplay semantics not present in the schema: omitting `language` lists all three types in one call, vault-wide scanning is only for Mermaid, and `filePath` is mandatory for Dataview languages. It also clarifies that `vaultPath` always overrides the ambient vault. This is exactly the kind of cross-parameter behavior an agent needs.

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: 'List fenced code blocks' of three named languages, scoped to a single note or the entire vault. It explicitly differentiates itself from the sibling tools blocks.read and blocks.update by stating it is for discovery 'before reading or updating them.' No ambiguity remains about what this tool does.

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 tells the agent exactly when to use it: 'Use this to discover what DQL, DataviewJS, or Mermaid blocks exist before reading or updating them.' It also gives concrete usage constraints: omitting `language` lists all three types, vault-wide scanning works only for Mermaid, and a `filePath` is required for Dataview languages. This is explicit, actionable guidance with no need for 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?

Beyond the readOnly and idempotent annotations, the description discloses key behaviors: blockId takes precedence over index, index defaults to 0 within the language group, failure returns not_found, and vault resolution prefers vaultPath over the session-active vault. This is substantial behavioral context that cannot be inferred 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?

The description is front-loaded with the core action and then adds only high-value details: locator rules, language requirement, failure behavior, and vault scoping. Every sentence contributes operational guidance, and the examples for metadata (Mermaid directives, Dataview DQL parts) clarify the abstraction.

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 an output schema exists and annotations cover safety, the description needs only to explain selection, error behavior, and vault scoping — all of which it does. Nothing required for a correct call is missing; the parameter semantics, failure mode, and vault override are all explicit.

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

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

Although schema coverage is already 80%, the description adds meaningful semantics: blockId is 'stable' and 'takes precedence,' index is '0-based within the language group' with a default of 0, language is required for parser dispatch, and vaultPath 'always wins.' It fully compensates for the undocumented vaultPath parameter and enriches the schema descriptions.

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

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

The description opens with 'Read one fenced block's source and language-specific metadata,' which is a specific verb+resource statement. It clearly differentiates this from sibling tools like blocks.list (reads one vs. lists) and blocks.update (read vs. modify), so an agent can identify the right operation 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?

The description provides clear usage context: locate by blockId (preferred) or index, language is required, and vaultPath overrides the active vault. It does not explicitly name alternatives like blocks.list for finding blocks or blocks.update for modifying them, so it stops short of full when/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?

The description goes well beyond the annotations: it explains the source-preserving behavior, language-mismatch failure, fence exclusion, idempotent no-op effect, in-place destructive overwrite, and vault selection semantics. These details align with the idempotentHint and destructiveHint annotations without contradicting them.

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 efficiently organized: core behavior and constraints first, then vault targeting, then concrete examples. Every sentence earns its place, and the examples are compact yet informative.

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

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

Given the tool's six parameters and the existence of an output schema, the description covers all essential calling context: block selection, language guard, source format, vault resolution, idempotency, destructiveness, and failure behavior. An agent has enough information to invoke this tool correctly without additional documentation.

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 83%, so the schema already documents most parameters. The description adds value by clarifying that source must exclude fences, that language is a guard, that blockId takes precedence over index, and especially by documenting the vaultPath override semantics that the schema leaves bare. The examples further disambiguate realistic usage.

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: replace one fenced block's body, with explicit scope boundaries (fences, language tag, and neighboring content untouched). This clearly differentiates it from read-oriented siblings like blocks.list/blocks.read and whole-note tools like notes.edit.

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

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

The description gives clear operational context: how to locate the block via blockId or index, that language acts as a guard, and that the tool operates on the session-active vault unless vaultPath is supplied. It does not explicitly name alternatives or say when not to use this tool, but the context is strong enough for an agent to apply it correctly.

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 state readOnlyHint, idempotentHint, and destructiveHint, so the description's 'Read-only' is redundant but not harmful. It adds valuable behavioral context about session-active vault resolution and the precedence of an explicit vaultPath, which is not derivable 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 tight sentences: operation, use case with alternative, and vault behavior. No filler, and the most important information is 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?

Given the output schema exists and annotations cover safety, the description provides the essential context: graph-walking use case, full-graph alternative, and vault resolution rules. Nothing critical is missing for an agent to select and invoke this 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?

Schema covers nodeId and filePath with good descriptions, and the description fills the gap for vaultPath by explaining it overrides the session-active vault. This is meaningful added meaning beyond the schema for the undocumented parameter.

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 precise verb and resource: 'Return the incoming and outgoing edges of a single canvas node.' It clearly differentiates from canvas.parse, which handles full-graph parsing, and from links.connections, which likely deals with note links rather than canvas edges.

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 this tool ('to walk the canvas graph one node at a time without loading the full document') and names the alternative for full-graph parsing ('use canvas.parse'). It also clarifies the vault selection behavior with vaultPath taking precedence.

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 is transparent about failure behavior and overwrite semantics, but annotations declare destructiveHint:false while the description states that overwrite:true overwrites an existing file. That is a contradiction on a safety-critical behavioral trait, so this dimension must be scored down despite the otherwise strong disclosure.

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, then adds only necessary details: failure behavior, file format relevance, next-step sibling, and vault targeting. Every sentence earns its place and there is 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 create operation with an output schema, the description covers the essential invocation context: target path, overwrite behavior, vault resolution, file type, and follow-up editing tool. An agent has enough information to call it correctly in most scenarios.

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 documents filePath and overwrite, but vaultPath has no schema description. The tool description compensates by explaining vaultPath precedence over the session-active vault, which is exactly the missing semantic context an agent needs. It also reinforces the overwrite behavior with the fail-if-exists default.

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 ('Create'), a precise resource ('new empty Obsidian canvas (.canvas) file'), and path-based placement. It also distinguishes itself from the sibling canvas.edit by making clear that canvas.edit is for adding nodes/edges after the file exists.

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

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

It explicitly says to use this tool first and then canvas.edit for nodes/edges, providing a clear workflow. It also explains the overwrite condition and the session-active vault resolution, including the vault.select/vault.current relationship, which helps an agent decide how to target the right vault.

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 transparently discloses that remove-node is destructive and cascades to incident edges, and explains vaultPath precedence. However, the annotations declare destructiveHint=false, which directly contradicts the description's explicit 'destructive' warning. Per the scoring rule, this contradiction forces a score of 1.

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 well-structured: a purpose sentence, operation-specific parameter requirements, vault behavior, and three concrete JSON examples. Despite its length, every sentence earns its place, and the examples dramatically reduce ambiguity for op-specific payloads.

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

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

The description covers all three op variants with required and optional parameters, the destructive side effect, vault resolution rules, and the standard mutation envelope return. With a full input schema and an output schema present, nothing needed 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 coverage is 100%, so the baseline is 3. The description adds value beyond the schema by grouping required parameters per op, explaining the content semantics for nodeType text vs file, and stating that vaultPath always wins over the active vault — details that help an agent assemble valid calls.

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: 'Mutate a canvas' followed by the three exact mutations (add node, add edge, remove node). This clearly distinguishes the tool from siblings like canvas.create and canvas.parse, and the op-specific breakdown leaves no ambiguity about what the tool does.

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

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

The description provides clear context for when to use the tool: any mutation of an Obsidian canvas, with explicit detail on which op needs which parameters. It also clarifies vault resolution (session-active vault vs explicit vaultPath), but it does not explicitly name sibling alternatives or list exclusion conditions, 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it explains the session-active vault resolution and that an explicit vaultPath always wins, which is important for correct invocation.

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 compact and front-loaded: the purpose, output, and primary alternative appear in the first two sentences. The vault-targeting note is the only additional context and is directly relevant to usage. No sentence 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?

With an output schema present, return-value details are handled structurally. The description covers the tool's purpose, when to use it, the alternative tool, and the vault resolution rule. It is complete for a read-only parsing tool, though it does not mention error behavior for invalid canvas files, which is a minor gap.

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

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

Schema coverage is 50%: filePath is documented but vaultPath has no schema description. The description compensates by explaining vaultPath's role and precedence over the active vault, giving the agent enough semantics to use it correctly. It does not detail vaultPath's format, but the core meaning is clear.

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 ('Parse'), a specific resource ('Obsidian canvas file'), and the exact output scope ('full structure: every node ... every edge'). It also explicitly contrasts itself with canvas.connections, so an agent can distinguish it from its closest sibling without opening 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?

The description gives an explicit usage rule: use this tool for the complete graph, and use canvas.connections for neighbours of a specific node. It also clarifies the vault-targeting behavior and references vault.current and vault.select, providing clear context for when this tool applies.

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. The description reinforces this by stating 'Destructive — the effect depends entirely on what the command does' and adds a verification warning. It also discloses the plugin requirement, the targeting of the live Obsidian vault, and that routing is unaffected by `vault.select`. This adds significant context beyond the annotations with no contradiction.

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

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

The description is two short paragraphs that are front-loaded with the core purpose and then add relevant contextual warnings. It avoids redundancy with the schema and each sentence contributes either a prerequisite, a caution, or a routing clarification. It could be slightly tighter (e.g., merging the two paragraphs), but it is appropriately sized for a potentially dangerous 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?

Given the tool's high risk (executes arbitrary commands) and the presence of a full schema and output schema, the description covers all critical aspects: how to identify a command, optional arguments, required plugin, destructiveness warning, target scope, and routing behavior. It does not describe error handling, but that is not essential when the description already meets the safety and usage needs for an agent.

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

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

Schema coverage is 100%, so both parameters are already well-documented. The description enhances this by clarifying that `args` is an optional argument map and that most built-in commands take no arguments (matching the schema's note). More importantly, it tells the agent where to obtain a valid `commandId` (via `commands.list`), which is not in the schema. This added guidance slightly exceeds the baseline for 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 description states a specific verb ('Execute') and a clear resource ('an Obsidian command by its internal id'), and references `commands.list` as the source of ids. It also explicitly notes that `vault.select` does not affect this tool, distinguishing it from filesystem-routing tools. This is a precise, unambiguous purpose statement.

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 mentions a clear prerequisite (Requires the Local REST API plugin) and gives a caution to verify the command id before calling, which guides safe usage. It does not explicitly state when to use this tool over alternatives, but the reference to `commands.list` implies a natural sequence and the `vault.select` note clarifies when it is not affected. Lacks an explicit when-not-to-use, so a 4 is appropriate.

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

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

Annotations already carry readOnlyHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context beyond annotations: it requires the Local REST API plugin, targets the currently open vault, and is unaffected by vault.select. These are non-obvious traits an agent needs to know and are not present in the annotations.

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

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

The description is two tight paragraphs. The first sentence delivers the core action, then each subsequent sentence adds necessary behavior, usage, or routing context. There is no redundant filler, and the most important facts (purpose, query behavior, read-only, usage) are front-loaded.

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

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

For a simple listing tool with one optional parameter and an output schema, the description is complete. It covers purpose, query semantics, read-only safety, plugin dependency, vault targeting, and routing independence. Nothing essential for an agent 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?

The input schema fully covers the query parameter (100% coverage), so the baseline is 3. The description adds specific detail: case-insensitive substring matching and that it returns both built-in and plugin-provided commands, which enriches meaning beyond the schema's minimal 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 clearly states the verb 'List' and the resource 'Obsidian commands', and explains behavior with and without the query parameter. It distinguishes itself from siblings like commands.execute by explicitly stating it is for discovering command ids before executing, making its purpose unmistakable.

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

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

It explicitly says 'Use this to discover command ids before calling commands.execute', giving a clear when-to-use scenario and differentiating from the primary sibling. It also notes it is read-only and not affected by vault.select, which helps an agent decide when to invoke it.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds meaningful behavior beyond that: the exact semantics of `extract` (combining page, list-item, and task-line fields) and `search` (coercion via `valueType`, scope restrictions). It also discloses the vault selection rule (`vaultPath` always wins), which is not derivable from the schema 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?

The description is information-dense but logically structured: it opens with the core purpose, then details each operation, then addresses read-only status and vault selection. Every sentence earns its place—no filler or redundancy.

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

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

Given the tool's moderate complexity (two operation modes, optional parameters), the description covers all necessary invocation details: the meaning of both ops, the role of `scope`, the vault selection mechanism, and the pointer to the write counterpart. An output schema exists, so return-value documentation is not needed here. 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 the schema itself provides descriptions for `key`, `scope`, and `valueType`, so the parameters are well-documented. The description adds value by explaining how parameters interact across the two `op` variants (e.g., `extract` requires `filePath`, `search` requires `key` and optional `value`/`valueType`). This goes beyond the schema's per-field descriptions.

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

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

The description clearly states the resource (Dataview fields) and the two distinct operations (`extract` and `search`) with precise scoping. It differentiates from the sibling `dataview.fields.write` by explicitly labeling itself read-only, so an agent can immediately tell which tool handles mutation.

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 a direct pointer to the alternative (`For mutating fields, use dataview.fields.write`) and explains when to use each operation: `extract` for a single note, `search` for whole-vault matching. It also clarifies the `vaultPath` precedence rule, which is essential for correct invocation in multi-vault sessions.

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 goes beyond the annotations by explaining exactly what each op does, including that remove 'deletes every occurrence' of a key, and explicitly discloses idempotence and vault selection behavior. No contradiction with annotations is apparent: idempotentHint matches, and the scoped field-write semantics are compatible with destructiveHint=false.

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, followed by compact parameter semantics, one behavioral caveat (idempotence/vault), and two worked examples. No sentence is filler; the length is justified by the two-branch op and several interacting options.

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

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

For a tool with a discriminated union, multiple enums, and optional interactions, the description plus schema is complete enough to call it correctly: it covers both ops, placement, syntax, scope, vault selection, and default behavior for insertAt. The output schema exists, so return values are not the description's burden.

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?

Even with 100% schema coverage, the description adds substantial meaning: it defines how syntaxType renders the field, how insertAt and lineNumber interact, how scope restricts removal, and that vaultPath overrides the active vault. The two JSON examples tie the parameters together into valid call patterns.

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 precise verb+resource: 'Insert or remove a Dataview field in a single note.' It then explains the two op modes and rendering options, making the tool's function unmistakable and distinct from read-only siblings like dataview.fields.read.

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 clearly establishes when the tool is appropriate: whenever a single note's Dataview field needs to be added or removed, and it explains vault targeting (session-active vault versus explicit vaultPath). It does not explicitly name sibling alternatives or state when not to use it, so it falls just short of full routing 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=true, destructiveHint=false, and idempotentHint=true. The description adds behavioral context beyond these by stating 'Read-only, runs locally (does NOT require the Local REST API)' and explaining that vaultPath overrides the active vault. This is useful extra information about execution environment and precedence, though it does not detail error handling or output structure (covered by output schema). No contradiction with annotations.

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

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

Two paragraphs: the first front-loads the main purpose and output scope in a compact sentence; the second addresses vault selection. No redundancy, no filler. Every clause adds information. Highly efficient for the information conveyed.

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 tool is moderately complex with an output schema. The description covers the key aspects: what data is returned, the read-only guarantee, local execution (no REST API), vault selection logic, and the intended use case. It does not discuss potential errors (e.g., file not found) but given the output schema and annotations, this is sufficient. Sibling tools are numerous, but the description positions it well.

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

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

Schema description coverage is 0%, so the description must compensate. It does clarify that vaultPath 'always wins' over the session-active vault, giving meaning to that optional parameter. For filePath, it only implies 'a single note' but does not specify path format or resolution rules. Given two parameters, the description provides some value but not comprehensive compensation for the missing schema descriptions.

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

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

The description states a specific verb ('Parse a single note') and a resource with explicit detail about what is returned: page-level metadata, list-item fields, task-line fields, and DQL/DataviewJS block locations. It clearly distinguishes from siblings like dataview.query (runs queries) and notes.read (raw content) by positioning itself as 'what Dataview would index'.

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

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

The description explicitly states the intended use case: 'Use this to understand what Dataview sees in a note without running a query.' It also gives context on vault selection (active vault vs explicit vaultPath). It does not explicitly name alternatives for when to run a query, but the phrase 'without running a query' implies the distinction. Clear enough for an agent to decide appropriately.

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 references an explicit `vaultPath` argument that does not exist in the input schema. This is misleading and could cause an agent to pass an invalid parameter. While annotations already cover readOnly/idempotent/destructive hints, the description adds inaccurate behavioral context rather than useful information, and the vault-selection behavior is described in a way that conflicts with the actual parameter list.

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

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

The description is two short paragraphs. The first paragraph states purpose and plugin requirements; the second clarifies vault selection. Information is front-loaded, and every sentence serves a purpose. There is no fluff or repetition of schema details.

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

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

While the description covers plugin requirements and vault behavior, the major inconsistency of referencing a `vaultPath` parameter not present in the schema creates a significant gap. An agent relying on this description might try to pass `vaultPath` and fail. The output schema exists, so that part is not an issue, but the misleading information makes the description incomplete and potentially harmful.

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 already has a clear explanation. The description adds an example for `sortBy` ('file.ctime desc') and clarifies the DQL mapping for where/sort/limit, but this is marginal. It does not significantly enhance understanding beyond what the schema provides, and the misleading `vaultPath` mention negatively impacts clarity.

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

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

The description clearly states it is a convenience wrapper around `LIST FROM "folder"` with optional DQL clauses. It explains the exact use case ('every note under a vault folder') and naturally distinguishes it from siblings like dataview.query (general DQL) and dataview.listByTag (by tag). The verb and resource are specific and unambiguous.

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

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

The description says it is 'useful when you want every note under a vault folder,' which is a clear usage context. It also mentions the Dataview and Local REST API plugin requirement. However, it does not explicitly name alternatives like dataview.query or state when not to use this tool, relying instead on implication from the term 'convenience wrapper.'

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

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

Annotations already mark it as read-only and idempotent, but the description goes further: it discloses that the tool is a convenience wrapper, returns the same shape as dataview.query, requires specific plugins, and operates on the session-active vault unless vaultPath is provided. These are significant behavioral details not encoded in annotations.

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

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

The description is compact and front-loaded: it states the core action, then usage guidance, then vault behavior. Every sentence adds value, no filler or repetition.

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

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

Given the tool's moderate complexity, the full schema coverage, the presence of an output schema, and rich annotations, the description covers all necessary aspects: purpose, usage, requirements, vault selection, and expected return shape. 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?

The input schema already has 100% coverage with clear descriptions for all four parameters (e.g., tag accepts leading `#`, sortBy is a DQL clause body). The description does not add further parameter-specific detail; it only restates the optional clauses in prose, so a baseline 3 is appropriate.

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

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

The description clearly states it is a wrapper around `LIST FROM #tag` and explicitly contrasts it with raw DQL ('Use this instead of authoring raw DQL when filtering by a single tag'), making its purpose and differentiation from sibling tools like dataview.query 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?

Provides explicit when-to-use guidance ('when filtering by a single tag') and names the alternative (raw DQL). It also adds prerequisites (Dataview and Local REST API plugins) and explains vault selection behavior, leaving no ambiguity about when to call it.

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

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

The description adds meaningful context beyond the readOnlyHint/idempotentHint annotations by disclosing plugin requirements, authentication configuration, and vault-scoping behavior. However, the statement about a 'vaultPath' argument that overrides vault selection is factually inconsistent with the schema, which undermines trust in the behavioral description. It provides some value but also introduces a false behavioral claim.

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 a clear purpose statement, followed by examples, alternatives, prerequisites, and vault behavior. It is somewhat long but each sentence adds value. The only structural issue is that the vaultPath mention is placed as a final aside, slightly muddling the otherwise clean flow.

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

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

The description covers the essential prerequisites, alternative tools, and vault behavior, and an output schema exists so return values are not required. However, the incorrect vaultPath reference is a significant completeness gap: an agent following the description may attempt to pass an invalid parameter. Additionally, the description does not mention error handling or query syntax validation, which would be useful for a raw DQL tool, though not strictly necessary given the 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?

The schema already covers the 'query' parameter well (100% coverage), so the baseline is 3. The description adds useful clarification that the query is 'raw DQL' and gives examples, which helps. But it also references a 'vaultPath' parameter that does not exist in the schema (additionalProperties: false). This is actively misleading and could cause an agent to include an invalid parameter, so the score is dropped below 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?

The description explicitly states the tool's action: 'Execute an arbitrary Dataview Query Language (DQL) query.' It provides concrete examples (LIST FROM #inbox, TASK WHERE !completed) and distinguishes itself from sibling sugar tools like dataview.listByTag by positioning this as the escape hatch for custom DQL. The verb+resource is specific and unambiguous.

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

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

The description clearly says to prefer dataview.listByTag/listByFolder/table for common patterns and fall back to dataview.query for custom DQL, which is excellent when-to-use guidance. It also lists prerequisites (Dataview plugin, Local REST API config) and explains vault selection behavior. However, the claim that an explicit 'vaultPath' argument can be passed is misleading because the input schema does not include such a parameter (additionalProperties: false), creating confusion for the agent.

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

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

Annotations already cover readOnly, idempotent, openWorld, and non-destructive behavior, so the description adds value by mentioning plugin prerequisites and vault resolution semantics. However, it claims an explicit `vaultPath` argument 'always wins,' but that parameter is absent from the input schema and additionalProperties is false. This is a misleading behavioral claim that an agent cannot actually act on, which undermines transparency.

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

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

The description is appropriately short and front-loaded: the first sentence defines the operation, the second gives the use case, the third gives prerequisites, and the final paragraph explains vault behavior. The vaultPath sentence is somewhat misleading and the vault.current/vault.select references add a small distraction, but overall the structure is compact and readable.

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

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

The description covers the core purpose, prerequisites, vault resolution, and structured output, and the output schema plus annotations handle return values and safety. However, it leaves the vaultPath mismatch unresolved and does not clarify what happens when `fromClause` is omitted, which is relevant for correct invocation. These gaps prevent it from being fully complete.

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

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

Schema description coverage is 100%, so the schema already documents all real parameters; the description only restates that WHERE, SORT, and LIMIT are optional, adding no new meaning. Worse, it introduces a phantom `vaultPath` parameter not present in the schema, actively confusing parameter expectations. This is a net negative beyond 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?

The description uses a specific verb ('runs') and names the exact DQL TABLE form it wraps. It also explicitly says 'structured columnar output,' which differentiates this tool from list-oriented siblings like dataview.listByTag and dataview.listByFolder. This is a clear, distinguishing statement of purpose.

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 an explicit usage trigger: 'Use this when you need structured columnar output.' It also notes a prerequisite (Dataview and Local REST API plugins), which is useful for pre-call checks. However, it never names alternatives or explains when to prefer dataview.query or listByTag, so exclusions are left implied 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?

It discloses important behaviors beyond the annotations: missing destination columns are created automatically, card matching for move/toggle is verbatim after checkbox, the result is a {changed, target, summary, ...} mutation envelope, and the tool operates on the session-active vault unless vaultPath is supplied. This adds substantial context that the annotations alone do not 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?

The description is longer than average, but every part earns its place: a clear op matrix, side-effect disclosure, vault routing rule, and concrete examples for each op variant. It is front-loaded with the core purpose and avoids 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?

The description is complete for a complex oneOf-based mutation tool. It covers op selection, required versus optional fields, automatic column creation, vault selection, and the return envelope shape. Since an output schema exists, not repeating full return details is acceptable.

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

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

The input schema already documents all parameters with high coverage, so the baseline is 3. The description adds value by grouping required parameters by op, explaining positional behavior with 'start'/'end', noting automatic column creation, and providing realistic examples that make the discriminated union much easier to invoke correctly.

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

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

The description uses a specific action set ('Add, move, or toggle') and names the resource ('a card on a Kanban board'), then explains what each op does. This clearly distinguishes the mutation tool from read-only siblings like kanban.parse and kanban.stats, even though the tool's title is somewhat generic.

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 explicit per-op usage rules: add requires columnName/cardText, move requires fromColumn/toColumn, and toggle uses optional columnName to scope the search. It also clarifies vault routing and the precedence of vaultPath. It does not explicitly name alternative sibling tools to avoid for read-only operations, 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?

Annotations already declare readOnlyHint and idempotentHint, so the description's 'Read-only' adds no new safety info. However, it adds valuable behavioral context beyond annotations: compatibility with the obsidian-kanban plugin format and the session-active vault behavior with vaultPath override. This improves the agent's understanding of execution context.

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 tight and front-loaded. The first sentence states the core purpose; the next sentences provide usage guidance, an explicit alternative, and the vault behavior. Every sentence earns its place with no redundant or vague phrasing.

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 output schema exists and annotations cover safety, the description is complete. It explains what the tool does, when to use it, which format is supported, and how vault selection works. No missing critical context for an agent to invoke 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?

Schema coverage is 50%: filePath is documented in the schema, vaultPath is not. The description compensates for vaultPath by explaining it overrides the session-active vault, giving that parameter meaningful semantics beyond its bare type. It could be stronger with path format details, but the description adds real value.

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

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

The description uses a specific verb and resource: 'Parse a markdown Kanban board file into its column/card structure.' It clearly distinguishes itself from kanban.stats by explaining that this tool provides the full board content, not just counts.

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 the tool: 'Use this when you need the full board content.' It also names the alternative for different needs: 'For completion counts and ratios instead of the full card list, use kanban.stats.' This leaves no ambiguity about tool selection.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds a meaningful behavioral detail: operation on the session-active vault unless vaultPath is passed, and that vaultPath always wins. This goes beyond the annotations and clarifies routing behavior. No contradiction, though it could also mention error conditions or performance implications.

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 paragraphs, no fluff. The purpose and metrics are front-loaded, and the vault behavior is placed in a separate sentence. Every sentence adds novel information; nothing is redundant with the 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?

An output schema exists, so return format is provided. The description covers purpose, usage context, alternatives, and vault routing. With only two parameters and rich annotations for safety, this is fully complete for agent decision-making.

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 50% — filePath has a description but vaultPath does not. The description compensates by explaining vaultPath's role and precedence ('unless an explicit vaultPath argument is passed, which always wins'). It does not add format details, but the essential semantics are covered.

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 ('Summarise') and resource (Kanban board), and enumerates the exact metrics (total cards, completed, incomplete, completion rate, per-column breakdown). It also distinguishes from kanban.parse by specifying it does not give card content, so 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?

Explicit guidance: 'Use this for dashboards or progress checks where you don't need each card's full text' and 'Use kanban.parse when you need the actual card content.' Also clarifies the active-vault vs vaultPath precedence, leaving no ambiguity about when to call this vs alternatives.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds meaningful behavioral context: it supports both wiki-style and markdown-style links, describes the includeContext/contextLength snippet behavior, and explains vault resolution precedence. No contradiction with annotations.

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

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

Two tight paragraphs with the core purpose front-loaded. Each sentence adds useful routing or behavioral information; only 'Read-only.' slightly duplicates the annotation, but it is brief and does not hurt clarity.

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 output schema exists and annotations cover safety, the description covers purpose, alternatives, vault behavior, and parameter semantics. An agent has everything needed to decide when to use this tool and how to invoke 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?

Schema covers path, contextLength, and includeContext, while the description adds the missing meaning of vaultPath ('explicit vaultPath argument ... always wins') and clarifies how includeContext and contextLength interact. This goes beyond the schema, though a touch more detail on contextLength's default could strengthen it.

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 that links TO a target note (inbound references).' It clearly differentiates from the links.outgoing sibling, so an agent can identify the tool's purpose 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 names the alternative for outbound links ('use links.outgoing') and explains when an explicit vaultPath wins over the active vault. It also points to vault.current and vault.select for vault selection, making usage conditions concrete.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description reinforces 'Read-only.' It adds useful behavioral context: the scan operates on the session-active vault unless vaultPath is supplied, and vaultPath always wins. It also discloses the per-result fields, which helps set expectations beyond the schema.

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

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

The description is compact and front-loaded: the core function, scope options, result contents, read-only nature, and repair workflow all appear in a few sentences. Every sentence adds value, and the vault-selection nuance is placed after the main purpose without bloating the definition.

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 an output schema present, the description need not fully specify return values, and it still gives a helpful preview (source file, line number, link text, unresolved target). Together with annotations and the vaultPath/directory semantics, an agent has enough context to select and 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?

Schema coverage is 50%: directory has a schema description, but vaultPath does not. The description compensates for vaultPath by explaining it overrides the session-active vault, and it clarifies that directory scopes the scan to a subtree. It does not give vaultPath format examples, but the added precedence semantics go beyond the schema.

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

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

The description states a specific verb and resource: 'Find every link in the vault (or a directory subtree) whose target does not resolve to an existing note.' This clearly distinguishes the tool from sibling link tools like links.outgoing or links.graph by focusing on broken/unresolved targets. The expected result fields further clarify what the tool does.

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

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

The description gives clear context: use it to find broken links, and explicitly pairs it with notes.move (updateLinks:true) to fix them after moves. It also clarifies the session-active vault and vaultPath precedence. It does not explicitly list alternatives or when-not-to-use scenarios, but the context is strong.

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

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

Annotations already cover read-only, idempotent, non-destructive behavior. The description adds valuable behavioral context beyond annotations, including the cost explosion with higher depth values and the precedence rule for vaultPath over the active vault.

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

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

Well-structured and front-loaded: the core behaviour and output come first, followed by cost warning and vault semantics. Slight redundancy exists because 'read-only' and 'result size blow-up' repeat annotation/schema information, but overall every sentence earns its place.

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

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

Comprehensive given the annotations, schema, and output schema: it explains scope, output shape, depth risk, and vault resolution. It does not discuss failure modes or when to choose a sibling tool, but the provided context is enough 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 covers noteName and depth reasonably well, but leaves vaultPath undocumented. The description compensates by explaining that vaultPath overrides the active vault, and reinforces depth semantics with a concrete limit recommendation.

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: explores the graph neighbourhood around a seed note with direct and multi-hop connections. Clearly distinguishes itself from sibling direct-link tools like links.outgoing and links.backlinks by describing traversal depth and returning reachable notes plus paths.

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 active vault is used by default, vaultPath overrides it, and depth should generally stay ≤3 to avoid result blow-up. It does not explicitly name alternatives or say when to prefer this over a sibling tool, but the guidance is sufficient for practical use.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description adds meaningful behavioral context beyond those: performance cost, return shape, and vault-scoping semantics. The 'Read-only' statement is consistent with the annotations, so there is no contradiction.

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

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

The description is compact and every sentence earns its place: graph definition, return shape, performance guidance, read-only confirmation, and vault selection. The most important scoping and routing information is 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?

The description provides enough information for an agent to call the tool correctly: what the output contains, when to avoid it, how vault context is resolved, and how vaultPath affects behavior. An output schema exists, so detailed return typing is not the description's burden.

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 only parameter, vaultPath, has no schema description (0% coverage), but the description compensates by explaining when it applies and that it overrides the session-active vault. It does not specify path format or expected values, leaving a small gap, but the core meaning is communicated.

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 ('Build a full vault link graph'), defines the exact graph model (nodes for notes, directed edges for outbound links), and clearly differentiates itself from targeted siblings like links.backlinks and links.outgoing. An agent can immediately understand what this tool does and how it differs.

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

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

The description explicitly warns that the tool is expensive for large vaults and recommends alternatives ('prefer links.backlinks, links.outgoing, or links.connections for targeted queries'). It also clarifies the active-vault behavior and that an explicit vaultPath overrides it, giving clear selection and invocation 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, idempotentHint, and destructiveHint, so the description's 'Read-only' is consistent. The description adds useful behavioral context beyond annotations: it aggregates across the whole vault, computes ratios and densities, and respects the session-active vault unless vaultPath is supplied. This is meaningful but not exhaustive; the output schema covers return details.

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

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

The description is compact and front-loaded, with the core purpose and output metrics in the first sentence. The second sentence gives routing guidance, and the third handles vault scoping. Every sentence adds distinct value with 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?

Given the tool's simple optional-parameter shape and the presence of an output schema, the description covers everything needed: what it returns, when to use it, sibling alternatives, read-only behavior, and vault targeting. No critical operational detail 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 0%, so the description must carry the burden for the single optional vaultPath parameter. It does: vaultPath is explained as an explicit override that 'always wins' over the session-active vault. It doesn't specify path format, but the parameter name and contextual explanation make the semantics clear enough for correct use.

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

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

The description uses a specific verb ('Summarise') and resource ('link health for the whole vault'), then enumerates the exact metrics returned. It also distinguishes itself from the sibling tools links.broken, links.orphaned, and links.hubs by explicitly framing this as an aggregate dashboard check rather than per-item listing.

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

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

The description explicitly says when to use it ('as a dashboard check') and names the alternatives for full per-item lists. It also clarifies vault selection semantics, including how vaultPath overrides the session-active vault, leaving no ambiguity about which vault is targeted.

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-destructive behavior, so the bar for added value is lower. The description still adds meaningful behavior: minimum threshold with default 10, descending sort by outbound count, result shape `{path, title, outbound, inbound}`, and vaultPath precedence over the session-active vault. No contradiction with annotations.

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

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

The description is tightly packed: core behavior, default, sorting, result fields, read-only note, usage guidance, alternatives, and vault-selection semantics are all covered in two focused paragraphs. No filler or redundancy.

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

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

Given the output schema exists, the description need not re-explain return values, but it still provides the threshold, ordering, vault behavior, and sibling routing. Everything an agent needs to decide when and how to invoke this tool is present.

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

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

The schema only documents `minOutlinks`; the description compensates for `vaultPath` by explaining that it overrides the session-active vault. It also restates the default for `minOutlinks` and clarifies that the count refers to outgoing links, making both parameters actionable.

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

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

The description uses a specific verb and resource: 'Return notes with at least `minOutlinks` outgoing links', then adds sorting criteria and conceptual framing ('connective tissue / MOCs / curated indexes'). It clearly distinguishes this hub-finding operation from sibling tools like `links.outgoing`, `links.graph`, and `links.health`.

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

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

The description explicitly states when to use this tool — to find navigational anchors and seeds for `links.connections` — and names the alternatives: `links.health` for a single vault-wide score and `links.graph` for the full raw edge list. It also clarifies vault-targeting behavior via `vault.current` and `vaultPath`.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds non-obvious behavioral context: it operates on the session-active vault unless an explicit vaultPath argument overrides it, with the override always winning. This is valuable information beyond the annotations. It doesn't describe return format, but an output schema exists to cover that.

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 compact and well-structured. The first sentence states the core definition, followed by usage context, then the important vault-selection behavior. No unnecessary filler; every sentence contributes to understanding. The structure is logical and front-loaded with the primary purpose.

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

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

For a simple, read-only tool with one optional parameter and an output schema, the description covers everything an agent needs: the exact condition, usage context, and vault selection behavior. It doesn't explain the output structure, but the output schema handles that. The description is complete 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?

The schema has 0% coverage for parameter descriptions, so the description is the only explanation. It clearly explains the optional vaultPath parameter: it overrides the session-active vault and always wins. This gives semantic meaning beyond the raw schema, though it doesn't specify the format (e.g., path syntax), which is a minor gap given there's only one parameter.

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 precisely defines the tool's action: 'Return every note with zero incoming AND zero outgoing links' and explains what that means ('disconnected from the rest of the vault graph'). It clearly distinguishes from sibling tools like links.broken and links.hubs by specifying the dual-direction condition, making the purpose unambiguous.

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

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

It provides clear usage contexts: 'useful for cleanup passes' and 'often paired with links.hubs and links.broken in a weekly vault-health routine.' This gives an agent a good sense of when to invoke it. It doesn't explicitly state when not to use it, but the defined scope and pairing guidance are sufficient for typical scenarios.

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

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

Descriptions adds meaningful behavioral context beyond the annotations: it discloses that both wiki-style and markdown-style links are extracted, that checkValidity adds a valid flag based on path resolution in the vault, and that vaultPath overrides the session-active vault. It also confirms the read-only nature, consistent with readOnlyHint and idempotentHint. No contradiction with annotations.

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

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

The description is compact and well-structured. Every sentence serves a purpose: purpose, validity flag behavior, read-only confirmation, sibling alternative, and vault scoping. It front-loads the main function and keeps supporting details 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?

The description is complete for a tool with an output schema that already explains return values. It details the link extraction scope, validity flag semantics, vault behavior, and explicit alternative. The references to vault.current and vault.select provide useful context without being excessive.

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 only 33% (only checkValidity has a description). The description compensates by explaining vaultPath (overrides session vault) and checkValidity (adds valid flag). The path parameter is not explicitly described, but it's implied as the note from which links are extracted. The added semantics cover two of three parameters well, though path could have been more explicit.

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

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

The description clearly states the verb 'Extract' and the resource 'links FROM a note', specifying both wiki-style and markdown-style link formats. It explicitly distinguishes itself from the sibling 'links.backlinks' by naming the alternative and its purpose, so an agent can readily tell them apart.

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 explicit usage guidance: 'For inbound references (what points AT the note), use links.backlinks.' It also explains the vault scoping rule (session-active vault vs explicit vaultPath) and which argument wins. This leaves no ambiguity about when to use this tool versus alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this with 'Read-only.' The description adds value by detailing output variability per part and the precedence of 'slideId' over 'index', which informs expected behavior beyond the static annotations. It also clarifies vault resolution, which is behavioral context not covered by annotations.

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

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

The description is concise and well-organized: it leads with the action and purpose, then details the three part variants in a compact way, and ends with vault resolution. Every sentence contributes to understanding the tool; there is no filler or redundancy. The structure front-loads the most critical discriminators.

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

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

Given the tool's complexity (three variants, multiple parameters, output variations), the description is thorough in explaining the input selection and vault behavior. It does not detail the exact return format, but the presence of an output schema (indicated in context) mitigates this. The only minor gap is lack of error-handling or edge-case notes, but for a read-only tool this is acceptable.

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 already covers parameter descriptions heavily (100% coverage per context), but the description enriches this by explaining the semantic differences between 'part' values, the meaning of 'slideId' versus 'index', and the override behavior of 'vaultPath'. This is more than schema repetition; it provides decision-relevant semantics for the agent's invocation.

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 ('Read') on a specific resource ('Marp presentation deck') and enumerates three distinct variants via the 'part' field. It also differentiates from the sibling 'marp.update' by explicitly noting it is read-only and that mutation goes through the update tool. This is a clear, unambiguous purpose.

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

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

The description provides clear usage context: it explains when to use the read tool versus the update tool, and clarifies that it operates on the session-active vault unless an explicit 'vaultPath' is provided. It also explains how to select a slide via 'slideId' or 'index', which are key usage decisions. However, it does not compare against other read tools (e.g., notes.read) for scenarios where a non-Marp markdown is involved, so it lacks full alternative routing.

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 destructive and idempotent behavior, and the description adds valuable context: slides are replaced without touching neighbors, unspecified frontmatter fields are preserved, `null` unsets a field, and identical re-runs are a no-op on file contents. This goes beyond the annotation flags and gives an agent a precise side-effect model.

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 behavior, then gives branch-specific semantics and closes with two illustrative examples. Despite its length, every sentence earns its place, and the detail is justified by the oneOf/two-mode design.

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 mutating tool with two distinct modes and an output schema, the description covers selection, side effects, vault routing, and example payloads. Nothing required to select or invoke the correct branch 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?

The schema documents `source`, `fields`, and `part`, but the description adds meaning not present in the schema: slide lookup by `slideId` or `index`, the precedence behavior of `vaultPath`, and the merge/unset semantics for frontmatter. The examples provide concrete payload shapes for both branches, making invocation unambiguous.

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?

Opens with a specific verb ('Mutate') and resource ('a Marp deck in place'), then distinguishes the two `part` modes: slide-body replacement and frontmatter merge. The tool is clearly separable from its read sibling and from general note-editing tools by the Marp deck scope and the named mutation targets.

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 clearly explains when to use the `slide` branch versus the `frontmatter` branch, and how vault targeting is resolved, including the rule that an explicit `vaultPath` overrides the active vault. It does not explicitly state when to use an alternative like `notes.edit` or `marp.read` instead, so it stops short of full exclusion 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?

The description richly discloses behavior beyond the annotations: `ifExists` semantics (`error`, `replace`, `skip`), idempotent folder creation, automatic creation of intermediate folders, and explicit precedence of `vaultPath` over the session-active vault. It also notes the return is a standard mutation envelope, which is useful given the annotations do not describe 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?

The description is efficiently organized: a lead sentence with the core operation, then mode-specific behavior, then operational context, then examples. Every section adds information, and the examples are compact and illustrative without 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?

For a discriminated-union mutation tool, the description covers all necessary decision points: note vs. folder, collision handling, path behavior, vault selection, and idempotency. The output schema exists, so the vague 'standard mutation envelope' reference is acceptable and does not leave a critical gap.

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

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

Although the schema already documents parameters well, the description adds meaningful cross-parameter semantics: how `kind` switches the object shape, how `ifExists` interacts with existing notes, how folder creation behaves idempotently, and how `vaultPath` overrides the active vault. The two concrete JSON examples further clarify expected usage.

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 — 'Create a new note or folder in the vault' — and clearly distinguishes the two modes via `kind:'note'` and `kind:'folder'`. It also differentiates from siblings like `notes.edit`, `notes.move`, and `notes.delete` by naming creation as the operation and specifying the resulting artifacts (markdown files or directories).

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

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

The description gives clear operational context: it explains that the tool operates on the session-active vault unless `vaultPath` is passed, and the schema-level note says to use `kind:'folder'` when the target should be a directory rather than a file. It does not explicitly contrast this tool with sibling creation-like tools (e.g., `tasks.create`, `templates.use`), so it stops short of full alternative routing.

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 significant context beyond the destructiveHint=true annotation: states the file is removed from disk, fails with not_found, and has no undo. It also explains the rationale for not exposing folder deletion to avoid cascading deletes. No contradiction with annotations.

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

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

Two concise paragraphs: first covers deletion behavior and alternatives, second covers vault context. Information is front-loaded with the core action and no sentences are wasted, though it is slightly longer than strictly necessary.

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

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

Covers failure modes, destructive nature, vault selection, and alternative for folders. Output schema presumably handles return values, so nothing critical is missing for an agent to call 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?

With 0% schema description coverage, the description compensates by explaining vaultPath always wins over the session vault and that path refers to the note path. However, path format details and vaultPath structure are not elaborated, leaving some ambiguity for the agent.

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 the tool deletes a note from the vault, a specific verb and resource. It distinguishes itself from siblings like notes.move (for folders) and other note operations, making it clear what this tool does and does not do.

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 directs folder deletions to notes.move instead, and explains the vault selection mechanism (vault.current/select) with vaultPath override. This provides clear when-to-use and when-not-to-use guidance, including a concrete 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?

Beyond annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false), the description adds crucial behavioral detail: 'replace mode is idempotent-destructive; the others are additive,' plus failure conditions and vault precedence rules. This is rich context that annotations don't provide.

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

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

The description is long but every sentence earns its place: purpose, mode semantics, failure condition, vault behavior, and three illustrative examples. It's front-loaded with the core action, and the structured examples make the modes unambiguous. No fluff.

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

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

The tool is complex (five modes, two anchor types, vault selection), and the description fully covers all required knowledge: mode differences, anchor syntax, default vault behavior, and error scenarios. With an output schema present, return values need no explanation. Nothing an agent needs 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?

Despite 100% schema description coverage, the description supplements the schema with examples illustrating the exact format for anchor (no leading '#' for headings, no '^' for blocks), clarifies placement for prepend ('after frontmatter'), and demonstrates real-world usage. This goes beyond what the schema's oneOf branches state.

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

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

The description uses a specific verb ('mutate') with a clear resource ('existing note') and enumerates the distinct modes, which immediately differentiates it from notes.create, notes.delete, and other note-related siblings. It's specific enough for an agent to know exactly what this tool does.

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 NOT to use it ('Fails if the note does not exist — use notes.create first') and clarifies vault selection ('Operates on the session-active vault... unless explicit vaultPath'). It doesn't contrast this with blocks.update or blocks.read, which might be plausible alternatives for fine-grained edits, but the guidance given is clear and actionable.

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

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

The description adds substantial behavioral context beyond the annotations: it explains the merge vs replace strategies, the requirement for at least one of set/unset, and the vault selection precedence. It also confirms idempotency, aligning with the idempotentHint annotation. No contradiction exists.

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 well-organized: it starts with the core operation, then covers strategy, requirements, idempotency, vault behavior, and provides two clear examples. It is thorough without being bloated, though slightly longer than strictly necessary.

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

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

For a tool with 5 parameters and nuanced merge/replace behavior, the description covers all key aspects: set/unset semantics, strategy selection, the requirement, idempotency, vault path precedence, and examples. Since an output schema exists, return-value details are handled there, so 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 60%, and while the schema already describes set, unset, and strategy, the description clarifies the semantics further: it explains what 'merge' and 'replace' do to unspecified fields, and it details the requirement that at least one of set/unset be present. It also adds meaning to vaultPath by explaining its precedence over the session-active vault.

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

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

The description clearly states the verb (set/unset) and resource (YAML frontmatter of a note), and precisely distinguishes between the two operations. It also differentiates from sibling tools like notes.edit or dataview.fields.write by focusing specifically on frontmatter manipulation.

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

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

The description implies when to use the tool (when you need to edit frontmatter fields) but does not explicitly mention alternatives or when not to use it. There is no reference to sibling tools like dataview.fields.read or notes.edit, so the selection guidance is implicit 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, idempotentHint, and destructiveHint, so the safety profile is known. The description adds valuable behavior not in annotations: parameter semantics (include, recursive, dateField interplay), the default modified date, and the vault scoping override. It does not contradict annotations and reinforces the read-only nature. It stops short of describing the exact output structure (e.g., which fields are returned per item), but the output schema covers that. With annotations covering safety, the description adds meaningful context, earning a 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?

The description is two succinct paragraphs. The first states the action and key parameters; the second addresses vault scoping. Every sentence contributes new information—no filler or redundancy. It is front-loaded with the core purpose and parameter semantics, making it easy to scan. This is appropriately sized for a tool with 7 parameters and no required args.

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

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

Given the tool's complexity (7 params, 0 required) and the presence of an output schema, the description covers all essential aspects: purpose, parameter behavior, default values, recursion, and the vault selection precedence. It also references sibling tools (vault.current, vault.select) for context. Nothing critical is missing for an agent to call it correctly. The read-only nature is reinforced, and the output format is left to the schema. This is complete.

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

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

Schema description coverage is 86%, so most parameters already have meaning in the schema. The description adds relational value beyond that: it ties since/until to dateField, explains recursive behavior, clarifies include options as notes, folders, or both (tagged by kind), and spells out the vaultPath precedence. This goes beyond individual parameter descriptions, helping an agent understand how parameters combine. Since coverage is high, the baseline is 3, but the description elevates it to 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 opens with a specific verb (list) and resource (notes/folders), and clarifies optional scoping and filtering. It distinguishes itself from siblings like notes.read (read a single note), notes.search (search), and vault.list (list vaults) by clearly stating what it enumerates in the session-active vault. The purpose is unambiguous and easy to differentiate at a glance.

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

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

The description gives clear context: list notes/folders, optionally scoped to a folder and date range. It mentions read-only behavior and explains vault selection precedence (vaultPath wins), which is critical for correct invocation. It does not explicitly name alternatives for when not to use it (e.g., 'for full-text search use notes.search'), but the scope is self-evident and enough for an agent to decide appropriately. A small deduction for not enumerating 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?

Beyond the annotations (destructiveHint=true, idempotentHint=true), the description discloses critical behaviors: it overwrites/replaces existing content at the destination, fails when the source does not exist, and rewrites wiki/markdown links vault-wide when updateLinks is true. It also explains the vaultPath override semantics. This adds substantial operational detail that annotations alone do not 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?

The description is tight and front-loaded: the first sentence states the core purpose, then details about kind, updateLinks, destructiveness, failure condition, and vault selection follow. Every sentence adds value with no fluff or repetition. It is well-structured for an agent to quickly grasp the essential information.

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

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

Given the tool's complexity (moving files/folders with link rewriting and destructive behavior) and the presence of an output schema, the description covers all necessary aspects: what it moves, how it handles links, destructive consequences, failure conditions, and vault selection. Nothing essential is missing for an agent to call 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?

Schema description coverage is 100% (each parameter has a description), so the baseline is 3. The description goes further by explaining the default behavior of updateLinks (true) and how vaultPath overrides the session-active vault, which is not fully captured in the schema. This added context justifies a 4.

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

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

The description clearly states the verb ('Move') and resource ('a note or folder to a new path'), and immediately distinguishes the two kinds ('note' vs 'folder' with 'moves every note beneath it'). It also explains link rewriting, making it distinct from sibling tools like notes.delete or notes.create. No tautology; the description adds specificity beyond the title.

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

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

The description provides clear context: it operates on the session-active vault unless vaultPath is passed, and it is destructive. However, it does not explicitly name alternative tools or state conditions like 'use notes.move instead of notes.delete when you need to relocate', so the 'when not to use' is only implied. The vault selection guidance is helpful, but the lack of explicit exclusions prevents 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?

Beyond the readOnlyHint and idempotentHint annotations, the description discloses the `not_found` error on missing paths and explains the vault selection behavior (session-active vault vs. explicit vaultPath). This adds meaningful operational context that the annotations do not cover.

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 compact and well-organized. The first sentence states the purpose and options; the second gives practical usage guidance; the third clarifies vault context. Every sentence earns its place without redundant 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 read tool with an output schema, the description covers the essential aspects: return sections, error behavior, vault selection, and parameter semantics. No critical information 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?

The description enriches the `include` parameter with explanation of what each value returns and the default, and clarifies `vaultPath` precedence. Since schema coverage is 67%, the description compensates for the undocumented `vaultPath` and adds nuance beyond the schema's enum for `include`.

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

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

The description clearly states the tool reads a note and returns selected sections (body, metadata, stats). It specifies the resource (note) and action (read), and the mention of the `include` parameter distinguishes it from listing/searching tools. This is specific and unambiguous.

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

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

It gives clear context for when to use this tool (reading a specific note by path) and even provides guidance on using `include` to request stats only. However, it does not explicitly name alternative sibling tools or state when not to use it, so it falls short of the 'explicit when/when-not/alternatives' criterion.

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 destructiveHint, and the description restates read-only, which is redundant. It adds meaningful behavior beyond annotations: query filter syntax, default context length, and the session-active vault precedence rule.

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 main purpose, then a compact set of filter semantics, a default, and a routing pointer. The repeated 'Read-only' is minor given annotations, but the definition is appropriately sized and all remaining sentences add 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 an output schema present, the description doesn't need to explain return shape. It covers the active-vault behavior, filter forms, default context length, and sibling alternatives, making the tool callable correctly in context.

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

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

Schema covers `query` and `contextLength` but leaves `vaultPath` undocumented; the description fills that gap by explaining that it selects a vault and always wins over the active vault. It also adds concrete syntax for `tag:` and `path:` filters and the default context length, adding 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: 'Full-text search across every note in the vault.' It also singles out `tags.search` and `notes.list` as alternatives, so an agent can distinguish it from sibling search/list 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?

Gives explicit routing guidance: for pure tag or date filtering, `tags.search` and `notes.list` are faster, implying notes.search is for full-text search. It also specifies that it operates on the session-active vault and that `vaultPath` overrides the active vault.

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 read-only, idempotent, non-destructive behavior. The description adds value beyond those by disclosing that the tool scans every .md file and by explaining how the target vault is resolved. This is meaningful behavioral context that structured annotations do not 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?

Three sentences carry exactly the necessary information: what the tool returns, a pointer to the per-note alternative, and how the vault target is resolved. The most important content is front-loaded and there is 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?

With an output schema present to document return structure, the description fully covers purpose, scope, alternatives, and parameter behavior. The combination of annotations, output schema, and description leaves no critical gap for an agent deciding whether and how to invoke this 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 0%, but the description compensates by explaining that the optional vaultPath is an explicit override that 'always wins' over the session-active vault. This gives the single parameter clear operational meaning, though it could be improved with path format details.

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

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

The description uses a specific verb ('Return') and a clearly bounded resource ('aggregate statistics for the whole vault'), then enumerates the exact metrics returned. It also explicitly contrasts itself with per-note statistics via notes.read, making its scope unambiguous relative to sibling 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?

The description gives an explicit when-to-use alternative: 'For per-note statistics use notes.read with include: ['stats']'. It also clarifies operational context by explaining the session-active vault behavior and that an explicit vaultPath overrides it, referencing vault.current and vault.select for selection.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description confirms 'Read-only; zero side effects.' It adds value beyond annotations by specifying exactly which runtime details are returned, which is useful behavioral context.

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, information-dense sentences. The first states what is returned; the second gives usage guidance. No redundant phrasing; 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?

For a zero-parameter, read-only health-check tool with an output schema, the description covers everything an agent needs: the exact data returned, the use case, and the safety profile. Nothing 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?

There are zero parameters, so the baseline is 4. The description doesn't need to explain any parameters, and the empty schema is fully covered. No additional parameter semantics are necessary.

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 ('Return'), a precise resource ('the running kObsidian server's package name, semver version, host runtime, and runtime version'), and distinguishes itself from all siblings. There is no ambiguity about what the tool does.

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 the tool: 'Use this as a health-check or to confirm which server build a client is talking to.' This provides clear context and intent, leaving no inference required.

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, and the description reinforces 'Read-only.' It adds context about the session-active vault and how `vaultPath` overrides it, which is valuable beyond the annotations. It does not detail the output format, but the presence of an output schema covers that.

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

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

Two sentences that are front-loaded with the core purpose, then immediately disambiguate from the sibling. No filler or repetition—every sentence adds value.

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

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

Given the output schema exists and the description clearly explains the tool's scope, usage context, and vault-selection nuances, an agent has enough to call it correctly. The only minor gap is the lack of detail on `vaultPath` formatting, but that's handled by the schema and the explicit 'always wins' note.

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 only 50% — `vaultPath` has no description in the schema. The description partially compensates by stating that `vaultPath` overrides the active vault, but it doesn't explain its format or default behavior in depth. This is adequate but not fully compensating for the low coverage.

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