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

No annotations are provided, so this description carries the full burden. It discloses that this is a write operation from base64 content, but does not state overwrite semantics, path constraints, directory creation, accepted base64 format, or any side effects; the dangling 'data: {size_bytes, mime_type}' fragment does not clarify 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 first sentence is concise and front-loaded, but the second fragment 'data: {size_bytes, mime_type}.' is unstructured and unclear; it does not earn its place and may be mistaken for a parameter or output specification without explanation.

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 no annotations and no parameter descriptions, the definition is incomplete for a write tool. The core idea is present, but an agent is left guessing about overwrite behavior, target path semantics, optional vault use, and the intended meaning of the data fragment. The presence of an output schema reduces the need for return-value detail, but not the need for behavioral and path guidance.

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 description only hints at content_base64 via 'base64-encoded content.' The required path and optional vault parameters receive no semantic explanation, and size_bytes/mime_type appear nowhere in the schema, making the second line unhelpful for parameter understanding.

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

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

The description names a specific action and resource: 'Write a binary attachment (image, PDF, etc.) to the vault', and clarifies the input encoding. While it doesn't explicitly compare itself to sibling attachment tools like create_attachment_token_tool, the write-versus-list/read/token distinction is largely 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?

Usage is implied: use this when you need to persist binary content into the vault. There is no explicit guidance about when to choose write_note_tool for text, create_attachment_token_tool for tokens, or how path/vault should be selected, so the agent must infer routing.

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

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

No annotations are provided, so the description carries the behavioral burden. It discloses that the operation avoids rewriting the whole file and that create=True creates a missing note, but it does not explain mutation effects, error handling, concurrency behavior, or how expected_revision is used.

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 and front-loaded with the core purpose. The parameter notes are compact and useful, though slightly telegraphic. Every sentence earns its place, but the structure could be clearer.

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

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

For a simple append operation, the description covers the main behavior and two important parametersfake. However, it omits explanation of expected_revision and vault, and since there are no annotations, an agent may lack sufficient context for edge cases. An output schema exists, so return values need not be described.

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%, so the description must compensate. It explains 'section' and 'create' but leaves path, vault, content, and especially expected_revision undocumented beyond their names. This is a significant gap for a six-parameter tool.

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: 'Append content to a note'. It also distinguishes itself from a full rewrite by stating 'without reading and rewriting the whole file', which differentiates it from write_note_tool and patch_note_tool.

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

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

The description implies when to use the tool ('without reading and rewriting the whole file') and explains the create flag behavior, but it does not explicitly name alternatives or state when not to use this tool. Usage context is clear but exclusions are missing.

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 full responsibility and does so thoroughly. It discloses token scoping, expiry, exact authorization constraints, the multi-vault api_key requirement, the OAuth limitation, and the conditional presence of url. It also documents the returned data shape, leaving little hidden 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 long but dense, and each section earns its place: purpose, parameter meanings, URL construction, authorization caveats, and return shape. It is front-loaded with the core purpose and could be tightened with structured bullets, but the verbosity is justified by the tool's complexity and security edge cases.

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

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

For a 4-parameter tool with no parameter descriptions and no annotations, the description is unusually complete: it covers defaults, max expiry, URL assembly, multi-vault behavior, OAuth limitations, and the return payload. It falls just short of full completeness because it never explicitly defines the expected path format and only shows the PUT curl variant.

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 description compensates for most parameters: method is defined as PUT or GET, expires_in is defined in seconds with default and max, path appears in the route and curl template, and vault is explained through the default-vault caveat. The main gap is that the required path parameter is never semantically defined beyond being a URL placeholder.

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

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

States a specific verb and resource: 'Create a short-lived, single-file upload/download token for the GET/PUT /attachments/{path} HTTP route.' It also distinguishes itself from direct attachment tools by explaining it exists to avoid handing out the server's master API_KEY, making its unique role clear among siblings like add_attachment_tool and read_attachment_tool.

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

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

