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

With no annotations, the description carries the behavioral burden. It discloses the non-destructive append-only nature and the create-if-absent behavior, which are key traits. It does not detail heading behavior or return values, but the core side effects are clearly conveyed.

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

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

The description is two tight sentences with no filler. The core behavior is front-loaded and the usage policy follows naturally, 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 description covers the essential append behavior and preferred use case, but it omits heading semantics, path details, and any return or error behavior. Since there are no annotations or output schema, these gaps leave the tool only partially specified for an agent.

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 adds little parameter-level meaning. It implies text is appended to a note identified by path, but the optional heading parameter and path format are left entirely unexplained, so the description does not 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 states a specific verb and resource ('Append to a note') and adds a defining behavior ('creating it if absent'). It also positions the tool as 'the append-only primitive,' distinguishing it from generic rewrite or 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?

The description gives clear guidance to prefer this tool over rewriting raw capture notes, which is a useful policy. It does not explicitly contrast with sibling tools like patch_section or create_note, but the append-only framing provides enough context for basic selection.

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

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

No annotations are provided, so the description bears the full burden of behavioral disclosure. It does disclose a key trait — that nothing is ever deleted — which is valuable. However, it does not mention required permissions, reversibility, what happens to the original file, or any side effects. For a simple move operation, this is adequate but not rich.

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

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

The description is two concise sentences with no fluff. The purpose is front-loaded ('Move a note into the archive folder'), and the non-deletion guarantee adds important context without redundancy.

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

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

For a simple tool with one parameter and no output schema, the description covers the core operation and a key guarantee. It does not explain the path parameter or mention prerequisites or error conditions, which would improve completeness. Given the low complexity, it is mostly sufficient but leaves minor 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?

The schema has one required parameter 'path' with no description, and schema description coverage is 0%. The description does not elaborate on the format, scope, or meaning of the path (e.g., absolute vs. relative, file name vs. full path). The description fails to compensate for the schema gap, leaving the agent uncertain how to specify the path.

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

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

The description states a specific verb ('Move'), a resource ('a note'), and a destination ('into the archive folder'). It is unambiguous and easily distinguished from the broader 'move_note' sibling. The added phrase 'Nothing is ever deleted' reinforces the tool's non-destructive purpose.

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

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

The description implies usage (you use this when you want to archive a note) but does not explicitly state when to prefer it over alternatives like 'move_note'. There are no exclusions, alternative names, or conditions provided; the guidance is merely inferred 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?

No annotations are provided, so the description carries the full burden. It does not disclose that this is a read-only query, what the return format looks like, whether it requires a valid path, or any performance implications. The behavior is implied but not elaborated.

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

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

The description is a single, concise sentence with no filler. It is appropriately short for a simple query tool, though it sacrifices completeness for brevity.

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 absence of an output schema and annotations, the description is incomplete. It does not specify what the output contains (e.g., list of paths, titles), how errors are handled, or whether the tool is read-only. An agent cannot fully anticipate the tool's behavior from this definition alone.

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 vaguely refers to 'this one' to indicate the path parameter. It does not clarify the expected format, whether a path must be absolute, or give examples. Minimal added value beyond the schema's bare 'Path' title.

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 the tool returns notes that link to the given note via wikilinks, which is a specific verb-resource combination. It implies the 'path' parameter identifies the note, but it doesn't explicitly name it. It distinguishes from 'related_notes' by focusing on wikilink references, though the differentiation is not explicit.

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 siblings like 'related_notes' or 'search_notes'. There is no mention of alternatives, exclusions, or typical use cases, leaving the agent to infer the appropriate context.

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

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

With no annotations, the description must carry the behavioral disclosure burden, but it only restates the write intent. It does not disclose whether an existing MOC gets overwritten, whether a new file is created, or how the 'topic' relates to the generated note, so an agent gets no side-effect or safety information.

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 one sentence, front-loaded with the action and object, and contains no filler. It is as concise as the available information allows.

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 no annotations and no output schema, this is too thin: an agent is not told what a Map-of-Content index note looks like, what happens to existing notes, what the result is, or how the parameters shape the output. The description fails to compensate for the missing structured context.

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

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

Schema description coverage is 0%, and the description does not define topic, note_paths, or intro, nor even mention them by name. The phrase 'notes you have curated' weakly hints at note_paths but adds no semantic detail, so the schema titles are all an agent has to go on.

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 ('Write') and a specific resource ('Map-of-Content index note'), and the phrase 'over notes you have curated' clearly ties it to a curated note set. This distinguishes it from generic note-creation siblings like create_note or append_to_note, so an agent can understand the tool's role.

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

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

