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

Annotations already declare readOnly/idempotent/non-destructive, so the description earns credit for the semantics it adds: counts span the whole population (limit never caps input), multi-value tag buckets can exceed the total, missing values form their own bucket, and buckets are ranked by count desc then casefolded key. That is real behavioral detail an agent cannot get from structured fields.

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?

Dense and front-loaded — five short clauses covering grouping, count semantics, caveats, key format, and ordering, with no filler. The telegraphic phrasing ('missing counts notes without a tag value') is slightly awkward but the compactness is mostly earned.

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 and 100% schema description coverage, the description only needs to carry behavioral quirks, which it does well for a 12-parameter tool. The remaining gap is the absence of any routing guidance relative to count_documents, stats, and query_documents.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds meaning beyond the schema by specifying the YYYY-MM month key format and the tag-bucket overflow behavior tied to the `by`/`field` parameters. It leaves the remaining filter parameters (pattern, filters, modified_*) to the schema, which is acceptable at 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?

States a specific verb and resource: group every matching indexed note into bounded frequency buckets. An agent can distinguish this from count_documents or stats, though the description never names a sibling to contrast against explicitly.

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

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

No when-to-use guidance and no indication of when the aggregation alternatives (count_documents, stats, query_documents) should be preferred. The agent must infer from the purpose that this is the grouping/frequency tool rather than a flat listing.

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

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

Annotations already declare non-read-only, non-idempotent, non-destructive, so the safety profile is covered. The description adds genuinely non-obvious behavioral detail: the appended text lands on a new line and the agent must prefix a blank line or heading to control paragraph/section formatting. It stops short of describing conflict behavior or what happens on a path collision, but if_match and create_if_missing carry that in 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?

Three short sentences, front-loaded with the core action, followed by the alternative and the formatting rule. No sentence is redundant and nothing is buried.

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

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

For a simple append tool with full schema coverage, annotations and an output schema, the description covers purpose, alternative and formatting behavior. The only remaining gap is concurrency or failure behavior, which is reasonably delegated to the if_match and create_if_missing schema docs.

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

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

Schema description coverage is 100%, so the baseline applies and the description need not restate path, content, if_match or create_if_missing. It mentions no parameter by name, so it adds nothing beyond the schema's own documentation.

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

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

States a specific verb and resource ("Add text to the end of an existing note") plus a distinguishing constraint ("without reading it first") that separates it from edit/write siblings. An agent can identify the operation without opening the schema.

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

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

Explicitly names the alternative ("Prefer it over edit") and the selecting condition ("when the change only adds at the end, such as a log entry"). The exclusion is implied by the same clause, so routing between append and edit requires no inference.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive), but the description adds the non-obvious behavioral fact that this launches an interactive surface for a human and yields no readable content — a critical disclosure that prevents an agent from expecting data back. It stops short of saying what happens in a non-interactive/headless client, which is the remaining behavioral unknown.

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

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

Four short lines total: purpose first, then the routing exclusions. Every sentence earns its place and nothing is repeated from the schema or annotations.

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

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

An output schema exists, so return values need no explanation — and the description usefully clarifies that there is nothing to read anyway. The one gap is environmental: an agent in a non-interactive session gets no warning that an interactive explorer may not be renderable or useful there.

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

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

Schema coverage is 100% and both parameters already document their defaults and the path-dependent default resolution for `view` (context with a path, browse without). The description mirrors the three view modes in prose but adds no format, path syntax, or edge-case detail beyond what the schema states, so the baseline 3 applies.

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

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

States a specific verb+resource ('Open an interactive vault explorer') and enumerates the three modes (file tree, link graph, note relationships) that map to the `view` parameter. It is clearly distinguished from the read/search siblings by the explicit 'returns nothing to read' clause, so an agent can tell it apart from vault_graph_neighborhood or get_backlinks without opening a schema.

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

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

Gives an explicit when-to-use (user wants to visually look through the vault) and an explicit when-not-to-use with named alternatives: 'use search, read, list_documents or get_context for content.' The routing decision between this tool and content tools is fully resolved in the text.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, so the write scope is structured. The description adds genuinely new operational context: the build is normally automatic, failures are diagnosable through last_build_embeddings_error, and force is the escalation path. It stops short of stating cost/duration or whether concurrent runs are safe for what is a heavy write operation.

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

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

Two short paragraphs: what it does and returns first, then exactly when it is warranted. No restatement of the name or title, and every clause carries decision-relevant information (automatic default, error hook, force path).

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 single-optional-boolean tool with full schema coverage, complete annotations and an output schema, nothing an agent needs is missing. The definition covers scope, triggers, failure recovery and the interaction with reindex, which is the only real ambiguity in this cluster.

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 force parameter already documents its own default and non-destructive swap behavior, so the baseline is 3. The description earns an extra point by tying force to concrete scenarios (a prior forced reindex, or a changed embedding model) that the schema does not name.

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

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

Specific verb and resource: "Bring the vector index behind semantic and hybrid search up to date with the notes," plus the return value (chunks embedded). It implicitly distinguishes itself from reindex, embeddings_status and get_index_status by framing itself as the incremental catch-up step rather than a status query.

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

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

Explicitly states the default of not needing it ("Embeddings are built automatically") and enumerates the three conditions that do select it: after reindex with force, after a failed build indicated by last_build_embeddings_error in get_index_status, or with force for a full rebuild. Both when-to-use and when-not are covered.

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

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

Beyond the safety annotations, the description discloses useful behavior: no content is fetched, the total is exact and unaffected by search result caps, and each note is counted once. It does not discuss permissions or index freshness, but the provided annotations and schema already cover the safety profile and pending-write behavior.

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

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

The description is two short sentences with the core purpose front-loaded. Every sentence adds useful information about scope and counting behavior, with no redundant wording.

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

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

For a count tool with a rich input schema, full schema description coverage, annotations, and an output schema, the description provides the essential behavioral context. It explains the key guarantee that the count is exact and independent of result caps, which is the main thing an agent needs beyond the structured fields.

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

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

The input schema already documents every parameter at 100% coverage, so the schema carries the parameter semantics. The description adds only a general notion of 'matching' notes and does not clarify filter combinations, query syntax, or scope beyond what the schema states. This is the expected baseline when schema coverage is complete.

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: counting matching indexed notes. It also distinguishes itself from content-fetching search tools by saying it operates 'without fetching content' and returns an exact total. It does not name a sibling alternative explicitly, which keeps it just below the top score.

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 implied usage context: use it when you need a count rather than note content, and when search result caps would distort the total. It lacks an explicit statement of when not to use it or which sibling to choose for retrieving notes, but the intended use case is clear.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered; the description adds the genuinely new fact that recovery is only possible through git history. It does not explain how if_match changes the failure behavior, but the critical irreversibility is disclosed.

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

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

A single short sentence with the most important consequence ('Permanently delete') front-loaded and the recovery caveat second. Nothing is wasted and nothing important is buried.

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

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

For a two-parameter destructive tool with full annotation coverage and an output schema, the description supplies the one thing annotations cannot: the irreversibility and its git-history escape hatch. Only the conditional-delete behavior of if_match is left entirely to the schema.

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

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

Schema description coverage is 100%, so both 'path' and 'if_match' (including its conditional/etag semantics) are already documented in the schema. The description adds no parameter-level meaning, so the baseline of 3 applies.

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

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

States a specific verb and scope ('Permanently delete a note or attachment'), which is far more informative than the bare tool name 'delete'. It implicitly separates itself from non-destructive siblings like move_folder or rename, but never names an alternative explicitly.

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

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

