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

Annotations already set readOnlyHint=false and destructiveHint=false; description adds non-obvious behaviors: automatic newline insertion only when missing, queued index refresh with no reindex needed, and no read required. No contradictory statements.

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 sentences, each earns its place: purpose first, usage guidance second, newline detail third, index behavior last. No filler or repeated schema content.

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 4-param tool with full schema detail and an output schema, the description covers the behavioral decisions an agent needs: when to choose it, what happens to newlines, and post-append index state. No significant gap remains.

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 has 100% coverage, so baseline is 3; description adds practical meaning by explaining the automatic newline behavior and telling the caller to include blank lines/heading markers for separation. It does not elaborate every parameter, but the schema already does.

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?

Description opens with 'Append text to the end of an existing .md note without reading it', giving a specific verb, resource, and scope. It explicitly contrasts with 'edit', making sibling differentiation immediate.

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?

States the exact condition for use—'purely additive at the end of the note'—and tells the agent to prefer this over 'edit'. Also notes that no prior 'read' is needed, which is the key cost/context benefit.

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, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds context that the tool displays an interactive visual panel (MCP Apps) to the user, which is useful beyond annotations. However, it does not describe any additional behavioral aspects like permissions or side effects beyond what annotations imply.

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

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

The description is concise and well-structured: front-loaded with the purpose, followed by exclusions (what not to use for), and then when to call. Every sentence adds value with no redundancy.

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

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

Given the tool's simplicity (opens a UI), the description covers purpose, usage guidelines, parameter hints, and has output schema present. No need to explain return values. It is fully complete for agent decision-making.

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

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

Input schema has 100% description coverage, so the schema already documents both parameters. The description mentions optional note path and view types but does not add additional semantics beyond what is in the schema. Baseline of 3 is appropriate given high schema coverage.

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

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

The description clearly states the tool opens a visual vault explorer UI for the user, using specific verbs and resource. It explicitly distinguishes itself from sibling tools by stating it is not for reading content programmatically and lists alternative tools for different purposes.

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 guidelines are explicit: only call when the user asks for the visual vault browser or explorer, and do NOT use for programmatic retrieval. Alternative tools (search, read, list_documents, get_context) are listed, providing clear when-to and when-not-to guidance.

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

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

The description goes well beyond the annotations by detailing convergence behavior (missing/changed docs embedded, orphans removed, unchanged chunks untouched), inline vs. background execution, soft-deadline semantics, and the immediate return shape with status and job_id. The destructive nature of force=True is disclosed clearly, and nothing contradicts the idempotentHint or destructiveHint annotations.

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

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

The description is longer than typical, but every sentence carries distinct information: purpose, normal unnecessity, force semantics, convergence behavior, and background execution. It is front-loaded with the core action and progresses logically, though it could arguably be tightened by merging the convergence and background sentences.

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

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

Given the output schema, annotations, and sibling context, the description covers all essential operational aspects: when to call, what force does, return behavior, background continuation, and how to obtain the final result. An agent has enough information to invoke the tool correctly and handle both fast and slow builds.

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 has a detailed schema description. The tool description adds contextual meaning—explaining when force is appropriate and what happens without it—which reinforces the parameter semantics without repeating schema text verbatim.

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

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

The first sentence states an explicit action and resource: 'Rebuild vector embeddings for semantic and hybrid search.' It clearly distinguishes the tool from siblings like embeddings_status (observability) and get_job_result (outcome fetching) by describing the rebuild action and background-job semantics.

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

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

The description explains that embeddings are built automatically on startup, so this tool is 'normally not needed,' and gives explicit guidance for when to use force=True (after changing the embedding model). It also references get_job_result and embeddings_status as alternatives for fetching outcomes and observing index state, though it does not provide an explicit when-not-to-use 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?

Beyond the destructiveHint annotation, the description reveals important side effects: .md deletions queue an index refresh, attachments do not, and deletion is irreversible unless git history exists. It also instructs the agent to confirm the path with the user, adding meaningful behavioral context not present in the structured annotation.

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

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

The description is compact and front-loaded, starting with a clear one-sentence summary. Every sentence earns its place: resource scope, index-refresh behavior, irreversibility, and user confirmation are all stated without redundancy.

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

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

For a destructive two-parameter tool with a full output schema and detailed annotations, the description supplies all essential context: what is deleted, side effects on the index, irreversibility, and the required confirmation step. The if_match concurrency behavior is already covered by the schema, so no critical guidance is missing.

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

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

Schema coverage is 100%, and the schema already thoroughly documents both 'path' and 'if_match', including optimistic concurrency semantics. The description reinforces the relative-path convention and the confirmation requirement but does not add significant new parameter-level 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 explicitly states 'Permanently delete a document or attachment', naming both the action and the specific resource types. It clearly distinguishes this tool from siblings like edit, write, and rename by focusing on destructive deletion with a clear 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 description gives clear context for use: it is destructive, irreversible, and requires user confirmation before calling. It does not name explicit alternatives or exclusion cases, but the conditional handling of .md documents vs attachments provides practical guidance on when the tool behaves differently.

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 are minimal (only hints about read-only, idempotency, destructiveness), so the description carries the full burden. It fully discloses behavior: three edit modes, normalization fallback with match_type='normalized', queued index refresh, and the need for a prior 'read'. This exceeds what annotations provide.

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

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

Well-structured with a clear opening line, bullet-pointed modes, and a closing operational note. Every sentence earns its place; no redundancy. The most critical instruction (call read first) is placed near the end but is highlighted separately, and the overall length is justified by the tool's complexity.

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

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

Given the tool's complexity (3 modes, normalization, concurrency), the description covers all essential context: how to invoke each mode, the normalization fallback, the index refresh behavior, and the prerequisite of reading first. An output schema exists, so not describing return values is acceptable. Nothing critical is missing.

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

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

Schema coverage is 100%, so each parameter is individually documented. The description adds value by explaining the relationships between parameters (e.g., line-range mode requires line_start+line_end and omits old_text; scoped match combines old_text with a range). This contextual semantics goes beyond the schema's per-field descriptions.

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

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

The description states a specific action ('targeted text replacement') on a specific resource ('existing .md note') and explicitly excludes attachments, clearly distinguishing it from write/append/delete/rename siblings. The three modes are detailed, leaving no ambiguity about what the tool does.

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

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

Provides explicit guidance on when to use each mode, instructs to always call 'read' first, and recommends passing if_match for safety. It doesn't explicitly contrast with sibling tools like 'write' or 'append', but the purpose is distinct enough that an agent can infer when 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 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?

