brain-mcp

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.