Usage is only implied: an agent can infer this is the removal operation when a note should no longer exist. There is no explicit 'use this instead of X' routing, no note about when to prefer rename/move_folder to relocate rather than delete, and no prerequisite guidance.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, so the safety profile is partly covered. The description adds genuinely new behavior — Unicode/dash/quote/whitespace normalisation matching and that such a match is reported as match_type "normalized" — but says nothing about failure when no unique match exists, what is returned, or why edits are not idempotent.

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

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

Front-loaded with the core action and the three modes, then the operational prerequisite, then the normalisation caveat — a sensible ordering. Slightly dense in the second sentence and the awkward mid-sentence line breaks make it marginally harder to scan, but no sentence is filler.

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

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

With a full schema and an output schema present, return values need not be explained, and the description covers the modes plus one non-obvious edge case (normalised matching). It is slightly incomplete on the no-match/ambiguous-match error path and on why repeat calls are not idempotent, which matter for an edit tool.

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

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

Schema description coverage is 100%, so all six parameters (including the if_match concurrency rules and line_start/line_end pairing) are already documented in the schema; baseline is 3. The description reinforces the matching semantics of old_text and adds the uniqueness-after-normalisation rule, but does not extend meaning for path, new_text or if_match beyond what the schema states.

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

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

States a specific verb and resource ('Replace text in an existing note') and enumerates the three selection modes (exact old_text, line range, old_text within a range). Together with the title 'Edit Note' this readily separates it from sibling mutation tools like write, append, rename and delete, though none of those siblings are named explicitly.

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

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

Gives a clear prerequisite ('Read the note first for its current text') and a conditional fallback rule for when an exact old_text match does not exist. It stops short of stating when to prefer this over append/write or when a line-range edit is preferable to an old_text edit, so the alternative-selection guidance is only implied.

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 fully covered. The description adds the specific scope (embedding provider and vector-index status) but doesn't disclose what the status output contains, whether it performs any checks that could be slow, or what failure modes exist. With annotations covering the safety profile, a 3 is appropriate.

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 a single, efficient sentence that front-loads the verb and resource. Every word earns its place, and there is no redundancy or filler.

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

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

For a zero-parameter, read-only status tool with an output schema present, the description is largely complete. The output schema presumably documents the return structure, so the description doesn't need to explain return values. The only minor gap is not naming sibling alternatives for disambiguation, but the tool's purpose is clear enough given the sibling list.

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

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

The tool has zero parameters, so the schema provides no parameter documentation. The description correctly indicates the tool takes no input and simply checks status. With 0 params, the baseline is 4, and the description adequately conveys that no parameters are needed.

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 ('Check') and resource ('embedding provider and vector-index status'), which clearly identifies the tool's purpose. It distinguishes itself from siblings like get_index_status and build_embeddings by focusing on status checking rather than building or indexing, though it doesn't explicitly name those alternatives.

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 usage context: it's a read-only status check for embeddings and vector-index health. However, it doesn't explicitly state when to use this tool versus alternatives like get_index_status or build_embeddings, nor does it mention any prerequisites or conditions that would make this tool the right choice.

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

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

Annotations declare readOnlyHint=false, idempotentHint=true, destructiveHint=false; the description is consistent, describing a save operation. It adds genuinely useful context the annotations don't carry – the bytes never traverse the conversation, so this is the right path for large payloads – though it doesn't warn about overwrite semantics when a file already exists at path.

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

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

Two tight sentences: the operation and its return shape first, then the reason to prefer it. No filler, and the most decision-relevant fact (bytes bypass the conversation) is front-loaded in the second sentence.

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

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

Annotations cover the safety profile and an output schema exists, so the description needn't enumerate returns; it still names the return fields for convenience. Combined with 100% schema coverage, the definition is essentially complete, with only overwrite/concurrency behavior left unaddressed.

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

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

Schema description coverage is 100%, so url, path, if_match, timeout_s and frontmatter are already fully documented, including the .md-vs-attachment rule and the redirect/final_url caveat. The description adds no parameter meaning beyond that, so the baseline 3 applies.

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

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

States a concrete verb+resource pair: downloads a URL server-side and saves it into the vault, with the destination deciding note vs attachment via the path schema. It implicitly differentiates from the vault-only siblings like read/list_documents, but never names an alternative explicitly.

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

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

"Use it for large files and then pass the path to other tools" gives a clear selection rule and a follow-on workflow, which is real usage guidance. It stops short of naming the alternative (read) for the case where the content is already in the vault, or stating when-not to use it.

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

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

Annotations already declare the tool read-only, idempotent and non-destructive. The description adds no behavioral context of its own, such as ordering, whether embedded links or aliases count, or index dependence. The stale-index behavior is documented only in 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?

Two sentences with no waste. The purpose comes first and the routing guidance follows.

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?

This is a simple read-only tool with an output schema, full parameter docs and rich annotations, so the brief description is mostly sufficient. Some notes on index-based behavior or link-type coverage would complete it.

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 documents case-sensitivity, the 'omit for all' default and timeout staleness. The description adds nothing about the parameters, so the baseline score applies.

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

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

"List the notes that link to a note" gives a specific verb and resource, and it defines inbound links precisely. That separates it from get_outlinks and get_most_linked, and the description also names get_context explicitly.

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

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

It names get_context as the alternative and gives the condition for choosing it: when outlinks or similar notes are also needed. It does not mention vault_graph_neighborhood or get_connection_path, which overlap in a large sibling set.

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, so the safety profile is covered; the description adds real scope information the annotations cannot convey — that attachment links are skipped and that results are attributed to the holding note. It doesn't discuss result size or pagination, which is a minor omission for a vault-wide listing.

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

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

Three short sentences: the first defines the operation and output, the second gives provenance and the sibling relation, the third gives the exclusion. No filler, and the core definition 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?

With an output schema present, the description only needs to convey purpose, scope and exclusions, which it does, including the attachment caveat that no structured field expresses. Slight gap: it doesn't note that a full-vault scan may be expensive or how the folder parameter narrows it, though the schema documents folder fully.

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

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

Schema description coverage is 100%, including folder semantics (sub-folders, empty string for top-level only) and the stale-index timeout behavior, so the schema carries the parameter burden. The description adds nothing about either parameter, which is the expected baseline when the schema is this complete.

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 ('List the links whose target is missing from the vault') and even describes the return shape ('each with the note that holds it'). It explicitly separates itself from the sibling stats tool, which only reports broken_link_count, so an agent can route correctly without opening a schema.

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

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

Gives the causal context for when this tool matters ('a rename without update_links leaves such links behind') and points at stats as the summary-level alternative. It does not state explicit when-not-to-use conditions beyond the attachment exclusion, which keeps it 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, idempotentHint and destructiveHint=false, so safety is covered. The description adds genuinely useful behavior beyond that: traversal is bidirectional and returns the shortest chain (implying breadth-first search). However, it says nothing about what happens when no path exists or when max_depth is exhausted.

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

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

A single tight sentence with no filler, front-loading the verb and the result ('shortest chain') before the traversal qualifier.

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 and the input schema is fully documented, so the description need not explain returns. The one meaningful omission is failure semantics — whether a missing path yields an empty result or an error — which matters for a graph traversal bounded by max_depth.

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

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

Schema description coverage is 100% and every parameter is documented inline, including the wait_for_pending_writes staleness semantics, so the baseline is 3. The description adds only the directional meaning of the traversal, not any parameter-level detail such as path formatting or depth-limit behavior.

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

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

