Get the vault sections that answer a question

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

Annotations already declare readOnly/idempotent/openWorld=false, so the description need not restate safety. It adds genuinely useful behavioral context: hybrid retrieval (keywords + meaning + reranker), that paraphrases work, and that the reply self-reports coverage as good/thin/none. It does not describe truncation/pagination behavior, but that is largely covered by budget_chars in the schema.

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

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

Three sentences, front-loaded with the core behavior and formatted so routing, phrasing and output expectations read in order. Slightly dense but every sentence carries information; no 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?

With no output schema, the description still tells the agent what comes back (relevant sections with source note ids) and how to interpret confidence (coverage: good/thin/none), and it explains the retrieval mode so the agent knows how to compose the query. Nothing needed to call it correctly is missing.

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 the baseline is 3, but the description meaningfully adds to the question parameter by specifying how to phrase it ('plain words', paraphrases okay, still include specific nouns/ids/dates). That guidance goes beyond the schema's 'question or topic, in plain words with specific nouns'.

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?

States a specific verb and resource ('returns the most relevant sections from across the vault for a question, with source note ids') and explicitly contrasts itself with the sibling brain_search. An agent can identify the tool's distinct role without opening either schema.

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?

Gives a clear when-to-use ('before brain_search when you need to answer or reason about something the owner may have written down') and an ordering relative to the alternative. It never states a when-not or explains exactly what brain_search does differently, so it stops short of full routing guidance.

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