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

Annotations only convey basic hints, so the description carries the burden and succeeds. It discloses the automatic newline insertion behavior, the immediate index update, the unconditional behavior when if_match is omitted, and the failing-loudly behavior for missing files by default.

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 the deciding factor (no read needed). Every sentence adds practical value—newline behavior, index updates, and avoid-reindex guidance—without redundancy or filler.

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

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

Given the rich output schema and fully covered input schema, the description is complete. It answers the key operational questions an agent needs: when to use it, what happens to formatting, concurrency behavior, missing-file behavior, and post-call indexing.

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 meaningful behavior beyond the schema: how newlines are handled, that leading blank lines/heading markers are the caller's responsibility, and that a typo in path fails loudly rather than creating a note. This elevates it above the baseline.

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

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

The description states a specific action (append text) on a specific resource (an existing .md note) with a precise location (end of the note). It also explicitly distinguishes itself from 'edit' by noting that no prior read is needed, 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 gives clear when-to-use guidance: use for purely additive at-end changes, prefer over 'edit' because it avoids loading the note into context. It also explicitly says not to call 'reindex' afterward, and explains the tradeoff of create_if_missing 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 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 annotations (destructiveHint=true, readOnlyHint=false, idempotentHint=true), the description discloses critical behavior: irreversibility unless git history exists, immediate search-index updates for .md files, and no index update for attachments. This adds substantial context about side effects and recovery options. No contradiction with annotations exists.

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

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

The description is four compact sentences: first states the action and object, then differentiates .md behavior from attachments, then gives irreversibility and confirmation warnings. No filler or repetition; the most important warning is placed last for emphasis.

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 an output schema, the description covers what is deleted, index implications, what not to do afterward, irreversibility, and a user-confirmation requirement. Nothing essential is missing for an agent to invoke this tool safely and 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 path and if_match are already fully documented in the input schema. The description adds only user-confirmation guidance about the path, which is more of a usage rule than parameter semantics. Baseline 3 is appropriate when structured schema handles parameter 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: 'Permanently delete a document or attachment.' This clearly distinguishes it from sibling tools like read, write, edit, append, and rename by naming the destructive action and the object types. The title 'Delete Note' further reinforces the tool's 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 gives explicit usage guidance: after deleting .md files, 'do not call reindex afterward' — an instruction that prevents an unnecessary follow-up action. It also states a precondition that the path must be confirmed with the user before calling. It does not explicitly name alternative tools, but the destructive-purpose distinction is clear among the sibling list.

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

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

Annotations only state readOnly=false, idempotent=false, destructive=false. The description adds substantial behavioral context beyond this: frontmatter is editable, line numbers are 1-based, normalized Unicode/comparison fallback may apply, match_type='normalized' can be returned, if_match provides optimistic concurrency, and the search index updates immediately. This is exactly the kind of operational detail an agent needs to avoid surprising edits.

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 detailed but efficiently structured: a one-sentence summary, a compact bulleted mode list, a normalization note, and workflow guidance. Every section earns its place, and the most important scoping information is front-loaded. Nothing is redundant with the schema or annotations.

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

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

Given six parameters, three modes, normalization behavior, and concurrency control, the description is remarkably complete. It tells the agent how to select modes, how to prepare with 'read', how to stay safe with if_match, and what to expect regarding index updates. An output schema exists, so it is acceptable that return details are not spelled out in the description.

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 real value by organizing old_text, line_start, line_end, and new_text into three named modes and explaining valid combinations, uniqueness constraints, and safety recommendations. It does not merely restate the schema; it clarifies how the parameters interact, which is meaningful beyond the property-level 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: 'Make a targeted text replacement in an existing .md note.' It clearly distinguishes this from sibling tools by noting it applies to existing notes, not attachments, and by defining three concrete replacement modes. An agent can immediately tell this is the in-place modification tool rather than write, append, or delete.

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: exact match when text appears once, line-range for replacing by line numbers, and scoped match when old_text appears multiple times. It also says to call 'read' first and not to call 'reindex.' However, it does not explicitly contrast this tool with write/append/delete for creation or additive changes, so the broader sibling-tool selection guidance is slightly implicit.

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, so the agent knows it's a safe read. The description adds behavioral context: it checks configuration and status, and details the return fields (available, provider, chunk_count, path). 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 two paragraphs: first paragraph focuses on usage guidance, second lists return fields. It is front-loaded with the main purpose, and every sentence provides necessary information. No redundant or vague statements.

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 tool with an output schema, the description fully explains the return fields and their semantic meaning. It covers the diagnostic use case and provides actionable guidance. It is complete for the tool's purpose.

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

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

