find_similar_notes_tool

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

With no annotations, the description carries full burden for behavioral disclosure. It explains the algorithm (TF-IDF cosine), the heuristic nature, the parameter effects (exclude_path, min_score), and the output format ('data.items: [{path, score}], most similar first'). It does not mention potential edge cases (e.g., empty text, no matches) or performance, but the core behavior is transparently described.

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 dense but well-organized: it opens with the purpose, then explains the algorithm, then lists parameter semantics inline. Each sentence adds value, and it avoids redundancy. It is somewhat long but appropriately detailed for a tool with no annotations or schema descriptions. The structure is logical and front-loaded with the key use case.

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 presence of an output schema (which covers return format) and the description's coverage of algorithm, use case, and key parameters, the tool is fairly complete. The only minor gaps are the vault parameter (though context likely implies a vault selector) and edge-case behavior. For a read-only search tool with 5 parameters, this is strong.

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 explain parameters. It explains exclude_path and min_score in detail, and implicitly covers text via the purpose. However, limit and vault are not explained; limit is likely self-evident (default 5) but vault could be ambiguous without context. Since it only explains 2 of 5 parameters explicitly, 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 a specific verb ('Find conceptually related notes') and resource ('notes'), and defines the core purpose (duplicate prevention before creating a new note). It distinguishes itself from simple keyword search by explaining the TF-IDF cosine similarity approach and its limitations (not a transformer model, catches shared distinctive words, not pure synonym rewrites). This clearly separates it from sibling tools like search_notes_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 provides an explicit use case: 'for duplicate prevention before creating a new note' with a concrete example question. It also implies when not to use it by stating it 'catches shared distinctive words... not pure synonym rewrites', which hints at limitations. However, it does not explicitly name alternative tools or contrast with keyword search, so the guidance is slightly implicit but still clear enough for an agent to decide.

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