Goes far beyond the annotations by disclosing zero context cost, server-side downloading, UTF-8 decoding for .md, binary saving for others, queued index refresh, SSRF protections, redirect-following behavior, and the need to check final_url. This is rich behavioral context that the annotations alone do not provide.

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

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

Well-structured and front-loaded: the core purpose appears first, then the key context-cost insight, then path-dependent behavior. Every sentence carries useful information, including security caveats, and the formatting makes the .md vs attachment cases easy to scan.

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

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

Given 5 parameters, an output schema, and nontrivial security behavior, this description is complete: it covers schemes, SSRF, redirects, etag concurrency, timeouts, optional frontmatter, and post-fetch usage. An agent has everything needed to invoke the tool correctly.

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

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

Schema coverage is 100% and each parameter already has a detailed description, so the baseline is 3. The prose description adds context around path extension handling and frontmatter behavior, but most parameter meaning is already fully documented in 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 ('Download a file from a URL and save it to the vault') and clearly distinguishes the tool's niche: MCP-to-MCP transfer of content too large for the LLM context window. It also differentiates .md note behavior from attachment behavior, so an agent can tell this apart from read/write/vault_read siblings.

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

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

Explicitly gives the intended use case ('MCP-to-MCP file transfer when content is too large to pass through the LLM context window') and tells the agent what to do afterward: reference the file by path, and call read(path) only for small results. This gives clear when-to-use guidance relative to sibling read and write tools.

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 readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the inbound scope and rationale but does not disclose return behavior, edge cases, or index freshness details beyond what the parameter schema already explains. This is adequate 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?

The description is short, front-loaded with the core definition, and structured clearly. A small amount of redundancy exists: the second sentence restates the first concept ('notes reference') and the final sentence reinforces relevance, but overall it remains 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?

The tool has a complete input schema, output schema, and annotations covering safety and idempotency. The description supplies the missing routing context by naming get_context as the broader alternative, making the definition complete enough for an agent to select and invoke it correctly.

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

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

Schema description coverage is 100%, with path, limit, and wait_for_pending_writes already documented in the input schema. The description adds no parameter-specific meaning beyond what the schema supplies, so the 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 opens with a specific verb and resource: 'Find all documents that link TO the given document (backlinks).' This clearly defines inbound links and distinguishes the tool from siblings like get_outlinks and get_context by naming the 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?

The description gives explicit routing guidance: use get_context for a full picture of a note's place in the vault and call get_backlinks directly when only the inbound link list is needed. It also notes that backlinks surface relationships search alone cannot, reinforcing when the tool adds value.

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, destructiveHint=false. The description adds useful context beyond these, explaining that a broken link means the target path does not match any indexed document and why that might happen (deleted, renamed, never created). This enriches the agent's understanding of the tool's semantics.

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

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

The description is mostly efficient, opening with a clear purpose and then giving concrete usage triggers. The last sentence about what 'broken link' means is slightly explanatory but adds useful background, so overall it earns its place without excessive bloat.

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

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

Given the output schema exists and annotations cover safety, the description is largely complete. It covers what the tool does, when to use it, and what a broken link means. It could mention the folder filter briefly, but the schema already does. No major gaps.

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 ('folder', 'wait_for_pending_writes') are thoroughly documented in the input schema. The description does not add 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?

States a specific verb ('find') and resource ('links that point to non-existent documents'), clearly distinguishing it from siblings like get_orphan_notes or get_backlinks. The purpose of auditing link health is explicit and actionable.

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

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

Gives concrete triggers: call when 'stats' shows broken_link_count > 0, or after a 'rename' that did not use update_links=True. This tells the agent exactly when to use the tool and what scenario it addresses, without confusion.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral detail beyond annotations: links are treated as undirected, BFS is used, and max_depth is clamped to [1, 10].

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

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

Three sentences with no filler. The core purpose is front-loaded, followed by key behavioral details and a practical use case. Every sentence contributes meaningful 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 description fully covers what the tool does, how it behaves on the link graph, the clamping behavior, and the intended use case. An output schema exists, so return values do not need to be described. No critical information 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%, so the schema already documents all four parameters. The description adds context around max_depth clamping and the undirected interpretation of links, but does not need to explain individual parameters further.

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

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

States a specific verb and resource: 'Find the shortest connection path between two notes in the link graph.' It clearly distinguishes itself from graph siblings like vault_graph_neighborhood and vault_graph_hubs by focusing on pathfinding between two specific notes rather than neighborhoods or hubs.

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

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

Gives clear context for when to use the tool: discovering how seemingly unrelated notes are connected, the 'six degrees of separation' use case. It does not explicitly name alternatives or state when not to use it, but the context is strong enough to guide selection.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds behavioral context beyond annotations: it consolidates multiple data sources into one call, includes a wait_for_pending_writes option that can return stale data with _meta.index_stale=true, and explains the similarity lookup can be skipped. This gives the agent useful operational knowledge beyond the 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?

The description is well-structured and front-loaded: the first sentence states the core purpose, followed by a concise list of what it returns, and ends with explicit usage guidance. Every sentence earns its place, and the length is appropriate for the tool's complexity. No fluff or redundancy.

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

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

The description is complete for a read-only consolidation tool. It explains what the tool returns, when to use it, and how it relates to siblings. The output schema exists, so return values don't need to be described. The parameter semantics are fully covered by the schema, and the annotations cover the safety profile. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters thoroughly. The description adds some context by explaining the consolidation behavior and the conditional use of similar_limit, but it doesn't add significant meaning beyond what the schema provides. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly states the tool's purpose: 'Get a consolidated context dossier for a document.' It explicitly lists what it returns (metadata, backlinks, outlinks, similar notes, same-folder notes, frontmatter tags) and names the sibling tools it replaces ('get_backlinks', 'get_outlinks', 'get_similar'). This distinguishes it from siblings and gives an agent a precise understanding of its function.

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

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

The description explicitly says when to use this tool: 'Use this instead of making 4-5 separate tool calls when you need a full picture of a note's place in the vault.' It also names the alternatives it replaces, providing clear routing guidance. The parameter description for similar_limit adds conditional usage guidance ('do this when stats shows semantic_search_available=False'), which further clarifies when to adjust behavior.

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. The description goes well beyond this by disclosing that conventions accumulate down the tree, are returned root-first with most specific last, load from a default '_conventions.md', and read directly from disk even while the search index is building. This is substantial behavioral context an agent could not infer from annotations alone.

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

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

The description is front-loaded with a one-sentence purpose and then layers in behavior, usage, and disk-read rationale. Each paragraph earns its place, though the example convention text is slightly verbose and could be trimmed without losing meaning.

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

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

