search_facts

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

No annotations are provided, so the description must carry the behavioral burden. It does disclose that it performs semantic search and returns a list with scores, and it clarifies the limit range. However, it does not explicitly state that the operation is read-only (though implied), nor does it mention any special behaviors like partial matches, staleness handling, or performance considerations. It is sufficient for a simple search but not rich.

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 compact and well-structured: a one-line purpose, then Args/Returns sections. Every sentence contributes value, and the most important information (purpose) is front-loaded. No redundancy or 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?

Given that there is an output schema (indicated by the context signal) and only two simple parameters, the description is adequate. It explains the input, the return behavior, and the limit semantics. It does not mention error scenarios or edge cases, but those are often not required for a basic search. It is complete enough for an agent to make a correct call.

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?

The schema only provides types and a default, but the description adds meaningful semantics: 'query' is described as a 'Natural language search query' and 'limit' as 'Maximum results (1-100, default 10)'. This gives an agent the exact range and an understanding of what the parameters are used for, fully compensating for zero schema coverage.

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 action ('Semantic search') on a specific resource ('indexed facts'). This distinguishes it from sibling tools like 'query_facts' or 'search_notes' by emphasizing semantic (natural language) retrieval. It also describes the return format, so an agent knows what to expect.

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 implies usage for natural-language fact searches but does not explicitly contrast it with alternatives such as 'query_facts' or 'list_facts'. There is no 'when to use' or 'when not to use' guidance. This leaves the agent to infer the right tool among many siblings, which is a missed opportunity.

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