mcp-vault-reader

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

The description provides no annotations and adds no behavioral details beyond the basic action. It does not disclose whether deletion is permanent, whether related backlinks or index entries are affected, or any error conditions.

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

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

A single, concise sentence that is front-loaded with the verb and object. No filler or redundant information, earning full marks.

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 one parameter, no output schema, and no annotations. The description is minimally viable but lacks safety-critical context for a destructive operation, such as irreversibility or side effects, which feels incomplete for the task.

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

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

The schema fully describes the 'path' parameter with a clear example, so the description adds no additional semantic value. Baseline of 3 applies since schema coverage is 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 uses the specific verb 'Deletes' with a clear object 'a note from the persistent memory vault'. It clearly distinguishes from sibling tools like memory_write_note (write) and memory_search (search), and the scope is unambiguous.

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

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

No guidance is provided on when to use this tool versus alternatives, or any exclusions or prerequisites. The description simply states the action without context, leaving the agent to infer usage from the name and sibling set.

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

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

With no annotations provided, the description carries the full burden of disclosing behavior. It does not state whether this is a read-only operation, what fields are returned, whether results are sorted, or how filters interact. The agent has no indication of the tool's safety or output format.

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

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

The description is a single, clear sentence with no redundant words. It front-loads the core action and mentions optional filters, earning its place efficiently.

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 no output schema and no annotations, so the description must explain what the response looks like and any behavioral nuances. It fails to mention return format, default limits, or how folder/tag filters combine. Given the presence of several similar sibling tools, this minimal description leaves important gaps for an agent to use 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 parameters are already well-documented. The description only reiterates that filters exist for folders and tags, adding no extra semantic value beyond the schema. It does not discuss the limit parameter or parameter combinations, 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 clearly states the tool lists notes from the persistent memory vault and mentions optional folder/tag filters. It names a specific verb and resource, making its function clear. However, it does not explicitly distinguish itself from similar sibling tools like memory_search or vault_list_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 provides no guidance on when to use this tool over alternatives such as memory_search or vault_list_notes. There is no mention of use cases or exclusions, leaving the agent to infer the appropriate context from the tool name and description.

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

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

With no annotations, the description carries the full burden. The verb 'Searches' implies a read-only operation, but it does not explicitly state that it has no side effects, nor does it describe return format, pagination, or behavior on empty results. The added context about persistent memory is useful but not comprehensive for a tool with no annotation safety net.

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 exactly two sentences: the first states the core function, the second provides practical usage context. Every sentence earns its place with no redundant or filler content. It is front-loaded with the action and resource.

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 4 parameters, no output schema, and moderate complexity. The description explains the overall purpose and typical use cases but does not describe return values, result ordering, or how parameters like tag and limit affect results. Given the absence of an output schema, slightly more detail would be warranted, but the core operation is simple enough that a 3 is fair.

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 has 100% description coverage for all four parameters, so the schema already documents each parameter. The description itself adds no additional parameter-specific meaning (e.g., how fuzzy matching works or the effect of limit). This matches the baseline of 3 for full 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 'Searches the persistent memory vault for stored knowledge,' specifying the verb and resource. It lists example content types (previous sessions, user preferences, project decisions), which clarifies scope. However, it does not explicitly differentiate from sibling tools like vault_search or memory_list, so it falls short of a 5.

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

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

The description provides clear usage context: 'Use this to recall information from previous sessions, user preferences, project decisions, and any previously stored context.' This tells the agent when to invoke the tool. It does not mention exclusions or alternatives, so it lacks the explicit when-not-to-use guidance 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?

No annotations are provided, so the description carries the full burden. It clearly discloses that the tool returns status/statistics and lists specific data points (enabled/disabled, note count, tag count, disk path). This is transparent for a read-only status operation; no side effects are implied or expected.

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

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

A single, well-structured sentence that packs all essential information. No wasted words, and the parenthetical list of returned fields improves clarity without verbosity.

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 no-parameter, no-output-schema tool, the description fully specifies what the tool returns and the key data categories. The complexity is low, and the description is complete enough for an agent to select and invoke it correctly.

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

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

The tool has zero parameters, and the baseline for no parameters is 4. The description adds no parameter-specific information because none exist, but also doesn't need to. Schema coverage is trivially 100% as there are no properties.

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 ('Returns') and clearly identifies the resource ('status and statistics of the persistent memory vault'), while listing concrete output fields. It distinguishes itself from sibling tools by focusing on vault health/statistics rather than search, read, write, or delete 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?

The description implies usage for checking vault status/statistics, which is clear context. It doesn't explicitly state when to use this tool instead of alternatives, but there is no direct alternative among siblings for purely status information, so this is sufficient.

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

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