Given the output schema and rich annotations, the description covers what the tool does, when to call it, how results are ordered, and why it works during index building. It is nearly complete, but it does not explicitly address what happens when no convention file exists for a given path, leaving a minor edge case to the output schema or agent inference.

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

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

The input schema already provides 100% parameter coverage, including path resolution to parent folder and the empty-string discovery mode. The description adds no parameter-level semantics beyond what the schema documents, so the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: "Get the user's authoring conventions that apply to a note or folder." It also gives a concrete example of what conventions contain, making the tool's purpose unmistakable and distinct from generic read or list operations.

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?

Clear usage guidance is provided: "Call this before creating, restructuring, or linking notes so the result follows the vault owner's rules." It also mentions that write/edit tools echo conventions for post-write checks, giving useful contextual boundaries. It does not explicitly name alternative tools or conditions when not to use it, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint and idempotentHint as true, so safety is clear. Description adds behavioral details: supported vault types, binary vs text handling, and the mutual exclusivity constraint. Could be slightly more detailed on return value shape, but helpful beyond annotations.

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

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

Four sentences, front-loaded with core purpose, then conditions and advice. No redundant words or repetition. Efficient and well-structured.

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

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

Given the presence of an output schema (indicated), rich input schema descriptions, and annotations, the description is complete. It covers prerequisites, parameter requirements, behavioral notes, and references related tools. No gaps identified.

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% with detailed descriptions for all 5 parameters. The description adds value by restating the mutual exclusivity of since_sha and since_timestamp and noting binary attachment behavior. While schema already covers details, the description reinforces key constraints.

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?

Clearly states the tool returns the diff of a note between a reference point and HEAD. Distinguishes from siblings like 'get_history' (which returns commit history) and 'read' (which returns content). The resource and action are specific.

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 prerequisite ('only available for git-backed vaults'), parameter requirement ('exactly one of since_sha or since_timestamp'), and references sibling tool ('Use get_history first to find commit SHAs'). Provides clear when-to-use and when-not-to-use context.

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 classify this as readOnly, idempotent, and non-destructive. The description adds a meaningful behavioral constraint: the tool only works on git-backed vaults and can raise an error otherwise, which is not inferable from the schema or annotations.

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

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

Two sentences deliver the purpose and the key precondition without redundancy. The core action is front-loaded, and the git prerequisite and stats fallback are presented immediately after.

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

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

Given the output schema, detailed parameter docs, and annotations, the description covers the essential contextual gap—git dependency and error handling. An agent can decide whether to call it and what to do if the vault isn't git-backed.

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% with detailed descriptions for path (vault-relative, file/folder subtree semantics), limit (default/max), and since/until (ISO 8601 or git expressions, inclusive boundaries). The description contributes no additional parameter meaning, so the baseline of 3 applies.

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

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

The description opens with 'List commits that touched a note, folder, or the whole vault,' giving a specific verb and resource while scoping the operation to git-backed vaults. This clearly distinguishes it from content-reading siblings like read and search, and from diff/recent variants like get_diff and get_recent.

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

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

The description explicitly states the precondition (git-backed vault) and gives an actionable fallback: use 'stats' to check whether git is configured, or call this and handle the error. It does not enumerate alternatives, but the precondition provides a clear selection rule versus non-git history tools.

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 and destructiveHint=false. The description adds valuable behavior beyond that: job records expire after a while, so results should be fetched promptly. It also explains the polling loop and the terminal state concept, which are not captured in annotations. It doesn't cover error handling for expired or invalid job_ids, but the key operational behavior 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?

Four sentences cover purpose, when to call, polling cadence, expiration warning, and source tools. Information is front-loaded with the core purpose first, then operational details. No repetitive or extraneous content.

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 polling tool, the description covers all necessary operational aspects: what the tool does, how to obtain the parameter, polling behavior, expiration risk, and which tools produce jobs. An output schema exists to document return values, so that requirement is met externally. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is 0% and the sole parameter job_id is just a generic string type. The description fully compensates by explaining that job_id is the identifier returned by a long-running tool in its 'working' status response, and instructs the agent to use that same job_id when calling this tool. With one parameter, this is sufficient and precise.

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 ('Retrieve') and clearly states the resource ('outcome of a background job'). It explicitly distinguishes itself from the long-running tools by explaining that it is the polling mechanism for jobs started by summarize, reindex, and build_embeddings calls. The purpose is unambiguous and easily differentiated from siblings.

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

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

It gives a direct trigger condition: call when a tool responds with status 'working' and a job_id. It also provides polling cadence ('every few seconds until the status is terminal') and a timing caution ('fetch results soon after completion'). This is explicit, actionable guidance with no need for inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds a behavioral detail beyond annotations by specifying that results are 'ranked by backlink count,' and it adds context about hub notes. It does not contradict annotations.

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

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

Two sentences pack the core behavior, the value proposition, and the sibling differentiation into ~50 words with no filler. The key function 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?

This is a simple read-only tool with an output schema, fully documented optional parameters, and annotations covering safety and idempotence. The description explains what it does, why to use it, and when to switch to an alternative, so an agent can call it correctly.

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

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

Both 'limit' and 'wait_for_pending_writes' are fully described in the input schema (100% coverage), so the baseline applies. The description does not add any parameter-specific meaning, but the schema already handles it.

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

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

The description states a specific verb ('Return') and resource ('documents with the most inbound links, ranked by backlink count'), and explicitly differentiates from get_backlinks: 'For the specific documents that link to a particular note, use get_backlinks instead.' An agent can distinguish this tool from its siblings clearly.

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 when to use the tool ('Useful for discovering hub notes') and when not ('For the specific documents that link to a particular note, use get_backlinks instead'), giving an explicit alternative. This is exemplary 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 mark it read-only and idempotent, but the description adds important behavioral context: 'returns ALL orphans with no limit' and the warning to check orphan_count on large vaults. This goes beyond the structured annotations and helps agents avoid expensive calls.

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

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

The description is compact and well-structured: main action first, then a warning, then a definition and usage trigger. Every sentence serves a purpose, and the most important operational caveat 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?

For a simple read-only tool with one optional parameter and an output schema, the description covers what it returns, when to call it, how to identify orphans, and a performance warning. Nothing needed for correct invocation is missing.

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

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

The single parameter wait_for_pending_writes is fully documented in the schema with 100% coverage, so the description does not need to repeat it. It adds no parameter-specific detail, but the schema carries the load; 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 opens with a specific verb and resource: 'Return all notes with no inbound or outbound links.' It then defines what an orphan note is in concrete terms, making the tool's scope unambiguous and distinct from link-focused siblings like get_backlinks or 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?

