search_notes

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It goes beyond a simple restatement by revealing the execution strategy (index search) and the fallback to a linear vault scan when the index is empty, which is valuable operational behavior. It does not mention read-only status, but 'search' reasonably implies non-mutating behavior, and no side effects are relevant for this tool.

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

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

The description is a single, front-loaded sentence with no filler. It packs the core purpose and a key behavioral nuance into the smallest possible space, earning every word.

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 tool with three parameters, no parameter descriptions in the schema, no annotations, and no output schema, the description is too sparse. It omits any explanation of what 'paths' controls, how 'limit' behaves, or what the result shape is. The fallback detail is nice, but it does not fill the major gaps an agent needs to call 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?

Schema description coverage is 0%, so the description must compensate for the lack of parameter documentation. It only implies the 'query' parameter through 'keyword search' and leaves 'limit' and 'paths' completely unexplained. Without additional parameter context, an agent cannot infer how to scope or paginate results.

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 states a specific verb-resource pair ('Keyword search over indexed notes') and distinguishes itself from the sibling rag_search by explicitly labeling the search as keyword-based. The fallback behavior is an additional specific detail that further clarifies scope.

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?

Usage context is implied by the phrase 'keyword search' — it signals when to prefer this tool over a semantic search tool like rag_search — but there is no explicit when-to-use/when-not-to-use guidance or mention of alternatives. The fallback text hints at behavior, not usage conditions.

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