It implies a workflow ('notes you have curated') but never states when to choose this over create_note or create_concept_note, nor any exclusions. The context is suggestive but not explicit enough to route an agent reliably.

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 burden and does it well: it reveals that the tool only files the summary, creates a note marked undistilled, and drops a pointer into today's log. It also warns against transcript-style content, giving the agent a clear boundary on what the persisted artifact should be. It does not cover deeper concerns like authentication or reversibility, but the disclosed side effects are the key ones here.

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

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

The description is front-loaded with the core purpose, then gives actionable guidance in compact, high-density sentences. Each sentence earns its place: purpose, division of labor, content expectations, and side effects. There is no filler or repetition of the schema.

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 8 parameters, no annotations, and no output schema, this description is unusually complete. It tells the agent what to prepare, what content the summary must contain, and what physical effects to expect in the vault. A small gap is the lack of guidance on how the optional session_id, tags, and project parameters relate to the overall capture workflow.

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 the most important parameters. It tells the agent that the summary should contain what was being done and why, and it explicitly maps the content categories to decisions, open questions, and artifacts. Tags, project, and session_id remain only schema-explained by name and type, which is a minor gap for optional fields.

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: 'Persist the current session into the vault -- the `/compact` step.' It goes further by explaining the concrete result: a note in the sessions folder marked undistilled and a pointer in today's log. This distinguishes it from generic note-creation siblings like create_note.

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

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

The description gives explicit when-to-use context ('the /compact step') and detailed before-calling instructions: the agent must compact the session into durable facts covering what/why, decisions, open questions, and artifacts. It does not explicitly name alternatives or say when not to use the tool, so it stops short of a 5.

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

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

The description discloses the core behavior: writing one atomic concept note and linking into the graph. However, no annotations are provided, and the description does not mention what happens when overwrite is true, whether an existing note is replaced, or what the tool returns. Given the overwrite parameter, this is a meaningful transparency gap.

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

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

The description is four short, front-loaded sentences with no filler. Every line earns its place by explaining what the note should contain and how to prepare links.

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 create tool with 7 parameters, no annotations, and no output schema, the description covers the core workflow well but omits overwrite behavior and optional field semantics. It is adequate for basic use but not fully complete for safe handling of the overwrite case.

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 prose must carry parameter meaning; it does for title, claim, and links with unusually specific semantics. However, body, tags, sources, and especially overwrite are left unexplained, so it only partially compensates for the complete lack of 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 verb and resource: 'Write one atomic note: one idea, stated as a claim.' The title and claim guidance ('assertion you could disagree with, not a topic label') clearly differentiates this from generic create_note and other note-related siblings.

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

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

It gives clear procedural guidance: links must be titles of existing notes, so the agent should call find_notes or search_notes first to avoid creating an island. It does not explicitly say when to prefer this tool over create_note or append_to_note, but the intended use case is strongly implied.

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

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

With no annotations present, the description must carry behavioral weight. It does disclose that existing notes are not clobbered unless overwrite=true, an important safety behavior. However, other meaningful behavior—error handling, idempotency semantics beyond overwrite, path constraints, or required permissions—is left undocumented.

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 brief and front-loads the core action, then provides one meaningful nuance. It avoids fluff, but the first sentence is largely redundant with the tool name, so it does not quite earn the top score for maximally efficient use.

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 absence of an output schema and annotations, this description leaves the agent without several critical call details: how frontmatter should be formatted, whether directories are created, what happens on conflicts beyond a terse 'refuses', and what the return value indicates. It is sufficient for a basic call but under-specified for reliable use.

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 adds meaning for overwrite ('unless overwrite=true'). path, body, and frontmatter receive no additional semantics, and frontmatter in particular is an open object that would benefit from explanation. Schema coverage zero, so the description does not bear the full load.

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 the action clearly ('Create a note.') and hints at non-destructive behavior. However, it does not explicitly distinguish create_note from sibling tools like create_concept_note, capture_session, or log_entry, so an agent must infer which creation-scope tool to pick.

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 append_to_note, patch_section, or create_concept_note. The clobber behavior is a safety note, not usage direction, so the agent receives no explicit context for selecting 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?

