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

With no annotations, the description carries the burden of disclosing side effects. It does mention appending to an existing note, implying a non-destructive behavior and a prerequisite of existence, but it does not describe error conditions (e.g., what happens if the note does not exist) or any permission requirements. This adds some value beyond the name but 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 concise, consisting of two sentences that front-load the core purpose and then provide use-case context. Every sentence adds value, with no redundant or filler content.

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

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

Given the tool's simplicity, two parameters, and no output schema, the description is largely complete. It covers the primary purpose, use cases, and the fact that it targets existing notes. Minor gaps include lack of error-handling details, but these are not critical for a straightforward append operation.

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 covers 100% of parameters with clear descriptions, so the baseline is 3. The tool description additionally clarifies that 'content' is appended rather than replacing anything, slightly enriching the semantics. However, it adds no new parameter-level details 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 appends text to the end of an existing note, using the specific verb 'append' and identifying the resource (note) and position (end). This distinguishes it from siblings like update_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 provides clear context by stating it is 'great for adding updates, new entries, or continuing a log,' which helps the agent understand typical use cases. However, it does not explicitly mention when not to use it or name alternative tools, so it lacks explicit exclusions.

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

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

No annotations are provided, so the description must carry the burden. It discloses the target folder and that no structure is required, which is helpful, but it doesn't explain other side effects like file creation behavior, collision handling, or permissions. This leaves some gaps in understanding the tool's exact 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?

Two sentences, front-loaded with the key action, no fluff. 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?

The tool is simple and well-described for its purpose. The schema covers parameters, and the description provides usage context and target location. Since there is no output schema, explaining return values is unnecessary. It's sufficiently complete, though a note about it being a write operation could be added.

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?

All four parameters are fully described in the schema (100% coverage), so the description doesn't need to add much. The phrase 'No structure required' reinforces that content can be free-form, and 'title' and 'content' are self-explanatory. The description adds minimal extra meaning 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 uses the specific verb 'capture' and identifies the resource as a thought/idea/brain dump saved to the Ideas/ folder. It clearly distinguishes from sibling tools like create_note and create_prd by emphasizing quick, unstructured capture.

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

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

Explicitly states when to use it: 'fleeting ideas, shower thoughts, or anything that needs to be captured fast.' It doesn't explicitly name alternatives or when-not-to-use, but the context is clear enough to guide an agent.

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

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

With no annotations provided, the description carries the burden of disclosing behavior. It does so by revealing that a hidden .gitkeep placeholder is written, which is non-obvious implementation detail. It lacks information about error handling (e.g., if the folder already exists) or permissions, but the core mechanism is transparent enough.

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

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

The description is concise, with only two sentences. The first sentence states the purpose and mechanism, and the second provides valuable context about Obsidian's behavior. No wasted words.

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

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

Given the simplicity of the tool (one parameter, no output schema), the description covers the essential aspects: what it does and how it behaves. It could mention potential failure modes or idempotency, but the current level of detail is sufficient for an agent to use the tool correctly in most cases.

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

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

The schema already provides full coverage (100%) with a clear description and example for the single folderPath parameter. The description adds no extra semantic detail about the parameter beyond what the schema already conveys, so 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 ('Create'), the target resource ('a new folder in the Obsidian vault'), and the mechanism (writing a hidden .gitkeep placeholder). This distinguishes it from sibling tools like create_note and list_folders, which involve different actions or resources.

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 implicit usage guidance by noting that Obsidian creates folders on demand when files are written, implying this tool is only needed when a folder must exist independently. However, it does not explicitly name alternative tools or state when not to use it, so it falls slightly short of a perfect 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?

No annotations are provided, so the description carries the burden of disclosure. It reveals the destination folder (Meetings/) and the included sections (attendees, agenda, decisions, etc.), but it does not mention potential side effects like overwriting, folder creation, or error handling. This adds useful context but lacks depth.

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 exactly two sentences: the first states the primary purpose and location, the second concisely lists the key content elements. Every sentence earns its place with no redundancy or filler.

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

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

For a 9-parameter create tool with no output schema, the description provides a solid overview, including folder placement and content structure, while the schema covers parameter specifics. It does not discuss return values or overwrite behavior, but the essentials for selecting and invoking the tool are present.

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

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