There are no parameters, so the baseline is 4. The description adds value by explaining the output fields and their interpretation, which goes beyond the input schema (empty).

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 starts with a clear verb and resource: 'Check the embedding provider configuration and vector index status.' It also specifies the use case: 'diagnose why semantic search is unavailable.' This distinguishes it from sibling tools like build_embeddings.

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

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

The description explicitly states when to use this tool ('to diagnose why semantic search is unavailable') and provides guidance on interpreting the chunk_count field relative to the FTS chunk count from 'stats'. It also directs to call 'build_embeddings' (without force) if chunk_count is lower, and specifies when to use force=True. This provides clear when-to-use and when-not-to-use 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?

Beyond the annotations, the description discloses key behavioral traits: the download happens server-side so the bytes cost zero context, the search index is updated immediately for .md files, and non-.md files are saved as binary attachments subject to the existing size limit. It also clarifies that after a successful fetch the agent should use the returned path rather than expecting content in the response, which is genuinely useful behavior not covered by 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 front-loaded with purpose, then moves to context cost, then to path-specific behavior, with each sentence earning its place. It is detailed but not redundant, and the use of short labeled paragraphs makes it easy for an agent 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 5-parameter schema with 100% coverage, the annotations, and the presence of an output schema, the description is complete: it covers the intended use case, when not to use read, how path determines handling, the zero-context-cost property, and the attached security-relevant redirect behavior in the URL parameter. 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?

The schema already covers all parameters at 100% with detailed descriptions, so the baseline is 3. The tool description adds extra semantic value by explaining how the path extension changes the behavior (.md becomes UTF-8 markdown with frontmatter, other paths become binary attachments) and by clarifying the practical meaning of the path parameter in the post-fetch workflow.

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-resource pair, 'Download a file from a URL and save it to the vault,' and immediately clarifies scope: HTTP/HTTPS URLs, saved as a note or attachment. This clearly differentiates it from sibling file-writing tools like write and edit, whose input would be literal content rather than a remote URL.

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

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

The description explicitly states when to use this tool: for MCP-to-MCP file transfer when content is too large to pass through the LLM context window. It also gives post-fetch guidance, telling the agent to reference the file by path and to only call read(path) for small results, which is actionable and distinguishes the intended workflow from plain read/write usage.

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, covering the safety profile. The description adds meaningful behavioral context by explaining that the tool returns the set of documents linking to the target and frames backlinks as implicit relationships. It does not contradict 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 front-loaded with the core action and uses short, purposeful sentences. The final conceptual sentence about implicit relationships is slightly extra but helps the agent understand when the tool is valuable; overall it is efficient and well organized.

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

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

For a read-only tool with rich annotations, a fully documented 3-parameter schema, and an output schema, the description is complete. It covers purpose, usage context, alternatives, and direct-call conditions without leaving operational 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%, so the schema already fully documents path, limit, and wait_for_pending_writes. The description does not add parameter-level detail beyond naming the 'given document' and 'inbound link list,' 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 a specific verb and resource: 'Find all documents that link TO the given document (backlinks).' It clearly distinguishes the tool from siblings by naming get_context and contrasting backlinks with the broader context set.

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 call this tool directly versus using get_context: 'For a full picture... use get_context instead... Call get_backlinks directly when you only need the inbound link list.' It also contrasts with search, explaining why backlinks add value search cannot.

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 useful domain context by explaining what a broken link means ('target path does not match any indexed document'), but it does not disclose additional behavioral details such as indexing freshness, rate limits, or output structure. This is adequate but not exceptional given 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 front-loaded with the core purpose, followed by clear usage guidance and a concise definition of a broken link. Every sentence contributes useful information, 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?

With detailed parameter schemas, a present output schema, and annotations covering safety, the description adds the remaining important context: when to call it and what a broken link semantically means. There is no critical missing information for an agent to select and invoke this tool correctly.

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

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

Schema description coverage is 100%, and both parameters have detailed descriptions, including the wait_for_pending_writes behavior and index staleness handling. The tool description itself adds no new parameter semantics, so it relies on the schema, which already 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 states a specific verb and resource: 'Find all links that point to non-existent documents (broken links).' This clearly identifies what the tool returns and is distinct from related link tools like get_backlinks, get_outlinks, and get_orphan_notes, even without naming them.

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

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