Since no annotations are present, the description must carry the behavioral burden. It does: it states this is only the queue view and that the actual distillation is 'YOUR job, not the server's', implying the call is read-only and no items are consumed. It does not explicitly mention 'does not modify state' or return format, but the workflow statement is sufficient to avoid misusing the tool as a distiller itself.

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 moderately sized and front-loaded with the core purpose before diving into instructions. Each sentence adds value; the only potential redundancy is the slightly long procedural second paragraph, but it is instructional and not filler. It balances brevity with the needed workflow.

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

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

The tool is a simple queue listing with two parameters and no output schema, so the description is mostly sufficient for a correct call. However, it does not describe the shape of each raw capture item (e.g., ID, body, metadata) or what `include_body=false` affects, which an agent might need to know when calling `mark_distilled` on the correct source.

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, but it does not. There is no mention of `limit` or `include_body` by name; the only hint is 'with their content,' which loosely maps to `include_body` default (true). An agent has no explicit guidance on how to control batch size or whether setting `include_body=false` changes the returned object shape, which is a meaningful 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 opening line, 'Raw captures not yet distilled, oldest first, with their content,' precisely states the resource, the ordering, and the payload. It clearly distinguishes distill_queue from list_notes and others in the sibling set by scoping it to undistilled raw captures and tying it to the distillation workflow.

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 goes beyond when to use it by providing an explicit end-to-end invocation guide: read each item, distill into `create_concept_note` with [[Title]] links, then `mark_distilled` with the produced list. It also covers the edge case of ephemeral items (mark with empty list), leaving no ambiguity about how to handle the response.

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 burden of behavioral disclosure. It does this well by explaining matching semantics: globs work and bare words match substrings. It doesn't cover folder/limit behavior or ordering, but it clearly communicates the core matching behavior without contradiction.

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

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

The description is short and front-loaded. It states the core behavior first, then adds matching syntax, then closes with usage guidance. Every sentence earns its place and there is no filler.

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

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

For a relatively simple 3-parameter finder tool, the description covers the primary usage scenarios and the essential pattern semantics. The main gaps are the behavior of folder and limit, but the tool's scope and decision context are clear enough for correct invocation 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?

The required pattern parameter is well explained with concrete matching rules: '*'/'?' globs and bare-word substring matching. However, the other two parameters, limit and folder, have no description enrichment, and schema description coverage is 0%. Their semantics remain inferred from names and defaults alone.

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 notes by NAME or path'. It also distinguishes itself from search_notes by clarifying that this tool searches names/paths, not content. This makes it easily separable from siblings like list_notes, search_by_tag, and search_frontmatter.

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

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

It explicitly says when to use this tool: 'when you know roughly what a note is called.' It also names the alternative, search_notes, and the condition for choosing it: 'when you need to look inside the content.' This gives the agent clear decision logic.

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

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

With no annotations, the description carries the behavioral disclosure burden. It meaningfully discloses that the operation is idempotent and that existing folders and notes are left untouched. It does not clarify config-file conflict behavior or what happens if the vault is not empty, but the core safety property is covered.

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 sentences with no filler. The main purpose is front-loaded, and the idempotence guarantee is stated separately and clearly.

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

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

The description covers the core function and the most important behavioral trait for a low-complexity tool with one optional parameter. However, it omits the effect of seed_readme and gives no indication of what a successful initialization produces, which matters because there is no output schema.

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

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

The only parameter, seed_readme, is undocumented in the schema and receives no explanation in the description. The name hints at its purpose, but the agent gets no explicit information about what seeding a readme entails or how it affects the vault.

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, 'Create the folder taxonomy and config file', and clearly scopes it to 'an empty or new vault'. This distinguishes it from note-level siblings like create_note and build_map without ambiguity.

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

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

The description clearly scopes when the tool should be used: on an empty or new vault. It does not explicitly name alternatives or tell the agent what to do for existing vaults, but the idempotence note reinforces the intended setup context.

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

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

No annotations are provided, so the description carries the full burden. The 'list' verb and 'paths' output convey a read-only, lightweight behavior, which is useful context. But it does not disclose limit-based pagination, the effect of with_frontmatter, recursion behavior, or path format.

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

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

