vault-bridge

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

With no annotations provided, the description carries the burden of behavioral disclosure. It states the dual get-or-create behavior, which is useful, but doesn't disclose details like whether creation is silent, what happens if the note exists, or any side effects. The create_if_missing parameter adds some context, but the description itself is minimal.

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 core purpose. It's efficient and doesn't waste words, though it could add a bit more context without becoming 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?

The tool has an output schema and 100% schema coverage, so the description doesn't need to explain return values or parameters. However, given the dual get-or-create behavior and the existence of sibling tools like read_note and write_note, a bit more context on when to use this tool would improve completeness.

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 well. The description adds no additional parameter semantics beyond what the schema provides. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description 'Get or create a daily note' clearly states the verb and resource, and the dual behavior (get or create) is explicit. It doesn't explicitly distinguish from siblings like read_note or write_note, but the 'daily note' resource is specific enough to convey its 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 implies usage for daily notes but doesn't explicitly state when to use this tool versus read_note or write_note. The create_if_missing parameter hints at the conditional creation behavior, but there's no explicit guidance on when to choose this over 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It does not state whether the operation is read-only, whether there are side effects, or what the return structure looks like (though an output schema exists). It only states the basic function, omitting important behavioral context such as recursion limits or filtering behavior. This is a significant gap, so a 2 is appropriate.

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

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

The description is a single, front-loaded sentence with no filler words. It is concise and directly states the primary action. However, its brevity results in under-specification, which slightly reduces the score; it does not merit a 5 because it omits necessary contextual 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?

This is a moderately complex tool with a nested request object and five sub-parameters, plus an output schema. The description only states 'List notes in the Obsidian vault' and fails to mention key contextual aspects such as recursion defaults, the fact that it filters by Markdown files, or the read-only nature. While the output schema may cover return values, usage context is largely absent, making the tool incomplete for an agent to use correctly.

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

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

The schema description coverage is 100%, with each parameter (path, max_depth, recursive, glob_pattern, include_frontmatter) having a description. The tool description adds no additional parameter meaning beyond what the schema already provides. Per the rubric, the baseline is 3 given high schema coverage, and the description does not enhance 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 clearly states the action (list) and resource (notes in the Obsidian vault). It is specific enough to distinguish from siblings like read_note or write_note, though it does not explicitly call out those alternatives. A clear verb+resource is present, so it earns a 4 for purpose 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 provides no guidance on when to use this tool versus search_notes, search_frontmatter, or get_daily_note. There is no mention of use cases, exclusions, or alternatives. This falls short of the expected guidance for selecting the right tool, earning a 2.

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 behavioral disclosure burden. 'Read a note' conveys non-mutating intent, which is helpful, but it does not mention how missing paths are handled, how include_frontmatter affects the result, or any other runtime behavior. The opacity is acceptable for a simple read tool but not fully transparent.

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, front-loaded sentence with no filler and no redundancy with the schema. It is easy to parse, though its brevity comes at the cost of usage guidance.

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 straightforward read operation with complete schema coverage and an output schema present, the minimal description is largely sufficient. However, it does not connect the tool to its sibling tools or explain the intended relationship to get_daily_note, which leaves a modest contextual gap.

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

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

Schema description coverage is 100%, with both path and include_frontmatter documented in the input schema. The tool description adds no parameter-level meaning, so the schema does the necessary work. This matches the baseline-3 case where the description need not repeat schema details.

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

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

The description clearly states the verb ('read') and resource ('a note from the Obsidian vault'), so an agent can distinguish it from write_note, list_notes, and search_notes. It does not explicitly contrast with get_daily_note or mention the by-path access mode, but the core purpose is unambiguous.

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

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

The description provides no guidance about when to use this tool versus siblings such as get_daily_note or search_notes. There are no stated alternatives, exclusions, or prerequisites, leaving the agent to infer selection criteria from the tool name alone.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It communicates a read-only search operation but gives no detail on recursion behavior, default path, matching semantics, result limiting (max_results default 100), or how missing keys are handled, despite all of this being configurable 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?