The schema description coverage is 89%, so the baseline is 3. The description lists content fields (attendees, agenda, discussion notes, decisions, action items) that map to schema properties, but it adds little beyond what the schema already documents. It does not clarify parameter formats or relationships 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 'Create a structured meeting note in the Meetings/ folder' – a specific verb, resource, and location. It distinguishes from siblings like create_note (generic) and create_prd/create_process_doc by emphasizing the meeting-specific structure and target folder.

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 capturing structured meeting notes and names the Meetings/ folder, providing clear context. However, it does not explicitly list when-not-to-use it or compare with alternatives like create_note, so the guidance stops short of being fully explicit.

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

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

Without annotations, the description must fully disclose behavior. It mentions overwriting, but this is misleading because the schema includes an 'overwrite' parameter defaulting to false, implying overwrites are opt-in. The description states unconditionally 'If the note already exists it will be overwritten,' contradicting the schema. It also omits details about error handling, return values, 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 concise at three sentences and front-loads the primary action. However, the second sentence about overwriting is not only inaccurate but also could confuse users, which slightly reduces its quality. Structurally it is well-organized, with the action first, then behavior, then formatting guidance.

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

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

For a simple create tool, the description covers the main action and path format, and the schema fully documents parameters. However, it does not describe return values, what happens when overwrite is false (error vs no-op), or whether parent directories are created. The overwrite contradiction also leaves a gap in understanding the tool's behavior, making it adequate but not complete.

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

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

Schema coverage is 100% with descriptions for all parameters, so the baseline is 3. The description adds value by giving a concrete path format example ('PRDs/my-feature.md') and clarifying content is markdown. It does not add much for the 'overwrite' parameter, but the schema already covers that, and the description's overwrite statement is inaccurate.

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 function: 'Create a new note in the Obsidian vault at the specified path.' This is a specific verb and resource, and it distinguishes from sibling tools like create_folder, update_note, append_to_note, and delete_note. The overwrite mention adds scope but does not obscure the core purpose.

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

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

The description provides path format guidance ('Use forward-slash separated paths like PRDs/my-feature.md') which is useful. However, it does not explicitly explain when to use create_note versus update_note or append_to_note, nor does it mention any exclusions or prerequisites. Usage is implied by the name and action, but not fully explicit.

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

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

With no annotations, the description carries full burden. It discloses key creation behavior (writes to PRDs/ folder, fills a template with specific sections) but omits details about overwrite behavior, idempotency, permissions, or return values—leaving a moderate gap for a creation tool.

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

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

The description is two sentences: the first states the action and destination, the second summarizes the template content and use case. Every word earns its place; no redundancy.

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

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

Given the tool has 12 params, no output schema, and excellent schema coverage, the description provides a strong high-level picture: what it creates, where, what it includes, and when to use it. Missing return behavior and duplicate handling, but these are minor for a creation tool with rich 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 coverage is 100%; each parameter has a description. The tool description echoes several fields (problem statement, goals, user stories, requirements, success metrics, open questions) but does not add meaning beyond the schema, 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 uses a specific verb ('Create') and resource ('structured Product Requirements Document'), states the target location ('PRDs/ folder'), and lists distinct content sections (problem statement, goals, user stories, etc.), clearly distinguishing it from sibling tools like create_process_doc or create_meeting_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?

Provides a clear use case ('Perfect for feature documentation') that implies when to use this tool, but does not explicitly mention alternatives or when not to use it. This is adequate context without exclusions.

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

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

No annotations are provided, so the description carries the burden. It clearly states that a note is created in the Processes/ folder and includes certain content, but it does not disclose side effects such as whether existing notes are overwritten, naming conventions, or output/return behavior. It adds some value beyond a simple tautology but remains sparse.

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

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

The description is two sentences, front-loaded with the core action and location, and every phrase adds meaning. No filler or redundancy.

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

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

The description provides the essential context for creating a process note—location and key content—and the schema covers all parameters and required fields. However, with no annotations and no output schema, it leaves return behavior and prerequisites implicit.

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

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

Schema coverage is 100%, so structured descriptions already document all 10 parameters. The description only repeats the names of a few parameters (steps, owners, tools, edge cases) without adding format, constraints, or relationships beyond what the schema provides.

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

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

The description uses a specific verb ('Create') with a clear resource ('process documentation or SOP note') and location ('Processes/ folder'), and summarizes the note's content. This distinguishes it from generic note creation tools and sibling PRD/meeting/project note 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 clearly implies this is for process documentation/SOPs rather than generic notes, and the folder location and content fields ('steps, owners, tools, and edge cases') provide context. However, it does not explicitly name alternative tools or state when not to use it.

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

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