A single, tight sentence with no filler. It is front-loaded and every word earns its place; the brevity costs are accounted for in other dimensions.

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 output schema and no annotations, this description is too thin. It omits what limit does, what with_frontmatter changes, the path format, and any relationship to sibling tools, making correct invocation uncertain.

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 the folder parameter via 'optionally restricted to one folder.' The limit and with_frontmatter parameters are entirely unexplained, so the description fails to compensate for the schema's lack of 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 uses a specific verb ('list') and resource ('note paths'), so the core operation is unambiguous. However, it does not explicitly differentiate this tool from siblings like find_notes or search_notes, which also retrieve note-related data.

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 about when to use list_notes versus any of the 26 sibling tools. An agent cannot determine whether to reach for this, search_notes, or recent_notes, and there are no exclusions or alternative references.

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 fully carries the burden. It discloses the most important behavioral trait: append-only, timestamped, never rewrites, and the log's role as a raw stream for distillation. This is substantial transparency for an otherwise annotation-free 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?

Three punchy, front-loaded sentences: the verb+resource come first, followed by use-case context and the rewrite prohibition. Every sentence earns its place and there is no filler.

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

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

The core behavioral contract is clear, but for a 3-parameter tool the description omits the meaning of optional parameters and prerequisites like vault initialization. Given no output schema and no annotations, an agent could invoke the tool incorrectly around date/source semantics.

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

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

Schema description coverage is 0%, and the description does not compensate. It gives the text' semantic hint ('a fact, a link...') but leaves date and source completely unexplained. An agent cannot know that a null date likely means today, or what values source accepts beyond the default 'manual'.

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?