The description names a specific verb and resource ('Find the shortest chain of links between two notes') and adds the key scoping detail 'following links in either direction', which distinguishes path-finding from the one-directional, single-hop siblings like get_backlinks and get_outlinks.

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 'between two notes' framing implies the use case, but there is no explicit when-to-use guidance, no exclusions, and no named alternatives (e.g., use get_backlinks for a single hop). The agent must infer selection logic from the sibling list.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered elsewhere. The description adds behavioral value by disclosing that several result categories are bundled in one call, which implies a batching/cost advantage and that the note body is not returned (only metadata plus link and tag structures). It does not mention result size, pagination beyond the limits, or what happens when a note has no backlinks.

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

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

Two sentences, zero filler, with the returned categories front-loaded and the routing guidance immediately after. Every clause earns its place.

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

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

Given an output schema exists, the description need not explain return shapes, yet it enumerates the categories returned so the agent knows the call's scope. Combined with full schema coverage on all four parameters and annotations covering safety, nothing material is missing for correct invocation.

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

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

Schema description coverage is 100%, and all four parameters carry their own descriptions including defaults and the stale-index fallback. The description adds no parameter-level meaning beyond the schema, so the baseline of 3 applies.

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

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

The description names a specific verb ('Return') and resource ('a note's metadata, backlinks, outlinks, similar notes, folder neighbours, indexed tags and applicable conventions'), and explicitly scopes the result as a single aggregated call. An agent can distinguish it from get_backlinks, get_outlinks and get_similar without opening any schema.

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

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

It gives a clear selection rule: use this 'instead of get_backlinks, get_outlinks and get_similar when you need more than one of them'. That is genuine when-to-use guidance with named alternatives. It stops short of covering other overlapping siblings such as get_conventions or get_toc, and gives no when-not condition beyond the implicit 'more than one' threshold.

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=false, so safety is covered. The description adds genuinely new behavioral detail: results are ordered from root to most specific, and a note inherits its folder's conventions, which tells the agent how to interpret the output rather than repeating annotation data.

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

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

A single tight sentence with the resource first and the ordering semantics trailing. Nothing is redundant and no sentence could be removed without losing 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?

One optional parameter, an output schema, and full annotation coverage mean the description is nearly complete. It still leaves open what a 'convention' record contains and how precedence interacts with any explicit per-note overrides, but the output schema handles the return-shape gap.

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

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

Schema description coverage is 100%, and the schema already explains the path parameter, the note-inherits-folder rule, and the empty-string default that returns root conventions plus a folder listing. The description's 'for a note or folder' only restates this, so the baseline of 3 applies.

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

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

The description uses a specific verb and resource: 'Return the vault owner's authoring conventions for a note or folder.' This clearly separates it from data-reading siblings like read or list_documents, and the ordering clause ('vault root first and the most specific last') further pins down what is returned. It does not explicitly name the nearby context tools (vault_context, get_context, show_context) it could be confused with.

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

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

Usage is implied by the resource: call it to learn authoring conventions before writing. There is no explicit when-to-use statement, no exclusion, and no pointer to alternatives such as vault_context or get_context, which an agent might reasonably pick instead.

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, so the safety bar is low; the description still adds the mutual-exclusion rule the schema does not enforce and the empty-diff edge case for vaults without git history. It also discloses the per-commit vs unified output shape, though it says nothing about binary-vs-text beyond what the schema documents.

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

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

Three short sentences with the core behavior front-loaded, then the constraint, then the edge case. No restated title, no filler, and the constraint is placed where an agent will read it before building arguments.

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?

Output schema and annotations carry the return format and safety profile, and the description covers the one genuine trap (specifying both since_sha and since_timestamp). Minor gaps remain: no mention of how limit interacts with per_commit default semantics, though the schema covers that.

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

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

Schema coverage is 100%, so the schema already explains path, limit, since_sha, since_timestamp and per_commit in detail. The description's only addition is the exactly-one-of constraint between the two since_* parameters, which is a meaningful but small increment over the structured data.

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

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

Names a specific verb and resource ('Return how a note or attachment changed from an earlier commit to now') and immediately states the output shape (one unified diff or one per commit). This cleanly separates it from get_history, which the description routes to for finding commits.

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

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

Gives an explicit precondition ('Pass exactly one of since_sha and since_timestamp') and names get_history as the way to obtain a SHA, which is real routing guidance. It stops short of saying when to prefer this over reading the note's current contents, but the core alternatives are covered.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds two real behavioral facts: results are ordered newest first, and a vault without git history yields an empty list rather than an error. It says nothing about paging behavior or how commits are identified, but the output schema covers the return shape.

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

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

Two sentences, front-loaded with the core action and scope, followed by the one precondition an agent must know. Nothing is wasted or 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?

For a read-only listing tool with a full parameter schema and an output schema, the description covers purpose, scope, ordering and the empty-result case, which is nearly everything needed. The remaining gap is routing guidance against the many sibling history/link tools.

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

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

Schema description coverage is 100%, so path, limit, since and until are already fully documented with formats, defaults and bounds. The description adds only the ordering semantics implied by limit (newest commits first), which is marginal value over the schema; baseline 3 applies.

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

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

States a specific verb and resource ("List the commits that touched a note...") plus the scoping options and sort order (newest first), so an agent knows exactly what comes back. It does not name or contrast with the closest siblings such as get_diff or get_recent, so sibling differentiation is left implicit.

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

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

Usage is implied by the scope statement (history of a path or the whole vault) and the note that an empty result means no git history. There is no explicit guidance on when to choose this over get_diff (per-commit content) or get_recent (recently modified notes), which is the main gap given how many siblings overlap.

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, so the description's 'Report' is consistent and adds no contradiction. It supplements the annotation by specifying that the tool reports progress and last build error, which are useful behavioral details beyond the generic read-only hint. It does not discuss rate limits or side effects, but none are needed for a pure status report.

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

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

A single, information-dense sentence that front-loads the action and scope. No filler or redundant wording. Every phrase contributes meaning.

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

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

For a parameterless status tool, the description is complete: it states what it reports (readiness, progress, error) and the output schema covers return details. No additional guidance is necessary. The tool's role is clear within the sibling set.

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

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

With zero parameters, the baseline is 4 per the rubric. There is nothing to document, and the description correctly mentions no inputs. The output schema (not shown) presumably defines the return structure, so the description does not need to compensate.

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 ('Report') and resource ('FTS index'), and clearly enumerates the reported aspects (readiness, progress, last build error). This distinguishes it from sibling tools like reindex, build_embeddings, or okf_generate_index, which perform actions rather than report status.

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 a read-only status check, and the readOnlyHint annotation reinforces this. However, it does not explicitly state when to use this tool versus alternatives (e.g., before reindexing, or to diagnose build failures). The intended use is inferable from the tool name and the sibling context, but not 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered; the description adds non-obvious lifecycle context — that job records expire and finished results must be fetched promptly, and that a working job yields no result yet. It does not mention polling cadence or what happens if the job_id is unknown or expired (error shape), leaving a small behavioral gap for a read tool.

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

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

Two tight sentences: the first front-loads purpose and return shape, the second adds the expiration constraint and job origins. No redundancy with the title and no filler wording.

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

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

With an output schema present, return-value detail needn't be explained, and annotations cover the safety profile; the description supplies the missing pieces — job origin, expiration, and terminal states. Only minor gaps remain, such as handling of unknown or expired job_ids and whether the caller should retry or poll.

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

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

Schema coverage is 100% and the single job_id parameter is already documented as the value a long-running tool returned. The description adds only indirect meaning by naming which tools emit job_ids, without adding format, expected value, or failure behavior for the 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?

States a specific verb and resource (get the status of a background job) and enumerates the return states (working, completed, failed) with result or error. It also scopes the tool to jobs started by long-running tools on this server, which separates it from sibling listing/read tools like reindex, build_embeddings, and get_index_status.

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 tells the agent to call this after a slow summarize, reindex, or build_embeddings call continues in the background, which is concrete when-to-use guidance tied to named siblings. It stops short of stating what to do instead when no job was started (presumably read the synchronous result directly), so it is clear context rather than a full when/when-not pairing.

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=false, so safety is covered. The description adds the ordering guarantee, which is genuine behavior beyond annotations, but says nothing about result shape limits, whether backlink counts are included, or index freshness beyond what the schema already documents.

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

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

Two short sentences, zero filler, with the core purpose front-loaded and the sibling routing as the follow-up. Nothing could be removed without losing 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?

An output schema exists so return values need not be explained, and both params are fully documented. Purpose, ordering and sibling routing are all present; only minor context such as what a 'backlink' counts as is left implicit.

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%: limit and wait_for_pending_writes are both documented in the schema, including timeout fallback behavior. The description adds no parameter meaning on top of that, which hits the baseline of 3.

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

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

States a specific verb and resource ('List the notes with the most backlinks') plus the sort order ('most first'), so the agent knows exactly what comes back. It also names a sibling it is not, distinguishing itself from the per-note link tools without requiring the schema to be opened.

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 to get_backlinks for the complementary question ('the notes that link to one of them'). It doesn't state an explicit trigger sentence like 'use this to find hub notes', so usage is partly implied, but the alternative-selection guidance is real 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?

Annotations already establish a read-only, idempotent, non-destructive call. The description adds that results are unbounded ('no limit on the count'), which warns about output size. That is valuable context the annotations don't give.

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 with the purpose front-loaded and an actionable caveat. No wasted words.

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

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

This is a simple, single-optional-parameter read tool with an output schema and full annotations. The description covers purpose, the unbounded-size risk and a pre-check strategy, which is complete for its complexity.

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

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

Schema coverage is 100%, and the single parameter wait_for_pending_writes is fully explained there, including stale-index behavior. The description adds nothing about the parameter, so baseline 3 applies.

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

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

The description says it lists every note with no links in or out. That is a specific verb, resource and definition of 'orphan', and it sets the tool apart from link siblings like get_backlinks, get_outlinks, get_broken_links and get_most_linked.

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 tells the agent to check orphan_count in the stats sibling before calling on a large vault, which is useful sequencing guidance. It doesn't say when an orphan listing beats other discovery tools, or how to filter or limit if the count is huge.

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=false, so the safety profile is covered. The description adds the missing-target behavior via the exists flag, but says nothing about ordering, truncation, or the stale-index path exposed by wait_for_pending_writes, leaving most behavioral burden on 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?

Two short sentences with zero filler, and the core purpose plus the missing-target caveat are front-loaded before the alternative-tool pointer. 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?

For a three-parameter read-only tool with an output schema and full annotation coverage, this is nearly sufficient: what it returns and when to prefer it are both stated. The only omission is that the dedicated get_backlinks sibling is not acknowledged as the alternative for the backlink case it mentions.

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

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

Schema description coverage is 100%, including the case-sensitivity of path, the default-for-all semantics of limit, and the timeout/staleness behavior of wait_for_pending_writes. The description adds no parameter meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ("List the links in a note") and adds a concrete return-field semantic (an exists flag that is false for missing targets). It also names a distinct sibling, so an agent can tell it apart from the context-aggregating tool without opening either schema.

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

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

Gives an explicit routing rule: use get_context when backlinks or similar notes are also needed, implying this tool is the narrow outlinks-only choice. It stops short of a full when-not list and never mentions get_backlinks, which is the more direct sibling for the backlink case, so the guidance is helpful but not exhaustive.

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 it read-only, idempotent, and non-destructive. The description adds that results are sorted by modification time, newest first. It says nothing about index freshness at the description level, though the schema covers the stale-index behavior.

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

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

There are two sentences, front-loaded with the purpose and then the usage context. Neither 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?

For a simple read-only listing tool with an output schema, full annotations, and a fully described schema, the description is nearly sufficient. The main gap is differentiation within a large set of overlapping listing and query siblings.

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 documents folder semantics and stale-index behavior thoroughly. The description adds no parameter information of its own, so the baseline of 3 applies.

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

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

It names a specific verb and resource, "List the most recently modified notes," and gives the ordering, "newest first." It does not separate itself from close siblings like list_documents, query_documents, or get_history, which could also list notes by date.

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

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

"Use it to pick up recent activity without a search query" gives a usage context and implies search is the alternative when a query exists. It gives no guidance relative to list_documents, query_documents, or get_history, which overlap with this tool.

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

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

Annotations only declare readOnlyHint=true, so the description adds real value by disclosing the conditional nature of one field ("when configured, the upstream service's version") and that the payload is connection-scoped ("the revision and client of this connection"). It stops short of saying the call has no side effects or that results are static from server start, but the safety profile is already 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?

Front-loaded with the verb and purpose, followed by a usage sentence. The middle field list is dense but each named field earns its place by telling the agent what questions this tool can answer; it is slightly encyclopedic for a zero-argument call.

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

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

An output schema exists, so return values did not need spelling out, yet the description still signals the key conditional (optional upstream version) an agent would otherwise misread. For a zero-parameter, read-only introspection tool this is fully sufficient.

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 no parameters, so the baseline is 4; the description correctly says nothing about inputs rather than inventing them. Nothing further can be added on this dimension.

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?

Uses a specific verb and resource ("Report the version information of markdown-vault-mcp") and enumerates exactly what comes back: server_name, server_version, core_version, supported protocol revisions, this connection's revision/client, and optionally the upstream service version. No sibling tool does version introspection, and the description makes that scope 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?

Gives a clear trigger condition: "Use it when asked which version or build is running or which protocol revision is in use." That covers the realistic invocation contexts. It doesn't name an alternative or a when-not case, but with zero sibling overlap there is little to route against.

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=false, so safety is covered by structured data. The description adds genuinely new behavior — self-exclusion from results, similarity ranking, per-section grouping, and the embeddings prerequisite — but says nothing about empty-result behavior or ordering ties beyond what the schema's wait_for_pending_writes note implies.

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

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

Two short sentences, front-loaded with what the tool returns, followed by the prerequisite caveat. No redundant restatement of the title or annotations.

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

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

With an output schema present, return values need not be described, and the description covers the prerequisite, the self-exclusion rule and ranking semantics. It leaves minor gaps around failure modes (invalid path, partially built embeddings) and how folder/filters narrow the comparison set.

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

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

Schema description coverage is 100%, so path, limit, folder, filters, chunks_per_file and wait_for_pending_writes are all documented in the schema itself. The description adds no syntax, defaults, or interaction rules beyond the schema, so the baseline 3 applies.

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

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

The description names a specific verb and resource ('Find the notes closest in meaning to a given note') and adds output shape ('ranked by similarity with their closest sections, the note itself excluded'). It distinguishes itself implicitly from query-based siblings like search, but never names an alternative explicitly, which keeps it short of a 5.

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

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

It states a concrete gating condition — semantic_search_available must be true per stats, and notes without built embeddings yield no results — which directly informs whether the agent should call this tool at all. It does not, however, contrast the tool with search or query_documents for agents choosing between retrieval strategies.

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/non-destructive, so the description's added value is in behavior: folder results include a truncated flag, note results lead with the title as level 1. It does not mention the index_stale behavior that wait_for_pending_writes implies, but the mode-dependent shape disclosure is genuinely useful 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 sentences, front-loaded with the core operation, then a compact breakdown of the two result shapes. 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?

With an output schema present and full schema coverage, the description only needs to frame the two modes, which it does. The main omission is any note about index freshness or when to prefer this over read, but nothing required to call it correctly is missing.

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

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

Schema description coverage is 100% and each parameter is documented with examples and defaults, so the schema does the heavy lifting. The description adds nothing parameter-specific beyond the schema, which is the expected baseline at 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?

States a specific verb and resource ('Return the heading outline of a note, or of every note under a folder') and cleanly distinguishes itself from read/list_documents by naming the outline concept. An agent can tell what this produces 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?

Usage is implied by the operation — you call it when you want a structural outline rather than full content — but there is no explicit when-to-use/when-not or routing to siblings like read or list_documents. The two modes (note vs folder) are clarified, which is the strongest guidance present.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond that: results carry metadata only, never body text, and attachments are excluded unless requested. It stays silent on index staleness and pending-write waiting, but those are documented in the schema and output schema.

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

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

Two short sentences with no waste. The return-shape constraint is front-loaded and the disambiguation follows immediately, so the reader gets the most decision-relevant fact first.

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

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

With an output schema present and full parameter coverage, the description need not restate return values or parameter formats; it correctly focuses on scope and sibling routing. Minor gap: it does not hint that the listing is filterable by folder, frontmatter or glob, which is the tool's main power, though the schema carries that fully.

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 explains folder scoping, frontmatter filters, glob patterns, attachment inclusion and write-waiting. The description only alludes to the attachment option and the returned fields, adding no syntax or edge-case detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ("List notes, and optionally attachments") and pins down the returned fields (path, title, frontmatter) while explicitly excluding body text. It also names the sibling it is not ("search") and the distinction between them, so an agent can route correctly without opening a schema.

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

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

The second sentence gives a clear selection rule: use this to enumerate, use search to find notes by content. That is a genuine when-to-use statement with a named alternative, though it does not mention other plausible alternatives such as count_documents or query_documents, nor any when-not conditions.

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=false, so the safety profile is covered. The description adds real behavioral context beyond that: only folders containing notes are returned, and `""` denotes the top level — non-obvious semantics an agent would otherwise guess wrong.

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

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

Two short sentences, the core definition front-loaded and the usage hint second. No filler, no restatement of the title, and the awkward line wrap does not obscure meaning.

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

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

An output schema exists and annotations are rich, so the description only needs to frame the concept, the sentinel value, and downstream use — all present. Minor gap: it does not say whether folder identifiers are paths, names, or namespaced, which matters for chaining into search/list_documents.

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

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

The single parameter wait_for_pending_writes is fully documented in the schema (100% coverage) including its timeout/staleness fallback behavior. The description says nothing about that parameter; its discussion of `""` concerns return values, not inputs. Baseline 3 applies since the schema does the work.

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 (list folders) plus a scope qualifier ('that holds notes') and defines the top-level sentinel `""`. It is clearly distinct from data-listing siblings like list_documents or list_tags, though it never explicitly contrasts itself with them.

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

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

Second sentence gives concrete downstream guidance: pass a returned value as the folder argument of search, list_documents and other folder-scoped tools, which implies the tool should be called before folder-scoped operations. No explicit when-not or alternative-to-use-instead guidance is given.

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, so the safety profile is covered. The description adds that results are distinct values and vault-wide in scope, but says nothing about index staleness or what happens when the index lags — that behavior only lives in the schema text for wait_for_pending_writes.

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

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

Two short sentences with no filler; the core scope (distinct values of one field, vault-wide) is front-loaded. The follow-up sentence on using the output in search filters is compact and earns its place, though the tool name and description are slightly out of alignment.

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 and both parameters are fully documented, so the description only needs to convey scope and purpose, which it does. Combined with annotations, an agent has enough to select and invoke it correctly without further prose.

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 explains both parameters, including the indexed_frontmatter_fields constraint and the stale-index timeout behavior. The description's phrase 'one indexed frontmatter field' lightly reinforces the field constraint but adds no format or example detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource: returns the distinct values a single indexed frontmatter field takes across the vault. That is precise and tells an agent it is an enumeration/distinct-values tool rather than a document listing. It stops short of naming how it differs from siblings like list_folders or aggregate_documents, and the name 'list_tags' undersells that the field is configurable.

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

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

The second sentence gives downstream guidance ('Use the values in the filters argument of search'), which is useful routing but describes what to do with the output, not when to call this tool versus alternatives. There is no explicit when-not or prerequisite (e.g. field must be indexed) stated as usage guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety bar is lower, yet the description still adds real substance: it discloses that every inbound link is rewritten vault-wide and that unrepaired links surface in failed_links, i.e. partial-failure semantics. It stops short of stating irreversibility or whether a failed rewrite leaves the vault in a half-moved state.

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

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

Two tight sentences, front-loaded with the action and scope. The colon appositive 'rename for a whole folder' gives the agent a one-glance mental model, and the failed_links sentence earns its place by flagging partial failure.

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

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

For a destructive two-parameter move, the description covers scope, the vault-wide link-rewriting consequence, and failure reporting, and an output schema exists so return values need no explanation. It could go further on ordering/atomicity and what happens to a folder already at the destination, but nothing essential for a correct call is missing.

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

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

Schema description coverage is 100% and both parameters are already documented with examples, including the merge-into-existing-folder behavior for new_dir. The description adds no parameter-level meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource (move a folder) plus the scope ('and everything under it') and the key side effect (rewriting every link into it across the vault). The gloss 'rename for a whole folder' cleanly separates it from the sibling `rename`, which acts on a single note.

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

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

The phrase 'rename for a whole folder' implies the boundary against `rename` and `write`, but usage is only implied — there is no explicit 'use this instead of X when Y' or warning about when a move is inappropriate (e.g. moving into a descendant). Guidance exists but requires inference.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is known. The description adds real value by disclosing that unresolvable wikilinks are left untouched and that re-running is a no-op, but it never states that files are rewritten in place, whether there is any undo path, or what 'destructive' concretely risks.

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

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

Two short sentences with the core action front-loaded and no filler; the second paragraph carries only non-obvious caveats. The first sentence is slightly overloaded by the appositive about OKF style, but nothing is wasted.

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

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

An output schema covers the returned counts, and the sole parameter is fully described in the schema, so the description need not repeat them. What remains thin is mutation semantics — in-place rewrite scope and irreversibility — which matters for a tool flagged destructive.

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

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

Schema coverage is 100% and the single 'folder' parameter is fully documented in the schema, including the omit-for-whole-vault default. The description adds nothing about the folder scoping or whether the folder path is vault-relative, so the baseline 3 applies.

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

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

States a specific verb ('rewrite') and a precisely named transformation ('wikilinks as bundle-root-absolute Markdown links'), plus the OKF framing. No sibling in the list does link-format conversion, so an agent can identify it unambiguously without opening the schema.

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

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

The purpose implies when to use it (normalizing a vault to OKF-recommended link style), but there is no explicit when-to-use statement, no prerequisites, and no alternatives named (e.g., okf_validate as a read-only check before running). Guidance is inferred 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?

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is known; the description usefully specifies exactly what is destroyed ('replacing the old listing') and what is preserved ('keeping its frontmatter'), plus the non-obvious recursive behavior that subfolders lacking an index.md also get one. It stops short of saying what happens on a nonexistent folder or whether existing subfolder indexes are rewritten.

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

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

Two short sentences with zero filler; the primary action and its outputs come first, and the recursive subfolder caveat is placed as a trailing note where it belongs.

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 one-parameter tool with an output schema, the description covers the essential behavioral facts: content generated, overwrite semantics, frontmatter preservation, and recursive scope. Minor gaps remain around error behavior for missing folders and whether subfolder indexes are regenerated or only created.

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 one parameter at 100% schema coverage, the schema already documents the folder string and the root default, so the baseline of 3 applies. The description only reinforces that the target is 'a folder's' index and adds no syntax, path-resolution, or edge-case detail beyond the schema.

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

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

States a specific verb and resource ('Write a folder's Open Knowledge Format index.md') and immediately enumerates the content produced: a link per note with its description plus a link per subfolder index. This is clearly distinguishable from siblings like okf_validate, okf_convert_links, reindex, and get_index_status.

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

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

Usage is implied rather than stated: the reader infers you run this after notes change to regenerate a folder listing. There is no explicit when-to-use or when-not-to-use guidance, and no routing versus reindex or get_index_status, which an agent may plausibly confuse with index maintenance.

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 this as a non-read-only, non-idempotent, non-destructive write. The description adds real value on top: a hard 100-commit cap, the guarantee that existing log.md files are untouched, and the edge case of a vault with no git history yielding an empty log. It does not clarify whether the call fails or silently no-ops when a log already 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?

Three short sentences, zero padding, with the core action and output shape front-loaded before the constraints. Every sentence carries distinct information (what it builds, what it won't overwrite, the commit limit, the empty-history case).

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 and full parameter coverage, the description covers the limits and edge cases an agent needs before invoking. The remaining gap is failure semantics when log.md already exists and whether git availability is a precondition, which matters for a write tool.

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

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

Schema description coverage is 100% and the single 'folder' parameter is fully documented in the schema, including the default-to-vault-root behavior. The description adds no meaning beyond that, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Create a folder's Open Knowledge Format log.md') plus the source of content ('from the git history of the notes under it') and the resulting shape ('one dated section per day, newest first'). This clearly separates it from siblings like get_history, okf_validate, and okf_generate_index, which read or transform rather than seed a log file.

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

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

Gives clear operating context and an implicit exclusion ('It never replaces an existing log.md'), which tells an agent not to call it expecting a refresh. It stops short of naming alternatives (e.g., get_history for raw commit data) or stating prerequisites such as needing a git-backed 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 declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds two useful behavioral facts beyond that: the report is graded ('how far the vault conforms') rather than binary, and it includes example paths per rule, plus the undeclared-vault precondition. It stops short of describing scope of the audit, failure behavior, or cost, so it is solid but not rich.

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

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

A single sentence that front-loads the audit action and packs the output detail and precondition into trailing clauses. Nothing is wasted, though the semicolon joins two fairly distinct ideas (output content and vault precondition) into one slightly dense line.

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 explain return values, and with zero parameters there is no input burden. It covers the essential precondition and characterizes the report, leaving only minor gaps such as whether it is read-only in effect on undeclared vaults or how large audits are handled.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly avoids inventing parameter talk and instead spends its words on scope and output content.

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: auditing vault conformance to the Open Knowledge Format. The sibling tools okf_convert_links, okf_generate_index, and okf_seed_log are visibly different actions, so an agent can distinguish this audit tool from them without opening the schema, though the description never names them.

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

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

The clause 'works on a vault not yet declared as a bundle' gives a real precondition that implies when this tool applies. However, there is no explicit when-not guidance and no mention of which sibling (e.g. okf_convert_links) to reach for if the vault is already a bundle or if the agent wants to fix rather than just audit.

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 readOnly/idempotent/non-destructive, and the description adds genuine behavior: exact totals independent of the page cap, ranking rules (keyword score then path for text, modification time descending for blank queries), and the important caveat that pages are live views where concurrent writes can shift notes across pages. That live-view instability note is a real operational disclosure not derivable from annotations or schema.

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

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

Three short sentences, front-loaded with the core action and total guarantee, then ranking rules, then the live-view caveat and the pointer to `read`. Nothing is redundant and no sentence is filler.

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

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

With 13 parameters, an output schema, and full schema coverage, the description needs only to explain the query model and result-stability semantics, which it does. The main residual gap is sibling disambiguation among the many list/search/count tools, which the description does not address.

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 13 parameters in detail. The description adds only indirect meaning about how `query` behaves (text vs blank ranking, total vs limit), without explaining scope, filters, pattern, or the pending-writes flag. Baseline 3 applies when the schema does the heavy lifting.

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

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

"Page through all matching indexed notes with an exact total" names a specific verb (page/query), the resource (indexed notes), and the distinguishing output property (exact total). It is clearly a paginated index-listing tool rather than a content fetch, but it never explicitly contrasts with siblings like list_documents, search, or count_documents.

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 only explicit routing is "Use read to retrieve full note content," which usefully separates querying from fetching. There is no guidance on when to prefer this over list_documents, search, count_documents, or get_recent, despite those being close alternatives in the sibling set.

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, so safety is covered. The description adds real behavior beyond that: attachments come back base64-encoded, and revision-based reads omit the etag — a subtle but consequential detail for callers planning a follow-up write.

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

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

Two sentences, front-loaded with the return contract before the path-lookup caveat. Zero filler and no restatement of the tool name or title.

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

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

With an output schema present, the description does not need to explain return shapes, and it correctly focuses on the return contract and path discovery. Minor gaps remain around error behavior for missing paths and any size limits on base64 attachment reads.

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 explains path casing, section-as-heading, and the revision/SHA-without-etag workflow. The description adds little parameter-level meaning beyond noting that etag appears only in the non-revision case, so the baseline 3 applies.

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

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

The description states a specific verb ('Return') and enumerates exactly what comes back: note text, frontmatter, etag, or attachment bytes as base64. That dual note/attachment coverage plus the explicit return payload lets an agent distinguish this from write, edit, append, or search 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?

It gives explicit routing advice for the path-resolution problem: 'Look paths up with search or list_documents first rather than guessing them.' However, it is silent on when to choose this over the sibling 'vault_read', which appears to be a close analogue, and gives no guidance on when not to read (e.g., huge attachments).

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

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

The annotations already declare that this is a non-read-only, idempotent, non-destructive operation. The description adds meaningful behavior: it exists for out-of-band changes, internal writes already update the index, and it returns added/modified/deleted/unchanged counts. It does not discuss force-reindex cost or search blocking, but those are covered in the parameter 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 two short paragraphs and front-loads the trigger condition. The second paragraph earns its place by preventing redundant calls after server-side writes.

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 single optional parameter, an output schema, and clear annotations, the description supplies the key missing context: external-change use case and the exclusion for internal writes. The remaining force-reindex details are fully handled by the schema.

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

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

Schema coverage is 100%, and the single force parameter is thoroughly documented in the schema, including its default, cost, blocking effect, and follow-up embedding step. The description itself does not mention force, so it adds no parameter meaning beyond the schema.

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

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

The description states a specific verb and resource: bringing the search index up to date. It also scopes the operation to files changed outside this server, which distinguishes it from index updates performed by write tools.

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

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

It explicitly says when to use the tool (after external edits or sync changes) and when not to use it (after writes through this server, because those update the index themselves). This is clear routing guidance with no ambiguity.

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 mark the tool as non-destructive and non-idempotent. The description adds that parent folders are auto-created and that links in other notes get rewritten. The schema adds that new_path must not exist and that attachment references are not tracked. The description does not say what happens on a path collision or an etag mismatch.

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

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

Two short sentences, front-loaded with the purpose and no filler. The update_links advice is duplicated between the description and 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 and the schema documents parameters well, so the description is reasonably complete for a 4-parameter mutation. It is missing failure behavior and folder-move routing.

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 covers if_match, new_path constraints and update_links. The description mostly repeats the update_links recommendation already stated in the schema, adding little new parameter meaning.

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?

It names a specific action on specific resources: "Rename or move a note or attachment," plus link-following. It does not set itself apart from move_folder, which is the sibling most likely to cause confusion, though "note or attachment" implies single-file scope.

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 directive "For a note, always pass update_links=True" is useful invocation guidance. There is no when-to-use versus alternatives, such as using move_folder for folders, or write/delete instead of rename.

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 fully covered structurally. The description adds the ranking/snippet return behavior, but that is also carried by the output schema, and it does not mention latency, index-staleness behavior, or result caps beyond what the schema states.

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 with zero filler; the capability and return shape are front-loaded and the sibling routing is compressed into one clause. Nothing could be removed without losing routing information.

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

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

With 8 parameters, full schema coverage, an output schema, and rich annotations, the description only needs to establish purpose and routing, which it does. The minor gap is that it does not point to stats or embeddings_status for the semantic-mode prerequisite, though the schema does.

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 including mode, folder, filters, snippet_words and wait_for_pending_writes is already documented in detail in the schema. The description adds no parameter-level meaning beyond the input schema, which is the expected baseline-3 case.

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

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

States a specific verb and resource ('Search notes by keyword and meaning') plus the return shape (notes ranked by score with best-matching sections as snippets). The second sentence names two siblings it is not, so an agent can distinguish it from list_documents and read without consulting schemas.

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

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

Explicitly routes two alternatives: list_documents for a complete listing and read for a path already known, giving the condition that selects each. No exclusion guidance is offered against other retrieval siblings such as search_paths, query_documents, get_similar, or aggregate_documents, which leaves some ambiguity in a 50-tool namespace.

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 readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds genuine behavioral detail beyond that: results are metadata-only (no bodies), an explicit ranking order (exact, then case-insensitive prefix, then other literal, then approximate), and the distinction between 'coverage' and 'truncated' as separate signals. It does not mention the fuzzy scan's candidate/time budget, though that lives in 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 opening clause front-loads the core purpose and the ranking rules follow in a compact, ordered sequence that mirrors actual result order. Every sentence carries information; the only slight drag is the coverage/truncated sentence, which reads as output-field plumbing though it is still relevant.

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 is not obliged to explain return values, and it correctly focuses on ranking, metadata-only scope, and the next-step call. The remaining gap is comparative placement among the many sibling search/listing tools, which for a vault with this many alternatives would be worth one extra clause.

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

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

Schema description coverage is 100%, so all six parameters are already documented in detail, including fuzzy edit-distance rules and limits. The description only contributes indirectly by framing fuzzy as 'optional typo matches' and tying 'coverage' to the approximate pass, which is marginal added meaning over the schema — baseline 3 applies.

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

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

States a specific verb and resource ('Discover note paths') and immediately scopes it to path/metadata discovery rather than content retrieval ('Returns metadata without bodies'). An agent can distinguish it from read, but the description does not name what separates it from list_documents, browse_vault, or search, so it falls short of full sibling differentiation.

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 one explicit routing instruction — 'Use read with a returned path to retrieve its content' — which covers the natural follow-up call. However, there is no guidance on when to prefer this over search, list_documents, or browse_vault, and no exclusion conditions, leaving the main selection decision to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds two non-obvious facts beyond that: the tool has a user-facing side effect (it renders a card and "shows the note to the user") and its response is deliberately impoverished ("returns only counts"), which prevents an agent from expecting payload data despite the output schema.

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

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

Two sentences with zero waste. The capability statement comes first and the sibling routing plus return-shape caveat follow, so the reader gets action, scope, and destination in the first pass.

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 simple (one path parameter, output schema present, annotations covering safety), and the description supplies exactly the missing pieces: that the output is a UI card rather than data, and where to go for the underlying data. Nothing needed to call it correctly is absent.

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

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

Schema description coverage is 100% and there is only one required parameter whose format and example are documented in the schema. The description says "a note's" and "shows the note," reinforcing that the argument identifies a single note, but it adds no syntax or edge-case meaning beyond the schema. Baseline 3 applies.

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

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

The description uses a specific verb and resource ("open an interactive card... showing a note's backlinks, outlinks, similar notes, tags and frontmatter") and explicitly names the sibling it is not ("use get_context for the data"). An agent can distinguish it from get_backlinks, get_similar, and get_context without opening any schema.

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

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

It names the alternative (get_context) and states the condition that selects it: this tool displays to the user and returns only counts, so fetch the data through get_context instead. It lacks an explicit when-not (for example, non-interactive or headless use where no human is watching), but the routing logic is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is fully covered and the description need not repeat it. What the description adds is the scope of reported data, but it omits relevant behavior such as whether figures come from the index (and may lag pending writes) and how expensive the link-health computation is.

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

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

One sentence, verb-first, with the four reported data classes enumerated after the colon and no filler. Nothing here could be deleted without losing 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, return-shape explanation is unnecessary, and the one optional parameter plus annotations are handled by structured fields. The description covers what is reported, leaving only minor gaps around index staleness and its relationship to the status/capability siblings.

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

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

Schema description coverage is 100% and the single parameter, wait_for_pending_writes, is documented in the schema including its timeout/_meta.index_stale behavior. The description adds nothing about the parameter, so the baseline of 3 applies.

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

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

The description uses a specific verb ("Report") and enumerates the resources returned: vault size, link counts, supported search modes, and facetable frontmatter fields. That is far more informative than the bare name "stats", though it does not distinguish this tool from capability/status siblings such as get_index_status, get_index_stats, or list_tags.

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

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

Usage is only implied: an agent can infer this is a capability-discovery call to run before constructing a search, since the description lists the search modes and filterable fields it exposes. There is no explicit when-to-use statement, no exclusion, and no pointer to the overlapping status siblings.

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

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

The annotations already declare that the tool is read-only, idempotent, non-destructive, and closed-world, so the safety profile needs no further explanation. The description adds the non-obvious detail that this is a UI-internal call path rather than a general-purpose endpoint, which is genuinely useful behavioral context. It does not say whether the result is cached, whether it is scoped to the current editor state, or what happens if the note is not open.

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

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

The description is three short lines, and the core action is front-loaded, so there is no wasted prose. The closing note that the tool is not visible to the LLM is slightly meta and self-referential, since this text is being read by an agent, but it is short and it carries real information.

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

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

The tool is simple: one required parameter and an output schema that defines the returned NoteContext, so return values need not be described. The annotations cover the safety profile, and the description covers the unusual calling context. The main gap is that an agent has no basis to know how this differs from the context siblings, which is the one thing a complete definition here should settle.

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

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

Schema description coverage is 100%, and the single path parameter is documented with an example format of 'Journal/2024-01-15.md'. The description adds nothing about path resolution, whether a leading slash is accepted, or behavior on a missing note. With one fully documented parameter, the baseline of 3 is correct.

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

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

The description states a specific verb and resource: 'Return the full NoteContext for a note', so the action is clear. However, 'NoteContext' is an internal term that is never defined, and the description does not distinguish this tool from sibling context tools such as show_context, get_context, or read. The parenthetical '(app-only)' narrows it, but only by saying it is not for the caller.

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 does state a usage condition, namely that the SPA context card view calls it via app.callServerTool(), and that it is not for the LLM. This amounts to implicit guidance for an agent to avoid the tool. It never names alternatives such as get_context or show_context, and it gives no criteria for choosing between them.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false, indicating a safe read operation. The description adds the important behavior that it is 'app-only' and 'Not visible to the LLM,' which is critical for an agent to know before calling it, as it may not be relevant or accessible for LLM workflows.

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 extremely concise, with three short sentences. The core purpose is front-loaded, and every sentence adds value: what it returns, when it's used, and a crucial caveat about LLM visibility. No waste.

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

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

The tool has only one optional parameter and an output schema, so it's relatively simple. The description covers the purpose and usage context, and the output schema likely explains the return format. The main missing piece is an explicit mention of the 'limit' parameter's effect on performance or graph size, but this is minor.

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 provides 100% coverage for the single parameter 'limit' with a clear description of 'Max number of hub notes to include.' The description does not add further parameter semantics, but since schema coverage is high, 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 returns the most-linked notes and their connections as a graph, specifying it is app-only and used by the SPA graph view. This distinguishes it from siblings like get_most_linked, which likely returns a simple list, and vault_graph_neighborhood, which focuses on a specific note's connections.

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 states it is called by the SPA graph view for the hub overview, giving clear usage context. However, it does not explicitly explain when to use this over siblings like get_most_linked or get_connection_path, nor does it mention any exclusions or 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, closed-world, and an output schema covers the return shape, so the bar is low. The description adds one genuine behavioral fact beyond them — that this is an internal SPA-facing entry point — but says nothing about traversal cost, semantic-edge fallback, or truncation, all of which live in the schema instead.

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

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

Two short sentences with no filler, and the most decision-relevant fact (app-only, not for the LLM) is front-loaded so an agent can dismiss the tool immediately.

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

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

With an output schema, full parameter coverage, and four annotations, the only thing the description needs to convey is scope, which it does decisively. What is missing is minor: no pointer to the sibling an agent should use instead for backlink/connection queries.

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

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

Schema description coverage is 100%, including defaults, BFS/truncation behavior and the embeddings requirement for include_semantic, so the schema carries parameter meaning fully. The description adds nothing about path, depth, max_nodes or include_semantic, making 3 the correct baseline.

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

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

States a specific verb and resource — returns the link neighborhood of a note as a node/edge graph — and specifies the output shape, which separates it from list-style siblings like get_backlinks or get_outlinks. It does not name those siblings explicitly, so an agent must infer which graph/list tool to reach for.

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?

Unusually explicit routing guidance: '(app-only)', 'Called by the SPA graph view via app.callServerTool()' and 'Not visible to the LLM' tell an agent clearly that this tool is out of scope for it. It stops short of naming the LLM-facing alternative (e.g. get_backlinks, get_connection_path) for the same neighborhood need.

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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds the meaningful operational fact that this is an internal SPA-invoked tool, but says nothing about recursion depth, whether hidden files are included, or pagination behavior on large vaults.

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

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

Three short lines, front-loaded with the actual capability before the invocation context. Nothing is padded, though the 'Not visible to the LLM' line is somewhat redundant with '(app-only)'.

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, complete annotations, and a fully documented single parameter, the structured data carries most of the burden. The description is adequate but leaves the main ambiguity unresolved: how this differs from the several other listing tools in the sibling set.

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

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

Schema description coverage is 100% and the single `folder` parameter is already documented as 'Folder to list (root if omitted).' The description adds no syntax, path format, or delimiter conventions beyond that, so the baseline of 3 applies.

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

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

States a concrete verb and resource: lists folders and notes within a vault directory. It partially distinguishes itself from list_documents and list_folders by covering both in one call, though it never names those siblings explicitly.

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

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

The '(app-only)' marker plus 'Called by the SPA browser view' establishes who invokes it, which is a usage constraint rather than routing guidance. It gives no when-to-use versus list_documents, list_folders, or browse_vault, so an agent must infer selection from names alone.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds that the entire note body is returned (not a summary) and that invocation happens through the SPA bridge, but says nothing about behavior for missing/invalid paths, encoding, or size limits. An output schema exists, so return-shape disclosure is not required, keeping this at a solid but unremarkable 3.

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

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

Three short lines, front-loaded with the action and resource, with no filler. The trailing audience note is slightly meta for a tool definition but is short and informative rather than wasteful.

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 single-parameter read with full annotation coverage and an output schema, the description supplies what an agent needs: what is returned, who calls it, and through what mechanism. The only gap is sibling differentiation against `read`, which is minor given the explicit app-only scoping.

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

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

There is a single parameter with 100% schema description coverage ('Relative note path'), so the schema carries the semantics. The description adds no information about path resolution, vault root, extension handling, or what counts as 'relative', which is the one place added value would have mattered.

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

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

The description gives a specific verb and resource — read a note's full content — and narrows the scope to preview rendering. It also distinguishes itself from the sibling `read` tool by declaring itself an app-internal endpoint rather than a general LLM-facing read, though it never explains the functional difference between the two.

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 states the caller context ('Called by the SPA browser view via `app.callServerTool()`') and explicitly excludes the LLM audience, which functions as a when-not-to-use signal. What is missing is routing guidance toward the likely alternative (`read`, `browse_vault`) for an agent that actually needs note content.

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, non-destructive and closed-world, so the safety profile is fully covered elsewhere. The description adds only the unusual invocation channel (SPA/app context), and says nothing about result shape, ranking behavior across the three modes, or cost – though an output schema exists to cover returns.

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

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

Two short sentences, front-loaded with the resource and the distinguishing qualifier, with no filler. Slightly cryptic rather than verbose, but structurally efficient.

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?

Annotations, a full-coverage schema and an output schema carry most of the burden, so this is close to adequate. The main gap is that the description positions itself as an internal app tool invisible to the LLM while being offered as an LLM tool, leaving the agent without a clear rule for when it should be chosen over `search`.

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%, with all three parameters documented including the mode enum and limit default. The description adds no meaning beyond that – notably it does not explain what keyword vs semantic vs hybrid actually do or when to pick each.

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?

"Search the vault" is a concrete verb+resource, but it does not separate this tool from several siblings with overlapping purpose (`search`, `query_documents`, `browse_vault`). The "(app-only)" qualifier hints at a different consumer but never states how results differ from those siblings, so the agent cannot distinguish it on capability alone.

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

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

The description does supply invocation context (called by the SPA search bar via `app.callServerTool()`) and states it is "Not visible to the LLM," which effectively tells an agent to avoid it. However, it never names the alternative the agent should use instead, so routing away is left to inference.

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

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

Beyond the annotations it discloses that the call reports whether the file was created and that parent folders are created implicitly. However, the phrase 'replace one whole' signals full-content overwrite while destructiveHint is false, and the description never warns that existing content is discarded or that if_match is the guard against clobbering; that is exactly the kind of context a write tool should surface. The mismatch is a soft tension rather than a flat contradiction, since overwrites may be recoverable via the history siblings.

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

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

Two tight sentences with the create/replace semantics front-loaded and the sibling routing immediately after. Every clause carries information: return values, alternatives, and implicit folder creation; nothing is padded.

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

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

An output schema exists, so return values do not need spelling out, and the description covers the create-vs-replace distinction, implicit folder creation, and sibling routing. It is nearly complete for a 5-parameter write tool; the missing piece is a caution about overwriting an existing note without an etag.

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 path, content, if_match, frontmatter and content_base64 are all already explained, including the extension-decides-note-vs-attachment rule. The description adds no parameter-level meaning beyond that, so the baseline 3 applies; folder auto-creation is behavioral rather than parameter guidance.

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

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

States a specific verb and resource ('Create a note or attachment'), plus a second mode ('replace one whole') and the return signal ('its path and whether it was created'). It also names the sibling tools it is not (edit, append), so an agent can separate it from the neighbouring mutation tools without inspecting any schema.

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

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

Explicitly routes between alternatives: 'Use edit for targeted changes and append to add to the end', which defines both when this tool is the right pick and which siblings cover the cases it does not. The only unstated condition is when an overwrite requires an etag, which the schema itself documents.

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