It gives an explicit trigger condition: 'Call this when stats shows orphan_count > 0.' It also warns to check stats before use on large vaults. It does not mention when not to use it or name alternative tools, but the usage context 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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is established. The description adds value by disclosing that 'Each result includes an exists flag — False means the link is broken (the target is missing from the vault).' This is a behavioral trait not present in the schema or annotations, informing the agent about broken-link detection. The description does not contradict any annotations, and it enriches the behavioral picture beyond the structured metadata.

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

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

The description is four sentences, front-loaded with the core purpose. It immediately states what the tool does, then provides usage guidance and a key output detail. Every sentence earns its place—no filler or redundancy. The structure is efficient and scannable, ideal for an agent parsing it quickly.

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

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

Given the tool's simplicity (3 parameters, all schema-documented), the presence of an output schema, and strong annotations covering safety, the description is complete. It covers the primary use case, the alternative tool for richer context, and a critical output behavior (exists flag). There is no missing information an agent would need to call this tool correctly. The description is sufficient on its own.

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%, meaning all three parameters (path, limit, wait_for_pending_writes) are already fully documented in the input schema with descriptions. The tool description adds no additional parameter-specific information, which is acceptable because the schema carries the burden. Per the rubric, a baseline of 3 is appropriate when schema coverage is high and the description does not need to compensate. It doesn't add extra meaning beyond the schema, so a 3 is warranted.

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

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

The description opens with a precise statement of function: 'Find all links FROM the given document to other documents (outlinks).' This gives a clear verb+resource combination. It also distinguishes itself from the sibling get_context by noting that get_context provides a 'full picture of a note's place in the vault,' while this tool is specifically for the outbound link list. This makes the tool's purpose unambiguous and separates it from related tools.

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

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

The description gives explicit guidance: 'For a full picture of a note's place in the vault, use get_context instead of calling this separately. Call get_outlinks directly when you only need the outbound link list.' This clearly states both when to use this tool and when to prefer an alternative. The condition for direct use is specific, making it easy for an agent to decide.

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 description's burden is lighter. It adds ordering behavior ('ordered by file modification time, most recent first') and implies index usage without a query, which goes beyond the annotations and adds 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?

The description is compact and front-loaded: the primary purpose is in the first sentence, followed by the ordering detail, and then use cases. Every sentence contributes value without redundancy, making it efficient and easy to scan.

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

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

With an output schema present and annotations covering safety, the description provides the essential context: what the tool does, how results are ordered, and when it's useful. It does not need to detail return values or parameter specifics because those are covered elsewhere. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100% (all three parameters have detailed descriptions), so the schema already documents parameters. The tool description does not add any additional parameter semantics; it only mentions the general purpose, which is already covered by the schema. Baseline of 3 is appropriate.

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

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

States a specific verb ('Get') and resource ('most recently modified notes in the vault'), and distinguishes itself from search by noting it works 'without a search query.' It clearly identifies what it returns (notes ordered by modification time) and separates it from siblings like search and list_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?

Provides concrete use cases ('summarize recent activity or resume work on recently edited notes') and implies the alternative of a search query, but does not explicitly name siblings or state when NOT to use it. This is clear context, though not fully explicit about exclusions.

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

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

Annotations already declare readOnlyHint=true. Description adds value by specifying the returned fields (server_name, version, core_version, upstream block) and that it is a read operation, consistent with annotations.

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

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

Two sentences, front-loaded with the key purpose. No unnecessary words; each 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?

Given an output schema exists and no parameters, the description fully explains what the tool returns and why it's useful. No gaps.

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

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

No parameters; schema coverage is 100% with an empty schema. Description compensates by explaining the output, meeting baseline for zero-parameter tools.

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?

Description clearly states it reports server and upstream version info for markdown-vault-mcp, listing specific fields. This distinguishes it from sibling tools that operate on vault content.

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?

Description provides a use case: 'verifying a deployment matches the expected build.' No explicit when-not-to-use or alternatives, but for a simple info tool this is adequate.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: it uses stored embeddings (no re-embedding), excludes the reference document from results, and returns an empty list under certain conditions. It also mentions the wait_for_pending_writes behavior via the parameter description, which is a useful behavioral disclosure.

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

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

The description is concise and well-structured. The core purpose is stated in the first sentence, followed by a brief mechanism note and then actionable guidance. Every sentence adds value, and the structure front-loads the most important 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 description is complete for an agent to use this tool correctly. It covers prerequisites (semantic search configured), fallback behavior (empty list), and remediation (build_embeddings). The output schema exists, so return values are documented elsewhere. The parameter descriptions are exhaustive, covering edge cases and OKF semantics.

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

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

Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds context beyond the schema by explaining the overall mechanism (stored embeddings) and the fallback behavior (empty list if not configured). The parameter descriptions themselves are detailed, including edge cases like folder='' for root-level documents and the OKF semantics for filters.

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

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

The description clearly states the tool's function: 'Find notes most semantically similar to the given document.' It specifies the resource (notes), the operation (find similar), and the mechanism (stored embedding vectors). It also distinguishes itself from sibling tools like 'search' by emphasizing semantic similarity rather than keyword matching.

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

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

The description provides explicit guidance on when to use this tool: it requires semantic search to be configured, and it tells the agent to check 'stats' for semantic_search_available. It also explains what to do if embeddings are not configured (call 'build_embeddings') and how to handle missing vectors. This is clear, actionable 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety bar is lower. The description adds real behavioral value beyond that: the conditional return shape per path type, the synthetic H1 title, the ordered aggregation of notes in folder mode, and the mirroring of the toc:// resource with added controls. It does not go into truncation/staleness behavior, but the schema documents those.

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

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

The description is well-structured: a one-sentence summary up front, then mode-specific behavior, then the resource mirroring note. Each sentence earns its place and the most decision-relevant fact (note vs folder behavior) is front-loaded. It is slightly verbose in recounting return shapes that the output schema already captures, which keeps it from a 5.

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

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

Given the tool's complexity — two output modes, four parameters, an existing output schema, and full schema-provided parameter descriptions — the description covers the mode-switching semantics, the synthetic H1 behavior, and the relationship to the toc:// resource. Nothing an agent needs to call it correctly is missing, and the description does not need to repeat return values because an output schema exists.

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

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

