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

Annotations indicate this is a non-readOnly, non-destructive operation, which the description aligns with by stating it 'creates' a note. The description adds valuable context beyond annotations: it specifies the default folder location ('Notes/'), notes that promotion is manual, and mentions error behavior ('error if the note already exists'), enhancing transparency about workflow and constraints.

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 front-loaded with the core purpose, followed by usage guidelines, parameter summary, and return behavior in a structured format. Every sentence adds value—no wasted words—and it's appropriately sized for the tool's complexity, making it easy to scan and understand.

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

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

Given the tool's moderate complexity (creation with parameters), annotations cover safety aspects, and an output schema exists (so return values don't need explanation), the description is complete. It covers purpose, usage, parameters, and error handling, providing all necessary context for an agent to invoke the tool correctly without redundancy.

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

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

Schema description coverage is 0%, so the description carries full burden. It adds meaningful semantics: it explains that params include 'Title, content (full markdown with frontmatter), and target folder,' clarifies the title becomes the filename with an example, and notes the default folder. This compensates well for the lack of schema descriptions, though it doesn't detail all parameter nuances like maxLength for title.

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

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

The description clearly states the specific action ('Create a new note') and resource ('in the vault'), distinguishing it from siblings like brain_update_note (update), brain_read_note (read), or brain_move_note (move). It explicitly defines the creation operation, making the purpose unambiguous and distinct.

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

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

The description provides explicit guidance on when to use this tool: 'Agent-created notes should always go to Notes/ first' and mentions 'promotion happens during manual vault review.' It also distinguishes from alternatives by specifying the default folder behavior, helping the agent choose this over other note-related 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?

Annotations already provide readOnlyHint=true, destructiveHint=false, openWorldHint=false, and idempotentHint=true, covering safety and idempotency. The description adds useful context beyond this by specifying the mechanism ('via [[wikilinks]]') and the scope ('across the vault'), which helps the agent understand the tool's behavior without contradicting 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 front-loaded with the core purpose, followed by usage examples, and ends with clear sections for Args and Returns. Every sentence adds value without redundancy, making it efficient 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 low complexity (1 parameter), rich annotations, and the presence of an output schema (implied by 'Returns' section), the description is complete. It covers purpose, usage, parameters, and returns adequately, leaving no significant gaps for the agent to operate effectively.

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

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

Schema description coverage is 0%, so the description must compensate. It adds meaning by explaining that the parameter is the 'Title of the note to find backlinks for' and clarifies the return value as a 'JSON list of notes that contain [[title]] wikilinks,' which provides essential context not in the schema. However, it does not detail parameter constraints like 'minLength: 1' from the schema.

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

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

The description clearly states the specific action ('Find all notes that link to a given note via [[wikilinks]]') and resource ('notes'), distinguishing it from siblings like brain_search_notes or brain_list_notes by focusing on backlink relationships rather than general search or listing. The purpose is precise and unambiguous.

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

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

The description provides clear context for when to use this tool ('Useful for understanding how a note is referenced across the vault, checking if a note is properly linked from MOCs, or mapping relationships between concepts'), but it does not explicitly state when not to use it or name alternatives among siblings. This gives good guidance but 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?

Annotations already provide readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=false, covering safety and behavior. The description adds value by specifying the return content (folder layout, note counts, MOC - Home) and its use for navigation, enhancing context without contradicting 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 front-loaded with the main purpose, followed by usage guidance and return details in three clear sentences. Each sentence earns its place by providing essential information without redundancy, making it efficient and well-structured.

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 is low (0 parameters, read-only), annotations cover behavioral traits, and an output schema exists, the description is complete. It explains what the tool does, when to use it, and what it returns, without needing to detail parameters or output values further.

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 0 parameters and 100% schema description coverage, the baseline is 4. The description appropriately omits parameter details, as none are needed, and focuses on the tool's purpose and output, adding no unnecessary information.

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 ('Get a high-level overview') and resource ('vault structure'), distinguishing it from siblings like brain_list_folders or brain_list_notes by emphasizing the 'overview' aspect and including MOC - Home content for navigation.

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

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

It explicitly states when to use this tool ('as a starting point for exploring the vault') and implies alternatives by mentioning folder statistics and note counts, which could be obtained via other tools like brain_list_folders or brain_list_notes, though not named directly.

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?