The description gives explicit trigger conditions: 'Call this when stats shows broken_link_count > 0, or after a rename that did not use update_links=True.' It provides clear context for when the tool is appropriate, though it does not explicitly state when not to use it or name 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?

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the mutation safety profile. The description adds meaningful behavioral detail beyond that: links are treated as undirected, the search uses BFS, and max_depth is clamped to [1, 10]. This gives the agent a solid model of how the search behaves.

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 adds algorithmic behavior, and the third provides a helpful use-case metaphor. Every sentence earns its place without redundancy or padding.

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

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

Given the annotations, fully documented parameters, and the presence of an output schema, the description covers the essential aspects: purpose, algorithm, edge-case clamping, and illustrative use case. It could be slightly stronger with explicit guidance on when to prefer it over direct-link tools, but nothing critical is missing 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 baseline is 3. The description adds extra semantic value by explaining the BFS algorithm and that max_depth is clamped to [1, 10], which is more specific than the schema's 'max 10' note. Source and target are already well 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?

The description opens with a specific verb and resource: 'Find the shortest connection path between two notes in the link graph.' This clearly distinguishes the tool from graph-related siblings like get_similar, get_backlinks, and get_outlinks by emphasizing shortest path between two notes rather than listing links or similar notes.

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: 'Useful for discovering how two seemingly unrelated notes are connected through the vault's link structure.' This tells the agent when to reach for this tool, though it does not explicitly mention alternatives or state when not to use it.

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

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

Annotations already establish readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds behavioral context by clarifying that this tool aggregates multiple lookups into one response and explicitly lists the categories of information returned, which goes beyond the annotations and helps the agent predict the tool's behavior.

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

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

The description is well-structured, leading with the core purpose, then the relationship to siblings, then the concrete return contents. There is minor redundancy between "Replaces separate calls..." and "Use this instead of making 4-5 separate tool calls...," but the information density is high and each sentence adds relevant 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?

The description is complete for an agent's decision-making: it states what the tool returns, when to use it instead of alternatives, and the exact scope of the 'context' it provides. The input schema and output schema cover parameter details and return structure, so nothing essential is missing.

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

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

Schema description coverage is 100%, so each parameter is already well-documented in the input schema. The description itself adds no parameter-level detail beyond the schema, which matches the baseline expectation of 3 when the schema carries the explanatory burden.

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: it "gets a consolidated context dossier for a document" and then enumerates exactly what that dossier contains (metadata, backlinks, outlinks, similar notes, same-folder notes, frontmatter tags). It also names the sibling tools it replaces, so an agent can distinguish it from get_backlinks, get_outlinks, and get_similar without opening their schemas.

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

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

The description gives explicit guidance: use get_context instead of making 4-5 separate calls when you need a full picture, and use it instead of get_backlinks, get_outlinks, and get_similar when more than one is needed. This directly tells the agent when to choose this tool over its siblings and when the consolidated call is appropriate.

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

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

Annotations already 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?

The description goes beyond annotations (readOnlyHint=true) to disclose critical behavioral details: the error field may be populated even when status is 'queryable' and is always None during 'building'. This helps the agent correctly interpret responses, especially edge cases.

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 somewhat lengthy but well-structured with a bullet list for return fields. Every sentence adds value, but it could be slightly more concise without losing clarity. Nonetheless, it effectively communicates the necessary 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 zero parameters and the presence of an output schema (described thoroughly), the description is complete. It covers all return fields, their types, possible values, and edge cases (e.g., documents_indexed vs documents_indexed_error). No gaps remain.

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 parameter semantics dimension gets a baseline score of 4. The description adds no parameter information because none is needed, and the schema coverage is vacuously 100%.

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: 'Return background-build state of the FTS index.' This is a specific verb-resource combination, and it distinguishes itself from sibling tools like embeddings_status or build_embeddings which deal with different indexes.

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 when initialize returned but bucket-3/4 calls block longer than expected or surface IndexUnavailableError.' It also explains what the status and error fields indicate, aiding correct invocation. It lacks explicit when-not-to-use or alternatives, but the context is sufficiently 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 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, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds the ranking-by-backlink-count behavior but does not add further behavioral context such as tie-breaking, self-link handling, or index freshness; the latter is addressed in the schema.

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

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

The description is concise, front-loads the primary behavior, includes a concrete use case, and ends with a clear pointer to an alternative. No sentence is wasted.

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

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

