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

No annotations are provided, so the description carries the full burden of behavioral disclosure. While it mentions the tool's core function (adding backlinks automatically), it lacks critical details: whether this is a destructive operation that modifies files, potential performance impacts for large vaults, error handling, or what happens if note names overlap. For a tool that likely alters multiple notes, this is a significant gap in transparency.

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

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

The description is a single, efficient sentence that front-loads the core purpose ('Automatically add backlinks throughout the entire vault') and elaborates on the method ('by detecting note names...'). There is no wasted verbiage, repetition, or unnecessary detail, making it easy for an agent to parse quickly.

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

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

Given the tool's complexity (automated, multi-note processing with 6 parameters) and lack of annotations or output schema, the description is incomplete. It doesn't address key contextual aspects: what the tool returns (e.g., a summary of changes), side effects (e.g., file modifications), or error conditions. For a tool that could significantly alter a vault, more guidance is needed to ensure safe and 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 100%, with each parameter well-documented in the schema (e.g., 'dryRun' for previewing changes). The description adds no additional parameter semantics beyond what the schema provides, such as explaining how 'excludePatterns' interacts with the vault structure. However, with full schema coverage, the baseline score of 3 is appropriate as the schema handles the heavy lifting.

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

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

The description clearly states the specific action ('Automatically add backlinks'), the resource ('throughout the entire vault'), and the mechanism ('by detecting note names in content and converting them to wikilinks'). It distinguishes itself from sibling tools like 'update_note' or 'search_vault' by focusing on automated link creation rather than manual editing or querying.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., whether notes must exist), compare it to manual linking in 'update_note', or specify scenarios like bulk processing versus single-note updates. Without such context, the agent must infer usage from the tool's name and parameters alone.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool creates a note but doesn't cover critical behaviors like whether it overwrites existing files, requires specific permissions, handles errors, or returns any output. This leaves significant gaps for a mutation tool.

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

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

The description is a single, efficient sentence that directly states the tool's purpose without any fluff. It is front-loaded and appropriately sized, making it easy to parse quickly.

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

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

For a mutation tool with no annotations and no output schema, the description is incomplete. It doesn't explain what happens on success or failure, whether the note is immediately saved, or how it interacts with other tools like 'auto_backlink_vault'. More context is needed given the complexity of file creation.

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

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

The input schema has 100% description coverage, with clear documentation for both parameters ('path' and 'content'). The description adds no additional semantic context beyond what the schema provides, such as path format examples or content constraints, so it meets the baseline for high 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 action ('Create') and resource ('new note in the Obsidian vault'), making the purpose immediately understandable. It distinguishes from siblings like 'update_note' or 'delete_note' by specifying creation, but doesn't explicitly differentiate from all siblings (e.g., 'manage_folder' could also involve 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?

No guidance is provided on when to use this tool versus alternatives like 'update_note' for modifying existing notes or 'manage_folder' for folder-related operations. The description lacks context on prerequisites, such as whether the path must exist or if overwriting is allowed, leaving usage unclear.

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 states the tool deletes a note, implying a destructive mutation, but fails to describe critical traits like whether deletion is permanent or reversible, what permissions are required, or if there are side effects like broken links. This leaves significant gaps in understanding the tool's behavior.

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

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

The description is a single, direct sentence with zero wasted words, making it highly concise and front-loaded. It efficiently communicates the core action without unnecessary elaboration.

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 destructive nature, lack of annotations, and no output schema, the description is incomplete. It does not address behavioral risks, return values, or error handling, which are crucial for a deletion operation. This leaves the agent with insufficient context for safe and 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?

The input schema has 100% description coverage, with the 'path' parameter clearly documented. The description does not add any meaning beyond what the schema provides, such as examples of valid paths or constraints. Since the schema does the heavy lifting, the baseline score of 3 is appropriate.

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

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

The description clearly states the action ('Delete') and the resource ('a note from the Obsidian vault'), making the purpose unambiguous. However, it does not explicitly differentiate from sibling tools like 'move_note' or 'update_note' beyond the verb, which slightly limits its distinction.

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

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

The description provides no guidance on when to use this tool versus alternatives, such as 'move_note' for relocation or 'update_note' for modification. It lacks context about prerequisites, like ensuring the note exists, or exclusions, such as not using it for non-note files.

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 mentions default behavior (recursive listing) but lacks details on permissions, rate limits, output format, pagination, or error handling. For a read operation with zero annotation coverage, this is insufficient, though it does add some basic 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 extremely concise and front-loaded: two sentences with zero waste. It efficiently states the purpose and default behavior without unnecessary details, earning a high score for brevity and clarity.

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

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

Given the tool's low complexity (simple list operation), no annotations, and no output schema, the description is minimally adequate. It covers the basic action and default behavior but lacks details on output, errors, or advanced usage, resulting in a baseline score of 3.

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

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