With no annotations provided, the description must carry the full burden of behavioral disclosure. While it explains the note's role, it omits critical details like whether existing notes are overwritten, what permissions are required, how links are embedded, or what the return value is. This leaves significant ambiguity for a creation tool, especially given the lack of any safety 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 concise, consisting of two sentences. The first sentence immediately states the action and target location, while the second adds valuable context about the note's role. Every phrase earns its place, and there is no redundant or filler wording.

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

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

The tool has 11 parameters and no output schema, yet the description only provides a high-level purpose. It does not explain the resulting note's structure, default behaviors, error conditions, or expected response after creation. For such a complex tool, a more detailed description is expected, leaving gaps 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 82%, so the schema already documents most parameters, setting a baseline of 3. The description adds only general context (e.g., links to PRDs and Jira epics, tracks milestones) but does not provide additional meaning for individual parameters beyond what the schema states. It does not compensate for the few undocumented parameters (e.g., 'name', 'description') but doesn't need to since those are self-explanatory.

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

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

The description uses a specific verb 'Create' with a clear resource ('project overview and tracking note') and location ('in the Projects/ folder'). It further distinguishes the tool from siblings by stating it acts as the single source of truth for a project, linking to PRDs, Jira epics, meeting notes, and tracking milestones, which separates it from generic create_note or specialized create_prd.

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

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

The description clearly establishes when to use this tool: when creating a project-level overview and tracking note. It provides context but does not explicitly mention alternatives or exclusions, such as 'use create_prd for product requirement docs.' Thus, the usage context is clear, but there is no explicit negative 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 the full burden of disclosure. It explicitly states the deletion is 'permanent', signaling irreversibility, which is a critical behavioral trait. It also scopes the operation to the Obsidian vault, but doesn't mention side effects like reference cleanup; however, that is not essential for this simple tool.

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

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

The description is one sentence of eight words, front-loaded with the verb 'delete'. Every word contributes meaning, with no redundancy or filler.

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

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

Given the tool's simplicity—one parameter, no output schema—the description covers all essential aspects: the action, the subject, and the permanence. The schema handles the parameter details, so no additional context is needed for an agent to invoke 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?

The input schema fully describes the 'path' parameter with its relative-to-vault-root format, achieving 100% coverage. The description adds no additional parameter semantics, so it relies on the schema, which is adequate.

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

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

The description uses the specific verb 'delete' with the resource 'note' and scope 'from the Obsidian vault', clearly distinguishing it from sibling tools like create_note, read_note, and update_note. The word 'permanently' adds important nuance about the operation's effect.

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 a user wants to remove a note from the vault. It doesn't explicitly list exclusions or alternatives, but the sibling tools don't offer an obvious competing delete operation, so the guidance is clear. The context is sufficient for an agent 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?

No annotations are provided, so the description carries the burden. It discloses the scope ('top-level folders and file counts') and implies a read-only operation via 'get'. However, it doesn't describe the exact return format, potential performance implications, or whether it aggregates across nested folders. It adds basic behavior but lacks depth.

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

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

The description is two short sentences. The first sentence front-loads the core functionality, and the second provides a clean use case. There is zero fluff or redundancy.

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

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

Given that the tool is simple (0 params, no output schema), the description covers what it does and why to use it. It explains the return contents (folders and counts) adequately. It doesn't need to explain return formats or side effects. Slightly lacking because it could mention that it's a read-only aggregation, but overall complete for its complexity.

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

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

The tool has zero parameters, so the baseline is 4. There is no parameter documentation needed, and the description appropriately says what the tool returns instead. It adds no param semantics because there are none, but this is not a 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 function: 'Get a high-level overview of the vault structure — top-level folders and file counts.' It names a specific verb ('get') and a specific resource ('vault structure'), with concrete outputs (folders and file counts), distinguishing it from sibling tools like list_folders or 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 a usage context: 'Use this to understand the current state of the knowledge base.' This implies when to use it, but it does not explicitly contrast with alternatives like list_folders or mention when not to use it. The guidance is implied rather than explicit exclusions.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It states the core function but does not specify whether subfolders are included recursively, what format the results take, or any permissions/requirements. The optional parent scoping is disclosed, but key behavioral details remain ambiguous.

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

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