The tool is a simple read-only query, annotations cover safety, the schema covers all parameters, an output schema exists, and the description adds use-case and sibling context. Nothing important is missing for correct selection and 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 fully documents both limit and wait_for_pending_writes. The description does not need to add parameter details, and 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 clearly states the operation: return the documents with the most inbound links ranked by backlink count. It also explicitly distinguishes itself from the sibling tool get_backlinks, making the tool's unique role easy to identify.

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 this tool ('discovering hub notes') and explicitly points to get_backlinks for the alternative case of finding documents that link to a particular note. This gives an agent actionable routing guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds important behavioral context beyond this: it warns that the tool 'returns ALL orphans with no limit' and advises checking orphan_count first. This is exactly the kind of unbounded-result warning that annotations do not convey.

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

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

The description is compact and front-loaded: the core behavior is stated immediately, followed by the high-value warning, then the precise definition and usage trigger. Every sentence serves a purpose, and there is 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?

With annotations covering safety, a fully documented optional parameter, an output schema present, and a description that includes the semantics of orphan notes plus a scalability warning, all information an agent needs to select and invoke this tool correctly is present.

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

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

Schema description coverage is 100%, and the single parameter wait_for_pending_writes is already thoroughly documented in the schema. The tool description adds no additional parameter-level guidance, but it does not need to because the schema carries the full burden.

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

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

The description states a specific verb and resource: 'Return all notes with no inbound or outbound links.' This clearly distinguishes it from sibling tools like get_backlinks or get_outlinks, which return link data for specific notes rather than orphan detection.

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

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

The description gives a concrete trigger condition: 'Call this when stats shows orphan_count > 0.' It also warns to check stats before calling on large vaults, which is useful usage guidance. It does not explicitly name alternative tools or when not to use it, but the 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, covering the safety profile. The description adds extra behavioral context beyond annotations by explaining the 'exists' flag and that False means a broken link to a missing target, which is useful and non-obvious.

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

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

The description is compact and front-loaded. It opens with the core action, then adds usage routing, then gives one crucial output-behavior note. Every sentence earns its place and there is no repetition or filler.

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

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

Given the tool's read-only nature, the rich input schema, and the presence of an output schema, the description is complete enough. It covers purpose, when to use it, the main alternative, and a key semantic detail about broken links, so an agent can confidently select and invoke 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 description coverage is 100%, and the input schema already provides detailed meaning for all three parameters: path, limit, and wait_for_pending_writes. The description does not add parameter-level detail, but with full schema coverage 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 uses a specific verb and resource: 'Find all links FROM the given document to other documents (outlinks).' It clearly distinguishes the tool from siblings like get_context by defining outlinks as the outbound link list, and it states the directionality of the links.

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

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

It explicitly tells the agent when to use this tool vs. an alternative: '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 is clear routing guidance with a named alternative and a condition.

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 the read-only, idempotent, non-destructive profile. The description adds the useful behavioral detail that results are sorted by file modification time, most recent first, and clarifies it surfaces recently changed content. It does not discuss index lag or error conditions, but the wait_for_pending_writes parameter schema addresses consistency, so the additional context is sufficient.

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 tightly written sentences, with the core operation in the first sentence, ordering semantics in the second, and concrete use cases in the third. 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?

With a comprehensive schema and an output schema, the description provides the remaining orienting context: scope is notes, ordering is by modification time, and no search query is needed. That is complete for selecting and invoking the tool. Minor absence of explicit alternative-routing is already accounted for under usage guidelines.

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 is fully self-descriptive (100% coverage), including defaults for limit, folder semantics including empty-string root behavior, and an extensive explanation of wait_for_pending_writes. The tool description itself adds no parameter-level guidance, so the baseline 3 applies.

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

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

Description leads with a clear verb+object: 'Get the most recently modified notes in the vault' and specifies ordering by file modification time. It distinguishes itself from search via 'without a search query' but does not name sibling tools such as list_documents, so it doesn't fully capitalize on 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 states when it is useful ('summarize recent activity', 'resume work on recently edited notes') and contrasts with a search query. However, it does not explicitly say when not to use it or point to an alternative tool by name, 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. 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?

Beyond the readOnly/idempotent annotations, the description discloses meaningful behavior: no re-embedding is performed, the reference document is excluded, and an empty list is returned in specific unconfigured or missing-vector cases. It also points to a remediation path via build_embeddings.

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 every subsequent sentence adds actionable detail: no re-embedding, exclusion behavior, configuration prerequisites, and failure-mode handling. There is no repetition or filler.

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

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

