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 that a leading newline is added (from schema) but does not mention whether the operation is destructive, if authentication is needed, or any side effects (e.g., whether it creates the note if missing). For a write operation, this is insufficient.

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, informative sentences. The first sentence states the core purpose; the second provides a typical use case. No wasted words or redundancy. Front-loaded 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?

Given no output schema, no annotations, and a rich set of sibling tools, the description lacks completeness. It does not explain behavior when the target note does not exist, whether appending is idempotent, or how it interacts with other tools (e.g., get_daily_note). The description is minimal and leaves many questions unanswered.

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 50% (content has description, period has enum but no description). The description adds that the note is 'current' and that other periods are possible ('or weekly/etc.'), which clarifies the period parameter. For content, it repeats 'markdown' but adds no new detail beyond schema. Overall, it partially compensates for the schema gap 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 the action ('append markdown') and the target resource ('current daily note', with parenthetical mention of weekly etc.). It distinguishes itself from siblings like append_to_note by specifying the period note context, and provides a concrete use case ('agent logs what it just did at the end of the day').

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 common usage pattern (logging at end of day), which gives context for when to use. However, it does not explicitly state when not to use this tool versus alternatives like append_to_note or create_note, nor does it list prerequisites 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?

No annotations provided, so description carries full burden. Discloses append-to-end and auto-create behavior, but omits details like idempotency, path format, or error conditions. Adequate but not exhaustive.

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?