Annotations already cover key behavioral traits (read-only, non-destructive, idempotent, closed-world), but the description adds valuable context beyond this: it specifies that it returns 'immediate subdirectories' (not recursive) and includes 'note counts' in the output. This enhances understanding of the tool's behavior without contradicting annotations.

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

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

The description is well-structured and front-loaded with the core purpose, followed by usage guidance, parameter details, and return information. Every sentence adds value without redundancy, making it efficient and easy to parse.

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

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

Given the tool's low complexity (one optional parameter), comprehensive annotations, and the presence of an output schema, the description is complete. It covers purpose, usage, parameter semantics, and output format, leaving no gaps for the agent to understand and 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?

With 0% schema description coverage, the description fully compensates by explaining the single parameter: 'folder: Optional vault-relative path. Omit for vault root.' This clarifies the parameter's purpose, optionality, and default behavior, adding essential meaning not present in the schema.

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

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

The description clearly states the specific action ('List subfolders') and resource ('within a vault directory'), distinguishing it from sibling tools like brain_list_notes (which lists notes) and brain_get_structure (which might provide broader hierarchy). It explicitly mentions the scope ('immediate subdirectories') and output ('note counts'), making the purpose unambiguous.

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

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

The description provides clear context for when to use this tool ('Useful for exploring the vault hierarchy before reading specific notes'), which helps differentiate it from brain_list_notes or brain_search_notes. However, it does not explicitly state when not to use it or name specific alternatives, preventing 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=false. The description adds useful context about what metadata is returned (path, title, type, updated date, status) and filterable frontmatter types, which goes beyond annotations. However, it doesn't mention behavioral aspects like pagination, rate limits, or authentication needs.

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 purpose, usage examples, parameters summary, and return information. It's appropriately sized, though the Args/Returns sections could be more integrated with the main text. Every sentence adds value, with 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?

Given the tool has annotations covering safety (readOnly, non-destructive) and an output schema exists, the description provides good context about what the tool does, when to use it, and what it returns. It adequately compensates for the 0% schema description coverage. The main gap is lack of explicit sibling differentiation.

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 0%, so the description carries full burden. It provides a high-level summary of parameters ('folder, note_type filter, recursive flag, limit') and clarifies the note_type filter values (moc, project, area, resource, archive). However, it doesn't explain parameter interactions or provide examples for the folder parameter.

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

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