The description is a single concise sentence that front-loads the main purpose and mentions the optional scope without unnecessary words. Every word earns its place.

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

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

For a simple tool with one parameter, the description covers the basic selection context, but lacks an explanation of the output format and recursive behavior, especially since no output schema is provided to fill that gap.

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 already describes the parent parameter as 'Parent folder path, or empty for root' with 100% coverage, so the description adds only slight reinforcement by mentioning vault-wide vs specific directory listing. It does not provide materially new parameter meaning.

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 'List all folders in the Obsidian vault or within a specific directory' with a specific verb (List) and resource (folders), and distinguishes this from sibling tools like list_notes by focusing on folders rather than notes or other actions.

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

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

The description implies when to use the tool (when listing folders is needed) and clarifies the optional directory scope, but it does not explicitly mention alternatives or when not to use it, such as comparing with get_vault_overview or search_by_tag.

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

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

The description discloses the behavior for the folder parameter (empty for root). Without annotations, it carries the responsibility; it lacks details about recursion, hidden files, or return formatting, but the read-only listing is straightforward.

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

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

Two sentences, front-loaded with the action, no redundancy.

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

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

For a simple one-parameter listing tool, the description covers the main functionality. It stops short of specifying whether the listing is recursive or what the response contains, but it remains adequate.

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 covers the folder parameter 100% with its description; the description reiterates the default behavior, adding no new semantics 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 lists files and folders in a directory and explains the root default. It is specific about the resource and scope, though it does not explicitly mention alternatives like list_folders.

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 about when to choose this tool over list_folders or get_vault_overview. Only the folder parameter usage is described, so the when-to-use context is missing.

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 'saves' notes, implying a write operation, but does not disclose whether it creates a new note each time, overwrites existing notes, appends to a log, or how it handles naming/conflicts. It also fails to mention any return value or error behavior, leaving significant behavioral ambiguity 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 two sentences, front-loaded with the main action and destination, and every word contributes. It avoids fluff, 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 has 13 parameters, no output schema, and no annotations, the description is somewhat under-specified. It clarifies the folder and content, but does not explain the resulting file structure, how notes are stored, or what the agent should expect after invocation. This is adequate but leaves notable gaps for a tool with this complexity.

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

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

The schema already covers 77% of parameters with descriptions, so the description adds minimal extra semantic value. It highlights key fields like 'summary, context, decisions, blockers, and links' which aligns with schema properties, but it does not explain format, types, or any nuances beyond the schema. The mention of 'decisions' has no direct field, which may be assumed to live in '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 tool's function with a specific verb ('Save'), resource ('structured notes for a Jira ticket'), and destination ('to the Jira/ folder'). It also identifies key content captured (summary, context, decisions, blockers, links), distinguishing it from sibling note tools like create_note or create_meeting_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 provides clear context for usage: 'Great for keeping rich context alongside Jira's limited fields.' This implies the tool is preferred when more detail is needed than Jira's native fields can hold. However, it does not explicitly exclude alternatives or name them, so it falls short of a 5.

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

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

With no annotations, the description carries the full burden. It adds that the tool returns 'full markdown content', which is valuable context. However, it does not disclose error behavior (e.g., missing path), return format, or any side effects. For a simple read operation, this is adequate but not rich.

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

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

The description is a single, front-loaded sentence (12 words) that conveys the essential information without any waste. Every word contributes to the meaning.

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

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

Given the low complexity (1 parameter, no output schema), the description is nearly complete. It explains the action and the parameter. It could optionally mention what happens if the note doesn't exist or the return format, but for a read-only operation, the current description is sufficient for an AI agent to select and invoke the tool.

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

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

Schema description coverage is 100% for the single 'path' parameter, which includes a clear explanation and an example. The tool description adds no further parameter semantics, but the schema already fully documents the parameter, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Read the full markdown content of a note from the Obsidian vault.' It uses a specific verb ('read'), identifies the resource (note), and specifies the content type (full markdown). This distinguishes it from sibling tools like create_note, update_note, or 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 implies usage when you need a note's content, but it does not explicitly state when to use this tool versus alternatives like search_notes or get_vault_overview. No exclusions or alternative tool mentions are provided, so the context is only implied by the name and description.

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 should disclose whether the tool is read-only, the return format, and any limitations. It does not mention the effect of the 'limit' parameter, and the phrase 'all notes' conflicts with the limit's existence. The only behavioral detail given is the #-prefix formatting rule, which is not sufficient.

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

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