Single, front-loaded sentence with no wasted words. Every phrase ('append markdown', 'end of existing note', 'creates if doesn't exist') adds value.

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

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

For a simple tool with 2 flat params and no output schema, description covers purpose and key behavior. Could mention path resolution or error handling, but overall sufficient.

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 has 0% description coverage and only two params. Description adds that content is markdown and path identifies the note, but doesn't elaborate on path format or constraints. Baseline 3 due to low coverage, with slight added 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?

Description clearly states the action (append), the resource (note), and the scope (markdown, end of note). Distinguishes from siblings like 'create_note' and 'update_note' by specifying append behavior and auto-creation when missing.

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

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

Description implies use case (adding content to end of note) but lacks explicit when-to-use or when-not-to-use guidance. No mention of alternatives or exclusions, e.g., vs 'upsert_note' or 'update_note'.

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?

Discloses key behaviors: overwrite flag to replace existing, frontmatter rendering as YAML, links appended as wiki-links. Lacks error handling details and return value info, but no annotations provided so description bears full burden.

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, front-loaded with core behavior, then details, then alternatives. No wasted words.

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

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

Covers main aspects given 5 params and no output schema. Lacks return value description but schema doesn't define output; mentions failure condition. Could mention read-only implications or permissions, but not required.

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?

Adds some value beyond schema: clarifies overwrite behavior and frontmatter rendering. However, schema already describes parameters well (80% coverage noted), and description mostly reiterates schema info.

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

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

Clearly states the tool creates a new note, with specific details (fails if exists unless overwrite, YAML frontmatter, wiki-links section). Explicitly distinguishes from siblings create_notes and upsert_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?

Explicitly provides when to use this tool (single note creation) and when to use alternatives (create_notes for batch, upsert_note for idempotent writes). No ambiguity.

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 covers per-note error reporting, the stop_on_error parameter behavior, and intra-batch path conflict handling. It does not mention atomicity or other side effects, but these are reasonably inferred.

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 concise sentences, front-loaded with purpose, then use case, then behavioral details. No wasted words.

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

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

While the description explains error handling, it does not specify the response format (e.g., array of results). Given the lack of an output schema, this omission creates a slight ambiguity for the 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 coverage is 100%, but the description adds value by explaining the batch context (e.g., each entry follows create_note schema, path conflicts within batch). It clarifies stop_on_error beyond the schema 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 description clearly states it creates multiple notes in one call, specifically for bootstrapping a knowledge graph, distinguishing it from the single-note sibling 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 a clear use case (bootstrapping a knowledge graph) and explains error handling options (stop_on_error). It implicitly contrasts with create_note but does not explicitly list 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?

The description labels the tool as 'Destructive,' which is a useful behavioral trait. Without annotations, this is the primary disclosure. However, it lacks details on permanence, undo options, or permission requirements.

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

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

The description is extremely concise with two sentences. The first sentence states the action, and the second provides a crucial warning. No unnecessary 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?

For a simple delete tool with one parameter and no output schema, the description adequately covers the purpose and destructive nature. It could add more context about permanence or effects on linked resources, but overall it is sufficient.

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

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

The input schema has 100% coverage for the single parameter 'path,' describing it as 'Vault-relative path.' The description does not add any additional meaning beyond the schema, so it meets the baseline but does not exceed it.

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

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

The description clearly states 'Delete a note from the vault,' using a specific verb and resource. It distinguishes itself from sibling tools like create_note or update_note by focusing on deletion.

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

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

The description explicitly says 'only call when the user has explicitly asked to remove a file,' providing a clear condition for use. However, it does not mention alternatives or when not to use it beyond that condition.

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

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

No annotations exist, so the description must cover behavioral details. It only states 'find' which implies read-only, but does not disclose performance implications, permissions, or what happens with no broken links. The description is too brief for a vault-scanning tool.

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

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

The description is two sentences, front-loads the purpose, and contains no superfluous text. 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 three parameters and no output schema, the description should explain parameter semantics and return format. It fails to do so, leaving the agent guessing about 'limit' and 'sample_size' and the structure of results.

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 does not explain any of the three parameters (folder, limit, sample_size). It adds no meaning beyond the schema, leaving the agent without guidance on parameter usage.

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

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

The description clearly states the verb 'find' and the resource 'broken links' (wiki-links and markdown links that don't resolve). It also suggests use cases ('vault hygiene' and 'before refactoring note titles'), distinguishing it from siblings like find_orphans.

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 provides two concrete use cases for when to use the tool, offering clear context. However, it does not explicitly state when not to use or mention alternatives, so it lacks exclusion 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?

No annotations are provided, and the description fails to disclose important behavioral traits such as idempotency, potential performance impact of scanning many notes, or whether it only considers links within the vault. The tool's read-only nature is implied but not stated.

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 with zero redundancy. The first sentence gives the core purpose, and the second provides a usage hint. Front-loaded 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?

For a tool with 3 parameters and no output schema, the description is too brief. It doesn't explain the output format, how 'orphan' is precisely defined (e.g., notes with no incoming links at all, or within certain limits?), or how scope is affected by folder and sample_size. Missing details that would help an agent anticipate results.

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 67%; the folder and sample_size parameters have useful descriptions, but the limit parameter lacks semantic explanation beyond default and constraints. The description adds marginal value over the schema, but the uncovered limit parameter reduces the score.

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

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

The description clearly states the verb 'Find' and the specific resource 'notes with no incoming links'. It adds purpose context with 'surface forgotten ideas or candidates for cleanup', and differentiates from sibling tools like find_broken_links and get_backlinks.

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 use case ('surface forgotten ideas or cleanup candidates') but lacks explicit guidance on when not to use this tool versus alternatives like find_broken_links or traverse_graph. No exclusions or context for when to prefer other tools.

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

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

With no annotations, the description carries full burden for behavioral disclosure. It fails to mention what happens if no note is open, or any edge cases. The simple read operation is implied but not fully transparent.

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

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

Two sentences, front-loaded with core purpose, no extraneous words. 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?

Adequate for a simple read operation, but missing return value description (path, content, name?). Without output schema, the description should hint at what the response contains.

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

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

No parameters exist, and schema description coverage is 100% (since empty). The description adds no param info, but baseline for zero-parameter tools is 4. No additional meaning needed.

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

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

Description clearly states the tool returns the note currently focused in Obsidian, using specific verb ('Return') and resource ('note') with condition ('currently focused'). It distinguishes from siblings like get_note which require identifiers.

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

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

Explicitly mentions usefulness for 'what am I looking at' prompts, providing clear usage context. However, no explicit when-not-to-use or alternatives are given, though the tool's simplicity and zero parameters make it straightforward.

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 provided, and the description implies a read-only operation by 'return notes,' but does not explicitly state safety, authentication needs, or other behavioral traits.

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 concise sentences front-loaded with essential information, no redundant content.

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

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

For a simple tool without output schema, the description adequately conveys that it returns notes with snippets. Slight gap in not specifying return structure, but generally sufficient.

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 50% (path described, limit not). The description only mentions 'given path,' adding no extra meaning for limit. It fails to compensate for the missing schema 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 description clearly states the tool returns notes linking to a given path with snippets, and distinguishes itself from get_note by noting it provides the same data as the backlinks field.

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

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

Explicitly advises using this when only backlinks are needed, indirectly suggesting get_note for full note data. No explicit when-not-to-use, but context is clear.

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

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

No annotations provided, so the description discloses output structure (content, frontmatter, tags) and a key prerequisite (plugin requirement). It does not explicitly state read-only behavior, but fetching implies it. Good disclosure for a simple 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 very concise, with three short sentences each providing distinct value: purpose, return format, and requirement. No wasted words.

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

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

For a simple tool with one parameter and no output schema, the description covers the essential aspects: what it does, what it returns, and a prerequisite. It could mention error behavior or fallback, but overall it is adequately 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 coverage is 100% with enum and description for the parameter. The tool description does not add additional meaning beyond what the schema already provides, so baseline score of 3 is appropriate.

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

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

The description clearly states the tool fetches a periodic note (daily, weekly, etc.) and distinguishes it from generic get_note or get_active_note by specifying the plugin requirement and periodic nature.

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 mentions the plugin requirement but does not explicitly guide the agent on when to use this tool versus siblings like get_note or when not to use it. Implied usage is clear but no exclusions or alternatives are named.

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. It discloses the performance cost of backlinks and implies read-only behavior, but doesn't mention error cases, return format, or permissions.

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 concise sentences: first states purpose and components, second provides critical usage guidance. Every sentence is informative with no redundancy.

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

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

Given 3 parameters and no output schema, the description adequately covers purpose, key parameter behavior, and return structure hints. Missing details like error handling or path existence prerequisites, but acceptable for a read-like 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 descriptions cover 67% of parameters (path and include). The description adds value by explaining the purpose of `include` and its performance impact, but the `backlinks_limit` parameter lacks explicit behavioral meaning beyond 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 clearly states 'Get a note's content plus its graph context' with specific components (backlinks, forward links, tags, frontmatter). This differentiates it from siblings like get_backlinks or get_active_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?

It advises using the `include` array to control fetched context and warns that backlinks are expensive, giving practical when-to-use guidance. However, it doesn't explicitly exclude alternatives or mention when not to use this tool.

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

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

With no annotations, the description carries the full burden. It discloses that the tool returns heading structure and is token-efficient, implying a read-only nature. It could be more explicit about being read-only, but the information 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 two sentences, front-loading the core functionality and then providing usage guidance. Every sentence adds value with no redundancy.

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

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

For a simple tool with one parameter and no output schema, the description adequately covers purpose, usage, and return format. The mention of specific heading details compensates for the absence of an 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 single parameter `path` has a schema description ('Vault-relative path.') that already covers its meaning. The description adds no extra detail beyond the schema, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool returns the heading structure with specific details (level, text, line number) and explicitly contrasts with `get_note`, demonstrating strong purpose clarity and sibling differentiation.

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

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

The description provides explicit guidance: use this tool instead of `get_note` when you only need to navigate to a section of a long note, citing token efficiency as a rationale.

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?

Discloses that word count is sampled ('total words (sampled)'), indicating non-exact behavior. No annotations exist, so description carries burden. Does not mention potential performance or limits, but for a read-only stats tool this is acceptable.

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: first defines what the tool returns, second provides usage context. No wasted words, front-loaded with key 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?

Lists return fields (notes, words, folders, extensions) despite no output schema. Could mention format, but given simplicity, it is sufficient for an agent to understand 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 coverage is 50% (sample_size described). Description adds no extra meaning for parameters; top_folders is left entirely unexplained. Agent must infer its meaning from context, increasing cognitive 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?

Description explicitly states it fetches high-level vault stats (total notes, sampled word count, top folders, file extensions) and gives example prompts, clearly differentiating from all sibling tools which focus on individual notes or actions.

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

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

Provides clear usage prompts ('how big is my vault?' etc.) implying when to use this tool. No explicit when-not-to or alternatives are given, but the sibling set has no competing tool for vault statistics.

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 provided, so description carries full burden. It is adequate for a list operation, stating it returns commands with id and name. Does not explicitly declare read-only or mention potential side effects, but being a list, side effects are unlikely.

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, no filler, front-loaded with main purpose. 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 no output schema, the description appropriately mentions the return fields (id and human name). Sufficient for an agent to understand and use 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 50% (filter described, limit only has constraints). The description adds no parameter information beyond the schema. While not detrimental, it could have explained limit's role.

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

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

The description clearly states the verb ('list'), resource ('every registered Obsidian command'), and output ('id and human name'). It distinguishes from sibling tool `run_command` by explicitly recommending its use before that.

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

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

Provides explicit when to use ('before `run_command`') and why ('vaults differ'). Could also mention when not to use or if alternatives exist, but the guidance is strong for its primary use case.

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

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

No annotations are provided, so the description carries the burden. It implies a read-only operation (returning data) and outlines the output shape. However, it does not discuss performance implications or limitations (e.g., scanning up to sample_size notes), which are only hinted by the parameter descriptions.

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

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

The description is two sentences long with no filler. The first sentence immediately states the core function and output, followed by a succinct use-case sentence. Every word contributes 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?

The description covers what the tool does and provides usage context. It mentions the output shape (counts and sample notes) even though no output schema exists. However, it does not specify ordering or aggregation details, which could be helpful for an agent expecting raw data.

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 67% (2 of 3 parameters have descriptions). The tool description adds no meaning beyond the schema; it does not explain or paraphrase any parameter. The third parameter ('sample_notes_per_tag') lacks a schema description and is not addressed in the tool description either.

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 resource ('tags'), and clearly states what is included: usage counts and a sample of notes per tag. It distinguishes this tool from siblings like 'search_vault' by focusing on an aggregated view of all tags.

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 concrete use cases: 'what topics do I write about most?' and as a starting point for organizing. While it does not explicitly mention when not to use or alternatives, the use cases are clear and sufficient 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?

No annotations are provided, so the description must convey behavior. It only says 'List all files' without disclosing return format, side effects, permissions, or limits beyond what the schema provides.

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 a single sentence plus a command-like suggestion. Every part is valuable and 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 three parameters and no output schema, the description covers the basic purpose and parameter usage but omits details about return format, pagination, or behavior with the limit 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?

Schema coverage is 100%, so the description adds minimal new meaning beyond restating the schema's parameter descriptions (e.g., folder for scoping, markdown_only for filtering).

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 files in the vault, with a specific verb and resource. It mentions two parameters for scoping, but does not explicitly differentiate from sibling tools like search_vault.

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 advises using folder and markdown_only parameters and prefers this over guessing paths, but lacks explicit guidance on when to use this tool instead of alternatives like search_vault, get_note, etc.

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 full responsibility. It discloses backlink rewriting and safe behavior, but omits side effects like file system changes, error handling when from path does not exist, or whether the operation is atomic. This is adequate but not comprehensive.

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 with no fluff. The first sentence states the function, the second provides a critical guideline. Information is front-loaded and each sentence earns its place.

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

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

The tool has 4 parameters and no output schema, but the description does not explain return behavior, error cases, or success confirmation. Given the complexity of moving notes (affecting backlinks and paths), the description is slightly incomplete, though the schema covers parameter details.

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

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

Input schema has 100% coverage with descriptions for all parameters. The description adds no additional parameter-specific details beyond mentioning 'rewriting wiki-links', which aligns with the update_backlinks parameter. Baseline 3 is appropriate.

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

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

The title and description clearly state the tool moves or renames notes with backlink updates. It distinguishes itself from destructive alternatives by explicitly advising against naive delete+create, showing it is the safe rename operation.

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

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

The description explicitly says this is 'the safe way to rename notes' and warns against 'delete + create' because it breaks the graph. It implies when to use (rename) and when not to (destructive moves), but lacks explicit mention of other sibling tools like update_note or patch_note for partial edits.

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?

Despite no annotations, the description details the behavior: it surfaces a note by focusing an existing tab or opening a new one, which is sufficient for a simple UI action. No hidden side effects are mentioned, but none are 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, front-loaded with the core action, no unnecessary words. 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?

For a simple tool with two parameters and no output schema, the description covers the behavior and usage context adequately. It could mention output (e.g., no return value), but the behavior is clear.

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

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

Schema coverage is 100%, so parameters are fully documented in the schema. The description repeats the schema info ('Vault-relative path', 'open in a new tab') without adding additional meaning, meeting the baseline.

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

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

The description clearly states the tool surfaces a note in Obsidian's workspace, specifying it focuses an existing tab or opens a new one. This distinguishes it from siblings like get_note (content retrieval) or list_vault (listing).

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 context: 'Great for ending an agent task with 'and here's the result for you to review.'' This tells the agent when to use it, though it 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, the description bears full behavioral responsibility. It notes that the tool does not rewrite the whole note, which is useful. However, it lacks details like whether missing targets are created, error handling, or permissions, leaving gaps in transparency.

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 concise sentences front-load the purpose and include a helpful example. Every word contributes, and no unnecessary details are present.

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 5 required parameters, 2 enums, no output schema, and no annotations, the description is too brief. It omits return values, error behavior, and what happens if the target doesn't exist, making it incomplete for full understanding.

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 60%, and the schema already describes most parameters. The description adds a concrete example showing parameter usage, but does not elaborate on values or edge cases, providing only modest added 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 inserts content relative to a heading, block, or frontmatter field without rewriting the whole note. It uses a specific verb and resource, and the example differentiates it from full-note rewriting tools like update_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 when to use (targeted insertion without rewriting whole note) and gives a concrete example. However, it does not explicitly state when not to use it or compare with siblings like append_to_note or update_note, leaving some ambiguity.

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 full burden. It implies read-only behavior by calling it a query, but does not explicitly confirm no side effects, performance characteristics, or error handling (e.g., if plugin missing). The plugin requirement is noted, which is helpful.

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 efficiently convey purpose, prerequisite, and usage. No redundancy or unnecessary detail. Front-loaded with the core action.

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

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

The description covers purpose and prerequisite but omits any mention of return values or output format. Since there is no output schema, the description should ideally indicate what the tool returns (e.g., matching notes). The example is helpful but 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?

With 100% schema coverage, the description adds value by giving a concrete example of the dql parameter. This clarifies the expected format beyond the schema's generic 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 description clearly states the tool runs Dataview DQL queries (LIST/TABLE/TASK), specifies the resource ('vault'), and provides an example. This distinguishes it from sibling tools like search_vault, which are not Dataview-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?

The description mentions the prerequisite (Dataview plugin installed) and gives a use case example. However, it does not explicitly state when not to use it or suggest alternatives, though no direct alternative exists among siblings.

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 exist, so the description carries full burden. It warns that the tool is powerful and triggers any plugin action, but does not disclose potential side effects, error states, or destructive behavior beyond the approval note.

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 concise sentences: first states action and examples, second adds important context about power and approval. No fluff.

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

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

Given the tool's simplicity (1 param, no output schema), the description covers purpose, parameter format, and discovery method. It does not explain return value or error handling, but is largely complete.

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

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

Schema description coverage is 100% for the single parameter, but the description adds concrete examples (e.g., 'app:reload', 'graph:open') beyond the schema's 'e.g. workspace:close', adding 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 executes an Obsidian command by ID, with specific examples like 'editor:toggle-bold'. It mentions discovering IDs via `list_commands`, distinguishing 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 provides a clear use case and warns to use only approved commands. It references `list_commands` for discovery, but lacks explicit when-not-to-use or alternative 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?

No annotations are provided, but the description does not disclose behavioral traits beyond the modes. It doesn't mention pagination, output format, or side effects. For a read-only search tool, this is adequate but minimal.

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

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

Two sentences, front-loaded with purpose, no wasted words. 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?

Given the tool's simplicity and no output schema, the description is nearly complete. It lacks mention of the return format or pagination behavior, but the essential information for usage is present.

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

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

The description adds meaning beyond the schema by explaining tag mode requires omitting the '#' and noting keyword mode is fast. Schema coverage is 75%; the missing description for 'limit' is not addressed, but overall the description enhances 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 clearly states it performs full-text search across all notes, specifies two distinct modes (keyword and tag), and distinguishes itself from the sibling `query_dataview` tool for structured queries.

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 describes when to use each mode and directs users to `query_dataview` for structured queries, providing clear guidance on tool 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 carries full responsibility. It discloses that the tool returns nodes and edges, supports depth and direction limits, and includes a cap for large vaults. It lacks an explicit statement that the tool is read-only, but the verbs 'walk' and 'returns' imply no side effects.

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

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

The description is concise, consisting of two tightly written sentences. It front-loads the purpose, uses inline code formatting for parameters, and every sentence contributes essential 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?

While the description covers key behaviors and usage, it lacks a detailed output structure description, especially since no output schema is provided. It only says 'returns nodes and edges' without specifying the format or whether the starting note is included. This gap reduces completeness for a tool with moderate complexity.

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

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

The schema description coverage is 60%, and the description adds meaning by explaining the direction parameter values and the role of max_nodes. It does not elaborate on depth or include_snippets beyond what the schema provides, but the added context for direction and capping compensates.

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

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

The description clearly states the tool's purpose: walking the link graph from a starting note, returning nodes and edges. It uses a specific verb 'traverse' and distinguishes from sibling tools like get_backlinks or search_vault by focusing on graph traversal.

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

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

The description provides explicit guidance on when to use each direction value (both, forward, backward) and mentions capping with max_nodes. It does not explicitly state when not to use this tool in favor of alternatives, but the context of sibling tools makes the distinction clear.

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

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

Without annotations, the description carries full burden. It notes the tool is 'destructive' (overwrites full content), which is the key behavioral trait. However, it does not detail other aspects like permission requirements or side effects, but the main concern 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 sentences, no wasteful words. The main action is front-loaded, and each sentence provides essential 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 simple mutation tool, the description covers the operation, usage guidelines, and destructive nature. No output schema is needed for a straightforward write action. The tool is well-specified given its complexity.

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

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

Schema description coverage is 0%, so description must compensate. The parameters 'path' and 'content' are self-explanatory from context: path is the note location, content is the new text. The description adds the meaning of overwriting, but does not specify 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 title 'Replace a note's content' and description 'Overwrite a note's full content' clearly state the verb and resource. It distinguishes from siblings by explicitly naming 'append_to_note' and 'patch_note' as alternatives for non-destructive updates.

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

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

The description explicitly advises when to use this tool vs alternatives: 'Prefer `append_to_note` or `patch_note` when only adding to a note — replacing wholesale is destructive.' This gives clear context 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?

No annotations provided, but description fully discloses replacement behavior: body always replaced, frontmatter replaced by default with merge option. Also mentions idempotency. This compensates for lack of annotations.

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

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

Two sentences, front-loaded with core functionality. No wasted words.

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

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

Given 5 parameters (one required) and no output schema, the description covers essential behavior, idempotency, and differentiation from siblings. No gaps identified.

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

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

Input schema has 100% coverage with descriptions for each parameter. Description adds context for merge_frontmatter behavior (merging vs replacing), which adds value beyond schema. However, schema already provides adequate descriptions, so a slight deduction is warranted.

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

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

Clearly states 'Create a note if missing, replace it if it exists.' Uses specific verb (upsert) and resource (note). Distinguishes from sibling tools by contrasting with create_note and update_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?

Explicitly tells the agent to use this for idempotent writes, and states that create_note and update_note do not handle that case. Provides clear when-to-use and alternatives.

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