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 appends content to files, implying a write operation, but doesn't clarify critical aspects like whether it creates files if they don't exist, how it handles existing content (e.g., appending at end vs. specific position), error conditions, or any rate limits. 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 unnecessary words. It's front-loaded with the core action and resource, making it easy to parse quickly. Every word earns its place.

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

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

For a mutation tool with no annotations and no output schema, the description is incomplete. It lacks details on behavioral traits (e.g., file creation, append behavior), error handling, and return values. Given the complexity of file operations and the absence of structured safety hints, more context is needed to adequately guide an agent.

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

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

Schema description coverage is 100%, with both parameters ('filepath' and 'content') well-documented in the schema. The description doesn't add any meaningful parameter semantics beyond what the schema already provides, such as explaining 'filepath' format examples or 'content' handling. Baseline 3 is appropriate given 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 action ('Append content') and target ('to a new or existing file in the vault'), providing a specific verb+resource combination. However, it doesn't explicitly distinguish this tool from similar siblings like 'obsidian_patch_content' or 'obsidian_put_content', which might also modify file content in different ways.

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 when to choose 'append' over 'patch' or 'put' content, nor does it specify prerequisites like file existence or permissions. 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions concatenation with headers, which adds useful context beyond the schema, but fails to address critical aspects like error handling (e.g., if a file doesn't exist), performance implications for large batches, or output format details. This is inadequate for a tool with mutation-like behavior (reading multiple files).

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 functionality ('Return the contents of multiple files') and adds key behavioral detail ('concatenated with headers'). Every word earns its place with zero waste.

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 lacks details on return values (e.g., format of concatenated output, error responses), and while concise, doesn't compensate for the missing structured data. For a batch operation tool, this leaves significant gaps in understanding its full behavior.

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 fully documents the 'filepaths' parameter. The description adds no additional parameter semantics beyond what's in the schema (e.g., no details on header format, ordering, or path validation). Baseline 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 tool's purpose with a specific verb ('Return') and resource ('contents of multiple files'), and distinguishes it from the sibling 'obsidian_get_file_contents' by specifying batch processing and concatenation with headers. This provides precise differentiation from the single-file version.

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 context by mentioning 'multiple files' and 'concatenated with headers', which suggests it's for bulk reading with formatted output. However, it doesn't explicitly state when to use this versus alternatives like 'obsidian_get_file_contents' for single files or 'obsidian_list_files_in_dir' for metadata only, leaving some guidance gaps.

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. It effectively discloses key behavioral traits: it's a read-only search operation (implied by 'search'), supports JsonLogic with extensions ('glob' and 'regexp'), and specifies that 'Results must be non-falsy.' It doesn't mention pagination, rate limits, or authentication needs, but covers core functionality 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: purpose, usage guidelines, and examples. It's appropriately sized for a complex tool, though the examples are lengthy. Every sentence adds value, but it could be more front-loaded by moving the usage guidance closer to the beginning.

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 (JsonLogic queries, pattern matching), no annotations, and no output schema, the description does a good job. It explains the query language, provides examples, and specifies result requirements. However, it doesn't describe the output format (e.g., what fields are returned), which is a gap since there's no output schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds significant value beyond the schema by explaining the JsonLogic operators ('standard JsonLogic operators plus 'glob' and 'regexp' for pattern matching'), providing three detailed examples with explanations, and emphasizing 'ALWAYS follow query syntax in examples.' This compensates for the schema's technical nature.

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: 'Complex search for documents using a JsonLogic query.' It specifies the resource (documents) and method (JsonLogic query), and distinguishes it from sibling 'obsidian_simple_search' by emphasizing complexity and additional operators like 'glob' and 'regexp'.

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

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

The description provides explicit guidance: 'Use this tool when you want to do a complex search, e.g. for all documents with certain tags etc.' It distinguishes from simpler alternatives by naming the use case, though it doesn't explicitly list when NOT to use it or name all alternatives.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the action ('Delete') but lacks critical details: whether deletion is permanent or reversible, what happens to nested directories, error conditions (e.g., non-existent paths), or permissions required. For a destructive operation 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 ('Delete a file or directory'). There is no wasted verbiage or redundancy, making it highly concise and well-structured 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 destructive nature, lack of annotations, and no output schema, the description is incomplete. It doesn't address safety considerations (e.g., irreversible deletion), error handling, or return values. For a delete operation, this leaves critical gaps in understanding behavioral outcomes.

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 clear descriptions for both parameters ('filepath' and 'confirm'). The description adds no additional parameter semantics beyond what the schema provides (e.g., it doesn't explain path formatting or why 'confirm' is required). 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 action ('Delete') and resource ('a file or directory from the vault'), making the purpose immediately understandable. It doesn't explicitly distinguish from sibling tools like 'obsidian_patch_content' or 'obsidian_put_content' (which modify rather than delete), but the verb 'Delete' is specific enough for basic differentiation.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., file must exist), exclusions (e.g., cannot delete locked files), or sibling tools for related operations like 'obsidian_list_files_in_vault' to check existence first. Usage is implied only by the action itself.

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 ('Return the content') but lacks details on error handling (e.g., if the file doesn't exist), performance aspects (e.g., file size limits), or output format (e.g., plain text, Markdown). This is a significant gap for a tool with potential read operations and no structured safety hints.

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, clear sentence with zero wasted words. It's front-loaded with the core action and resource, making it highly efficient and easy to parse. Every part of the sentence earns its place by directly contributing to understanding the tool's 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?

Given the complexity of file operations and the lack of annotations and output schema, the description is incomplete. It doesn't address key contextual elements like error cases (e.g., missing files), return value details (e.g., content format), or how it fits into the broader vault management context with siblings. This leaves gaps for safe and effective tool invocation.

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

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

The input schema has 100% description coverage, with the 'filepath' parameter well-documented in the schema itself. The description doesn't add any extra meaning beyond what the schema provides (e.g., it doesn't clarify path formatting examples or vault-specific nuances), so it meets the baseline for high schema coverage without compensating value.

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

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

The description clearly states the verb ('Return') and resource ('content of a single file'), making the purpose specific and understandable. However, it doesn't explicitly differentiate from sibling tools like 'obsidian_batch_get_file_contents' (which handles multiple files) or 'obsidian_simple_search' (which might return content with search filtering), leaving some ambiguity about when to choose this exact tool.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention scenarios like preferring 'obsidian_batch_get_file_contents' for multiple files or 'obsidian_simple_search' for filtered content, nor does it specify prerequisites like file existence. This lack of context makes it harder for an agent to select the correct tool 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 states the tool 'gets' data, implying a read-only operation, but doesn't disclose behavioral traits such as error handling (e.g., if no note exists for the period), performance considerations, or output format details. The description is minimal and lacks context beyond the basic action, leaving gaps in understanding how the tool behaves in practice.

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, clear sentence that front-loads the core action ('Get current periodic note') and specifies the key input ('for the specified period'). There is no wasted text, repetition, or unnecessary elaboration, making it highly 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 no annotations and no output schema, the description is incomplete. It doesn't explain what 'current' means (e.g., today's daily note, this week's weekly note), how the tool handles missing notes, or the structure of returned data (content vs. metadata). For a tool with 2 parameters and behavioral uncertainty, more context is needed to fully guide an agent.

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

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

Schema description coverage is 100%, with both parameters well-documented in the schema (period types and data types). The description adds no additional parameter semantics beyond what the schema provides, such as explaining what 'current' means relative to the period or default behaviors. With high schema coverage, the baseline is 3, as the description doesn't compensate but doesn't need to heavily.

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 ('Get') and resource ('current periodic note'), specifying it retrieves notes for a given period. It distinguishes from siblings like obsidian_get_file_contents (general files) and obsidian_get_recent_periodic_notes (recent notes), but doesn't explicitly contrast them. The purpose is specific and actionable, though sibling differentiation is implicit rather than 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 implies usage for retrieving periodic notes, with context from the input schema (period types and data types). However, it lacks explicit guidance on when to use this versus alternatives like obsidian_get_file_contents (for non-periodic files) or obsidian_get_recent_periodic_notes (for recent notes). Usage is clear from the tool name and parameters but not explicitly stated in the description text.

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 'Get' implies a read-only operation, the description doesn't address important behavioral aspects like whether this requires specific permissions, how results are sorted (e.g., by modification time), what happens when no recent files exist, or whether there are rate limits. For a 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 states the core purpose without any wasted words. It's appropriately sized for a simple retrieval tool and gets straight to the point.

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

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

For a relatively simple read operation with good schema coverage but no annotations or output schema, the description is minimally adequate. It states what the tool does but lacks important context about behavioral characteristics, usage scenarios, and result format that would help an agent 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 description doesn't mention any parameters, but the input schema has 100% description coverage with clear documentation for both 'limit' and 'days' parameters including defaults and constraints. According to scoring rules, when schema_description_coverage is high (>80%), the baseline is 3 even with no parameter information 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 verb 'Get' and resource 'recently modified files in the vault', making the purpose immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'obsidian_list_files_in_vault' or 'obsidian_list_files_in_dir' which also list files, though the 'recently modified' aspect provides some implicit 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. With siblings like 'obsidian_list_files_in_vault' and 'obsidian_list_files_in_dir' that also list files, there's no indication of when this filtered-by-recent-changes approach is preferred over those broader listing tools.

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

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

No annotations are provided, so the description carries full burden. It states the tool retrieves notes but doesn't disclose behavioral traits like whether it returns metadata only (unless include_content=true), how 'most recent' is determined (e.g., by creation or modification date), pagination, error handling, or rate limits. The description is minimal and lacks 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 a single, efficient sentence that front-loads the core purpose. It wastes no words and is appropriately sized for the tool's complexity. Every part of the sentence contributes to understanding 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?

Given no annotations and no output schema, the description is incomplete. It doesn't explain what 'most recent' means, the return format (e.g., list of notes with metadata), or how results are ordered. For a tool with 3 parameters and no structured output documentation, 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%, with clear descriptions for all parameters (period, limit, include_content). The description adds no additional parameter semantics beyond what the schema provides, such as explaining period types further or content inclusion implications. Baseline 3 is appropriate as the schema adequately documents parameters.

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

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

The description clearly states the action ('Get most recent') and resource ('periodic notes'), specifying the scope ('for the specified period type'). It distinguishes from siblings like 'obsidian_get_periodic_note' (singular) and 'obsidian_get_recent_changes' (general changes), but doesn't explicitly contrast them. Purpose is clear but sibling differentiation is implicit.

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 explicit guidance on when to use this tool versus alternatives. The description implies usage for retrieving recent periodic notes, but doesn't mention when to choose it over 'obsidian_get_periodic_note' (likely for a specific note) or 'obsidian_get_recent_changes' (for all recent changes). No prerequisites or exclusions are provided.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the core function (listing files/directories) and notes that empty directories are not returned (via schema description), but does not disclose other behavioral traits such as permissions needed, rate limits, output format, pagination, or error handling. It adds some context but leaves significant gaps for a tool with no annotation coverage.

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 scope, making it easy to parse. Every part of the sentence contributes essential information, earning its place with zero waste.

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 a simple single-parameter input schema, the description provides basic completeness for a read-only listing tool. However, it lacks details on output structure (e.g., format of returned list), error conditions, or integration with sibling tools. It is minimally viable but has clear gaps in contextual information that could aid an AI agent.

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

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

Schema description coverage is 100%, with the single parameter 'dirpath' fully documented in the schema (path relative to vault root, empty directories not returned). The description does not add any parameter-specific semantics beyond what the schema provides, such as format examples or edge cases. Baseline 3 is appropriate as the schema handles parameter documentation 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 verb ('Lists') and resource ('all files and directories') with specific scope ('in a specific Obsidian directory'). It distinguishes from sibling 'obsidian_list_files_in_vault' by specifying directory-level rather than vault-wide listing, though not explicitly named. The purpose is unambiguous but could be more explicit about the sibling 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 implies usage context (directory-level listing) but does not explicitly state when to use this tool versus alternatives like 'obsidian_list_files_in_vault' or file-content tools. It provides no guidance on prerequisites, exclusions, or comparative scenarios. The context is clear but lacks explicit alternative naming or when-not-to-use advice.

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 behavioral disclosure burden. It states what the tool does but doesn't describe behavioral traits like whether it returns recursive listings, file metadata, sorting order, pagination, error conditions, or performance characteristics. For a listing tool with zero annotation coverage, this leaves significant behavioral 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 a single, efficient sentence that front-loads the essential information ('Lists all files and directories') followed by the scope constraint. Every word earns its place with zero redundancy or 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 simplicity (zero parameters, no output schema) and lack of annotations, the description provides adequate basic functionality explanation but lacks completeness about behavioral aspects. For a listing operation, additional context about return format, recursion behavior, or error handling would be valuable but isn't provided.

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

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

The tool has zero parameters with 100% schema description coverage, so the schema already fully documents the parameter situation. The description appropriately doesn't waste space discussing nonexistent parameters. A baseline of 4 is appropriate for zero-parameter tools where the schema handles all 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 specific action ('Lists all files and directories') and target resource ('in the root directory of your Obsidian vault'), distinguishing it from sibling tools like 'obsidian_list_files_in_dir' which operates on arbitrary directories. The verb+resource+scope combination 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 implicitly defines usage context by specifying 'root directory' scope, suggesting this tool is for vault-wide listing rather than directory-specific operations. However, it doesn't explicitly state when to use this versus alternatives like 'obsidian_list_files_in_dir' or 'obsidian_get_recent_changes', missing explicit comparison guidance.

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

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

With no annotations provided, the description carries full burden but lacks critical behavioral details. It doesn't disclose whether this operation is destructive (e.g., 'replace' operation could overwrite content), what happens if the target doesn't exist, error conditions, or formatting expectations. For a mutation tool with 5 parameters, this leaves significant gaps in understanding tool 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, well-structured sentence that efficiently communicates the core functionality without unnecessary words. Every element (verb, resource, method) earns its place, making it easy to parse and 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?

For a mutation tool with 5 parameters, no annotations, and no output schema, the description is insufficient. It doesn't cover behavioral aspects (destructiveness, error handling), doesn't explain return values, and provides minimal parameter guidance beyond what's in the schema. Given the complexity, more context about how operations work and what to expect is needed.

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%, providing clear documentation for all 5 parameters. The description adds minimal value beyond schema, only vaguely referencing parameter concepts ('heading, block reference, or frontmatter field' relates to target_type/target). No additional syntax, format details, or examples are provided, so baseline 3 is appropriate.

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

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

The description clearly states the specific action ('Insert content'), target resource ('existing note'), and positioning method ('relative to a heading, block reference, or frontmatter field'). It distinguishes from siblings like obsidian_append_content (which likely appends to end of file) and obsidian_put_content (which likely replaces entire file) by specifying targeted insertion.

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 context by specifying 'relative to a heading, block reference, or frontmatter field,' suggesting this tool is for targeted modifications rather than whole-file operations. However, it doesn't explicitly state when to choose this over alternatives like obsidian_append_content or obsidian_put_content, nor does it mention prerequisites like file existence.

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 creating or updating files but lacks details on permissions, overwrite behavior, error handling, or rate limits. This is insufficient for a mutation tool with zero annotation coverage.

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 clearly states the tool's function without unnecessary words. It is front-loaded and wastes no space, 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?

Given the tool's complexity (a mutation operation), lack of annotations, and no output schema, the description is incomplete. It fails to address critical aspects like behavioral traits, error cases, or output expectations, leaving significant gaps for an AI agent.

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

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

Schema description coverage is 100%, so the input schema fully documents both parameters ('filepath' and 'content'). The description adds no additional semantic context beyond what the schema provides, meeting the baseline for high 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 verb ('create' or 'update') and resource ('file in your vault'), making the purpose understandable. It distinguishes between creating new files and updating existing ones, though it doesn't explicitly differentiate from sibling tools like 'obsidian_append_content' or 'obsidian_patch_content' beyond the basic 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?

No guidance is provided on when to use this tool versus alternatives like 'obsidian_append_content' (for adding to files) or 'obsidian_patch_content' (for partial updates). The description only states what it does without context for selection among similar tools.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions the tool performs a 'simple search' and returns context around matches, but doesn't specify what 'simple' entails (e.g., case sensitivity, regex support, performance characteristics, or error handling). For a search tool with zero annotation coverage, 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 concise and front-loaded, consisting of two sentences that directly state the purpose and usage. There's no unnecessary information, and each sentence contributes to understanding the tool's role. It could be slightly more structured but is efficient overall.

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 a search tool with no annotations and no output schema, the description is insufficient. It doesn't explain what the search returns (e.g., file names, snippets, or full content), how results are formatted, or any limitations. For a tool with 2 parameters and behavioral uncertainty, more context is needed to be 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?

The schema description coverage is 100%, so the input schema already documents both parameters ('query' and 'context_length') with descriptions. The description adds no additional parameter semantics beyond what's in the schema, such as examples or constraints. With high schema coverage, 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 tool's purpose: 'Simple search for documents matching a specified text query across all files in the vault.' It specifies the verb ('search'), resource ('documents'), and scope ('across all files in the vault'). However, it doesn't explicitly differentiate from its sibling 'obsidian_complex_search' beyond the 'simple' qualifier, which is somewhat vague.

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 some guidance: 'Use this tool when you want to do a simple text search.' This implies usage context but doesn't explicitly state when to use alternatives like 'obsidian_complex_search' or other search-related siblings. It offers basic direction but lacks clear exclusions or comparisons.

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