Schema description coverage is 100%, so the schema fully documents both parameters. The description adds no additional parameter semantics beyond what the schema provides (e.g., it doesn't explain folder path formats or recursive implications). Baseline 3 is appropriate when the schema handles parameter documentation.

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

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

The description clearly states the tool's purpose: 'List notes in the Obsidian vault.' It specifies the resource (notes) and the action (list), but does not explicitly differentiate it from sibling tools like 'search_vault' or 'read_multiple_notes', which prevents a score of 5.

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

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

The description provides minimal guidance: 'By default lists all notes recursively.' It implies usage for listing notes but offers no explicit when-to-use advice, alternatives, or exclusions compared to siblings like 'search_vault' or 'read_multiple_notes'. This lack of context results in a low score.

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 mentions operations but lacks details on permissions, side effects (e.g., what happens to contents when deleting), error handling, or rate limits. For a tool with multiple mutation operations, this is a significant gap in transparency.

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

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

The description is a single, efficient sentence that front-loads all key operations (create, rename, move, delete) and the resource (folder in Obsidian vault). There is no wasted verbiage, making it highly concise and well-structured for quick understanding.

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 of multiple mutation operations, no annotations, and no output schema, the description is incomplete. It does not address behavioral aspects like safety, response formats, or error conditions, which are critical for an agent to use the tool correctly in a vault environment.

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

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

Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds no additional meaning beyond what the schema provides, such as examples or edge cases. Baseline 3 is appropriate as the schema does the heavy lifting, but the description does not compensate with extra context.

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

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

The description clearly states the specific actions (create, rename, move, delete) and the resource (folder in Obsidian vault), distinguishing it from sibling tools like create_note or move_note that operate on notes rather than folders. It precisely defines the tool's scope without being vague or tautological.

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

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

The description provides no guidance on when to use this tool versus alternatives, such as create_note for notes or other folder-related operations. It lists operations but does not specify contexts, prerequisites, or exclusions, leaving the agent to infer usage from the operation names alone.

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

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

With no annotations provided, the description carries full burden but offers minimal behavioral insight. It states the tool performs a move/rename operation, implying mutation, but doesn't disclose critical traits like permission requirements, whether it overwrites existing files, error handling for invalid paths, or if it updates internal links. For a mutation tool with zero annotation coverage, this is a significant gap.

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

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

The description is a single, efficient sentence that front-loads the core purpose ('Move or rename a note') and specifies the context ('in the Obsidian vault'). There is zero wasted text, making it highly concise and well-structured for quick understanding.

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 (a mutation operation with 2 required parameters), lack of annotations, and no output schema, the description is incomplete. It doesn't cover behavioral aspects like safety, error conditions, or return values, leaving gaps that could hinder an AI agent's ability to invoke it correctly. More context is needed for adequate completeness.

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

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

Schema description coverage is 100%, with both parameters clearly documented in the schema. The description adds no additional meaning beyond the schema's details about source and destination paths. According to rules, when schema coverage is high (>80%), the baseline score is 3 even with no param info in the description.

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

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

The description clearly states the action ('Move or rename') and resource ('a note'), specifying the target location ('new location in the Obsidian vault'). It distinguishes from siblings like 'create_note', 'delete_note', and 'update_note' by focusing on relocation/renaming rather than creation, deletion, or content modification. However, it doesn't explicitly differentiate from 'manage_folder' which might also handle file movements.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., note must exist), exclusions (e.g., cannot move to non-existent folders), or comparisons with siblings like 'update_note' for renaming or 'manage_folder' for broader file operations. Usage is implied but not explicitly defined.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. While it mentions 'AI-powered summarization' and the TRILEMMA-PRINCIPLES framework, it doesn't describe what insights are generated, the format of output, potential limitations, or how it interacts with notes (e.g., does it analyze existing notes from the vault?). For a tool with no annotations and no output schema, this leaves significant gaps in understanding its behavior.

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

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

The description is a single, efficient sentence that states the core purpose without unnecessary words. It's appropriately sized and front-loaded, making it easy for an agent to quickly understand what the tool does.

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 of generating insights with AI and a specific framework, no annotations, and no output schema, the description is incomplete. It doesn't explain what insights look like, how they're derived, or what the tool returns. This leaves the agent with insufficient context to use the tool effectively beyond basic parameter passing.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters thoroughly. The description doesn't add any meaning beyond what the schema provides about parameters like 'topic', 'maxNotes', etc. It implies topic analysis but doesn't elaborate on parameter interactions or constraints. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description clearly states the tool's purpose: 'Generate insights about a topic using TRILEMMA-PRINCIPLES framework with AI-powered summarization.' It specifies the verb ('generate insights'), resource ('topic'), and method ('TRILEMMA-PRINCIPLES framework with AI-powered summarization'). However, it doesn't explicitly distinguish this from sibling tools like 'search_vault' or 'read_note' that might also provide information about topics.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, ideal use cases, or when to choose this over sibling tools like 'search_vault' or 'read_note' for topic analysis. The agent must infer usage from the purpose alone.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool reads content but doesn't specify what happens if paths are invalid, if there are rate limits, permission requirements, or the format of the returned content. This leaves significant gaps for a tool that interacts with multiple resources.

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

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

The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It is front-loaded with the core action and resource, making it easy to understand at a glance.

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 lack of annotations and output schema, the description is incomplete. It doesn't explain what content is returned (e.g., raw text, structured data), error handling, or performance implications for reading multiple notes. For a tool with no structured behavioral hints, this leaves critical gaps.

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

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

The input schema has 100% description coverage, clearly documenting the 'paths' parameter as an array of note paths. The description adds no additional semantic information beyond what the schema provides, such as path format examples or constraints, so it meets the baseline for high 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 action ('Read content') and resource ('from multiple notes simultaneously'), distinguishing it from the sibling 'read_note' tool which presumably reads a single note. However, it doesn't specify the format or scope of the content being read (e.g., full text, metadata, or specific fields).

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

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

The description implies usage when multiple notes need to be read at once, suggesting an alternative to repeatedly calling 'read_note'. However, it doesn't explicitly state when to use this tool over 'read_note' or other siblings like 'list_notes' or 'search_vault', nor does it mention any prerequisites or limitations.

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 states this is a read operation, which implies safety, but doesn't cover important aspects like error handling (e.g., what happens if the path is invalid), return format, or performance considerations (e.g., file size 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 a single, direct sentence that efficiently conveys the core functionality without unnecessary words. It's front-loaded with the key action and resource, making it easy to parse quickly.

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

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

For a tool with no annotations and no output schema, the description is insufficient. It doesn't explain what the tool returns (e.g., note content, metadata), error conditions, or how it interacts with the vault structure, leaving significant gaps for an AI 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?

The schema description coverage is 100%, with the 'path' parameter fully documented in the schema. The description doesn't add any additional semantic context beyond what the schema provides, such as path format examples or vault structure details, so it meets the baseline for high 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 action ('Read') and resource ('content of a note in the Obsidian vault'), making the tool's purpose immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'read_multiple_notes' or 'list_notes', which prevents a perfect score.

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

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

The description provides no guidance on when to use this tool versus alternatives like 'read_multiple_otes' or 'list_notes'. It also lacks information about prerequisites, such as whether the note must exist or if there are access restrictions, leaving usage context unclear.

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 states the action ('Search') but doesn't describe what the search returns (e.g., file names, content snippets, metadata), how results are formatted, or any limitations (e.g., search scope, performance). This leaves significant gaps for a tool with no output schema.

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

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

The description is a single, efficient sentence with zero waste—it directly states the tool's purpose without unnecessary words. It's appropriately sized and front-loaded for quick understanding.

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 is incomplete. It doesn't explain what 'content' means (e.g., files, text, metadata), the search behavior (e.g., full-text, fuzzy), or the return format, making it inadequate for a search tool in a complex vault system.

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

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

Schema description coverage is 100%, with the single parameter 'query' documented in the schema. The description adds no additional meaning beyond implying a search operation, so it meets the baseline of 3 where the schema does the heavy lifting.

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

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

The description clearly states the verb ('Search') and resource ('content in the Obsidian vault'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'list_notes' or 'notes_insight' that might also involve finding content, so it doesn't reach the highest clarity level.

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

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

The description provides no guidance on when to use this tool versus alternatives like 'list_notes' or 'notes_insight'. There's no mention of prerequisites, context, or exclusions, leaving the agent with minimal 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?

No annotations are provided, so the description carries full burden. It mentions 'update content' but doesn't disclose critical behavioral traits: whether changes are reversible, permission requirements, error handling (e.g., if note doesn't exist), or side effects. The 'dryRun' parameter hints at preview capability, but this isn't explained in the description. For a mutation tool with zero annotation coverage, this is a significant gap.

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

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

The description is a single, efficient sentence that front-loads the core action ('Update content in an existing note') and adds method details ('using text replacements or precise insertions'). There's no wasted wording, and 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 (mutation with nested edit operations), lack of annotations, and no output schema, the description is incomplete. It doesn't explain return values, error cases, or behavioral nuances like how 'dryRun' works. For a tool that modifies notes with multiple edit modes, more context is needed to guide 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 100%, so the schema fully documents all parameters. The description adds minimal value beyond the schema by hinting at 'text replacements or precise insertions', which loosely maps to the 'edits' parameter modes. However, it doesn't provide additional syntax, examples, or constraints beyond what's in the schema descriptions. Baseline 3 is appropriate when schema does the heavy lifting.

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

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

The description clearly states the tool's purpose as 'Update content in an existing note using text replacements or precise insertions', which specifies the verb ('update'), resource ('existing note'), and method ('text replacements or precise insertions'). It distinguishes from siblings like 'create_note' (creates new) and 'delete_note' (removes), but doesn't explicitly differentiate from 'move_note' or 'read_note' beyond the update action.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., note must exist), compare to 'create_note' for new notes, or specify scenarios where 'replace' vs 'insert' modes are appropriate. Usage is implied by the action but lacks explicit context.

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