No annotations are provided, so the description must disclose behavior. It mentions the persistent vault and cross-session storage, and implies mutation via 'creates or updates.' However, it does not describe what happens when an existing note is updated (overwrite vs merge), or whether the operation is reversible. This is a notable gap for a mutation tool without annotation safety hints.

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 sentences, front-loaded with the core action, followed by usage guidance and feature highlights. Every sentence adds value; there is no redundancy or fluff.

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

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

The description covers purpose, usage, and key features, and the schema thoroughly documents parameters. However, it lacks information about return values and precise update semantics, and there is no output schema or annotations to fill these gaps. For a write tool, this is acceptable but not fully complete.

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

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

Schema description coverage is 100%, with detailed descriptions for all 5 parameters. The tool description adds little beyond the schema; it repeats that content supports wikilinks and tags, which is already in the schema. Baseline of 3 applies as the schema does the heavy lifting.

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

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

The description clearly states the tool 'Creates or updates a markdown note in the persistent memory vault,' specifying the verb, resource, and scope. It distinguishes from siblings like memory_delete_note by focusing on write/update, and lists concrete use cases that add clarity.

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

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

The description explicitly says 'Use this to store knowledge, user preferences, project context, decisions, and any information worth remembering across sessions,' providing clear when-to-use context. It does not mention alternatives or exclusions, but the context is sufficient for typical use.

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

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

With no annotations, the description must carry the behavioral disclosure. It states the resolution outcome (actual note path) and gives format examples, but it doesn't explicitly mention read-only behavior, error handling when a link is invalid, or how response_format affects the output. The verb 'resolves' implies non-mutation but is not explicit.

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 entire description is a single focused sentence that front-loads the action and all essential information without 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 resolver with three required parameters and no output schema, the description adequately states what the tool does and what it returns (the note path). It doesn't discuss edge cases like unresolved links or the difference between text/json response formats, but these are secondary for a simple lookup 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?

The schema covers all parameters with descriptions (100% coverage), so the baseline is 3. The tool description adds an example with an alias ([[Note Target|Alias]]), which is not in the schema, but does not explain vault_name or response_format beyond what the schema already 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 uses the specific verb 'resolves' and clearly identifies the resource (Zettelkasten/Wikilink format) and the output (actual note path). It distinguishes itself from sibling tools like vault_read_note which reads content, and vault_get_backlinks which finds inbound 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 establishes clear context: use when you need to convert a wikilink in a source note into a concrete vault path. It doesn't explicitly name alternatives or exclusions, but the purpose is unambiguous enough that an agent can select it over related 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?

With no annotations provided, the description must carry the behavioral disclosure burden. It does convey that the operation is read-only via 'Retrieves' and signals the inclusion of 'local context around each link,' but it does not disclose any potential costs, limitations, or how the backlink graph is traversed. This is adequate but not rich.

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

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

The description is a single, well-structured sentence that front-loads the core action and immediately conveys the tool's purpose and return value. Every word contributes 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 simple read-only nature and a fully self-describing schema, the description is largely complete. It explains the return content (all linking notes plus local context), which is sufficient for most use cases. However, because there is no output schema, it could have mentioned the available response_format (text/json) to clarify expected output variants.

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 no parameter-specific semantics beyond what the schema already provides; it only refers to a generic 'specified note' and 'local context,' which does not enhance understanding of path, vault_name, or response_format.

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 a specific action ('Retrieves all notes that link to a specified note') and resource, with the parenthetical '(incoming links/backlinks)' reinforcing the exact scope. This distinguishes it from sibling tools like vault_get_related or vault_follow_link, which address different relationship types.

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

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

No explicit guidance is given on when to use this tool versus alternatives like vault_search or vault_get_related. The intended use is only implied by the tool name and the description's focus on backlinks, but the description does not state exclusions or mention any 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?

No annotations are present, so the description carries the burden. It discloses the date format support and optional filtering/limit behavior, but does not mention response format default, error cases, or explicitly confirm a read-only nature beyond the verb 'Retrieves'. Moderate disclosure for a simple retrieval tool.

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

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

The description is two sentences, front-loaded with the main action, and contains no filler. It efficiently communicates the core purpose and key options.

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

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

For a simple retrieval tool, the description covers the essential aspects: what it retrieves, optional date filter, limit, and date format. The schema handles the parameter details, and while no output schema exists, the description plus schema is sufficient for typical use. It does not explain return structure, but that is a minor gap for this complexity.

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

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

All four parameters have schema descriptions (100% coverage), so the description adds minimal semantics beyond the schema. It reinforces the date format and limit concepts but does not explain vault_name or response_format beyond what the schema already provides, warranting the baseline 3.

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

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

