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 effectively describes key behaviors: tags are added to frontmatter (not content), hierarchical structures are supported, duplicates are automatically prevented, and it returns the updated tag list. However, it doesn't mention error conditions, permission requirements, or rate limits.

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 well-structured with clear sections (purpose, when to use, tag format, when not to use, returns) and every sentence adds value. There's no redundant information, and the most important information (what the tool does) is presented first.

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 and no output schema, the description does an excellent job covering purpose, usage guidelines, parameter semantics, and behavioral traits. The main gap is the lack of explicit error handling information or permission requirements, which would be helpful for a tool that modifies notes.

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 67% schema description coverage (2 of 3 parameters documented in schema), the description adds valuable context about tag format (simple vs. hierarchical) and the automatic handling of duplicates. While it doesn't explicitly discuss the 'path' parameter or the optional 'ctx' parameter, it provides meaningful semantic information about the core 'tags' parameter beyond what the schema offers.

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 specific action ('Add tags') and target ('to a note's frontmatter'), distinguishing it from sibling tools like update_note (for content) and update_tags (for replacement). It provides a precise verb+resource combination that leaves no ambiguity about the tool's function.

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 includes explicit 'When to use' and 'When NOT to use' sections with clear alternatives named (update_note for content tagging, update_tags with merge=False for replacement). This provides comprehensive guidance on when to select this tool versus other available options.

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

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

With no annotations provided, the description carries the full burden. It discloses key behavioral traits: it's a mutation tool (implied by 'update'), handles bulk operations, supports specific search criteria, manages frontmatter and tags with deduplication, and includes error handling (shown in the return structure). However, it doesn't mention permissions, rate limits, or irreversible changes, leaving some gaps.

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 well-structured with clear sections (purpose, usage guidelines, search criteria, property operations, examples, exclusions, returns) and every sentence adds value. It's front-loaded with the core purpose and efficiently uses bullet points and examples without redundancy.

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

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

Given the tool's complexity (7 parameters, mutation operations, no annotations, no output schema), the description is largely complete. It covers purpose, usage, parameters, and return values in detail. However, it lacks explicit mention of behavioral risks (e.g., data loss potential) and doesn't explain the 'ctx' parameter, leaving 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?

Schema description coverage is low (29%), but the description compensates well by explaining parameter semantics in 'Search criteria options' and 'Property operations' sections. It clarifies the purpose of 'search_criteria', 'property_updates', 'add_tags', 'remove_tags', and 'remove_inline_tags', though it doesn't cover all 7 parameters (e.g., 'ctx' is unexplained).

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 with specific verbs ('batch update properties across multiple notes') and distinguishes it from sibling tools like 'update_note_tool' for single-note updates. It explicitly names the resource (notes) and scope (batch operations).

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

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

The description provides explicit 'When to use' scenarios with concrete examples (e.g., archiving projects, bulk tag operations) and a 'When NOT to use' section that names specific alternatives ('use update_note, add_tags, etc.'). This clearly guides the agent on when to choose this tool over 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?

With no annotations provided, the description carries full burden and does well by disclosing key behaviors: it creates all necessary parent folders (with a concrete example), mentions placeholder file creation, and describes the return format. It doesn't cover potential errors, permissions, or rate limits, but provides substantial operational context.

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 efficiently structured with clear sections (purpose, usage guidelines, note, returns), each sentence adds value, and it's appropriately sized for a tool with behavioral complexity. No wasted words while maintaining completeness.

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 and no output schema, the description provides good coverage: clear purpose, usage guidelines, behavioral details, and return format description. It could mention error conditions or permissions, but addresses most critical aspects given the 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?

With 67% schema description coverage (2 of 3 parameters documented), the description adds meaningful context beyond the schema. It explains the parent-folder creation behavior for 'folder_path' and mentions placeholder files which relates to 'create_placeholder', though it doesn't address the undocumented 'ctx' parameter. This compensates well for the coverage gap.

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

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

The description clearly states the specific action ('Create a new folder in the vault') and resource ('folder'), including the key behavioral trait of creating parent folders. It distinguishes from sibling tools like 'create_note_tool' by focusing exclusively on folder creation rather than note creation.

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 'When to use' and 'When NOT to use' sections with concrete scenarios, including a direct alternative ('create notes directly') and a specific sibling tool scenario ('folders are created automatically' with create_note_tool). This gives 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?

With no annotations provided, the description carries full burden and does well by disclosing key behavioral traits: it can overwrite/delete existing content (destructive potential), mentions 'use carefully' for overwrite parameter, and describes the return format ('Created note information with path and metadata'). It doesn't cover rate limits or authentication needs, but provides solid operational context.

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 perfectly structured with clear sections (purpose, when to use, when not to use, returns), front-loads the core functionality, and every sentence adds value. No wasted words while maintaining completeness.

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 and no output schema, the description provides excellent context about behavior, usage boundaries, and return values. It covers the destructive potential of overwrite and distinguishes from alternatives. The main gap is lack of explicit error handling or permission requirements, but otherwise quite 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?

With 75% schema description coverage, the description adds meaningful context beyond the schema. While it doesn't detail individual parameters, it explains the tool's overall behavior with parameters (creating/overwriting notes, setting up templates) that helps understand how parameters work together. The 'Returns' section also provides output context not in the 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 the tool's purpose with specific verbs ('create' and 'overwrite') and resource ('note'), distinguishing it from siblings like update_note_tool. It explicitly mentions both creation and replacement functionality, which is more specific than just 'create'.

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 'When to use' and 'When NOT to use' sections with clear alternatives named (update_note with specific strategies). It distinguishes this tool from update_note_tool for complete replacements versus partial updates.

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

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

With no annotations provided, the description carries full burden and does well by disclosing critical behavioral traits: it's a destructive operation ('permanently deleted'), has no undo capability, and includes a warning about irreversibility. It also mentions the return format (confirmation with path), though it could elaborate on error cases 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?

The description is well-structured with clear sections (purpose, usage guidelines, warnings, returns), front-loaded with the core action, and every sentence adds value without redundancy. It's appropriately sized for a destructive tool needing careful explanation.

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

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

For a destructive tool with no annotations and no output schema, the description does a good job covering purpose, usage, warnings, and return values. It could be more complete by detailing error scenarios (e.g., what happens if the path doesn't exist) or auth requirements, but it's largely sufficient given the 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 50% (only 'path' has a description, 'ctx' is undocumented). The description doesn't add parameter-specific details beyond what's in the schema for 'path', and doesn't explain the 'ctx' parameter at all. Baseline 3 is appropriate as the schema covers half the parameters adequately.

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 specific action ('Delete a note from the vault permanently') with the resource ('note'), distinguishing it from siblings like move_note_tool or archive operations. It explicitly mentions permanent deletion, which differentiates it from temporary removal or archiving 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 provides explicit 'When to use' scenarios (removing outdated notes, cleaning drafts, move operations) and 'When NOT to use' guidance (archiving, temporary removal), including a named alternative (move_note to Archive folder). This gives clear context for when to choose this tool over 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: section identification rules (case-insensitive, first match, content boundaries), operations (insert_after, insert_before, replace, append_to_section), and the create_if_missing option. However, it lacks details on error handling, permissions, or rate limits, which are relevant for a mutation tool. The description does not contradict any annotations, as none 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 well-structured with clear sections (purpose, usage guidelines, section identification, operations, returns), each sentence adds value, and it avoids redundancy. It is appropriately sized for a tool with 6 parameters and complex behavior, front-loading the core purpose and usage guidelines for quick comprehension.

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 complexity (6 parameters, mutation operation, no annotations, no output schema), the description is largely complete: it covers purpose, usage, behavioral rules, and parameter semantics. However, it lacks output details (only mentions 'Edit status' vaguely) and doesn't address potential errors or side effects, which are important for a tool that modifies notes. This minor gap prevents a perfect score.

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

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

The schema description coverage is high (83%), so the baseline is 3. The description adds meaningful context beyond the schema: it explains how 'section_identifier' works with markdown headings and matching rules, clarifies the 'operation' options with practical examples, and mentions the 'create_if_missing' behavior. This compensates for the 17% coverage gap and provides valuable semantic understanding, though it doesn't detail all parameters (e.g., 'ctx' is unexplained).

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 starts with a clear, specific statement: 'Edit a specific section of a note identified by a markdown heading.' This explicitly states the verb ('edit'), resource ('specific section of a note'), and mechanism ('identified by a markdown heading'), distinguishing it from sibling tools like update_note_tool or create_note_tool. The purpose is unambiguous and well-articulated.

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 includes explicit 'When to use' and 'When NOT to use' sections, listing four use cases and three exclusions with named alternatives (e.g., 'use update_note with merge_strategy='append''). This provides clear, actionable guidance on when to select this tool over its siblings, such as update_note_tool for whole-note edits or create_note_tool for new 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?

With no annotations provided, the description carries the full burden. It describes what the tool does (finds broken links) and the scope, but lacks details on behavioral traits like performance implications, error handling, or output format beyond 'All broken links found'. It doesn't mention whether this is a read-only operation or has side effects, though 'find' implies read-only.

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 well-structured with clear sections (purpose, when to use, when not to use, returns) and uses bullet points for readability. Every sentence adds value without redundancy, making it efficient and easy to parse.

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

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

Given the complexity (3 parameters, no annotations, no output schema), the description does a good job covering purpose, usage guidelines, and high-level parameter semantics. However, it lacks details on the output format (beyond 'All broken links found') and doesn't address potential behavioral aspects like performance or errors, leaving some gaps for a tool with 3 parameters.

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 the scope parameters ('vault, a specific directory, or a single note'), which aligns with the 'directory' and 'single_note' parameters. However, it doesn't explicitly mention the 'ctx' parameter or provide detailed examples of parameter usage beyond the high-level scope 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's purpose with specific verb ('find') and resource ('broken links'), and distinguishes it from siblings by mentioning alternatives like get_outgoing_links and get_backlinks. It explicitly defines the scope ('in the vault, a specific directory, or a single note'), making it highly 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 includes explicit 'When to use' and 'When NOT to use' sections with concrete scenarios (e.g., 'After renaming or deleting notes', 'Regular vault maintenance') and named alternatives (get_outgoing_links, get_backlinks). This provides comprehensive guidance on when to select this tool versus others.

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

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

With no annotations provided, the description carries the full burden and does so well. It discloses performance characteristics ('Scans entire vault', 'may take 10-30 seconds for vaults >1000 notes'), default exclusions (e.g., 'Templates folder'), and what the tool returns (list of notes with metadata). It doesn't contradict any 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?

The description is well-structured with clear sections (e.g., 'When to use', 'Orphan types explained', 'Performance note'), front-loaded key information, and every sentence adds value without redundancy. It's appropriately sized for the tool's complexity.

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

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

Given the tool's complexity (4 parameters, no annotations, no output schema), the description is highly complete. It covers purpose, usage, parameters, behavior, performance, exclusions, and includes an example response, providing all necessary context for an agent to use it effectively.

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 low (25%), but the description compensates by explaining 'orphan types' in detail (e.g., 'no_backlinks: Notes with no incoming links'), clarifying 'default exclusions' (e.g., 'Templates folder'), and mentioning 'min_age_days' context ('Helps exclude recent work-in-progress'). It adds meaningful context beyond the 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 the tool's purpose with specific verb ('Find') and resource ('orphaned notes'), and distinguishes it from siblings by explaining what makes notes 'orphaned' (e.g., 'no_backlinks', 'no_links'). It explicitly differentiates from tools like 'search_notes' and 'list_notes'.

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

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

The description provides explicit guidance on when to use (e.g., 'Regular vault maintenance and cleanup', 'Finding forgotten or disconnected notes') and when NOT to use (e.g., 'Finding specific notes (use search_notes)', 'Getting all notes in a folder (use list_notes)'), including clear alternatives.

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

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

With no annotations provided, the description carries full burden and does well by disclosing performance characteristics ('Fast for small vaults', 'May take several seconds for large vaults') and return format information ('All notes linking to the target with optional context'). It doesn't mention authentication needs or rate limits, but provides useful operational context.

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 well-structured with clear sections (purpose, when to use, when not to use, performance note, returns) and each sentence adds value. It could be slightly more concise by combining some usage scenarios, but overall it's efficiently organized and front-loaded with the core purpose.

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 no annotations and no output schema, the description provides good context about performance, usage scenarios, and return format. It covers the essential behavioral aspects and distinguishes from alternatives. The main gap is lack of output structure details, but given the tool's relative simplicity, the description is reasonably 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 75%, and the description doesn't add significant parameter information beyond what's in the schema. The 'Returns' section mentions 'optional context' which relates to the include_context parameter, but doesn't explain the 'ctx' parameter or add meaningful semantics beyond the schema's descriptions. Baseline 3 is appropriate given the decent schema coverage.

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

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

The description clearly states the tool's purpose with a specific verb ('Find') and resource ('all notes that link to a specific note'), and explicitly distinguishes it from sibling tools like get_outgoing_links and find_broken_links. The opening sentence 'Find all notes that link to a specific note (backlinks)' is precise and unambiguous.

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

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

The description provides explicit 'When to use' and 'When NOT to use' sections with clear alternatives named (get_outgoing_links, find_broken_links, search_notes). It gives specific scenarios for usage and explicitly tells the agent when to choose other tools instead.

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 effectively communicates that this is a read-only operation ('without reading its content'), describes what information is returned, and clarifies it's for metadata/statistics only. However, it doesn't mention potential limitations like rate limits, authentication requirements, or error conditions.

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

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

The description is well-structured with clear sections (purpose, usage guidelines, returns) and every sentence adds value. It's front-loaded with the core purpose, followed by practical guidance, and concludes with return details. No wasted words or redundant information.

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

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

For a tool with no annotations and no output schema, the description provides excellent context about what the tool does, when to use it, and what it returns. The 'Returns' section effectively documents the output structure. The main gap is the lack of explicit behavioral constraints (like rate limits or permissions), but overall it's quite complete for this complexity level.

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 50% (only the 'path' parameter has a description), but the description compensates by providing context about what the 'path' parameter represents ('Path to the note to analyze') and includes examples in the schema. The 'ctx' parameter remains undocumented, but the description's overall clarity about the tool's purpose helps contextualize 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 tool's purpose with specific verbs ('get metadata and statistics') and resource ('about a note'), explicitly distinguishing it from sibling tools like read_note and search tools by emphasizing it doesn't read content. The first sentence provides a concise, accurate summary of the tool's function.

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 includes explicit 'When to use' and 'When NOT to use' sections that provide clear guidance on appropriate contexts and name specific alternative tools (read_note, search tools, update tools). This gives the agent precise direction on when to select this tool versus its 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?

With no annotations provided, the description carries full burden and does well by explaining what the tool returns ('All outgoing links with their types and optional validity status') and the optional validity checking behavior. It doesn't mention performance characteristics, rate limits, or authentication needs, but covers core functionality adequately.

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 well-structured with clear sections (purpose, when to use, when not to use, returns), front-loaded with the core functionality, and every sentence adds value. No wasted words or redundant information.

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

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

For a read-only tool with no annotations and no output schema, the description does an excellent job covering purpose, usage guidelines, and return values. The main gap is the lack of output format details (structure of returned links), but given the tool's relative simplicity and clear behavioral description, it's mostly 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 67% (2 of 3 parameters have descriptions). The description adds value by explaining the purpose of validity checking ('Also check if each linked note actually exists in your vault'), which complements the schema. However, it doesn't provide additional context for the 'path' parameter beyond what's in the 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 the specific action ('List all links') and resource ('from a specific note'), with explicit differentiation from sibling tools like get_backlinks and find_broken_links. The title 'outgoing links' reinforces the directional nature of the 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 provides explicit 'When to use' scenarios (understanding references, checking dependencies, exploring structure, validating links) and 'When NOT to use' cases with named alternatives (get_backlinks for inbound links, find_broken_links for cross-note searches). This gives comprehensive 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?

With no annotations provided, the description carries the full burden. It discloses behavioral traits: it's a read operation (implied by 'List'), returns folder structure with paths and names, and mentions optional directory parameter with default behavior. However, it doesn't specify pagination, rate limits, or error conditions, leaving some gaps.

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 well-structured with clear sections (purpose, when to use, when not to use, returns). Every sentence adds value: the first states the core function, the bullet points provide practical guidance, and the returns section clarifies output. 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 read-only tool with no output schema, the description is mostly complete: it covers purpose, usage guidelines, and output format. However, with no annotations and incomplete parameter documentation (missing 'ctx'), there are minor gaps in behavioral context and parameter 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 description coverage is only 33% (1 of 3 parameters described in schema). The description compensates by explaining the directory parameter's purpose ('specific directory to list folders from') and default behavior ('defaults to root'), and mentions recursive behavior in the schema. However, it doesn't address the 'ctx' parameter at all, which remains 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 clearly states the tool's purpose with specific verb ('List') and resource ('folders in the vault or a specific directory'). It distinguishes from siblings by explicitly mentioning when NOT to use it for listing notes or searching content, which are handled by other tools like list_notes and search_notes.

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

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

The description provides explicit 'When to use' scenarios (exploring structure, verifying names, checking existence, understanding hierarchy) and 'When NOT to use' cases with named alternatives (list_notes for notes, search_notes for content). This gives clear guidance on tool selection versus 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?

With no annotations provided, the description carries full burden and adds valuable behavioral context: performance characteristics (fast for <100 notes, slower for large vaults with recursive=True), what it returns (hierarchical structure with paths), and a warning about loading full paths versus just counting. It doesn't contradict any annotations since none exist.

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 well-structured with clear sections (purpose, when to use, when not to use, performance notes, returns). Every sentence adds value without redundancy. It's appropriately sized for the tool's complexity and front-loaded with 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?

Given no annotations, no output schema, and low schema coverage, the description does an excellent job providing context. It covers purpose, usage guidelines, performance characteristics, and return format. The main gap is that it doesn't fully document all parameters, but it provides enough context for effective 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 only 33% (1 of 3 parameters described), but the description compensates well. It explains the directory parameter's purpose ('list notes in the vault or a specific directory') and implies recursive behavior in performance notes. While it doesn't detail all parameters explicitly, it provides meaningful context beyond the sparse 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 the tool's purpose with specific verb ('List') and resource ('notes in the vault or a specific directory'), distinguishing it from siblings like search_notes or list_folders. It explicitly defines the scope of listing notes versus other operations.

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

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

The description provides explicit 'When to use' and 'When NOT to use' sections with clear alternatives named (search_notes, search_by_property). It gives specific scenarios for usage and exclusions, making it easy to choose between this tool and 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It does this well by explaining performance characteristics (speed based on vault size), implementation details ('Uses batched concurrent requests'), and the effect of include_files parameter. It doesn't cover error conditions or authentication needs, but provides substantial operational context.

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 well-structured with clear sections (When to use, Hierarchical tags, File paths, When NOT to use, Performance note, Returns). While comprehensive, some sections could be more concise (e.g., the 'When to use' bullet list has some redundancy). Overall, it's appropriately sized for the tool's complexity.

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

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

Given the tool's moderate complexity (4 parameters, no output schema, no annotations), the description provides excellent completeness. It covers purpose, usage guidelines, parameter implications, performance characteristics, hierarchical tag behavior, file path details, and return value information. This fully compensates for the lack of structured metadata.

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

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

Schema description coverage is 75% (3 of 4 parameters well-described). The description adds significant value beyond the schema by explaining the implications of include_files=true (returns file paths, useful for bulk operations, paths relative to vault root) and providing context about hierarchical tags. However, it doesn't fully explain the ctx parameter, which has no 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's purpose: 'List all unique tags used across the vault with usage statistics.' It specifies the verb ('List'), resource ('unique tags'), and scope ('across the vault'), and distinguishes itself from siblings like get_note_info and search_notes by explicitly stating when not to use it. This provides excellent 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 includes explicit 'When to use' and 'When NOT to use' sections, naming specific alternatives (get_note_info, search_notes with tag: prefix). It also provides contextual guidance like 'Before adding tags to maintain consistency' and 'Finding all files that use a specific tag (with include_files=true)', giving comprehensive usage direction.

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

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

With no annotations provided, the description carries the full burden. It discloses key behavioral traits: it's a mutation operation (implied by 'move'), it handles bulk content ('all its contents'), and it returns status with counts. However, it lacks details on permissions, error conditions, or rate limits, which would be helpful for a destructive operation.

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 well-structured with clear sections (purpose, usage guidelines, returns), uses bullet points for readability, and every sentence adds value without redundancy. It's appropriately sized for the tool's complexity and 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?

Given the tool's moderate complexity (4 parameters, no output schema, no annotations), the description is largely complete: it covers purpose, usage, and return values. However, it could better address potential pitfalls (e.g., what happens if the destination exists) and the unexplained 'ctx' parameter, leaving 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?

Schema description coverage is 75%, so the schema documents most parameters well. The description adds value by implicitly clarifying that 'source_folder' and 'destination_folder' refer to paths for moving operations, and it hints at the 'update_links' parameter's purpose ('future enhancement'). It doesn't fully compensate for the 25% gap (e.g., 'ctx' is unexplained), but provides useful context beyond the 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 the specific action ('Move an entire folder and all its contents') and resource ('folder'), distinguishing it from sibling tools like 'move_note' which handles individual notes. The verb 'move' is precise and the scope 'entire folder and all its contents' is 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?

The description provides explicit 'When to use' scenarios (e.g., reorganizing vault structure, archiving projects) and 'When NOT to use' cases (e.g., moving individual notes, creating circular references), including a named alternative ('move_note'). This gives clear guidance on tool selection versus 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?

With no annotations provided, the description carries the full burden of behavioral disclosure and does so effectively. It explains link updating behavior (automatic detection, wiki-style link updates, preservation of aliases), folder creation behavior, and what the tool returns. It doesn't mention permissions, rate limits, or error conditions, but provides substantial operational context.

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 well-structured with clear sections (purpose, usage guidelines, link updating, returns) and every sentence adds value. It's appropriately sized for a tool with complex behavior and no annotations, with no redundant or unnecessary information.

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

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

Given the tool's complexity (mutation with link updating), no annotations, and no output schema, the description provides comprehensive context. It covers purpose, usage guidelines, behavioral details, parameter semantics, and return information, making it complete enough for an agent to understand and use the tool effectively.

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 75% schema description coverage, the description adds meaningful context beyond the schema. It explains the link updating behavior tied to the 'update_links' parameter and clarifies that 'destination_path' creates folders if needed. The 'ctx' parameter remains undocumented, but the description compensates well for the schema's partial coverage.

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

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

The description clearly states the tool's purpose with specific verbs ('move', 'rename') and resource ('note'), and distinguishes it from sibling tools like rename_note, create_note, and move_folder. The opening sentence 'Move a note to a new location, optionally with a new name' is precise and actionable.

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 'When to use' and 'When NOT to use' sections with clear alternatives named (rename_note, read_note + create_note, move_folder). This gives comprehensive guidance on when to select this tool versus other available options.

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 effectively explains what the tool does (reads image files for analysis), what it returns (Image object that Claude can analyze), and distinguishes it from related operations. However, it doesn't mention potential limitations like file size constraints, supported formats beyond what's in the schema pattern, or error conditions.

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

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

The description is well-structured with clear sections (purpose, when to use, when not to use, returns) and every sentence adds value. It's front-loaded with the core purpose and efficiently organized without wasted words. The bullet-point format enhances readability while maintaining conciseness.

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

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

For a read operation with no annotations and no output schema, the description provides good context about what the tool does, when to use it, and what it returns. It covers the essential aspects well, though it could benefit from mentioning potential error cases or limitations. Given the straightforward nature of an image reading tool, the description 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 67% (2 of 3 parameters have descriptions). The description doesn't explicitly discuss parameters, but the 'path' parameter's purpose is implied through the tool's overall purpose. The 'include_metadata' and 'ctx' parameters aren't mentioned, but with moderate schema coverage and the tool's straightforward purpose, the description provides sufficient context for understanding the primary parameter'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 tool's purpose with specific verb ('Read') and resource ('image file from the Obsidian vault'), and distinguishes it from sibling tools by specifying it's for standalone images rather than embedded ones. The opening sentence 'Read an image file from the Obsidian vault for analysis' provides immediate clarity about the tool's function.

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 'When to use' and 'When NOT to use' sections with clear alternatives named (view_note_images and list_notes). It gives specific scenarios for appropriate use (analyzing specific image files, examining standalone images) and explicitly contrasts with sibling tools for different use cases.

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 effectively describes the tool's behavior: it's a read operation (implied by 'Read'), returns content and metadata with specific details (tags, aliases, frontmatter), preserves image references without loading them, and includes proactive user interaction guidance for handling images. It covers key aspects like output format and user interaction patterns, though it doesn't mention error handling 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?

The description is well-structured with clear sections ('When to use,' 'When NOT to use,' 'Returns,' 'IMPORTANT'), making it easy to scan. It is appropriately sized for the tool's complexity, with each sentence adding value (e.g., usage scenarios, output details, user interaction advice). However, the 'IMPORTANT' section is somewhat verbose and could be more 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?

Given the tool's moderate complexity (2 parameters, no output schema, no annotations), the description is highly complete. It covers purpose, usage guidelines, behavioral details (including output format and image handling), and proactive user interaction. It effectively compensates for the lack of annotations and output schema, providing all necessary context for an AI agent to 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% (only 'path' has a description, 'ctx' does not). The description adds no explicit parameter information beyond what's in the schema, but it implicitly clarifies the tool's focus on a single note via 'specific note,' which aligns with the 'path' parameter. Since there are only 2 parameters and the schema covers the critical 'path' parameter well, the description compensates adequately without redundancy, though it doesn't address the undocumented 'ctx' parameter.

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 as 'Read the content and metadata of a specific note,' which is a specific verb+resource combination. It distinguishes from siblings like 'search_notes' (for multiple notes), 'get_note_info' (for metadata only), and 'view_note_images' (for images), providing clear 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 includes explicit 'When to use' and 'When NOT to use' sections with specific scenarios and named alternatives. It provides clear guidance on when to use this tool versus siblings like 'search_notes,' 'get_note_info,' and 'view_note_images,' including efficiency considerations and workflow advice (e.g., 'ALWAYS before updating a 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?

With no annotations provided, the description carries full burden and does well by disclosing key behavioral traits: it specifies 'Only removes exact matches' (important constraint), explains hierarchical tag handling, and describes the return value (updated tag list with count). However, it doesn't mention potential errors (e.g., if note doesn't exist) 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 well-structured with clear sections (purpose, when to use, when not to use, note, returns) and every sentence earns its place. It's front-loaded with the core purpose and efficiently communicates necessary 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?

For a mutation tool with no annotations and no output schema, the description provides good coverage: clear purpose, usage guidelines, behavioral constraints, and return value description. It could be more complete by addressing error cases or permission requirements, but it covers the essential context well given the 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?

With 67% schema description coverage (2 of 3 parameters documented in schema), the description adds meaningful context: it clarifies that tags should be provided 'without # prefix' and that removal is 'exact matches only', which complements the schema's tag description. The 'ctx' parameter remains undocumented in both schema and description, but the description provides good coverage for the core parameters.

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

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

The description clearly states the specific action ('Remove specific tags from a note's frontmatter') and distinguishes it from sibling tools like 'update_tags_tool' and 'add_tags_tool'. It specifies the exact resource (tags in note frontmatter) and scope (exact matches only).

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 'When to use' scenarios (cleaning up outdated tags, removing temporary tags, etc.) and 'When NOT to use' guidance with named alternatives (use update_tags for removing all tags or replacing tags). It clearly differentiates this tool from sibling update_tags_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 provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: the tool automatically updates wiki-style links, preserves link aliases, shows which notes were updated, and has constraints like 'Can only rename within the same directory'. However, it lacks details on error conditions, permissions, or rate limits, which slightly limits 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?

The description is well-structured with clear sections ('When to use', 'When NOT to use', 'Important', 'Returns'), front-loaded with the core purpose, and every sentence adds value without redundancy. It efficiently conveys necessary information in a compact format.

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 (a mutation tool with 4 parameters, no annotations, and no output schema), the description is mostly complete. It covers purpose, usage, behavioral traits, and return details. However, it lacks explicit error handling or permission requirements, which are important for a tool that modifies data, leaving a minor gap in completeness.

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

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

Schema description coverage is 75%, so the schema already documents most parameters well. The description adds meaningful context beyond the schema by explaining the purpose of parameters implicitly (e.g., 'Automatically updates all [[wiki-style links]]' relates to update_links) and clarifying constraints like 'must be in same directory' for new_path. This compensates well for the 25% coverage gap.

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

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

The description clearly states the tool's purpose with a specific verb ('Rename') and resource ('a note'), and explicitly distinguishes it from sibling tools by mentioning what it does not do (e.g., 'Moving notes to different folders (use move_note)'). This provides clear differentiation from alternatives like move_note or 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 includes explicit 'When to use' and 'When NOT to use' sections with concrete examples (e.g., 'Changing a note's title', 'Fixing typos') and named alternatives (e.g., 'use move_note', 'use read_note + create_note'). This gives comprehensive guidance on when to select this tool over others.

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 effectively describes the tool's behavior by specifying what it returns ('Notes matching the date criteria with paths and timestamps'), which is crucial for understanding output. However, it lacks details on potential limitations like result ordering, pagination, or error conditions.

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

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

The description is well-structured with clear sections (purpose, usage guidelines, returns), front-loaded with the core purpose, and every sentence adds value without redundancy. It efficiently communicates essential information in a compact format.

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 (4 parameters, no output schema, no annotations), the description provides good contextual completeness. It covers purpose, usage guidelines, and return values, which is sufficient for a search tool. However, without an output schema, it could benefit from more detail on the return structure (e.g., format of 'paths and timestamps').

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 75%, with three parameters well-documented (date_type, days_ago, operator) and one (ctx) lacking description. The tool description doesn't add parameter details beyond the schema, but since coverage is high and the undocumented 'ctx' parameter appears to be a common context parameter (implied by its name and null default), the description is adequate. A baseline of 3 is adjusted upward due to the high schema coverage compensating for the description's lack of parameter elaboration.

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 as 'Search for notes by creation or modification date,' which is a specific verb+resource combination. It distinguishes itself from sibling tools like 'search_notes' (for content-based search) and 'search_by_property_tool' or 'search_by_regex_tool' by focusing exclusively on date-based filtering.

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 includes explicit 'When to use' and 'When NOT to use' sections, providing clear guidance on appropriate scenarios (e.g., finding recently modified notes) and alternatives (e.g., using 'search_notes' for content-based search). This directly addresses sibling tool differentiation and usage 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 provided, the description carries the full burden. It effectively discloses key behavioral traits: it's a read-only search tool (implied by 'search'), supports various property types and operators, handles legacy migrations, and returns notes with values displayed. However, it lacks details on rate limits, error handling, or pagination, preventing a perfect score.

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 well-structured with clear sections (purpose, when to use, property types, when not to use, examples, returns), each sentence adds value without redundancy. It's appropriately sized for a complex tool with 5 parameters and no annotations, making it easy to scan and understand.

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 complexity (5 parameters, 60% schema coverage, no annotations, no output schema), the description is largely complete. It covers purpose, usage, parameters, and return behavior. However, it lacks explicit output details (e.g., format, pagination) and full parameter documentation (e.g., ctx), leaving 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?

Schema description coverage is 60%, and the description compensates well by explaining parameter semantics beyond the schema. It clarifies that property_name refers to 'frontmatter property values' and provides examples of usage for property_name, value, and operator (e.g., 'exists' checks presence). However, it doesn't fully address context_length or ctx, leaving some gaps.

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: 'Search for notes by their frontmatter property values.' It specifies the verb ('search'), resource ('notes'), and scope ('frontmatter property values'), distinguishing it from siblings like search_notes_tool (content search) and search_by_date_tool (date-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 explicitly provides 'When to use' with six specific scenarios (e.g., filtering by metadata, numeric properties, dates) and 'When NOT to use' with three clear exclusions (content search, tag search, path search), naming alternatives like search_notes. This comprehensive guidance helps the agent choose correctly 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 are provided, so the description carries the full burden. It discloses key behavioral traits: the tool returns 'Notes containing regex matches with match details and context,' and the 'Common patterns' section implies it supports complex regex features. However, it doesn't mention performance considerations like speed or resource usage, which could be relevant for a regex 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 well-structured with clear sections (purpose, usage guidelines, patterns, returns), front-loaded key information, and every sentence adds value (e.g., specific examples, explicit alternatives). It's appropriately sized for a tool with 5 parameters and no annotations.

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

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

Given the tool's complexity (regex-based search, 5 parameters, no annotations, no output schema), the description is mostly complete: it covers purpose, usage, parameters via examples, and output behavior. However, it lacks details on error handling, performance implications (e.g., regex complexity impact), or the 'ctx' parameter's purpose, leaving 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?

Schema description coverage is 60%, so the description must compensate. It adds significant value: the 'Common patterns' section provides concrete regex examples (e.g., for URLs, emails, TODO comments) that clarify the 'pattern' parameter beyond the schema's examples, and the 'Returns' section explains output semantics. However, it doesn't detail all parameters like 'ctx' or fully explain 'flags' beyond the 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 the tool's purpose: 'Search for notes using regular expressions for advanced pattern matching.' It specifies the verb ('search'), resource ('notes'), and method ('regular expressions'), distinguishing it from sibling tools like 'search_notes_tool' for simple text search and 'search_by_property_tool' for property-based searches.

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 with 'When to use' and 'When NOT to use' sections, listing specific scenarios (e.g., finding complex patterns, URLs, TODO comments) and naming alternatives ('use search_notes instead' for simple text search, 'use dedicated tools' for tags/properties). This clearly differentiates it from sibling tools.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: default search mode (both filenames and content), ranking logic (filename matches ranked higher), search modes with prefixes, hierarchical tag support, and return format (results with scores, match_type). It doesn't mention performance characteristics like rate limits or authentication needs, but covers most operational aspects well.

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 well-structured with clear sections (default behavior, when to use, search modes, examples, when not to use, returns) and uses bullet points for readability. While comprehensive, some sections could be more concise (e.g., the examples are detailed but necessary). Every sentence adds value, but the overall length is substantial though justified by the tool's complexity.

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

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

Given the tool's moderate complexity (4 parameters, no output schema, no annotations), the description is highly complete. It covers purpose, usage guidelines, behavioral details, parameter semantics through examples, and return format. The lack of output schema is compensated by explicitly describing the response structure (results with scores, match_type). No significant gaps remain for effective tool selection and invocation.

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

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

Schema description coverage is 75%, so the schema already documents most parameters well. The description adds valuable context beyond the schema: it explains the query parameter's default behavior (searches both filenames and content), provides multiple search mode examples with prefixes, and clarifies tag hierarchy support. However, it doesn't add meaningful information about the other parameters (context_length, max_results, ctx) beyond what's in their 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 clearly states the tool searches for notes by filename or content with smart ranking. It specifies the verb 'search' and resource 'notes', distinguishing it from siblings like list_notes (listing all notes) and search_by_date (searching by date). The opening sentence is specific and immediately communicates the core functionality.

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 this tool (e.g., finding notes by name, content, tags, folders, properties) and when NOT to use it (e.g., searching by date, listing all notes, reading a specific note with exact path). It names specific alternative tools (search_by_date, list_notes, read_note) for excluded use cases, offering clear decision boundaries.

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 effectively describes key traits: the default destructive behavior ('REPLACES the entire note content'), the need to read first to preserve content, and the return format ('Update status with path, metadata, and operation performed'). However, it lacks details on permissions, rate limits, or error handling, leaving some gaps.

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 well-structured and front-loaded, starting with the core purpose followed by important warnings and usage guidelines. Each sentence earns its place: the first states the action, the warning highlights critical behavior, and the bullet points provide clear context without redundancy. It's appropriately sized for a tool with multiple parameters and behavioral nuances.

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 complexity (5 parameters, no annotations, no output schema), the description does a good job covering key aspects: purpose, usage, behavioral traits, and some parameter context. However, it doesn't fully explain the return values beyond a brief mention, and with no output schema, more detail on the 'Update status' would be helpful. It's mostly complete but has 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?

Schema description coverage is high at 80%, setting a baseline of 3. The description adds value by explaining the default behavior ('REPLACES the entire note content') and mentioning the 'append' option for 'merge_strategy', which complements the schema. It also implicitly clarifies that 'path' identifies the note and 'content' is the new text, though it doesn't detail all parameters like 'create_if_not_exists' or 'ctx'.

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 ('Update') and resource ('content of an existing note'), making the purpose specific. It distinguishes from sibling tools like 'create_note_tool' (for creating new notes) and 'edit_note_section_tool' (for small edits), which helps differentiate its role in the toolset.

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 with dedicated 'When to use' and 'When NOT to use' sections. It specifies scenarios like replacing content, appending, and programmatic modifications, while warning against small edits (suggesting 'read first') and directing to 'create_note' for new notes. This clearly defines when to choose this tool over alternatives.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively explains the tool's behavior: it can replace or merge tags, and an empty tags list removes all tags (as noted in the schema). It also describes the return values. However, it doesn't mention potential side effects like error conditions or permissions needed, which keeps it from a perfect score.

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 well-structured with clear sections (purpose, usage guidelines, returns) and uses bullet points for readability. Every sentence adds value, such as distinguishing from siblings and explaining parameter behavior, with no wasted words. It's appropriately sized for the tool's complexity.

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

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

Given no annotations and no output schema, the description does a good job covering purpose, usage, and behavior. It explains the return values and key parameters. However, it doesn't address potential errors or edge cases (e.g., what happens if the path doesn't exist), which would enhance completeness for a mutation tool with 4 parameters.

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 75%, so the description doesn't need to fully compensate. It adds value by clarifying the 'merge' parameter's semantics ('True = add these tags to existing ones, False = replace all tags with this new list') and implies usage of 'tags' and 'path' in context. However, it doesn't explain the 'ctx' parameter, which has no description in the schema, leaving a minor 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 starts with a clear, specific statement: 'Update tags on a note - either replace all tags or merge with existing.' This explicitly states the verb ('update'), resource ('tags on a note'), and distinguishes it from siblings like add_tags_tool and remove_tags_tool by mentioning replacement vs. merging. It goes beyond just restating the name/title.

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 includes explicit 'When to use' and 'When NOT to use' sections with concrete scenarios (e.g., 'After analyzing a note's content to suggest relevant tags') and named alternatives (e.g., 'use add_tags' or 'use remove_tags'). This provides clear guidance on when to choose this tool over others.

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 effectively describes what the tool does (extract/analyze embedded images), specifies the return format (List of Image objects), and mentions that Claude can analyze/describe them. It doesn't cover error conditions, performance characteristics, or memory implications of image processing, but provides solid core behavioral 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 well-structured with clear sections (purpose, when to use, when not to use, returns). Each sentence earns its place by providing essential information without redundancy. The front-loaded purpose statement immediately communicates the tool's function.

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 no annotations and no output schema, the description provides good contextual completeness. It explains what the tool does, when to use it, what it returns, and distinguishes it from alternatives. The main gap is lack of explicit mention of the 'max_width' parameter's memory-saving purpose, but overall it's quite comprehensive given the structured data limitations.

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 50% schema description coverage, the description doesn't mention any parameters directly. However, the schema provides good documentation for the 4 parameters, including clear descriptions and examples for 'path' and 'image_index'. The description doesn't add parameter-specific context beyond what's implied by the tool's purpose, meeting the baseline for moderate schema coverage.

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

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

The description clearly states the tool's purpose with specific verbs ('extract and analyze') and resources ('images embedded in a note'), distinguishing it from siblings like read_note (text only) and read_image (standalone files). The first sentence provides a concise, accurate summary of functionality.

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 includes explicit 'When to use' and 'When NOT to use' sections with named alternatives (read_image, read_note). This provides clear guidance on when this tool is appropriate versus when to use sibling tools, covering both inclusion and exclusion criteria.

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