The description is concise at two sentences, starting with the primary function and following with a necessary formatting instruction. Every word adds value, with no redundant or vague phrasing.

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?

There is no output schema, so the description should at least hint at the response shape. It says 'Find all notes' but does not specify whether it returns note contents, paths, or metadata. It also lacks information about tag matching behavior (exact vs partial) or search scope (frontmatter/body), leaving significant gaps for an agent.

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

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

Both parameters are described in the schema with 100% coverage, so the baseline is 3. The description's note about omitting the # prefix duplicates the schema's tag description and adds no new meaning. The 'limit' parameter is not mentioned but is already well-documented 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 action ('Find all notes') and the resource ('containing a specific Obsidian tag'), with examples like #prd and #jira. It also clarifies the tag format (no # prefix), which makes the purpose unambiguous and distinguishes it from a general note search 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 implies the tool is for tag-based searches, but it does not explicitly state when to use this tool versus alternatives like search_notes. There is no mention of exclusions or preferred scenarios, leaving the agent to infer usage from the name and description.

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 the return format (file paths with context snippets) and scope (full-text across all notes), which is useful behavioral detail beyond a tautological statement. It does not mention edge cases like case sensitivity or performance, but the core behavior is clearly conveyed.

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

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

The description is two sentences long: the first states purpose and return format, the second gives usage guidance. It is front-loaded and contains no 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?

The description covers purpose, return format, and usage examples, which is sufficient for a simple search tool with three well-documented parameters. It could mention behaviors like case sensitivity or pagination, but these are not essential given the schema covers parameter details.

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

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

Schema coverage is 100%, and all parameters have descriptions. The description does not add any parameter-specific semantics beyond what the schema already provides, so the baseline 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 performs a full-text search across all notes in the Obsidian vault and returns matching file paths with context snippets. The verb 'search' and resource 'all notes' are specific, and it distinguishes from sibling tools like search_by_tag by focusing on full-text content rather than tags.

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

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

It provides explicit usage context: 'Use this to find existing PRDs, processes, Jira notes, or any content.' However, it does not explicitly mention when NOT to use it or alternatives like search_by_tag, so it is clear but lacks exclusions.

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

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

With no annotations, the description lists the folders and index notes created, giving a clear picture of the main action. However, it does not disclose idempotency, whether existing notes are overwritten, or other side effects when run multiple times.

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

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

The description is two sentences, front-loaded with the purpose, and the folder list is compact. No unnecessary words.

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

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

For a zero-parameter setup tool, the description covers what it does, when to use it, and what it creates. No output schema is needed, and the description is sufficient.

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

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

The tool has zero parameters; the schema is empty with 100% coverage. The description does not need to explain parameters, so the baseline 4 applies.

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

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

The description clearly states it 'Initialize the recommended PM vault folder structure' and lists the specific folders created (PRDs/, Processes/, Jira/, etc.), distinguishing it from sibling tools like create_folder which create individual folders.

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

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

It says 'Run this once to set up your Obsidian vault for PM work,' providing clear context that this is for initial setup. However, it does not explicitly mention when not to use it or name 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. It transparently communicates that the operation overwrites the entire content, which implies destructiveness. However, it does not disclose error behavior, whether the note must exist, or any side effects beyond replacement, leaving some behavioral context under-specified.

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

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

The description is a single sentence that immediately states the core action and object. It is free of filler, front-loaded with the key verb 'Replace', and perfectly sized for a tool with only two parameters.

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

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

The tool is simple, the schema fully documents both parameters, and the action is clear. The description is sufficient for selection and invocation in most cases. Its main shortfall is the lack of usage guidance relative to sibling mutation tools, but this does not critically undermine completeness given the simplicity.

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

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

With schema description coverage at 100%, the parameters 'path' and 'content' are already well-documented. The description adds no additional semantic meaning about parameter format or usage beyond what the schema provides, so a baseline 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 uses a specific verb 'Replace' with a precise resource 'the entire content of an existing note in the Obsidian vault'. This clearly distinguishes it from sibling tools like append_to_note or create_note, which have different actions.

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

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

The description contains no explicit guidance on when to use this tool compared to alternatives such as append_to_note or create_note. It does not mention prerequisites (e.g., note must exist) or any exclusions, leaving usage only implied by the verb 'replace'.

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