Names a specific verb ('Append') and resource ('the day's append-only log'), which clearly distinguishes it from read-only sibling tools like read_daily_log or list_notes. It does not explicitly name a competing sibling, but the append-only log resource makes the purpose specific.

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

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

Provides a strong context sentence — 'For in-flight capture: a fact, a link, a half-formed idea' — and a behavioral exclusion ('Never rewrite the log'). It does not explicitly say when to use this tool versus append_to_note or capture_session, so the routing remains implied rather than fully explicit.

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

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

The description discloses the core behavior: a state transition on a raw capture and recording of produced notes. With no annotations, however, it does not mention reversibility, idempotency, or what happens to previously recorded produced notes, so behavioral coverage is only partial.

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

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

The description is a single sentence that front-loads the action and adds the relationship detail without redundancy. Every word contributes meaning.

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

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

For a simple two-parameter state-marker tool, the description sufficiently covers what the tool does and what the parameters represent. It lacks explicit workflow cues and return-value expectations, but the low complexity keeps the gap minor.

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

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

Schema description coverage is 0%, so the description carries the semantic weight. It clarifies that path refers to the raw capture and produced refers to the notes that came out of it, which goes well beyond the bare parameter names. It stops short of describing formats or constraints.

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

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

The description states a specific verb ('mark') on a clear resource ('raw capture') and records the relationship to produced notes. It is clear and distinguishable from creation/reading siblings, though it does not explicitly name an alternative 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 phrasing 'mark a raw capture as distilled' implies it is used after distillation has occurred, but there is no explicit guidance on when to use it versus related tools like distill_queue or create_concept_note. The usage context is implied rather than 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?

With no annotations, the description carries full responsibility for disclosing side effects. It reveals that the tool mutates the vault, but it does not mention overwrite behavior, whether links/backlinks are updated, or what happens when the destination 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 a single, front-loaded sentence with no filler. Every word contributes to the core purpose, making it appropriately concise.

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 mutating tool with no annotations, no output schema, and three undocumented parameters, the description is too thin. An agent lacks enough detail to predict overwrite semantics, return values, or how renaming interacts with the vault.

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 src or dest path formats or the meaning of overwrite. The parameter names are suggestive, but the overwrite default and rename semantics are left 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?

The description uses a specific verb ('Move or rename') and a clear resource ('a note inside the vault'), so an agent knows the core operation. It does not explicitly differentiate from siblings like archive_note, but the action 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 about when to use move_note versus a sibling like archive_note or patch_section, or how moving differs from renaming in practice. The description states what it does but leaves tool selection entirely 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 provided, the description carries the full burden and does disclose key behavior: text is inserted at the end of an existing section, and a missing section is appended to the note. It explains the mutation and fallback clearly, though it omits return/error 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?

A single, well-structured sentence with no filler. The primary action and conditional fallback are front-loaded, and 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?

For a simple three-parameter mutating tool with no annotations or output schema, the description covers the main workflow and fallback behavior. However, it leaves the path parameter implicit and does not mention heading-matching caveats, making it adequate but not fully complete.

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

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

Schema description coverage is 0%, so the description must compensate. It clarifies heading and text semantics well, but 'path' is only implied by 'the note' and not explicitly defined. Meaning is added for two of three required 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 names a concrete action ('Insert text') and a specific target ('section under heading'), including fallback behavior when the section is missing. This clearly differentiates it from note-level siblings like append_to_note.

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

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

Usage is implied rather than explicit: an agent can infer this tool is for adding text under a heading, and that a missing section will be created. However, there is no when-not guidance or explicit distinction from append_to_note and similar tools.

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

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

No annotations are provided, so the description must carry the burden of describing behavior. It mentions the date default (today) and the ISO format, but does not disclose whether the tool returns an empty result if no log exists, whether it creates a log if missing, or any side effects. The behavior is simple, though, so a 3 is reasonable.

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

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

The description is a single sentence that is concise and front-loaded: states the action (read), the resource (one day's log), and key constraints (ISO date, default today). No wasted words, but it could include a bit more detail without bloating, so a 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?

For a tool with one parameter and no output schema, the description is thin. It doesn't specify the return format, whether it handles missing dates gracefully, or how it relates to log_entry (sibling). Given the simple scope, it meets minimum viability but leaves gaps that could cause mis-calls when agents need to retrieve logs vs. create entries.

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 for the 'date' parameter. It only specifies ISO format and default today, but lacks details on timezone handling, acceptance of datetime vs date-only, or whether null is allowed (though the schema allows null). This is minimal, so a 2 is appropriate.

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

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

The description clearly states the tool reads a day's log with an optional ISO date, defaulting to today. This is specific and distinct from siblings. However, it does not explicitly differentiate from related tools like log_entry or recent_notes, though the action and resource are clear.

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

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

The context is implied: use when you need to retrieve a daily log, with date format and default behavior mentioned. No explicit guidance on when not to use it or how it compares to alternatives like log_entry or recent_notes, but the description gives enough for basic selection.

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

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

With no annotations, the description carries the burden of explaining behavior. It clearly signals a non-mutating read operation and lists the returned components, including outgoing links as distinct from backlinks. It does not discuss failure modes, but for a simple read tool this is sufficient.

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

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

The description is a single efficient sentence that front-loads the action and immediately lists the returned content. There is no filler or redundancy.

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

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

For a one-parameter read tool with no output schema, the description covers the main outcome and returned fields. However, it omits path semantics and usage guidance, so the definition is minimally viable but not fully complete.

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

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

Schema description coverage is 0%, so the description should compensate by explaining the 'path' parameter. It does not mention path at all, leaving the format (vault-relative, extension, etc.) unspecified. The single parameter is self-named and required, which slightly mitigates the 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 states a clear verb and resource: 'Read one note', and enumerates what is returned (frontmatter, body, tags, outgoing links). It distinguishes itself from list-oriented siblings by emphasizing a single note, though it does not explicitly name any alternative 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?

There is no guidance about when to choose read_note over siblings like search_notes, list_notes, backlinks, or related_notes. The singular 'one note' hints at the intended use, but no exclusion criteria or alternative routing 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?

No annotations are provided, so the description carries the full burden. It discloses the time window and ordering but doesn't mention whether the result is limited to a folder, how the 'days' filter interacts with the 'folder' parameter, whether deleted or archived notes are excluded, or what the return format looks like. For a read tool, this is a moderate gap.

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

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

The description is a single concise sentence that front-loads the core behavior (recency filter) and ordering. It earns its place with no filler, though it could add a brief note about the folder parameter without becoming verbose.

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

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

With no annotations, no output schema, and 0% schema description coverage, the description is too thin. An agent cannot tell whether 'folder' is a filter or a target, what the default behavior is (though defaults exist in the schema), or what the response shape is. For a tool with three parameters, 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 compensate. It explains 'days' (time window) and 'limit' (implicitly via 'newest first' but not explicitly), but it doesn't explain the 'folder' parameter at all. The description adds some meaning for 'days' but leaves 'folder' and 'limit' semantics unclear.

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 ('modified') and resource ('notes') with a clear time window ('last N days') and ordering ('newest first'). It distinguishes itself from siblings like list_notes and stale_notes by focusing on recency, though it doesn't explicitly name an alternative.

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

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

The description implies a use case: retrieving recently modified notes. However, it doesn't explicitly state when to use this tool versus alternatives like list_notes, find_notes, or search_notes, nor does it mention any exclusions or prerequisites.

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

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

The description goes beyond annotations (which are absent) to disclose that the tool is structural only and does no semantic analysis, and that results include a reason for each match. This is important context for the agent to set expectations. It also warns that candidates need manual judgment. This is valuable behavioral disclosure.

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

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

The description is concise, with two sentences contributing to clarity. It front-loads the core purpose and scoring criteria, then adds the behavioral disclaimer. No filler words. It could be slightly clearer on parameter usage, but it's well-structured.

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

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

Given the tool's moderate complexity and lack of output schema and annotations, the description is fairly complete for usage. It covers what it does, how matches are scored, and the limitation. However, it doesn't specify the format of 'path' or whether the result includes the reason in a structured way, which an agent might need. Also, no guidance on how limit affects results, but that's minor.

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

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

Schema description coverage is 0%, so the description must compensate for documenting parameters. It doesn't explicitly explain 'path' or 'limit', but the description implies 'path' is the note identifier and 'limit' is not mentioned at all. Since the schema provides default for limit and names parameters clearly, the description adds minimal value. Score is 3 because schema has defaults and clear type, but description could have clarified path format.

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

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

The description clearly identifies the tool as finding graph neighbours of a note and specifies the scoring criteria (direct links, shared outbound links, shared tags). It distinguishes itself from sibling tools like backlinks (which likely focuses only on direct backlinks) and search tools. However, it doesn't explicitly state the resource type (note) but it's implied by 'note'.

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

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

The description explains the matching logic but does not explicitly say when to use this over alternatives such as backlinks or search tools. The warning about structural-only matching implies it's for graph exploration, but no direct comparison to siblings. The note to 'Judge the candidates yourself' gives some context on expected use, but lacks explicit when-not-to-use guidance.

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

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

With no annotations provided, the description must disclose behavioral traits. It mentions the purpose and subsequent actions but does not explain important behaviors: how random selection works, whether it modifies any state (e.g., marks as reviewed), or if there are any side effects. It does not contradict annotations (none exist), but it fails to disclose potential state changes or selection logic.

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

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

The description is concise and front-loads the core purpose. It is a single sentence for the purpose plus a brief directive on next steps. It is efficient, but the lack of parameter details and depth on usage makes it slightly under-informative for a 3-parameter tool.

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

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

Given the complexity (3 optional params, no output schema, no annotations), the description is incomplete. It misses parameter semantics, any behavioral details like selection randomness or side effects, and doesn't clarify how it differs from related tools like `stale_notes` or `recent_notes`. An agent would struggle to call it correctly.

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

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

Schema description coverage is 0% and the description provides zero explanation of the parameters (count, folder, with_body). The agent has no information on what these control, their formats, or defaults beyond the bare schema. The description's mention of 'Random notes' and linking doesn't connect to the parameters, so the agent is left to guess.

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 ('Random notes pulled up for re-reading') and indicates it is about resurfacing notes for review, distinct from tools like `list_notes` or `stale_notes`. The purpose—revisiting notes to link, sharpen, or archive—is clear, though it doesn't explicitly name alternatives, but the unique framing distinguishes it from siblings.

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

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

The description gives guidance on when to use it: when you want to revisit random notes and take actions (link, sharpen, archive). However, it does not explicitly contrast with siblings like `related_notes` or `distill_queue`, so usage context is implied rather than explicit. It could be clearer about when not to use it, e.g., for targeted searches or when you need specific notes.

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 does disclose that nested tags match (e.g., 'ml' matches 'ml/rl'), which is a useful behavior. However, it doesn't mention case sensitivity, whether the search is exact or partial, or that it's a read-only operation. Given the lack of annotations, more behavioral disclosure would be expected.

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

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

Two sentences, both dense with information. The main action is front-loaded, and the nested-tag nuance is appended without bloat. No filler words.

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

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

Given the presence of multiple sibling search tools and no output schema or annotations, this description is insufficient. It doesn't describe return format, sorting, or how it differs from other search tools. It also leaves parameter semantics partially unexplained.

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% as the description does not explain the parameters. It does partially explain the 'tag' parameter by mentioning frontmatter and inline tags, but doesn't specify format (e.g., with or without '#'). The 'limit' parameter is entirely unexplained, despite having a default.

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 ('Find') and resource ('notes') with a clear condition (carrying a tag). It distinguishes from siblings by focusing on tag-based search, but doesn't explicitly differentiate from similar tools like search_notes or find_notes, so it's not a 5.

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

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

No guidance on when to use this tool vs alternatives like search_notes, search_frontmatter, or find_notes. The description doesn't mention any criteria for selection.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does not reveal whether the search is case-insensitive, whether it only matches exact keys, or what happens when 'value' is null (e.g., finds all notes that have the key regardless of value, or only those with null value). It also doesn't specify the return format or pagination behavior, which is a gap for a search 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 one sentence, extremely concise, and front-loads the main action ('Find notes') and the key concept ('frontmatter key'). It avoids any redundancy or fluff, and every word contributes to understanding the tool's primary functionality.

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

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

Given the complexity (3 parameters, search behavior) and that there is no output schema, the description is somewhat minimal. It covers the basics but misses important details like the behavior when 'value' is null, whether the search is exact-case sensitive, and how results are sorted or limited. For a search tool where precision matters, this is a gap, but it is not fatally 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 compensate. The description effectively explains the 'key' and 'value' parameters (key is the frontmatter key to search, value is an optional exact value to match). It implicitly suggests that 'value' being null might mean 'any value', but it doesn't explicitly define the behavior for null or the 'limit' parameter (though 'limit' is self-explanatory). This adds meaningful context beyond the schema's basic type definitions.

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 ('Find') and resource ('notes'), and clarifies the core behavior: searching by a frontmatter key, with an optional exact value match. This clearly distinguishes it from siblings like 'search_notes' (full-text search) and 'search_by_tag' (tag-based search), though it doesn't name them explicitly.

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

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

The description implies when to use this tool: when you need to find notes based on a specific frontmatter key, potentially with an exact value. However, it does not explicitly state when NOT to use it or mention alternatives such as 'search_notes' for content search or 'search_by_tag' for tags. There is also no guidance on limitations like case-sensitivity or partial matching.

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 burden of behavioral disclosure. It discloses that matching is literal/regex-based ('Plain text matching, no embeddings'), that results include 'surrounding lines,' and that results are excerpts requiring the agent to judge relevance. These details add meaningful behavioral context beyond the schema. It stops short of describing pagination, limits, or error behavior, but the essentials are present.

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

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

The description is two sentences with no filler. The first sentence front-loads the core function and output, and the second sentence adds a practical workflow instruction. 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?

Given five parameters, no schema descriptions, no output schema, and no annotations, the description is incomplete. It explains the search type and points to read_note for follow-up, but it does not explain parameter meanings, result format details beyond 'surrounding lines,' or edge cases. An agent would still need to guess at folder scoping and case sensitivity behavior, making the description insufficient for a fully informed call.

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 mentions 'Literal or regex,' which maps to the regex parameter. It does not explain query, limit, folder, or case_sensitive, leaving the agent to infer their meanings from names and defaults. This is a significant gap given the lack of 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 verb ('search'), a specific resource ('note CONTENT'), and the method ('Literal or regex'), which clearly differentiates it from sibling tools like search_frontmatter and search_by_tag. It also indicates the output includes surrounding lines, making the tool's purpose unmistakable.

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

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

The description implies usage by saying 'Read the excerpts, judge relevance yourself, then `read_note` the ones that matter,' which gives a clear workflow. However, it does not explicitly state when to use this tool versus alternatives like search_frontmatter or search_by_tag, nor does it provide exclusions or conditions. The 'Plain text matching, no embeddings' line hints at a limitation but does not offer a direct alternative.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does state that results are ordered 'oldest first,' which is a behavioral trait, but it does not explicitly indicate that the operation is read-only, describe the output format (e.g., list of note IDs/titles), or mention any side effects or prerequisites. This is a minimal 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 only seven words, which is concise but under-specified. It lacks a complete sentence and omits essential details about the tool's operation and parameters. It is not front-loaded with the most critical information; it simply gives a fragment that could be interpreted in multiple ways.

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

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

Given the tool has three parameters, no output schema, and no annotations, the description is severely incomplete. It fails to explain any parameter, describe the return value, or provide usage context. An agent would have insufficient information to know how to call the tool correctly or what to expect.

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 the parameters. It does not. The phrase 'N+ days' loosely corresponds to the 'days' parameter, but it never explicitly names or explains 'days', 'limit', or 'folder'. The schema itself is the only source of parameter meaning, and the description adds no clarification.

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 'Notes untouched for N+ days, oldest first' clearly identifies the tool's purpose: it retrieves notes that have not been modified for a specified number of days, sorted by age. The term 'untouched' and the ordering criterion effectively distinguish it from siblings like recent_notes or list_notes, though it lacks an explicit verb such as 'list' or 'retrieve'.

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 explicit guidance on when to use this tool over alternatives. The name and description imply it is for finding stale notes, but no comparison to recent_notes or other query tools is provided, and there is no mention of appropriate contexts or exclusions.

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

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

With no annotations, the description carries the full burden. 'Merge' usefully communicates that the operation is additive/updating rather than wholesale replacement of the frontmatter. However, it does not disclose whether frontmatter is created if absent, how nested updates are handled, or what side effects or return values should be expected.

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

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

A single short sentence with no filler. The verb ('Merge') and resource ('YAML frontmatter') are front-loaded, and 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?

For a mutation tool with no annotations, no output schema, and zero schema description coverage, the context is too thin. An agent must infer critical details about the updates object, path resolution, return values, and failure modes.

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

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

Schema description coverage is 0%, so the description must compensate. It implies that updates is the payload of keys to merge and path identifies the note, but it never explicitly defines the path format, the requirement for updates to be an object of key-value pairs, or merge semantics for nested keys.

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—'Merge keys'—and a precise target: 'a note's YAML frontmatter.' This clearly separates it from content-focused siblings like append_to_note and patch_section, though it does not explicitly name alternatives, so it falls just short of a 5.

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

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

There is no explicit guidance about when to use this tool versus alternatives such as create_note, patch_section, or append_to_note. The description implies its niche (frontmatter editing) but provides no exclusions or 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 communicates a read-only diagnostic purpose by listing what the report contains and by framing the output as an aid for choosing maintenance work, not performing it. It does not explicitly state 'read-only' or describe return format, but for a zero-argument health overview the implied behavior is clear.

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

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

Two sentences deliver a concise list of report contents and an actionable use case. The opening metaphor is vivid but immediately followed by concrete metrics, and 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?

For a no-input tool with no output schema, the description fully covers what the report contains and what decision it should inform. An agent can correctly select and invoke vault_health without needing additional context.

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

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

The input schema has zero parameters, so there are no parameter semantics for the description to clarify. The baseline of 4 for no-parameter tools applies, and the description does not introduce any conflicting or confusing parameter-related claims.

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

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

The description names the resource (vault graph health) and enumerates the specific diagnostic categories: undistilled backlog, orphan notes, unresolved links, most-connected hubs, and per-folder counts. It is clear how this differs from siblings like list_notes or stale_notes, though it lacks an explicit imperative verb such as 'show' or 'report'.

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 second sentence gives an explicit usage context: 'Use it to pick the next maintenance job.' This tells the agent when to call the tool. It does not name alternatives or provide exclusions, but the health-report focus is distinct enough to guide selection.

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

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

With no annotations provided, the description carries the full burden of telling an agent what the tool does. 'Describe' strongly implies read-only behavior, and the description helpfully notes the taxonomy is data in .secondbrain/config.json rather than code. However, it does not explicitly state that the call has no side effects, does not mention performance, or clarify how 'method' is derived. The config location is a useful disclosure, but some behavioral traits are left 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?

The description contains only two sentences: the first defines exactly what the tool returns, the second gives usage guidance and a crucial data-source architectural note. Every sentence earns its place, and the guidance is front-loaded before the caveat. No filler or redundancy.

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

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

The scenario is a zero-parameter read-only info tool with no output schema. The description is complete enough: it states what will be returned, when to call it, and where the taxonomy lives. It could add that the call is non-mutating, but that is reasonably inferable from 'describe' and from the strong usage direction, so this counts as a minor 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?

The tool has zero parameters, so the input schema already covers everything. The description adds no parameter-specific semantics, but none are needed. Per the rubric, a zero-param tool gets a baseline of 4, and the description gives enough via the output content to keep it at that level.

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 ('Describe') and resource ('the vault') and enumerates distinct outputs: root path, folder taxonomy, note counts, method. This clearly separates it from sibling tools like vault_health, which likely focuses on health checks, and from note/crud tools that operate on notes rather than vault structure.

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 this first in a session so you know the structure you are writing into.' This tells the agent to invoke it before mutations show up. It does not name any alternative tool, but none of the siblings serve the same purpose, so the lack of explicit exclusions is not a significant gap.

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