The description clearly states the verb 'Retrieves' and specifies the resource as 'daily/periodic notes', which distinguishes it from sibling tools like vault_read_note and vault_list_notes. It also notes optional date filtering and limiting, but lacks an explicit alternative comparison.

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

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

The description implies usage for fetching daily/periodic notes and mentions date filtering, but does not provide explicit when-to-use versus alternatives or exclusion criteria. It offers clear context but no exclusions, so it is not fully prescriptive.

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

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

With no annotations provided, the description carries the full burden. It only says 'retrieves the link graph' and mentions localization, which largely restates the schema. It does not disclose output format, graph representation, or any side effects/limitations beyond what the parameters indicate.

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

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

The description is two concise sentences with no redundant words. It front-loads the core purpose and then adds the localization detail efficiently.

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 graph retrieval tool with 5 parameters and no output schema or annotations, the description is too sparse. It does not explain what the link graph contains, how nodes/edges are represented, or how the response_format parameter affects output, leaving the agent with significant ambiguity.

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 covers 100% of parameters with descriptions, so a baseline of 3 is appropriate. The description adds minimal meaning beyond the schema, such as framing 'center' and 'depth' for graph traversal, but does not enrich parameter semantics further.

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

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

The description clearly states the tool retrieves the link graph of a vault, using the specific verb 'Retrieves' and a specific resource. It also mentions localization around a center note with depth, which differentiates it from sibling tools like vault_get_backlinks or vault_get_related.

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

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

The description implies usage for whole-vault or localized graph exploration via the center and depth parameters, but it does not explicitly compare with alternatives like vault_get_backlinks or vault_get_related. No when-not-to-use guidance is given.

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

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

With no annotations, the description carries full burden. It discloses the algorithmic basis (links, backlinks, tags) and ordering, but does not explicitly confirm read-only status, error behavior, or output structure. This is adequate but not rich.

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

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

The description is a single sentence with no filler or redundancy. It is front-loaded with the core purpose and every phrase adds value.

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

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

For moderate complexity, the description covers core functionality and ordering. However, since there is no output schema, it could have stated what the returned related notes look like (e.g., whether scores are included). Still, it is sufficiently complete for a read tool.

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

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

Schema description coverage is 100%, so all parameters are already documented. The tool description adds no extra meaning to the parameters, making the baseline of 3 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 ('Finds') and resource ('notes conceptually related to a given note'), with explicit criteria (direct links, backlinks, shared tags) and ordering by relationship score. This clearly distinguishes it from siblings like vault_get_backlinks and vault_search.

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

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

Provides clear context for use (finding conceptually related notes) and implicitly differentiates from more specific alternatives. However, it does not explicitly state when not to use it or name alternatives, so a full 5 is not warranted.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses that the tool retrieves tags and counts, implying a read-only operation, but does not mention response details, ordering, potential performance implications, or edge cases (e.g., empty vault). For a simple retrieval, this is adequate but not rich.

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

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

The description is a single concise sentence that front-loads the purpose and includes the key detail about counts. No wasted words or 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 small parameter count and no output schema, the description sufficiently conveys the tool's behavior and result. It states what is returned (tags and counts), which is the core need. It does not detail the response_format influence, but that is covered by the schema enum.

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 input schema already documents both parameters. The tool description adds no additional meaning beyond what the schema provides, which meets the baseline but does not exceed it.

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

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

The description uses the specific verb 'Retrieves' and clearly identifies the resource ('all unique tags in the vault') and the added value ('count of notes associated with each tag'). This clearly distinguishes it from sibling tools like vault_search or vault_read_note.

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

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

The description implies a use case (getting tags with counts) but provides no explicit guidance on when to use this tool over alternatives, nor any exclusions or prerequisites. Context from sibling names is present but not referenced.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It indicates a read-only listing operation but does not mention important behaviors such as default limit if no limit is specified, sorting order, exact match vs partial match for tags, or whether the return includes full note content or just metadata. This leaves agents uncertain about 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 a single sentence that is direct and information-dense. It front-loads the core purpose and mentions key optional filters without extraneous 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 tool has no output schema and no annotations, the description is insufficiently complete. It does not clarify what the returned list contains (note titles, paths, or content), whether vault_name must exist, or how filters combine. These are significant gaps for an agent to invoke the tool correctly without additional assumptions.

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 the parameters. The description adds little beyond paraphrasing the filter and limit parameters, and does not provide extra meaning such as default values, syntax examples, or parameter interactions.

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 a specific action (Lists notes) and a specific resource (in a specific vault), and mentions optional filters for subfolders, tags, and limit. This distinguishes it from sibling tools like vault_search (likely full-text search) and vault_read_note (read a single note).

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

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