The description clearly states the specific action ('List notes in a vault folder') and resource ('notes'), with explicit mention of optional filtering by type. It distinguishes from siblings like brain_search_notes (which likely searches content) and brain_list_folders (which lists folders, not 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 clear context for when to use this tool ('Useful for browsing a folder, reviewing inbox contents, or finding all notes of a specific type'). However, it doesn't explicitly state when NOT to use it or name specific alternatives among siblings (e.g., brain_search_notes for content-based searches).

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?

Annotations already indicate this is not read-only, destructive, idempotent, or open-world, but the description adds valuable context: it specifies the tool moves files (implied mutation), mentions promotion as a common use case, and notes it returns confirmation or errors. This goes beyond annotations by clarifying the operation's intent and output 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 front-loaded with the core purpose, followed by usage context, and then structured sections for Args and Returns. Every sentence adds value without redundancy, making it efficient and easy to parse for an AI agent.

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

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

Given the tool's moderate complexity (moving files), the description covers purpose, usage, parameters, and returns. With annotations providing safety hints and an output schema existing (though not shown), the description is complete enough for an agent to understand when and how to invoke this tool effectively.

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

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

Schema description coverage is 0%, so the description carries full burden. It adds meaning by explaining that params include 'Source path and destination folder', with examples in the Args section ('e.g., Notes/my-note.md' and 'e.g., Projects'). This clarifies the purpose of the single 'params' object beyond the schema's structural definition.

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 explicitly states the action ('Move a note from one folder to another') and the resource ('note'), with a specific example ('promote from inbox'). It clearly distinguishes this from sibling tools like brain_create_note or brain_update_note by focusing on relocation rather than creation or content modification.

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 when to use this tool ('Commonly used to promote notes from Notes/ to their final location in a domain folder'), including a typical workflow example. However, it does not explicitly state when not to use it or name alternatives (e.g., when to use brain_update_note vs. move for content changes).

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 adds valuable behavioral context beyond what annotations provide. While annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, the description specifies that it 'Returns the complete markdown content including frontmatter, plus extracted metadata (type, wikilinks, updated date)' and describes the return format. This provides important implementation details about what data is returned and in what structure.

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

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

The description is perfectly structured and concise. The first sentence states the core purpose, the second describes the return value, and the Args/Returns sections provide essential details without redundancy. Every sentence earns its place, and information is front-loaded with the most important details first.

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

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

Given the tool's moderate complexity, rich annotations (readOnlyHint, idempotentHint), and the presence of an output schema, the description is complete enough. It explains what the tool does, what it returns, and provides parameter guidance. The output schema will handle return value details, so the description appropriately focuses on purpose and 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?

With 0% schema description coverage, the description must compensate but only partially succeeds. It states 'Either a vault-relative path or a note title' which clarifies the param's purpose, but doesn't explain the path format, title matching behavior, or what happens if both are provided. The schema itself has good descriptions for path and title fields, but the overall param object lacks description 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 specific action ('Read the full content'), target resource ('a specific note'), and identification method ('by path or title'). It distinguishes this read operation from siblings like brain_create_note, brain_update_note, and brain_move_note which are write operations, and from brain_list_notes which lists multiple notes rather than reading one.

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 when to use this tool ('Read the full content of a specific note by path or title'), implying it's for retrieving a single note's content. However, it doesn't explicitly state when NOT to use it or name specific alternatives like brain_search_notes for finding notes by content rather than path/title, or brain_list_notes for getting metadata about multiple notes.

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

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

Annotations already provide readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=false. The description adds valuable behavioral context beyond annotations: it specifies that it returns 'matching notes with context snippets' and 'Returns an error message if no results found,' which clarifies output format and error handling not covered by annotations.

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

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

The description is well-structured and front-loaded with the core purpose in the first sentence. Each subsequent sentence adds value: use cases, parameter overview, and return details. There is no wasted text, and it efficiently conveys necessary information.

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

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

Given the tool's moderate complexity (search function), rich annotations (covering safety and idempotency), and the presence of an output schema (which handles return values), the description is complete enough. It covers purpose, usage, behavioral traits, and parameter overview without needing to duplicate structured data.

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

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

Schema description coverage is 0%, but the description includes an 'Args' section that explains the 'params' object contains 'Search parameters including query, optional folder scope, and limit.' This adds some meaning beyond the schema, but does not detail individual parameters (query, folder, limit) or their interactions. With 0% coverage, it partially compensates but not fully.

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

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

The description clearly states the specific action ('Full-text search across the Brain Obsidian vault'), resource ('notes'), and scope ('Searches note content for the given query string'). It distinguishes from siblings like brain_list_notes (which lists without search) and brain_find_backlinks (which finds references).

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 when to use this tool ('Useful for finding notes about a topic, locating references, or discovering related content'), but does not explicitly state when not to use it or name alternatives among siblings (e.g., brain_list_notes for unfiltered listing).

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?

Annotations provide readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds valuable context: 'Replaces the full content' clarifies the mutation scope, and the update_date flag behavior explains a side effect. It also mentions error handling ('error if not found'). However, it doesn't cover rate limits, auth needs, or confirmation format details.

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 a purpose statement, behavioral details, and Args/Returns sections. It's front-loaded and efficient, but the Args section could be more specific (e.g., 'params: object with path/title, content, update_date') to avoid redundancy with the schema.

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 annotations cover safety (non-destructive, idempotent) and an output schema exists, the description is reasonably complete. It explains the core mutation, update_date behavior, and error cases. However, it misses details on note identification (path vs. title priority) and doesn't reference sibling tools for context.

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

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

Schema description coverage is 0%, so the description must compensate. It mentions 'Note path or title, new content, and update_date flag' and explains the update_date default/effect, adding meaning beyond the schema. However, it doesn't detail the path/title conflict resolution, content format, or error semantics for missing notes, leaving gaps.

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

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

The description clearly states the tool 'Update the content of an existing note' with the specific action 'Replaces the full content', which distinguishes it from siblings like brain_create_note (create) and brain_read_note (read). However, it doesn't explicitly differentiate from brain_move_note (which might update path/title) or mention the note identification mechanism (path vs. title) in the purpose statement.

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 by stating it's for 'existing note' and mentions the update_date flag behavior, but lacks explicit guidance on when to use this vs. alternatives like brain_create_note for new notes or brain_move_note for relocating notes. No prerequisites (e.g., note must exist) 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.