Given the detailed input schema, output schema, and readOnly/idempotent annotations, the description covers the key operational context an agent needs: when the tool works, when it returns empty, and how to make it work via build_embeddings. Nothing essential 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 parameters thoroughly. The tool description adds some context around the path parameter (reference excluded, missing vectors) but does not need to compensate for any parameter documentation gaps.

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 'Find notes most semantically similar to the given document,' which names a specific action, resource, and comparison basis. It clearly distinguishes this from sibling tools like 'search' by emphasizing semantic similarity via stored embeddings.

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 usage context: semantic search must be configured, embeddings_status should be checked, and build_embeddings should be called when vectors are missing. It does not explicitly route to an alternative tool such as 'search' for keyword or non-semantic use, but the conditions are clear enough.

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 non-destructive behavior, so the bar for added context is lower. The description adds valuable behavioral detail: synthetic H1 in note mode, aggregation and truncation in folder mode, and the parallel to the 'toc://vault/{path}' resource. 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, then branches into clear note vs. folder behavior. Every sentence contributes meaning, and the resource cross-reference is useful without being verbose.

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

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

With a rich input schema, annotations, and an output schema present, the description covers the remaining conceptual context: the two path modes, aggregation semantics, and truncation behavior. There are no significant gaps an agent would need to resolve elsewhere.

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

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

Schema description coverage is 100%, so the schema already explains all four parameters in detail. The description adds only a high-level pointer to the max_level/max_notes controls and the path-mode distinction, which does not materially exceed what the schema provides.

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

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

The description names the exact resource ('heading outline') and clearly distinguishes the two operating modes: single note ('.md' path) vs. folder subtree. It also states the return shape for both cases, which makes the tool's purpose unambiguous even among many sibling tools.

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

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

The description gives clear context for when to use the tool: you supply a note path or folder prefix and get a heading outline. It does not explicitly name alternatives or exclusion criteria, but the behavior is specific enough that an agent can infer when it is the right choice.

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

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

Annotations already establish read-only/idempotent behavior, and the description adds the key behavioral constraint 'Does NOT include body content' and the optional-attachments behavior. This is useful beyond the annotations and prevents the agent from expecting full note text.

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

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

Three short sentences: the first states the action/scope, the second gives usage context, and the third states an important exclusion with a pointer to the alternative. 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?

Given the rich input schema, output schema, and annotations, the description fully covers what the tool does, when to use it instead of search/read, and what it deliberately omits. Nothing needed for correct invocation is missing.

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

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

Schema description coverage is 100%, with detailed parameter descriptions in the schema itself. The tool description adds little beyond the phrase 'optionally attachments,' 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?

Description opens with a specific verb and resource: 'List documents (and optionally attachments) in the vault.' It also distinguishes from siblings by explicitly contrasting with 'search' (ranked content search) and 'read' (body content), so an agent can select it without 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?

Provides explicit when-to-use guidance: use for a 'complete listing, not ranked search results,' and names the alternatives 'search' for content and 'read' for full text. This directly routes the agent to the correct sibling 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 non-destructive behavior. The description adds useful non-obvious detail beyond annotations, especially that the root folder is represented as an empty string. It does not contradict 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 short, front-loaded with the action, and every sentence adds value: it states what is listed, why/when to call it, and the non-obvious root-folder convention. There is no redundant restatement of the schema or annotations.

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

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

For a simple read-only tool with one fully documented optional parameter and an output schema, the description supplies the key missing semantics: folder names are discoverable pre-filter values and the root folder is an empty string. No additional context is needed for correct selection and invocation.

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

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

Schema description coverage is 100%, and the wait_for_pending_writes parameter is already thoroughly documented in the schema. The description does not need to repeat parameter details, so the 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 states a specific verb and resource: 'List all folder paths that contain documents.' It also distinguishes this tool from sibling list operations by clarifying that these are folder names meant for filtering search/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?

The description explicitly instructs when to use the tool: before filtering search or list_documents by folder. It does not enumerate when not to use it or fully compare against list_tags, but the intended call context is clear and 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 declare readOnlyHint, idempotentHint, and destructiveHint false, covering the safety profile. The description adds meaningful behavioral context beyond that: unsupported fields silently return an empty list rather than an error, which the agent must know to interpret results correctly.

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

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

The description is tight and front-loaded: purpose in the first sentence, usage guidance in the second, and the key indexed-field caveat in the third. Every sentence earns its place and there is no redundant phrasing.

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

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

For a simple optional-parameter read tool with an output schema and safety annotations, the description covers the decision-relevant information: what it does, when to use it, and the non-obvious failure mode for invalid fields. It also points to stats for the authoritative list of valid fields.

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

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