The description implies usage for listing and filtering notes within a vault, but does not explicitly state when to use this tool versus alternatives like vault_search or vault_get_related. It provides context (filters, limit) but no explicit exclusions or 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?

With no annotations, the description carries the full burden. It discloses that the tool returns status, source, and size stats, implying a read-only list operation. However, it does not explicitly confirm non-destructive behavior, potential network calls for GitHub URLs, or response format nuances beyond the schema. The verb 'Lists' suggests safety, but deeper behavioral traits like performance or side effects are not addressed.

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

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

The description is a single, concise sentence that front-loads the action ('Lists all registered vaults') and immediately provides useful details about the output. Every word adds value, with no redundancy or filler, making it appropriately sized.

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 list tool with no output schema, the description adequately covers what the tool does and what it returns (current status, source, size stats). It does not explicitly mention the response_format parameter, but that is covered in the schema. It is complete enough for an agent to understand the tool's capability, though it could benefit from a note that it is a read-only operation.

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 has only one optional parameter, response_format, with a complete description and enum values. Schema description coverage is 100%, so the schema fully documents the parameter. The tool description adds no additional semantic meaning beyond the schema, matching the baseline score of 3 for 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's function: 'Lists all registered vaults' with specific details about status, source, and size stats. This unambiguous verb+resource combination distinguishes it from sibling tools like vault_list_notes and vault_search, making its purpose immediately 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 implies usage for obtaining an overview of registered vaults, but it does not explicitly state when to choose this tool over alternatives or mention exclusions. There is no guidance about using this before other vault-specific operations, but the purpose itself suggests a general listing use case.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It adds a valuable security warning about exposing untrusted content from user-registered vaults and potential prompt injection risks. It does not detail error handling or edge cases, but for a read operation this 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?

The description is exactly two sentences: the first clearly states the tool's function, and the second delivers a critical security warning. No wasted words, and the purpose is front-loaded.

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

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

For a simple read tool, the description covers the main purpose and adds an important security warning. It does not explain the return format, but the response_format parameter in the schema covers this. Error behavior is not mentioned, but that is a minor gap.

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

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

Schema coverage is 100%, and each parameter is already well-described in the schema. The description adds minimal extra meaning beyond clarifying that 'path' is relative and the note is in a vault. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly states the tool reads the content of a specific note by relative path, using a specific verb (reads) and resource (note content). It distinguishes from siblings like vault_search, vault_list_notes, and vault_get_related, which have 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 is implied: use this when you need the content of a specific note given its path. However, there is no explicit differentiation from alternative sibling tools, such as vault_search or vault_get_related, nor any when-not-to-use guidance. The security caution provides context but not selection 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 no annotations provided, the description carries the full burden and does so exceptionally. It explicitly warns about exposure of user-registered vault content and indirect prompt injection risks from untrusted remotes, and discloses that results include scores and snippets. This goes well beyond basic descriptions.

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-loaded with the core purpose, and the caution is placed at the end as an important but secondary warning. Every sentence earns its place without redundancy.

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

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

Given no output schema, the description covers the return value (matches, scores, snippets), mentions the optional vault scoping, and includes a critical security warning. This is complete for a search tool with this complexity and no annotations.

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 input schema already documents all five parameters. The description adds no additional parameter-level semantics beyond what is already in the schema, earning the baseline 3.

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

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

The description uses a specific verb ('Performs a full-text search') and identifies the resource ('notes in one or all indexed vaults'), clearly distinguishing it from sibling tools like memory_search or vault_list_notes. It also states what is returned, making the tool's purpose unambiguous.

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

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

The description clearly implies usage for full-text search across vaults and mentions the optional vault_name parameter for scoping. However, it does not explicitly contrast with alternatives or provide when-not-to-use guidance, so it stops short of a full 5.

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

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

With no annotations, the description carries the full burden. It discloses that it runs git pull, rescans files, and atomically rebuilds indices, which are key behavioral traits. It does not mention permissions or failure modes, but the provided details are substantive.

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

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

The description is three sentences, purpose-first, with no wasted words. It is well-structured and immediately conveys the core function and key behavioral variants.

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 core sync behavior for two vault types and mentions atomic index rebuild. With 2 optional params and no output schema, this is complete enough for the agent to invoke correctly, though it could mention error cases or response format implications.

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 description does not add meaning beyond what the schema already provides for vault_name and response_format. Baseline 3 is appropriate since the schema handles the parameters.

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: 'Synchronizes one or all vaults.' It clearly distinguishes from sibling tools like vault_search or vault_read_note, which are read/search operations, by describing a synchronization action.

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 context for when to use the tool by explaining different behavior for GitHub vaults (git pull) versus local vaults (rescan in-place). It does not explicitly name alternatives, but among the siblings only this tool syncs, so the usage context is clear.

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