Provides explicit usage branches: if PUBLIC_BASE_URL is configured, use the returned url as-is; otherwise build the curl request manually. It also names an exclusion, directing GitHub-OAuth identities to use a plain Authorization: Bearer request against /attachments/* instead, and references list_vaults_tool for the default-vault check.

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 behavioral burden. It discloses the core mutation and parent-creation behavior, but omits error behavior, idempotency, permission requirements, vault validation, and what happens when the folder already exists.

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

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

The description is exceptionally concise: one action-focused sentence plus one return-value sentence. Every word earns its place, and the most important information 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?

Given no annotations and no schema-level parameter descriptions, the description should provide more operational context. It covers the return shape, but path semantics and vault selection are left to inference, making the definition incomplete for a mutation 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 0%, and the description does not explain the path format, whether the path is relative to the vault root, or how the optional vault parameter behaves. The 'missing parents' note adds some meaning to path, but it is insufficient compensation for two undocumented 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 clearly states the action (create), the resource (folder), and the scope (vault), and adds the useful detail that missing parent folders will also be created. It does not explicitly name sibling tools, but the verb/resource combination already sets it apart from note, attachment, and template 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 intended use is implied by 'Create a folder...', so an agent can infer when to call this tool. However, there is no explicit guidance about when not to use it, prerequisites, or how it compares to alternatives such as listing folders or creating from templates.

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 full burden. It adds useful behavioral detail about built-in variables, format specifiers, and unknown variables being preserved, which goes beyond the schema. However, it omits key side-effect behavior: what create_only does, how expected_revision affects writes, and whether an existing note at output_path is overwritten.

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 and front-loads the main purpose in the first sentence. However, the final line '`path` is the written note; data: {template, variables}.' is cryptic and does not earn its place, and the variable list is run-on rather than 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?

For a tool with six parameters, two required, and zero annotation support, the description leaves significant gaps: template resolution, output path semantics, and conflict behavior are unclear. An output schema exists, so return-value documentation isn't strictly needed, but the description is not complete enough to invoke the tool correctly without further investigation.

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%, so the description must explain parameters itself. It only addresses the 'variables' dict (custom variables override built-ins) and vaguely mentions 'path' as the written note; it never clarifies template_path, output_path, vault, create_only, or expected_revision. Required parameters are left to the reader to infer from context.

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 'Render a template and write it as a new note,' a specific verb-object pair that clearly distinguishes it from siblings like list_templates_tool or write_note_tool. The rendering/variables details reinforce the templating purpose. The closing 'data: {template, variables}' is cryptic but does not undermine the core 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 when to use the tool (when a note should be produced from a template) and explains rendering behavior, but it never states exclusions or compares to alternatives such as write_note_tool or patch_note_tool. No prerequisites or when-not-to-use conditions are 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 for behavioral disclosure. It explains the algorithm (TF-IDF cosine), the heuristic nature, the parameter effects (exclude_path, min_score), and the output format ('data.items: [{path, score}], most similar first'). It does not mention potential edge cases (e.g., empty text, no matches) or performance, but the core behavior is transparently described.

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

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

The description is dense but well-organized: it opens with the purpose, then explains the algorithm, then lists parameter semantics inline. Each sentence adds value, and it avoids redundancy. It is somewhat long but appropriately detailed for a tool with no annotations or schema descriptions. The structure is logical and front-loaded with the key use case.

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

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

Given the presence of an output schema (which covers return format) and the description's coverage of algorithm, use case, and key parameters, the tool is fairly complete. The only minor gaps are the vault parameter (though context likely implies a vault selector) and edge-case behavior. For a read-only search tool with 5 parameters, this is strong.

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%, so the description must explain parameters. It explains exclude_path and min_score in detail, and implicitly covers text via the purpose. However, limit and vault are not explained; limit is likely self-evident (default 5) but vault could be ambiguous without context. Since it only explains 2 of 5 parameters explicitly, it partially compensates but not fully.

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 verb ('Find conceptually related notes') and resource ('notes'), and defines the core purpose (duplicate prevention before creating a new note). It distinguishes itself from simple keyword search by explaining the TF-IDF cosine similarity approach and its limitations (not a transformer model, catches shared distinctive words, not pure synonym rewrites). This clearly separates it from sibling tools like search_notes_tool.

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

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

The description provides an explicit use case: 'for duplicate prevention before creating a new note' with a concrete example question. It also implies when not to use it by stating it 'catches shared distinctive words... not pure synonym rewrites', which hints at limitations. However, it does not explicitly name alternative tools or contrast with keyword search, so the guidance is slightly implicit but still clear enough for an agent to decide.

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

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

With no annotations, the description carries full burden. It discloses the append-only nature, ordering (most recent first), optional filters (path/tool/since), and the entry structure. It also states a clear coverage limitation, giving the agent accurate expectations.

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, with no wasted words. It front-loads the core purpose, then covers filters and limitations efficiently. Every sentence 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?

Given an output schema exists, return values are handled. The description covers purpose, scope, filters, ordering, and coverage limits, making it complete for an agent to decide when and how to call this 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 coverage is 0%, so the description must explain parameters. It explicitly explains path/tool/since as optional filters and since as ISO timestamp inclusive. It does not mention limit or vault, but these are self-explanatory from the schema (limit is a count, vault is a vault identifier). It covers the core filtering parameters well.

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 ('Query') and resource ('append-only log of write-tool activity'), and clarifies what it is not ('not just the .trash/ state after the fact'). It is clearly distinct from sibling tools that operate on notes directly.

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 it (audit write activity) and explicitly states what it covers and does not cover (canvas/kanban/excalidraw/bases writes aren't logged yet). However, it does not name alternative tools for those unlogged areas, leaving some inference needed.

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?

Since no annotations are provided, the description carries the full burden of disclosing behavior. It does state the core operation ('Return all notes that link to the given note') and the response shape ('data.items is a list of note paths'), which adds useful context about output. However, it does not explain the meaning of 'alias-aware' in terms of how aliases are resolved, nor does it mention error handling, ordering, or scope (e.g., whether it searches across all vaults or only the specified vault). This is a moderate level of transparency, adequate for a simple read operation but lacking depth.

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 exceptionally concise: two short sentences. The first sentence states the primary action and the second adds a minimal but helpful output detail. There is no redundant phrasing, no fluff, and the most important information (what the tool does) is front-loaded. Every word earns its place, making it easy for an agent to parse quickly.

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

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

The tool itself is simple, and the presence of an output schema reduces the need to describe return values in detail. However, the complete lack of parameter documentation (0% coverage) and the absence of annotations place a higher burden on the description to cover usage context. The description explains the main purpose and one output field, but it does not clarify the 'vault' parameter, alias behavior, or edge cases. This is adequate for a straightforward tool but not fully complete given the missing structured metadata.

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 schema description coverage at 0%, the description must compensate by explaining the parameters. The phrase 'the given note' implies that 'path' identifies the note whose backlinks are returned, but it does not explicitly name 'path' or clarify the expected format (e.g., file path vs note ID). The 'vault' parameter is not mentioned at all in the description, leaving its purpose and default behavior entirely undocumented. This is a significant gap because the agent cannot infer whether 'vault' is required or how it affects the search.

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 ('Return') and a precise resource ('all notes that link to the given note'), making it immediately distinct from sibling tools like list_notes_tool, read_note_tool, and search_notes_tool. The 'alias-aware' qualifier adds further differentiation by hinting at a special handling of aliases, which is not present in other list/read tools. This clearly identifies the tool's purpose without needing to inspect the schema.

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

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

The description gives no explicit guidance on when to use this tool versus alternatives. It does not mention when to prefer get_backlinks_tool over get_link_graph_tool or get_broken_links_tool, nor does it state any exclusions or fallback conditions. The usage context is only implied by the tool name and the brief description, which is not sufficient for an agent deciding among many similar note-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?

There are no annotations, so the description carries the full behavioral burden. It does convey the output shape ('data.items: [{source, link}]') and the all-wikilinks scope, but it does not disclose behavior around vault resolution, invalid vault values, or whether the operation is safe/read-only, though the 'get' name implies it.

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 and front-loaded with the core purpose. The second sentence is a somewhat fragment-like data shape note, but it is not wasteful; it loses a point only because it omits context around the only parameter.

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 one optional parameter and no annotations, the description is not complete. It fails to explain the 'vault' parameter's meaning, defaults, or how to discover valid vault names, though the output schema does reduce the need to document return values.

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

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

The schema has only one parameter, 'vault', with 0% description coverage, and the description never mentions it. The agent is left to guess what values are valid, what null means, and whether this is a vault name, path, or ID.

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 wikilinks in the vault that point to non-existent notes.' This clearly distinguishes it from related sibling tools like get_orphans_tool or get_backlinks_tool by naming the exact broken-link behavior.

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 given on when to choose this tool over alternatives. Sibling tools such as get_orphans_tool, get_link_graph_tool, and get_backlinks_tool cover related but different link-analysis cases, and the description does not mention any exclusion or selection criteria.

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 behavioral traits. It adds some context with 'traversable' and the data shape, but it does not explain traversal semantics (e.g., depth meaning, cycle handling, whether only reachable notes appear), rate limits, or side effects. The disclosure is minimal for an unannotated 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 compact and front-loaded with the core purpose. The inline details about direction and output data are useful and free of filler, though the mix of parameter notes and output shape could be slightly better 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?

Even with an output schema present, the description lacks parameter semantics for depth and vault, usage guidance relative to sibling link-related tools, and behavioral context about traversal. For a graph tool with four parameters and no annotations, this is 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 0%, so the description must compensate. It explains 'direction' with the allowed values 'outgoing' | 'incoming' | 'both' and implies 'root' via 'starting from a note', but it leaves 'depth' and 'vault' undefined. Only one of the four parameters is meaningfully described.

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

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

The description states a specific action and resource: 'Return a traversable link graph starting from a note.' It clarifies the graph structure (nodes and edges) and the direction options, which distinguishes it from sibling tools like get_backlinks_tool or list_notes_tool, though it does not explicitly name those alternatives.

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

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

There is no guidance on when to use this tool versus alternatives such as get_backlinks_tool or get_broken_links_tool. The description implies use for traversing a link graph, but it never states explicit conditions, exclusions, or why an agent would pick this over a sibling.

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 Journal and Templates are excluded by default, which is a behavioral trait beyond what the schema reveals. It also states the structure of the response (data.items is a list of paths), which is useful. This adds significant context, though it could be more explicit about the meaning of the output, so 4.

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, two sentences, and front-loads the core function. The second sentence adds the exclusion default and output format. No waste, but it could be structured to include more explicit usage context. So 4.

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 relatively simple tool with two optional parameters and an output schema that likely describes the data.items structure. The description covers the main behavior and the response format, which is sufficient. However, it doesn't mention the exact format of the paths or the impact of the exclude_folders parameter, but given the output schema exists, this is adequate. Score 4.

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 has 0% description coverage, so the description must compensate. It does not explain the vault or exclude_folders parameters at all. However, the parameter names are somewhat self-explanatory, and the description does mention the default exclusion of Journal and Templates, which implies how exclude_folders works. But this is not enough to fully compensate, so 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 tool finds notes that no other note links to (orphans), which is a specific concept. It distinguishes itself from siblings like get_backlinks and get_broken_links by focusing on notes with no incoming links. However, it does not explicitly contrast with any sibling, so it loses a point for not providing that 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 implies the tool is for finding orphan notes, which is a clear context, but it does not provide explicit when-to-use or when-not-to-use guidance. There's no mention of alternatives or exclusions beyond the default folders. This is clear but limited, so it scores 3.

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

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

Annotations are absent, so the description carries the burden. It discloses the read-only nature, allowed period/date values, and the returned data shape including exists, content, frontmatter, and tasks. It does not explain 'preview' semantics or vault default behavior, but the core behavior and output fields are 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?

Three compact lines, front-loaded with the verb and resource, followed by value grammars and return shape. No filler, repetition of schema defaults, or unnecessary prose.

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, the description is largely sufficient: it gives value domains, return fields, and an existence flag. The main gaps are vault parameter semantics and the precise meaning of 'preview', which are nonfatal but prevent a higher score.

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%, so the description must compensate. It does for period and date by listing valid values, but the vault parameter is completely undocumented beyond the schema's default null. The description adds meaning for two of three parameters only.

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 ('Read or preview') on a specific resource ('periodic note'), and the period/date enumerations make the scope concrete. This distinguishes it from generic sibling tools like read_note_tool without needing to inspect the schema.

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

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

The description implies the tool is for periodic notes rather than arbitrary notes, but it never explicitly says when to choose it over siblings or how it relates to them. No exclusions or alternative routing are provided.

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 explains date filtering semantics, states that tasks without a due date never match either filter, and details how emoji markers are parsed and stripped from text into dedicated fields. This goes well beyond a simple 'list tasks' description.

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

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

The description is dense but well-structured: purpose, parameters, special date behavior, parsing behavior, and output item shape are each given compact, useful sentences. There is no filler or redundantly repeated schema 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?

For a six-parameter tool with no annotations, the description is nearly self-contained. It covers scope, all relevant filters, date edge cases, marker parsing, and the return item structure. The only minor omission is the `vault` parameter, but the description is otherwise complete enough for an agent to call the tool correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It adds meaningful semantics for status values, date format and inclusivity, and folder/tag filtering. The only notable gap is the `vault` parameter, which is not explicitly explained in the description, though the phrase 'across the vault' and the parameter name provide some context.

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

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

The description opens with a specific verb and resource: 'Return tasks from across the vault.' The term 'tasks' is distinct from all sibling note, attachment, and vault tools, and the mention of Tasks-plugin emoji markers further clarifies that this is a task-oriented retrieval tool.

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

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

The description gives clear context for when to use the tool: retrieving tasks by status, folder, tag, or due date across the vault. It does not explicitly name alternatives or exclusions, but none of the sibling tools appear to be task-specific, so the usage context 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?

With no annotations, the description must disclose behavior itself. It identifies the source file and notes that data.conventions is raw Markdown, which gives useful return-context. However, it does not state read-only behavior explicitly, what happens if the file is missing, or any access requirements. 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?

Two compact sentences, front-loaded with the primary action and source, then a precise note about the return field. Every word earns its place.

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

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

The tool is simple and an output schema exists, so return values need not be fully spelled out. Still, the complete absence of parameter semantics and usage guidance leaves the definition only partially complete for an agent encountering it fresh.

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 description never explains the 'vault' parameter. The only hint is 'the vault's', but there is no detail on format, default behavior, or how it relates to vault identifiers. The description does not compensate for the undocumented schema.

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

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

The description states a specific verb ('Return') and resource ('the vault's AI instructions / conventions from _AI_INSTRUCTIONS.md'), making the tool's function unmistakable. It is clearly differentiated from sibling tools, none of which focus on vault-level conventions.

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

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

The purpose implies when to use the tool—whenever an agent needs the vault's AI conventions—but there is no explicit when/when-not guidance or mention of alternatives. This is implied usage rather than stated selection criteria.

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 behavioral disclosure burden. 'Return vault statistics' makes clear this is a read-only aggregation, and the vault-wide statement adds a useful invocation trait. It omits deeper behavioral details like whether stats are live or cached or whether any special access is needed, but for an apparently read-only stats tool this is a reasonable baseline.

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 crisp sentences with no filler. The purpose and output fields are front-loaded, and the vault-wide scoping note follows as a relevant clarification. Every sentence earns its place.

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

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

The output schema likely covers the return shape, so the description does not need to fully spell out fields, though listing them is harmless. It is missing a definition of the `vault` parameter and does not route the agent away from sibling broken-link/orphan tools, leaving a small but real completeness gap for a low-complexity 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 input schema has one optional `vault` parameter with 0% description coverage, and the description never mentions how `vault` should be populated, what it defaults to, or when to pass null. The only parameter-adjacent statement is about `path` not being carried, which concerns a non-existent property and does not explain the actual parameter. The description fails to compensate for the schema gap.

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 'Return' and names the resource 'vault statistics', then enumerates the exact aggregates: note count, link count, orphans, broken links, most-linked notes. This makes the tool's purpose clear, though it does not explicitly differentiate it from sibling tools like get_broken_links_tool or get_orphans_tool that target a subset of these stats.

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 'Vault-wide, so the envelope carries no `path`' sentence gives a clear scope boundary: this tool is for whole-vault statistics, not note-level operations. It does not name alternatives or state when to prefer get_broken_links_tool/get_orphans_tool, but it provides clear context and an exclusion of path-scoped 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?

With no annotations, the description carries the full burden of behavioral disclosure. It thoroughly explains edge cases: missing fields are not violations, only invalid values are; returns only deviations; and returns an empty pair when no schema is parsed. This gives the agent a clear picture of what to expect, though it does not explicitly state that the tool is read-only or describe any 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?

Every sentence adds value: it defines the scope, the return format, what counts as a violation, and the edge case of no schema. The purpose is front-loaded, and the structure is clear and efficient 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?

The description is comprehensive for a validation tool: it explains the exact output shape, the rule for violations, and the empty-schema case. It omits only the meaning of the 'vault' parameter, which is a minor gap given the tool's simplicity and optional parameter.

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 'vault' is completely undocumented. The description never mentions what it represents (path, name, etc.), and schema coverage is 0%. Since the description is the only source of meaning for parameters and it provides none, this is a significant gap.

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 validates note frontmatter against enum fields defined in _AI_INSTRUCTIONS.md. It specifies the action (validate), the resource (every note's frontmatter), and the source of truth (the schema heading). It also distinguishes itself from siblings by focusing on validation rather than reading, writing, or patching 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 makes the tool's purpose obvious, but it does not explicitly state when to use it versus alternatives, nor does it mention any exclusions or alternatives. The usage is implied (e.g., when you need to check enum compliance), but no direct guidance is provided.

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 a good job: it discloses output shapes (data.items vs data.tree), default behavior, and that sort_by is ignored in tree mode. It does not explain vault selection behavior or edge cases, which keeps it from being a 5.

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 uses compact bullet-style formatting for modes. Every sentence adds useful information 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 an output schema exists and all parameters are optional, the description covers the main mode and sorting behavior well. The main missing piece is the vault parameter's semantics, but for a simple read-only listing tool the definition is nearly 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 0%, so the description must compensate. It explains mode and sort_by with defaults and examples, but the vault parameter is only named and never described, leaving a notable gap for a low-coverage 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: 'Return every tag in the vault.' It further clarifies scope with flat/tree modes, making it clearly distinct from sibling tools like manage_tags_tool.

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

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

The mode and sort_by options give clear internal usage context, but the description does not state when to prefer this tool over alternatives or when it should be avoided. Usage is implied rather than explicit.

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

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

There are no annotations, so the description carries the behavioral burden. It does disclose the result envelope and item fields (data.items with path, size_bytes, mime_type, mtime), but it leaves filtering/recursion semantics and the optional folder/vault behavior implicit.

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

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

Two short, purposeful sentences: the first states the tool's scope, the second specifies the returned item shape. There is no filler or repetition of schema fields.

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 output schema may cover return shape, but the definition does not explain how the optional vault and folder parameters affect the listing; 'all ... in the vault' is even ambiguous against the folder parameter. For a two-parameter tool this is a meaningful omission.

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 0% schema description coverage, the description had to explain vault and folder, but it mentions neither. The folder parameter's role as a filter and the null vault behavior are entirely undocumented, so a caller cannot reliably invoke the tool.

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 ('List'), a well-defined resource ('all non-Markdown files'), and a scope ('in the vault'), with illustrative types (images, PDFs, audio). The 'non-Markdown' qualifier clearly separates it from sibling list_notes_tool.

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

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

The description implies use for attachment-style files rather than Markdown notes, but it never explicitly names alternatives or gives when-to-use/when-not-to-use guidance. An agent can infer the context, but routing to list_notes_tool or list_files_tool is left to inference.

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

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

With no annotations, the description carries full responsibility. It discloses hidden files are skipped, extension filtering behavior, and the output format (data.items as vault-relative paths). These are the key behavioral traits an agent needs. Minor gaps like recursion behavior or sorting are not critical for a listing 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 three sentences with no fluff. It front-loads the primary purpose, then adds the extension filter, hidden-file behavior, and output format. Every sentence adds value, and the structure is easy to scan.

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

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

For a 3-parameter tool with an output schema, the description covers the main functional aspects: scope (vault/subfolder), filtering (extension), exceptions (hidden files), and return shape (data.items). The only missing piece is a clear explanation of the 'vault' parameter, but overall it is sufficient 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 coverage is 0%, so the description must compensate. It thoroughly explains the 'extension' parameter (suffix without dot, omit for everything) and partially explains 'folder' (subfolder context). However, the 'vault' parameter is left unexplained, leaving ambiguity about its purpose or accepted values. This is a notable gap given zero schema descriptions.

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

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

The description states a specific action ('List every file in the vault (or a subfolder)') and explicitly differentiates from siblings by noting it covers any type, not just notes/attachments/bases/canvases. This makes the tool's purpose unmistakable and sets it apart from list_notes_tool and list_attachments_tool.

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

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

The description implies when to use it: when you need all files, including non-standard types like .lock files, and explains the extension filter for narrowing. It contrasts with note/attachment tools, giving clear context for selection, though it doesn't name alternatives explicitly.

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 behavioral burden and does well: it discloses hidden-item exclusion, root-path behavior, recursion output differences, and max_depth semantics. It does not mention permissions, sorting, or errors, but these are less critical for a read-only listing operation and an output schema 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 front-loaded with the core purpose and then uses compact, line-oriented parameter examples. Every sentence adds operational value 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 read-only listing tool with an output schema, the description covers the main behavioral branches (immediate vs recursive, depth limiting, root path) and the hidden-items constraint. The only substantive omission is the meaning of the vault parameter, but the rest is complete enough 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 0%, so the description compensates by explaining path, recursive, and max_depth with concrete output shapes and defaults. The only gap is the vault parameter, which is not described at all; otherwise this is strong parameter-level documentation.

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

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

The opening sentence states a specific action ('List the contents') and resource ('a vault folder'), and adds a distinguishing constraint ('non-hidden items only'). This separates it from sibling tools like list_notes_tool and list_files_tool without requiring schema inspection.

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 practical parameter guidance: path='' is root, recursive=False vs True changes output shape, and max_depth controls depth. However, it never explicitly tells an agent when to prefer this tool over siblings such as list_files_tool or list_attachments_tool, so the usage guidance is implied rather than explicit.

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

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

With no annotations, the description carries the behavioral disclosure burdenaging. It clearly states the result container (data.items) and its two shapes: a list of plain paths or a list of objects with path, title, tags, status, created, and mtime when include_meta=True. This goes beyond the schema by describing the actual output representation.

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

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

Three sentences with no wasted text; the main action is front-loaded)Skip. Each sentence earns its place by adding scope, optional behavior, or return-shape detail. This is a model of concise tool documentation.

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

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

For a read-only listing tool with three optional parameters and an output schema, the description is nearly complete: it explains the include_meta toggle and return shape. The remaining gaps—default vault behavior, folder path format, recursion semantics—are minor but still matter for an agent that needs to call it with vault=null or a nested folder path.

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%, so the description must compensate. It directly explains include_meta and its effect, and 'in the vault (or a subfolder)' connects vault and folder to the location concept. However, it does not define what a null vault means, how folder paths should be formatted, or how recursive/subfolder traversal behaves.

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

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

The description names a specific verb ('List') and a specific resource ('Markdown notes') with clear scope ('in the vault or a subfolder'), and it is distinct from sibling tools that operate on files, attachments, folders, or search queries. The optional metadata mode is stated immediately, so an agent knows what this tool yields.

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 the main use case—enumerating Markdown notes at a vault or subfolder level—and specifies when to set include_meta=Trueasm but gives no explicit guidance about when to prefer search_notes_tool or query_notes_tool for filtered lookups. The pattern is understandable by inference but not stated as criteria.

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 must carry the full burden of behavioral disclosure. It only mentions the output format (data.items) but does not disclose side effects, permission requirements, or error behavior. For a simple read operation, this is minimal but lacks depth.

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 and front-loaded with the purpose. The additional note about data.items is useful, but the structure could be improved by separating output format details. Overall, it is concise and efficient.

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

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

Although an output schema exists, it is not described in detail. The vault parameter is completely unexplained, and there is no context about its purpose or default behavior. For a simple listing tool, this is insufficient for an agent to call it correctly 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?

The schema description coverage is 0%, and the description does not explain the 'vault' parameter at all. The agent has no idea what value to pass or what it controls, making it impossible to correctly invoke the tool without external knowledge.

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 verb ('List') and resource ('template files in the Templates/ folder'), which distinguishes it from siblings like list_notes_tool and list_files_tool. It is unambiguous about what the tool does.

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

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

The description provides no guidance on when to use this tool versus alternatives such as list_files_tool or list_folder_tool. It does not mention any exclusions or specific contexts, leaving the agent to infer 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?

No annotations are provided, so the description carries the full burden. It discloses the return format, the is_default behavior, and the single-vault vs multi-vault behavior. It could add more about error cases or auth failures, but for a read-only listing tool the behavioral disclosure is strong.

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

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

The description is dense but well-organized, front-loading the core purpose and return shape. The trailing 'data.items' line is slightly redundant with the earlier return shape mention, but it does not significantly hurt clarity.

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 list tool with an output schema, the description is nearly complete. It explains the return shape, the default-vault semantics, and how to use the result with other tools. Minor gaps: no mention of error conditions or what happens if the identity has no vault access, but these are not critical 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?

The tool has zero parameters, so the schema provides no parameter semantics. The description compensates by explaining the vault selection mechanism (vault=<name> on other tools) and the is_default flag, which is the relevant semantic context for using this tool's output.

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 vault(s) accessible to the current identity and specifies the exact return shape. It distinguishes itself from sibling tools by being the only vault-listing tool, and it explains the is_default concept that is central to 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 gives explicit when-to-use guidance: call at session start when more than one vault is returned, and explains how to pass vault=<name> to other tools. It also covers the single-vault mode case, leaving no ambiguity about when this tool is needed.

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 transparency burden and does disclose the mutation behavior: it updates the frontmatter tags array and strips inline #tag occurrences from the body. It also states the return shape. The main gap is not explaining expected_revision conflict behavior, but the core side effects are clearly visible.

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 terse sentences with no filler: purpose, behavior, and return value. Each sentence earns its place and the most important verb 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 output schema covers the return value, and the description does convey the core mutation. However, for a 5-parameter mutation tool with no annotations, it is incomplete: expected_revision semantics, vault behavior, add/remove edge cases (e.g., already-existing tags), and conflict handling are all absent.

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

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

Schema description coverage is 0%, so the description must compensate, but it only hints at add/remove and ignores path, vault, and expected_revision entirely. An agent would not know what expected_revision is for or how vault falls back, leaving significant parameter semantics undocumented.

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

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

States a specific action ('Add or remove tags on a note') and a precise resource, then details scope by covering both the frontmatter tags array and inline #tag occurrences. This distinguishes it from siblings like patch_frontmatter_tool and patch_note_text_tool, which address only one layer.

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 use case is implied by the verb and resource, but the description never says when to choose this over patch_frontmatter_tool or patch_note_text_tool. No exclusions or alternative conditions are provided.

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 fully carries the behavioral burden. It discloses dry-run behavior, merge semantics, batch failure isolation, return payloads for both single and batch modes, and an important incompatibility between expected_revision and paths. This is exceptionally transparent for a mutation 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 detailed but every sentence earns its place. It front-loads the core purpose, then logically organizes parameter behavior, return formats, and constraints. The length is justified given the tool's complexity and the absence of 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?

The description covers single-note and batch behavior, dry-run output, merge_array semantics, revision handling, and failure summary expectations. Given the complexity of the tool and an output schema that can define return fields, this is fully complete for an agent to select and invoke it correctly.

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

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

Schema description coverage is 0%, yet the description compensates well by explaining path, paths, updates, dry_run, merge_arrays, and expected_revision. The only unaddressed parameter is vault, which relies on the schema's type information and likely the tool's contextual naming; this is a small but notable gap.

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: 'Update specific YAML frontmatter keys without touching the note body.' This clearly distinguishes it from sibling tools like patch_note_text_tool and write_note_tool, so an agent can immediately identify its scope.

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

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

The description clearly explains when to use the tool for frontmatter-only updates and provides rich context for path vs paths, dry_run, merge_arrays, and expected_revision. It doesn't explicitly name alternatives or state when not to use it, but the 'without touching the note body' phrase gives clear contextual 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 burden and discloses important behaviors: default first-match replacement, count=0 replacing all, dry_run not writing, and raising ValueError when find matches nothing. It stops short of explicitly stating the write behavior when dry_run is false and doesn't mention expected_revision concurrency behavior, but it is substantially 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 compact and front-loaded: main purpose first, then sibling comparison, then parameter semantics, then error behavior. Every sentence adds useful information without 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?

For an 8-parameter mutation tool with no annotations, it covers purpose, alternatives, parameter semantics, dry-run behavior, and errors. Since an output schema exists, return values need not be described. Minor gaps remain around vault and expected_revision, but overall it is nearly 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 0%, so the description compensates well by explaining mode ('exact' default vs 'regex'), count semantics, and dry_run's preview output. It does not explain path, vault, or expected_revision, but the most behaviorally meaningful parameters are covered.

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: "Find and replace text anywhere in one note's body." It also explicitly differentiates itself from patch_note_tool by noting it requires no heading/block-ref anchor, and from write_note_tool by being cheaper for scattered single-note edits.

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 names two sibling tools and gives concrete selection criteria: use this instead of patch_note_tool when no anchor is needed, and instead of write_note_tool for targeted single-note edits. This is explicit when-to-use guidance with 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?

No annotations are present, so the description carries the full behavioral burden. It discloses that dry_run=True previews without writing and returns {preview, diff}, and that dry_run=False commits changes. It also explains the target_type syntax for block references. However, it does not mention error handling, revision conflicts, or consequences of the 'append' mode beyond the mode name.

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 with the core purpose. The colon-list format efficiently conveys modes and targets. Each sentence contributes meaningful information, though the syntax for block_ref could be clearer. It avoids redundancy and stays within a few lines.

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 8 parameters, 0% schema coverage, and no annotations, the description leaves significant gaps. It does not explain 'path' or 'vault' (needed to locate the note), nor 'expected_revision' (likely an optimistic concurrency guard). The description covers the editing mechanics but not the preconditions or error cases, so an agent may still struggle to call it correctly in all scenarios.

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 0% schema description coverage, the description must compensate. It explains the meanings of 'mode' (replace, insert_before, insert_after, append), 'target_type' (heading vs block_ref with section='^block-id'), and 'dry_run'. However, it does not clarify 'path', 'vault', 'expected_revision', or the exact format of 'section' beyond the block_ref case, leaving several parameters underspecified.

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 'Edit a section or block reference inside a note,' which conveys a specific verb and resource. It distinguishes itself from siblings like patch_note_text_tool (text edits) and append_to_note_tool by focusing on section/block references, though it doesn't explicitly name alternatives.

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

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

The description provides a useful dry_run workflow (preview then commit) but does not explain when to choose this tool over similar editing tools (e.g., patch_note_text_tool, append_to_note_tool). It lacks explicit when-to-use/when-not-to-use guidance, relying on the agent to infer from the edit modes.

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 behavior disclosure burden. It discloses tags AND semantics, valid sort_by values, inline field matching syntax, and the data.items shape, which is substantive for a read-only query tool. It does not explicitly state read-only or side-effect-free, though 'query' strongly implies it.

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: purpose first, then syntax details, then output shape. Each sentence carries distinct information with no filler. It is telegraphic but effective.

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 9-parameter query tool with no annotations, the description covers the core query behavior and output shape, and an output schema exists to define returns. It is still incomplete as a selection aid because it does not explain when to use this tool versus search_notes_tool/list_notes_tool, and several parameter semantics remain implicit. Overall it is adequate but has clear 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 descriptions cover 0% of parameters, so the description must compensate. It adds meaning for tags (AND), sort_by (allowed values), and inline_field_filter (key:: value syntax), and it lists output fields. However, frontmatter_filter, status, limit, vault, folder, and sort_desc semantics are left to their names, leaving several parameters underspecified.

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

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

The description names a specific operation ('query/filter notes') and enumerates the filter dimensions (tags, status, frontmatter, inline fields), so an agent knows what the tool does. It doesn't explicitly distinguish itself from list_notes_tool or search_notes_tool, so the differentiation burden is not fully met.

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 given on when to choose this tool over siblings such as search_notes_tool or list_notes_tool. 'Dataview-like' hints at intended use, but there are no explicit when-to-use, when-not-to-use, or alternative recommendations.

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 does disclose output format behavior (UTF-8 vs base64, mime_type/encoding), which is useful. However, it omits error handling, permissions, and any side-effect declaration (though 'read' implies none). It partially compensates for missing annotations but not fully.

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 action ('Read an attachment file') and then provides essential output details. No waste, efficient and clear.

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 (not shown) which covers return values, but the description still fails to explain parameter usage, preconditions (e.g., need a path from list_attachments_tool), or error cases. For a read tool with two params and no schema coverage, this is incomplete.

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%, so the description must explain parameters. It does not mention 'path' or 'vault' at all, leaving the agent to guess what path refers to (relative/absolute, vault-relative?) and what vault does. This is a major gap for a 2-parameter tool.

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 clear verb and resource: 'Read an attachment file.' This distinguishes it from siblings like list_attachments_tool (listing) and add_attachment_tool (writing). It could be a 5 if it explicitly noted the need for a path, but the 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?

No guidance is given on when to use this tool versus alternatives. It does not mention that list_attachments_tool should be used to discover paths, or that read_note_tool is for notes, or that vault is optional. The agent is left to infer usage context entirely.

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 behavioral burden, and it is highly transparent: it details the data returned per mode, depth semantics for rendered embeds, and the revision-pinning nuance. It even notes that rendered reads span several notes and therefore pin nothing.

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

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

The description is dense but well organized: purpose first, then mode and depth details, then the revision caveat. Every sentence adds useful information and there is no filler or repetition of 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?

The output schema already exists, so the returned field lists do not need deeper explanation. The main remaining gap is the complete absence of path/vault semantics, which matters for a required parameter.

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 has 0% parameter description coverage, so the tool description must compensate. It thoroughly explains mode and depth, but it never describes the path parameter (the required note identifier/location) or the vault parameter, which remain undocumented in both the schema and the description.

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

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

The first sentence names a specific verb and resource: 'Read one note'. The mode list then defines what 'level of detail' means, clearly distinguishing this from sibling list/search/write tools.

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

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

It gives explicit usage guidance for mode='outline' ('Use this on a large note when you only need its shape') and clarifies when depth applies. However, it does not explicitly contrast this tool with alternatives like list_notes_tool or search_notes_tool, so no when-not-to-use boundaries are stated.

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

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

No annotations are provided, so the description carries the behavioral disclosure burden. It usefully explains the not-found behavior (`path` and `data.resolved` are null, and `path` is omitted). It does not discuss permissions, errors, or side effects, but for a resolution tool this is a reasonable amount of disclosure.

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

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

The description is short and front-loaded with the primary purpose. The second sentence about not-found behavior is useful but is somewhat awkwardly phrased ('`path` and data.resolved are null (and `path` omitted)'), which slightly reduces clarity.

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 two parameters, no annotations, and an output schema present, the description covers the core behavior and the not-found case. It does not explicitly cover the optional vault parameter, but that parameter is self-descriptive and optional. Overall, an agent has enough information to invoke the tool correctly in most cases.

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%, so the description must compensate. It adds meaning by indicating the `name` parameter is the note alias or stem to resolve, but it does not explicitly explain the `vault` parameter or the exact format expected. The optional `vault` parameter is left to inference from its name.

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

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

The description clearly states a specific action ('Resolve a note alias or stem to its real vault path') and names the resource (note alias/stem → vault path). It is distinct from sibling tools like read_note_tool or search_notes_tool because it maps an alias to a canonical storage path rather than reading or searching note 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?

The intended use is implied by the purpose: use when you have an alias or stem and need the real vault path. However, the description does not explicitly state when to use this tool versus alternatives, nor does it mention 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?

With no annotations, the description carries the full burden of behavioral disclosure. It does a good job explaining parameter-specific behaviors: mode options, threshold semantics, field selection, and the frontmatter_filter syntax. It also reveals the output shape (`data.items`) and that results include snippets, scores, and tags. However, it does not state read-only intent, pagination behavior, or error cases, though these are less critical for a search tool and partially covered by the output schema.

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

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

The description is compact and front-loaded with the core purpose, then lays out parameter details in a bullet-like format. Each line is information-dense with no filler. The structure is clear, though the inline enumeration of modes and filter shapes could be slightly cleaner with separators, but it remains easy to scan.

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

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

The tool has 8 parameters and no schema-level descriptions, yet the description covers only the complex ones. It doesn't explain how `query`, `limit`, `vault`, and `tag` behave, nor does it mention response structure beyond the `data.items` hint (which is partly redundant given the output schema). Some gaps remain for an agent to infer defaults and interactions, but the presence of an output schema and the detailed explanation of the hardest parameters make it adequate.

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%, so the description must compensate, and it does for several non-obvious parameters: mode, field, threshold, and frontmatter_filter are all explained with meaning beyond their names. The description omits details for `query`, `limit`, `vault`, and `tag`, but these are fairly self-explanatory or have conventional meanings. The explanation of `frontmatter_filter` with operand examples adds substantial semantic value.

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 performs 'Full-text search with snippets and relevance ranking,' which is a specific verb and resource. It also distinguishes from siblings like query_notes_tool (structured queries) and find_similar_notes_tool (semantic similarity) by focusing on full-text search and relevance ranking. The mention of `data.items` output shape reinforces the 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 provides no explicit guidance on when to use this tool versus alternatives like query_notes_tool or find_similar_notes_tool. It references query_notes_tool only to explain the shape of frontmatter_filter, not to differentiate use cases. There is no 'use this when' or 'instead of' advice, leaving the agent to infer the tool's role from the name and purpose.

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

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

With no annotations provided, the description carries the full burden and does so thoroughly: it discloses that the tool writes (mutates), conditionally preserves frontmatter, returns a diff and frontmatter_preserved flag, and that dry_run previews without writing. This covers the essential behavioral traits an agent needs to know.

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 compact sentences, each adding unique value: purpose, frontmatter behavior, and dry_run workflow. No redundancy, and the most important operational detail (dry_run preview) is saved for last as an actionable instruction.

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?

Despite having an output schema, the description omits three parameters (vault, create_only, expected_revision) and doesn't address error conditions or concurrency. For a tool with 6 parameters and no schema descriptions, this is a meaningful gap that could lead to misuse.

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 0%, so the description must compensate. It explains content (frontmatter preservation), path (target), and dry_run (preview). However, it leaves vault, create_only, and expected_revision unexplained — these are critical for correct invocation (selecting vault, enforcing create-only semantics, and optimistic concurrency).

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 ('Write') and resource ('note'), and clarifies 'create or overwrite'. This clearly distinguishes it from partial-edit siblings like patch_note_tool and append_to_note_tool without needing explicit naming.

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

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

Provides concrete usage context: mentions READ_ONLY/WRITE_PATHS constraints, explains dry_run preview flow ('previews... without writing anything — check it, then call again'), and advises checking the returned frontmatter_preserved flag. However, it doesn't explicitly state when to prefer this over patch/append tools, relying on implied full-content replacement.

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