One efficient sentence with zero wasted words; the verb, resource, and scope are front-loaded. It is arguably under-sized relative to the tool's 6-parameter nested request model with 9 operators, but it earns its place and is easy to parse.

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 schema covers every parameter with descriptions and an output schema exists, so the description doesn't need to explain return values or field semantics. However, for a parameterized tool of this complexity, the single-sentence description leaves gaps — no guidance on topological scope, operator semantics in practice, or distinction from sibling search tools. Adequate, but clearly short of complete.

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

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

Schema description coverage is 100%, so the schema already documents all six nested parameters thoroughly. The description's mention of 'key/value' maps to the key and value parameters, adding slight semantic emphasis, but it provides nothing beyond what the schema fields already describe. Baseline 3 applies.

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

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

States a specific verb (search), resource (notes), and scope (frontmatter key/value) in a single phrase. The frontmatter qualifier cleanly differentiates it from the sibling search_notes, which presumably searches full note content, so an agent can tell this tool apart 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 implies usage: use this tool when the search target is frontmatter metadata rather than note body content. However, it never explicitly names search_notes as the alternative or states when not to use this tool, leaving the routing decision to inference.

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

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

No annotations are provided, so the description carries the full burden of disclosing behavioral traits. It only states that it searches notes with regex, implying a read-only operation, but does not disclose that it defaults to markdown files, uses ripgrep, or how results/context lines are returned. The schema provides parameter defaults but the description itself adds no behavioral detail beyond what the tool name suggests.

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 zero filler words. It front-loads the primary purpose (search notes) and the method (regex) without redundant qualifications. It is appropriately sized for the tool's complexity.

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

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

Even though the schema is rich with six parameters and an output schema exists, the description is incomplete for an agent deciding when to invoke this tool. It lacks usage guidance, alternative routing, and behavioral transparency beyond the literal action. The description's brevity means the agent must infer context from the tool name and schema alone, which is insufficient for a tool with multiple sibling search/list options.

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's mention of 'regex' aligns with the pattern parameter and adds a small semantic cue, but it does not elaborate on path, glob_pattern, max_results, or case_sensitive. Since the schema already documents each parameter thoroughly, the description adds minimal extra parameter meaning, which is acceptable at 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 states a specific action (search), resource (notes in the Obsidian vault), and method (regex), which clearly conveys what the tool does. It is distinguishable from siblings like read_note, write_note, and list_notes by its focus on searching, and from search_frontmatter by the general 'notes' target. The phrasing 'using regex' adds precision beyond the tool name.

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

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

The description provides no guidance on when to use this tool versus alternatives such as search_frontmatter, which searches only frontmatter, or list_notes for enumeration. It does not mention exclusions, prerequisites, or specific use cases. The only hint is the tool name and the one-line description, leaving the agent to infer usage context on its own.

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 of behavioral disclosure. It only says 'Write a note' without mentioning that it overwrites existing notes, whether it creates parent directories (though schema has create_dirs), whether it prepends frontmatter, or any side effects. The schema covers some parameters, but the description itself adds no behavioral context beyond the basic write action.

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, short sentence that is front-loaded with the verb and resource. It's concise and to the point, though it could add a bit more context without becoming 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?

Given the tool has a nested request object, an output schema, and no annotations, the description is thin. It doesn't mention overwrite behavior, path constraints, or any return value expectations. The schema covers parameters, but the description doesn't provide enough behavioral context for an agent to fully understand the tool's side effects.

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 including path, content, atomic, create_dirs, and frontmatter. The description adds no parameter-level meaning beyond what the schema provides. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description states a specific verb ('Write') and resource ('note to the Obsidian vault'), which clearly distinguishes it from read_note, list_notes, and search_notes. It doesn't explicitly name sibling tools, but the action is unambiguous enough that an agent can tell it apart from the read/search 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?

The description implies usage: use this when you need to create or overwrite a note in the vault. It doesn't explicitly state when not to use it or mention alternatives like update_note (which doesn't exist among siblings), but the context of a write operation versus read/search siblings is clear enough for basic selection.

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