Schema description coverage is 100%, with detailed parameter descriptions for both field and wait_for_pending_writes. The description reinforces the purpose of field as a filter-discovery mechanism but does not add semantic detail beyond what the schema already provides, 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 'List all distinct values for a frontmatter field across the vault,' naming a concrete operation, resource, and scope. It clearly distinguishes this tool from sibling list tools by focusing on frontmatter field enumeration rather than documents or folders.

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 gives a critical constraint by directing the agent to stats for indexed_frontmatter_fields and warning that non-indexed fields return an empty 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 annotations, the description discloses atomicity at the gate, best-effort link rewrites with failed_links reporting, and the real possibility of a partially moved subtree with an unchanged index on OS errors. This is rich, honest behavioral disclosure that materially helps an agent anticipate side effects.

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

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

The description is front-loaded with the core definition and then adds progressively deeper detail in a logical order. Every sentence carries necessary information about behavior, failure modes, or index handling; there is no filler.

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

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

For a destructive, non-idempotent folder operation, the description covers the critical operational concerns: atomicity, link rewriting success/failure, index update timing, and partial-move recovery. The presence of an output schema covers return-value details, so nothing essential is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema: new_dir may be an existing folder with merging, and a per-file name clash aborts the whole move. This extra context justifies a 4.

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

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

The description states a specific verb and resource: moving an entire folder subtree to a new location in one call, and explicitly frames it as the 'folder-level analogue of rename,' distinguishing it from the sibling rename tool. The scope (all files under old_dir, links rewritten, structure preserved) is clear.

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

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

The description gives explicit usage context: it is the folder-level equivalent of rename, and it warns not to call reindex afterward because the index is updated immediately. It also instructs to call reindex after a partial OS failure, which is concrete when-to-use 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 adds substantial behavioral detail beyond the annotations: writes go through the normal write path, git commit occurs if configured, re-running is safe, resolvability determines conversion, and the link graph is preserved exactly. This gives an agent a clear model of side effects and safety considerations, complementing the destructiveHint and idempotentHint 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, front-loaded with the primary action, and every subsequent sentence adds meaningful information about behavior, edge cases, or safety. There is no filler or repetition that detracts from its usefulness.

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 rich description, an output schema, and annotations covering mutability and idempotency. The description covers the main action, scope, exceptions, side effects, re-run behavior, and link-graph preservation, leaving no material gap for an agent to select and invoke the tool correctly.

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

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

The single parameter 'folder' is fully described in the schema with default and behavior (restrict to folder subtree, omit for whole vault). The description reiterates the 'vault or folder' scope but does not add new parameter-level semantics beyond what the schema already provides, so the 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 states a specific action ('Rewrite wikilinks as OKF bundle-root-absolute markdown links') and identifies the exact resource (resolvable wikilinks in the vault or a folder). It clearly differentiates this migration tool from siblings like okf_validate and okf_generate_index by describing its unique transformation purpose.

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

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

The description clearly establishes when to use the tool: during an OKF migration to convert wikilinks to markdown links. It also specifies constraints on usage, such as only converting indexed targets and leaving unresolvable links untouched. It does not explicitly name alternative tools, but the context is strong enough to make the intended use 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?

The description goes well beyond the annotations by disclosing that it 'writes (or overwrites) the folder's index.md', preserves existing frontmatter, and omits reserved files like index.md and log.md. It also specifies the listing format and that descriptions come from frontmatter, giving a complete picture of the tool's side effects consistent with destructiveHint and idempotentHint.

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 then adds precisely targeted details: output format, data source, overwrite behavior, frontmatter preservation, and omitted files. Every sentence earns its place; there is no fluff or repetition.

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

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

With only one optional parameter, full schema coverage, an output schema, and annotations covering idempotence and destructiveness, the description supplies the remaining essential context: what gets overwritten, what is preserved, and what is excluded. The 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?

The input schema already describes the only parameter (`folder`) completely, including its meaning and default behavior. The tool description adds context about 'bundle-root' but does not materially expand parameter semantics. Baseline 3 is appropriate given 100% schema description 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 opens with a specific verb and resource: 'Generate a reserved OKF index.md listing from the table of contents.' It then details the exact output format and source, making the tool's purpose unmistakable and distinguishing it from sibling tools like get_index_status or okf_validate.

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

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

