Vector search a workspace

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

With no annotations, the description carries the full behavioral burden. It usefully discloses that no LLM generation occurs, gives a default scoreThreshold of 0.2 with a rationale, and states the return shape. It does not mention side-effect safety, sorting behavior, or possible failure/empty-result behavior, leaving some burden uncovered.

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 short sentences, front-loaded with the core purpose. Every clause adds a distinct fact: what it searches, that it is not generation, the threshold default, and the return format. There is no filler or redundancy.

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 straightforward search tool with no output schema, the description is largely complete: it explains the operation, non-generation behavior, threshold default, and return output. It could be more complete by naming alternative sibling tools or describing topN semantics, but the essential invocation details are covered.

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 low (25%), so the description must compensate. It does add real value for scoreThreshold (default and why) and query semantics, but topN is left entirely to inference from its name and schema constraint. The description partially compensates for the schema gap 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 opens with a specific action and object: 'Semantic search over a workspace's embedded docs.' It also disambiguates from generation tools by stating 'No LLM generation' and clarifies the output ('Returns matching chunks with scores'). This clearly differentiates it from sibling write/forget/find tools.

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 usage is implied rather than explicit: it is a semantic retrieval tool, not an LLM-generation call, and the threshold default gives some context for tuning. However, it never names alternatives like rag_write or rag_find, nor does it state when not to use this tool.

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