Schema description coverage is 100%, so the baseline is 3 and the schema carries the full detail on max_level, max_notes, and wait_for_pending_writes. The description adds marginal semantics by explaining how 'path' determines mode (”.md" suffix → note vs folder prefix) and by naming the controls, but stops short of enriching the parameters' meaning beyond that.

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

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

The opening sentence 'Heading outline for a single note or a whole folder subtree' names a specific resource and purpose, and the description immediately distinguishes two modes by path type ('If 'path' ends in '.md' it is a note... Otherwise 'path' is a folder'). This cleanly separates it from sibling read/navigation tools like read, search, and browse_vault.

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

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

The description gives strong operational guidance on mode selection (note vs folder based on path suffix) and connects the tool to the 'toc://vault/{path}' resource. However, it never explicitly tells the agent when to prefer this over siblings such as read, list_documents, or search, nor states any when-not conditions, so the usage context against alternatives 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 covered. The description adds a meaningful behavioral trait: 'Does NOT include body content — call 'read' for full text.' This goes beyond annotations by clarifying the return semantics and what the tool will not do.

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

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

The description is compact and front-loaded: the first sentence states the core purpose, and each subsequent sentence earns its place by addressing alternatives or exclusions. There is zero filler and every line contributes to the agent's ability to invoke the tool correctly.

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

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

Given the tool has a rich output schema.</thinking> The description covers all decision-relevant context: enumeration vs. search, body content exclusion, attachment option, and alternative tool selection. The remaining details (folder semantics, filter behavior, pattern syntax) live in the input schema, which is thoroughly documented. Nothing an agent needs to decide when to call this tool is missing.

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

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

Schema description coverage is 100%, so the schema fully documents all five parameters. The description adds contextual framing (e.g., 'optionally attachments', complete listing vs. search) but does not introduce parameter-level semantics beyond what the schema already provides. 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 opens with a specific verb and resource: 'List documents (and optionally attachments) in the vault.' It also differentiates itself from sibling tools by explicitly contrasting with 'search' for content-based retrieval and 'read' for full text, making its purpose unmistakable.

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

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

The description provides explicit when-to-use guidance: 'Use this to enumerate documents when you need a complete listing, not ranked search results.' It also names alternatives ('search', 'read') with the conditions that select them, leaving no ambiguity about routing.

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

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

Annotations already include readOnlyHint=true, idempotentHint=true, and destructiveHint=falseainer. The description adds useful behavioral detail by clarifying that root-level documents correspond to an empty string path. It does not contradict the annotations, though it leaves the wait_for_pending_writes behavior to the schema and parameter description.

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 short, front-loaded, and has no filler. Both sentences contribute essential information: what the tool returns and the important root-folder convention.

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 one optional parameter, an output schema, and clear annotations, the description fully covers what an agent needs to select and invoke it correctly. The root-path clarification adds important context that is not otherwise obvious.

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

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

Schema description coverage is 100% for the single optional parameter, and the schema itself explains its semantics, default, and timeout behavior. The tool description does not need to add anything further about parameters; 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 states a specific operation ('List all folder paths that contain documents') and clearly identifies the resource. It also distinguishes itself from list_documents and search by emphasizing folder paths rather than content or 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 description explicitly says to call this tool to discover valid folder names before filtering 'search' or 'list_documents' by folder. This gives clear, actionable guidance on when to use it and for what purpose.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=falsehare. The description adds non-obvious behavior: unindexed fields return an empty list rather than an error forging a timeout. This is useful behavioral context beyond the annotations.

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

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

The description is compact and front-loaded: the first sentence states the core purpose, the second gives direct usage guidance, and the third warns about a critical edge case. Every sentence earns its place with no redundancy.

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

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

Given the output schema existswrong documents return values, and annotations already describe safety, the description is sufficiently complete. It covers what the tool lists, how to use it, where to find valid fields ('stats'), and what happens with invalid inputs.

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

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

Schema description coverage is 100%, and the schema already documents both 'field' and 'wait_for_pending_writes' clearly. The description mostly restates the field concept at a higher level without adding new parameter-level details, so a baseline score of 3 is appropriate.

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

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

The description uses a specific verb and resource: 'List all distinct values for a frontmatter field across the vault.' This clearly states what the tool does and distinguishes it from sibling tools like list_documents, list_folders, and stats by focusing on frontmatter field value enumeration.

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

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

The description explicitly states when to use the tool: 'Use this to discover valid filter values before calling search with the filters argument.' It also tells the user to reference 'stats' for indexed fields and warns that querying non-indexed fields returns an empty list, giving clear before-use context.

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

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

The description discloses the atomic gate (fails if destination exists), best-effort link rewrites with failed_links reporting, and the risk of partial moves on OS errors with a recommendation to reindex. This goes well beyond the destructiveHint annotation, providing rich behavioral context.

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

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

The description is lengthy but every sentence carries essential information about failure modes, link rewriting, and recovery. It is front-loaded with the core purpose and avoids fluff, though it could be tightened slightly.

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 complex recursive move with link rewriting, the description covers the atomic gate, best-effort rewrites, failure reporting, and recovery via reindex. Nothing essential for correct invocation is missing, and the output schema is referenced via failed_links.

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 already covers both parameters at 100%, but the description adds meaning by explaining old_dir/new_dir as relative prefixes, describing merge behavior into existing folders, and noting that a name clash aborts the move. This adds value beyond the schema descriptions.

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

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

Clearly states the tool moves an entire folder subtree in one call and rewrites all links into the moved subtree, explicitly positioning itself as the folder-level analogue of rename. This distinguishes it from sibling rename and other 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 identifies itself as the folder-level analogue of rename, implying use for moving folders with link rewriting. However, it does not explicitly state when not to use it or name alternatives (e.g., rename, write), leaving the selection context somewhat implicit rather than explicit.

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

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

Annotations already signal idempotent and destructive, and the description deepens this by disclosing that changed notes go through the write path with possible git commits, that it waits up to 60s for index writes, that refresh errors abort before conversion, and that re-running is safe because converted links are plain markdown. No contradiction with readOnlyHint=false, idempotentHint=true, or destructiveHint=true.

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

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

The description is dense but purposeful, front-loading the core transform in the first sentence and then listing behavioral constraints. It is longer than strictly necessary because the first sentence restates the title's 'Convert Wikilinks' concept, but every remaining clause adds meaningful operational detail.

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

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

For a one-optional-parameter destructive transform with an output schema, the description covers the conversion rule, scope, skip conditions, write-path behavior, idempotency, timeout, and error handling. An agent has enough context to decide and invoke the tool without needing the return structure, which is covered by the output schema.

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

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

Schema coverage is 100%, so the optional folder parameter is already fully documented in the schema. The description reinforces that the folder restricts subtree conversion, but it does not add semantic detail beyond the schema, so the 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 first sentence names a specific verb and resource: 'Rewrite wikilinks as OKF bundle-root-absolute markdown links,' and the paragraph clarifies it converts resolvable [[wikilinks]] in the vault or a folder. This distinguishes it from sibling tools like okf_validate or okf_generate_index, which serve different migration/indexing purposes.

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 frames the tool as a migration transform and states explicit input constraints: only indexed/resolvable wikilinks are converted, unresolvable ones are skipped, and attachment embeds are not links. It does not name alternative tools, but the unique migration purpose and constraints give an agent clear guidance on when this tool applies.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, and the description adds meaningful behavioral context: it overwrites index.md, preserves frontmatter, omits reserved files, waits up to 60s for prior writes, and aborts on refresh errors. This goes beyond the annotations and gives an agent a clear model of side effects and failure modes. It does not contradict annotations.

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

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

The description is compact and front-loaded: the first sentence states the core purpose, and the following sentences add necessary behavioral details without redundancy. Every sentence earns its place, and the structure is easy to scan.

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

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

Given the tool's complexity (a migration transform with overwrite behavior, frontmatter preservation, reserved-file omission, and timeout/error handling), the description covers the key operational aspects. It does not detail the output schema's contents, but an output schema exists, so that is not required. A minor gap is not explicitly stating what happens if the folder does not exist or has no table of contents, but the description is otherwise complete enough for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents the 'folder' parameter. The description adds value by explaining that omitting folder targets the bundle root and that the folder is vault-relative. This is useful semantic context beyond the schema's default/description.

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

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

The description states a specific verb ('Generate'), a specific resource ('reserved OKF index.md listing'), and the mechanism ('from the table of contents'). It clearly distinguishes this from sibling tools like okf_validate or okf_seed_log by naming the output artifact and the OKF migration-transform context.

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

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

The description explains when to use it: to generate or regenerate a folder's index.md, with the folder parameter optional for the bundle root. It does not explicitly name alternatives or say when not to use it, but the context of OKF migration transforms and the explicit 'writes (or overwrites)' behavior gives clear usage context. A small gap is not stating which sibling tool would be used instead for other index operations.

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

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

It goes well beyond the annotations by disclosing exactly what is written, that an existing log.md is never overwritten, and that a log is written empty when there is no git history. These behaviors are consistent with readOnlyHint=false, idempotentHint=false, and destructiveHint=false.

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

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

The lead sentence states the purpose, and every subsequent sentence adds necessary behavioral, scoping, or prerequisite detail. There is no filler, ambiguity, or repeated schema content.

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 tool with an output schema, the description covers creation behavior, overwrite protection, folder scoping, the git-backing prerequisite, and the empty-history edge case. Nothing an agent needs to invoke it correctly is missing.

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

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

The schema already documents folder's role and default at 100% coverage, so the baseline of 3 applies. The description adds nuance about subtree-scoped commits versus whole-vault history, but it does not introduce significant new parameter-level 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?

The description opens with 'Seed a reserved OKF log.md change history from git history', naming a specific action and artifact. It then explains the newest-first format and folder scoping, which distinguishes it from generic write/edit tools and sibling OKF transforms like okf_generate_index.

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

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

The description gives concrete invocation context: folder selects write location and content scope, the bundle root seeds whole-vault history, and a git-backed vault is required. It does not explicitly name sibling alternatives or state when not to use it, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description doesn't need to restate safety. The description adds only the notion of 'audit', implying a read-only check. It doesn't disclose what the audit returns or whether it produces a report, but the output schema likely covers that. Given the annotations carry the safety profile, the description adds minimal behavioral context, so 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 sentence with no unnecessary words. It front-loads the verb 'Audit' and the resource, making it immediately clear. There is zero waste.

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

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

For a simple read-only tool with no parameters and annotations covering safety, the description is mostly complete. It doesn't explain what 'conformance' means or what the output looks like, but the presence of an output schema and the read-only annotations cover the essentials. An agent can call it without needing extra context.

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

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

The tool has zero parameters, and the schema is empty with 100% coverage. Per guidelines, a 0-parameter tool gets a baseline of 4. The description adds no parameter information, which is fine since there are none to document.

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 'Audit' and identifies a clear resource: 'the vault's Open Knowledge Format conformance'. This distinguishes it from sibling tools like okf_convert_links and okf_generate_index, which have different purposes. It is not a tautology and directly conveys the tool's function.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention conditions like 'use when you need to verify OKF compliance before converting links' or 'use after generating an index to validate'. There is no mention of exclusions or preferred workflows, leaving the agent to infer usage from the tool name alone.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description goes well beyond this by disclosing return types (raw markdown vs base64 binary), context-cost implications, byte-size limits with environment variables, ValueError behavior, and the fact that section= is ignored for non-.md paths. No contradiction with annotations.

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

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

The description is front-loaded with the core purpose and organized into clear paragraphs for file types, path discovery, section usage, revision usage, and context cost. It is longer than average but most sentences add value; the only minor issue is some repetition of the section= guidance near the end.

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

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

For a tool with three parameters, annotations, and an output schema, the description covers discovery prerequisites, markdown vs attachment returns, section semantics, revision semantics, size limits, and error behavior. Nothing an agent needs to call this correctly is missing.

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

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

Although the input schema already covers 100% of parameters, the description adds substantial meaning: section= should receive the heading value from a search result and is case-sensitive with collapsed whitespace; revision= accepts a sha from get_history or previous_revision and follows renames; and path should not be guessed. This meaningfully exceeds the schema descriptions.

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

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

The description opens with a specific verb and resource: 'Read the full content of a document or attachment by path.' It clearly distinguishes .md behavior from attachment behavior, but it does not explicitly differentiate itself from sibling read-like tools such as get_context, vault_read, or browse_vault, so it stops 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?

The description gives explicit when-to-use guidance: use list_documents(include_attachments=True) to discover attachment paths, use stats for allowed extensions, and do not guess paths but look them up via search or list_documents. It also explains when to use section= and revision=, and how to restore a previous version with write and if_match. This is strong, actionable routing.

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

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

Beyond the annotations (readOnly=false, idempotent=true, destructive=false), the description reveals async continuation: a reindex past the server deadline returns immediately with job_id, and get_index_status covers non-client-initiated builds. It also details hash-based detection, force behavior (index not queryable during rebuild), and interaction with embedding builds. This is rich disclosure out of annotation tags.

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

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

The description is front-loaded with the function and its trigger, then gives exclusions, force semantics, embedding interactions, and async result handling. Some sentences (e.g., '#1124' reference) are minor extraneous color, but each paragraph advances a decision an agent must make. It's thorough without being bloated for the tool's real complexity.

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 1 param, the description references the observability tool get_index_status and attr the async job fetch tool get_job_result; it also pre-charts the build_embeddings path for force=True. The common-case and rare-case flows are both covered, leaving nothing an agent needs to call correctly.

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

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

The schema already documents force at 100% coverage, but the description gives extra context on when to force (repair for content mismatch, version upgrade auto, manual escape hatch), contrasts it with routine reindexing, and mandates the follow-up build_embeddings. This meaningfully lifts the parameter beyond schema bare definition, justifying a step above 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-resource pair ('Run an incremental reindex on the writer thread') and immediately scopes it to files modified outside the server, distinguishing it from write/edit/delete/rename (which queue updates) and from build_embeddings (which rebuilds the vector index). The purpose is unique and not generic.

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

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

Explicitly explains when to use: only when files were modified by an external process (text editor, sync tool, direct vault writes). It also says when NOT to use it — never after write/edit/delete/rename — and guides force=True usage, routing to build_embeddings for a full semantic rebuild. This is full when/when-not/alternatives coverage.

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

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

The description discloses several non-obvious behaviors beyond the annotations: link rewrites wait for prior index writes, the move queues another index refresh (no reindex needed), and attachment references are not tracked as links. It also notes that parent directories are created automatically. These details are highly valuable for an agent to understand side effects. The annotations are minimal (readOnlyHint, idempotentHint, destructiveHint) and the description does not contradict them; it adds substantial behavioral context.

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

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

The description is three concise paragraphs, each with a clear purpose. The first sentence states the core function. The second gives a key rule. The third splits behavior by file type. There is no fluff or repetition; every sentence adds necessary information. The structure is logical and front-loaded.

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

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

Given the complexity of this operation (rename/move with link rewriting, concurrency, index refresh), the description covers all non-obvious aspects: link rewrite behavior, attachment exceptions, automatic directory creation, and index refresh timing. Since an output schema exists, return format is covered elsewhere. The description is complete for an agent to correctly invoke the tool without additional hidden details.

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

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

Schema coverage is 100%, so all parameters are already documented in the input schema. The description adds extra semantic value by advising to always set update_links=True for .md files and clarifying that update_links is irrelevant for attachments. It also notes automatic directory creation, which relates to new_path. While it doesn't elaborate on old_path or if_match, those are self-explanatory from the schema. This goes beyond the baseline 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?

The description opens with 'Rename or move a document or attachment,' which clearly identifies the verb and resource. It distinguishes itself from sibling tools like write/edit/delete by specifying the rename/move action, and it even clarifies scope (documents and attachments). This is unambiguous and immediately tells an agent what this tool does.

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

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

The description provides explicit conditional guidance: 'When renaming a .md note, always pass update_links=True' and explains that attachments don't need it. It also clarifies that parent directories are auto-created. However, it doesn't explicitly compare to alternative tools (e.g., 'use this instead of move_folder for files'), but the context is clear enough. The guidance for the key decision (update_links) is strong, so this is slightly above average.

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 the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral context beyond that: result content is a snippet by default, not the full document, and read should be used for full sections. It also implies mode fallback behavior without contradicting the annotations.

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

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

The description is compact and front-loaded: the first sentence states the core purpose, the second paragraph gives actionable mode guidance, and the third covers the snippet caveat. No sentence is wasted, and the structure guides the agent from broad behavior to invocation details.

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

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

Given the rich input schema (100% coverage), the output schema, and the read-only/idempotent annotations, the description is complete enough. It covers the key decision points an agent needs—mode selection and the snippet-versus-full-document distinction—without needing to restate schema details or return values.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds decision-oriented meaning for the mode parameter (hybrid when embeddings are configured, keyword when not, semantic for pure vector similarity) and clarifies that content fields are snippets, which helps interpret snippet_words. It does not need to repeat the well-documented schema details.

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

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

The description opens with a specific verb and resource: 'Find documents matching a query using full-text or semantic search.' It also clarifies the scope ('Search the vault') and differentiates the tool from read by directing the agent to use read for full document text, which separates search from a sibling retrieval tool.

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

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

The description gives explicit mode-selection guidance: omit mode for the best available mode, use keyword for exact terms/operators/filenames, and use semantic for pure vector similarity. It also tells the agent when to hand off to read for full section text, which is concrete alternative guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds behavioral context that the tool displays an interactive panel to the user, not for reading relationships, which complements the annotations without contradiction.

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

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

The description is extremely concise: three sentences total, with the main purpose front-loaded, followed by clear usage guidelines. Every sentence serves a purpose without any redundant information.

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

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

Given the simplicity of the tool (one parameter, full schema coverage, clear annotations, and an output schema), the description provides all necessary context for an AI agent to correctly select and invoke the 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?

With 100% schema coverage for the single parameter 'path', the description does not need to add additional parameter semantics. The schema already provides sufficient description, so baseline score of 3 is appropriate.

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

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

The description clearly states it opens a visual context card UI for the user, using specific verbs like 'open' and 'display'. It explicitly distinguishes from sibling tool 'get_context' which returns structured data, ensuring no ambiguity.

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

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

The description provides explicit guidance: only call when the user asks to open the visual context card (e.g., 'show me the context card for this note'), and warns against using it for programmatic data retrieval, directing to 'get_context' 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds useful behavioral context by revealing that the output includes a semantic_search_available field that determines whether mode='semantic' or mode='hybrid' can be used in search.

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 sentences with no filler. The purpose is front-loaded, followed by explicit usage guidance and a useful output-field hint. 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?

The tool has rich annotations, a well-described parameter, and an output schema, so the description does not need to repeat those. It supplies the missing context: when to call, what to use the result for, and how the result relates to search modes.

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 only one optional parameter, and the schema description covers it 100%, including its default and timeout behavior. The tool description adds no parameter semantics, so the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: 'Get an overview of the vault's size, capabilities, and configuration.' It also clarifies the practical purpose—understanding what the vault contains and which search modes are available—which distinguishes it from sibling tools like get_server_info or 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?

The description explicitly recommends calling this 'at the start of a session' and explains how the semantic_search_available field affects use of the search tool. It does not name alternatives or exclusions, but the context is clear enough for an agent to know when this is the right 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 already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered structurally. The description adds useful invocation context ('SPA context card view', 'app.callServerTool()') and notes that it returns the 'full NoteContext,' but it does not go beyond that. With strong annotations, 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?

Three short, purposeful sentences. The core purpose is front-loaded, followed by invocation context and visibility restriction. There is no filler or repetition of annotation data.

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 a full output schema and rich annotations, the description provides sufficient context: what it returns, who calls it, and that it is not visible to the LLM. Nothing needed to select or invoke 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%: the path parameter already has a clear description and example. The tool description adds no parameter-specific meaning, but with full schema coverage 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 action and resource: 'Return the full NoteContext for a note.' It further clarifies the tool is 'app-only' and 'Not visible to the LLM,' which distinguishes it from LLM-facing context tools like get_context or show_context. This is not a tautology of the title.

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

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

It clearly specifies when this tool is used: 'Called by the SPA context card view via app.callServerTool().' The 'Not visible to the LLM' line provides a when-not to use it, though no alternative tool is explicitly named. The invocation context is unambiguous.

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

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

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 readOnlyHint, idempotentHint, and destructiveHint=false; the description adds the node/edge graph return shape and internal caller context. It does not contradict annotations, but it contributes little behavioral detail beyond what the schema and annotations already encode.

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 only three short sentences, with the core purpose front-loaded before caller context. It is efficient and scannable, with only slight redundancy between 'app-only' and 'Not visible to the LLM.'

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, the input schema is fully documented, and annotations cover safety, so the description need not repeat those details. It sufficiently conveys the tool's restricted visibility and purpose for its intended caller, though it could improve by pointing to graph-related 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%, with rich per-parameter details such as the default depth, soft node cap, truncated flag, and conditional semantic-edge behavior. The description itself adds no parameter-level meaning, so the baseline of 3 is appropriate.

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

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

The first sentence identifies a specific action and resource: 'Return the link neighborhood of a note as a node/edge graph (app-only).' The purpose is unmistakable, but it does not differentiate this from related graph siblings such as vault_graph_hubs or get_connection_path.

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

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

The description explicitly scopes the tool as 'app-only,' says it is 'Called by the SPA graph view via app.callServerTool(),' and adds 'Not visible to the LLM,' giving clear invocation context and an exclusion. It stops short of naming alternatives or selection conditions versus other graph tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds the app-only and SPA context, which is valuable behavioral context beyond the annotations, clarifying the intended invocation path and non-LLM visibility.

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 concise sentences with zero waste. The primary purpose is front-loaded, and the app-only note follows naturally. 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 simple read-only tool with one optional parameter, annotations cover safety, an output schema exists (so return format is defined), and the description clarifies usage scope. Nothing an agent needs to correctly avoid or understand this tool is missing.

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

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

The schema fully documents the single 'folder' parameter with its description ('Folder to list (root if omitted).'), giving 100% coverage. The tool description adds no extra parameter detail, so the baseline of 3 is appropriate since the schema already carries the 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?

The description clearly states the tool lists folders and notes in a vault directory, using a specific verb and resource. It also distinguishes itself from sibling tools like list_folders and list_documents by covering both types, and notes it's app-only, which further clarifies its role.

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

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

The description explicitly states it is called by the SPA browser view via app.callServerTool() and is not visible to the LLM, which tells an agent this tool is not for direct LLM use. It doesn't name alternative tools, but the app-only note strongly implies the agent should look elsewhere for LLM-facing list operations.

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

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

Annotations already cover readOnly, idempotent, and non-destructive behavior. The description adds meaningful context beyond those: the intended caller (SPA browser view), invocation mechanism (app.callServerTool()), and visibility restriction (not visible to the LLM).

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

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

Three short sentences, each carrying distinct information: purpose, invocation context, and visibility. The core purpose is front-loaded with no wasted words.

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

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

For a simple one-parameter read tool with strong annotations and an output schema present, the description supplies the necessary invocation context and access restriction. Nothing critical is missing for an agent to decide whether and how to call 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 single parameter 'path' is already described as 'Relative note path.' The description adds no additional parameter-level semantics beyond confirming the resource is a note.

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 action and resource: 'Read a note's full content for preview rendering'. It also clearly scopes the tool as 'app-only', distinguishing it from LLM-facing siblings like 'read' and 'browse_vault'.

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

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

Provides explicit usage context: called by the SPA browser view via app.callServerTool(), and explicitly says it is not visible to the LLM. It stops short of naming a specific alternative ('use read instead'), but the exclusion 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 cover read-only, idempotent, non-destructive behavior. The description adds important behavioral context: the tool is app-only, invoked through a specific server call path, and hidden from the LLM. No annotation contradiction.

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

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

Extremely concise: three short lines front-load the core purpose, then add only the necessary caller and visibility context. Every sentence earns its place with no redundant filler.

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

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

Given the low complexity, complete input schema, and presence of an output schema, the description covers everything needed: what it does, who calls it, and why it should not be used by the LLM. Nothing essential is missing.

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

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

Schema description coverage is 100%, so the schema fully documents query, mode, and limit. The description adds no parameter-level meaning beyond what the input schema already provides, matching the baseline for high 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: 'Search the vault'. The qualifier '(app-only)' and the caller context distinguish it from sibling search-like tools such as 'search', 'vault_read', and 'browse_vault', making selection unambiguous.

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

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

Explicitly names the sole caller: 'Called by the SPA browser search bar via app.callServerTool()'. It also gives a clear when-not condition with 'Not visible to the LLM', so an agent knows this tool is not intended for LLM selection.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds important behavioral context: it warns that the entire file is replaced, explains that the index refresh is queued (no reindex needed), and notes that 'content' and 'frontmatter' are ignored for attachments. It also discloses the base64 token cost. This goes beyond the annotations and provides meaningful behavioral transparency.

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

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

The description is well-structured with clear sections for .md documents and attachments. It front-loads the core purpose, then provides conditional details. Every sentence adds value: the warning about file replacement, the index refresh note, the base64 cost warning, and the parent directory behavior. 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?

The description is complete for a write tool with an output schema. It covers the two main use cases (markdown and attachments), explains the overwrite behavior, the etag requirement (via schema), the index refresh behavior, and the base64 cost. The output schema exists, so return values don't need to be described. Nothing critical is missing for an agent to call this correctly.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds value by explaining the relationship between parameters (e.g., 'content' vs 'content_base64' based on file extension, 'frontmatter' ignored for attachments) and by warning about the base64 token inflation. This is more than the schema alone provides, though the schema already does 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?

The description clearly states the tool's function: 'Create or overwrite a document or attachment.' It distinguishes between .md documents and attachments, and explicitly names the sibling 'edit' for targeted changes, which differentiates it from the write operation. The verb 'write' plus the resource types (document/attachment) makes the purpose unambiguous.

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

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

The description provides explicit usage guidance: it says to use 'edit' for targeted changes, and explains when 'content' vs 'content_base64' is used. It also notes that parent directories are created automatically, which is a useful prerequisite. This is clear context for when to use this tool vs alternatives.

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