The description implies when to use the tool—when you need to generate or regenerate an OKF index.md—but it does not explicitly state when to prefer it over alternatives such as write, reindex, or get_index_status. No exclusions or alternate routing are provided, so the usage context is clear but not fully 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?

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 readOnly/idempotent/non-destructive, and the description adds substantial context: reads from disk, respects exclude patterns, reports degrees rather than verdicts, and exempts reserved files. This goes well beyond the structured annotation 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 long but every section earns its place: purpose, usage timing, severity taxonomy, and exact return keys. It front-loads core behavior and organizes the detailed enumeration clearly.

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 audit tool with rich output, the description fully covers detection semantics, severity rules, exclusions, and the exact report structure. The presence of an output schema plus this description leaves no ambiguity about what the agent will receive.

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

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

The tool takes zero parameters, so there is nothing to document and the empty schema is fully covered. The detailed return-format description is valuable but belongs to contextual completeness rather than parameter semantics, so the baseline of 4 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 ('Audit') and resource ('vault's OKF conformance'), and distinguishes itself from sibling okf_* tools by focusing on conformance reporting rather than conversion, index generation, or log seeding. The description clearly defines what validation means in this 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?

Explicitly frames the tool as a migration progress meter and notes it works before the index is built or okf_version is declared, giving clear conditions for use. It does not name sibling alternatives or exclusions, but the context is unambiguous and sufficient for a zero-parameter 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=true and destructiveHint=false, indicating safe read-only operation. The description adds valuable behavioral context: context cost limits and ValueError for large reads, which is not covered by annotations. No contradiction.

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

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

The description is well-structured with bullet points and clear sections, front-loading the main purpose. However, it is somewhat lengthy; the context cost paragraph could be more concise. Still, it effectively communicates key information without excessive 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 complexity (different handling for .md vs attachments, section parameter, size limits, path discovery), the description covers all essential aspects: behavior, error conditions, context cost, and prerequisite steps. The presence of an output schema does not reduce the need for this clarity; the description enhances 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%, so baseline is 3. The description adds meaning beyond schema, especially for the 'section' parameter, explaining its matching behavior and how to use search results. It also reinforces case-sensitivity for path.

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

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

The description clearly states the tool reads full content of documents or attachments by path, and distinguishes between .md documents (returning content, frontmatter, title, folder) and attachments (returning base64 and MIME type). This specificity and resource differentiation make it highly clear.

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

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

The description explicitly instructs not to guess paths but to use 'search' or 'list_documents' first, and explains when to use the 'section' parameter. While it does not exhaustively list alternatives, it provides sufficient context for when to use this tool versus siblings like 'search'.

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

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

The description adds substantial behavioral detail beyond the annotations: hash-based change detection, background execution with job_id, index unavailability during force rebuilds, and the relationship with embedding convergence. It also clarifies that force=True is a 'manual escape hatch, not routine maintenance,' which is exactly the kind of judgment context an agent needs. No contradiction with 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 long but every sentence carries operational weight. It front-loads the core purpose immediately and organizes the rest by when-to-use, when-not-to-use, force semantics, follow-up actions, and response behavior. Nothing feels redundant or promotional.

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 one optional parameter, the description fully covers the common path, the force edge case, background job behavior, and how to retrieve results. It also explains the relationship to get_index_status and build_embeddings, so an agent can handle the complete workflow without guessing.

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

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

Although the schema already documents the force parameter at 100% coverage, the description goes further by explaining the trade-offs of force=True: it drops every indexed document, re-parses the whole vault, makes the index unqueryable during the rebuild, and scales cost with vault size. It also tells the agent to follow force=True with build_embeddings in semantic-search setups. This adds real decision-making value 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 opens with a specific verb and resource: 'Run an incremental reindex on the writer thread.' It clearly distinguishes reindex from sibling tools like build_embeddings and get_index_status by explaining what reindex does versus what those tools handle. Even without knowing the siblings, an agent understands this is an index-refresh operation.

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 reindex is needed ('files modified outside this server') and when it is not ('Do NOT call this after using write, edit, delete, or rename'). It also routes the agent to alternatives: build_embeddings for embedding rebuilds, get_job_result for background outcomes, and get_index_status for observability. This is exceptional 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?

With annotations only saying readOnlyHint=false, idempotentHint=false, and destructiveHint=false, the description carries the behavioral burden and does so thoroughly. It discloses immediate index updates for .md files, no index update for attachments, automatic parent directory creation, best-effort link rewriting, and the broken-link risk when update_links is omitted.

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 structured with a clear opening, a prominent warning about update_links, then labeled .md and attachment behavior. Every sentence carries actionable information, and the most important usage rule is front-loaded.

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

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

The tool has four parameters and non-trivial side effects (link rewriting, index updates, directory creation), and the description covers all of these without needing to explain return values since an output schema exists. It is complete enough for an agent to call this tool correctly and avoid common mistakes.

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, but the description adds meaningful parameter context beyond the schema: parent directories are created automatically for new_path, .md files get index updates immediately, and attachments do not. This helps the agent reason about the consequences of the parameters, not just their types.

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: 'Rename or move a document or attachment.' It clearly distinguishes the tool from siblings like write/edit (content changes) and move_folder (folders) by restricting scope to documents and attachments.

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: always set update_links=True for .md notes, and it explicitly says not to call reindex afterward. It does not explicitly compare against move_folder or write, but the .md vs. attachment distinction and the reindex exclusion provide clear usage 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?

Goes beyond the readOnly/idempotent/destructive annotations by revealing important runtime behavior: the default mode automatically adapts based on whether embeddings are configured, and the 'content' field returns snippets rather than full documents. This is genuinely useful behavioral context that 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 compact and well-structured: purpose first, then mode-selection guidance, then a critical output caveat. Every sentence earns its place, and the most actionable decision logic 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 search tool with 8 parameters, a dedicated output schema, and rich schema-level parameter documentation, the description covers the essential non-obvious context: mode fallback behavior, snippet semantics, and when to delegate to 'read'. Nothing an agent needs to select or invoke the tool 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 coverage is 100% and each parameter already has a rich description, so the baseline is 3. The description adds value by condensing the mode decision logic into clear heuristics ('hybrid when embeddings are configured, keyword when they are not') and by explaining why keyword can beat fusion for exact-term queries. That goes slightly beyond the schema without duplicating 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?

Opens with a specific verb and resource: 'Find documents matching a query using full-text or semantic search.' This clearly identifies the tool's function and immediately distinguishes it from read-focused siblings. It also names the vault as the scope and the query as the primary input.

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 mode-selection guidance: omit 'mode' for the best automatic option, pass keyword for exact terms/operators/filenames, and pass semantic for pure vector similarity. It also tells the agent when to use the sibling tool 'read' instead — when full section content is needed rather than snippets.

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 establish readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful behavioral context by pointing to the semantic_search_available field and how it affects search mode choices, which helps the agent interpret the response. No contradiction exists.

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

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

The description is compact and front-loaded: the first sentence states the purpose, the second gives a concrete usage recommendation, and the third highlights a key response field. Every sentence earns its place with no filler.

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

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

For a simple read-only stats tool, the description is complete: it explains when to call it, what it returns at a high level, and which field drives search-mode decisions. The detailed parameter schema and presence of an output schema cover the remaining invocation needs.

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 description coverage is 100% and the wait_for_pending_writes parameter is fully explained in the schema. The tool description does not add parameter-level meaning beyond the schema, which matches the baseline for full coverage.

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

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

The description states a specific verb and resource: 'Get an overview of the vault's size, capabilities, and configuration.' This clearly distinguishes the tool as a vault-level stats endpoint, but it does not explicitly contrast it with related siblings 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 gives explicit guidance to call this tool 'at the start of a session' to understand vault contents and available search modes. It does not provide exclusions or when-not-to-use guidance, but the recommended usage context is clear and actionable.

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

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

The description warns 'replaces the entire file', which is a destructive overwrite behavior, while the annotations declare destructiveHint=false. This is a direct contradiction: an agent relying on annotations could wrongly assume the operation is non-destructive. Despite useful disclosures like immediate index updates, the contradiction forces a score of 1.

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

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

The description is well-structured and front-loaded: the core purpose appears first, followed by clearly separated markdown and attachment branches. The warning and index-update note are valuable rather than filler. It is slightly long but every section 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 description covers the two main usage modes, the overwrite warning, index behavior, automatic parent directory creation, and the concurrency option via if_match. Since an output schema exists, return-value details are not required. A small gap is that it does not describe failure behavior when if_match conflicts, but overall the description is complete enough for successful 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 coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema by grouping parameters by file type: content/frontmatter for .md files, content_base64 for attachments, and explicitly noting that content and frontmatter are ignored for attachments. It also adds the base64 token-cost warning, which is helpful context not present 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?

The description opens with a specific verb and resource: 'Create or overwrite a document or attachment.' It clearly separates markdown documents from binary attachments and explicitly names the sibling alternative 'edit' for targeted changes, so an agent can distinguish write from edit/append/delete without opening schemas.

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

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

The description gives explicit when-to-use guidance: use 'edit' for targeted changes instead of write, and do not call 'reindex' afterward because the search index updates immediately. It also states that parent directories are created automatically, removing any need for a separate mkdir step.

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