Search Stored Answers (local FTS)

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

With no annotations, the description carries the full burden. It discloses offline operation, local-only scope, no rate-limit cost, and the snippet marker format. Lacking are details on what happens if no results or an error occurs, but the provided behavioral notes are substantive for a read-only search 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 extremely concise at three sentences, with the most critical information (purpose, technology, offline nature, scope, and limitation) presented upfront. Every sentence adds unique value, achieving high density without sacrifice of clarity.

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 moderate complexity of an FTS tool with two parameters and no output schema, the description covers the key aspects: what is searched, performance (millisecond-fast), offline property, and snippet format. Minor gaps exist (no mention of return structure or error handling), but overall completeness is high.

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 50% (only 'query' has a description). The description adds context about FTS5 syntax (plain words, phrases, AND/OR/NOT) and the fields searched, which extends what the schema provides. It implicitly describes the limit parameter's purpose but does not provide per-parameter enrichment beyond the schema baseline.

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 identifies the tool as performing full-text search over locally stored answers from oe_ask/oe_article_get, specifying the searched fields (questions, titles, answer bodies). It distinguishes itself from the sibling tool oe_history_list by noting coverage of only local data, leaving no ambiguity about its purpose.

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 states when to use (for fast offline local search) and explicitly advises against using it for complete server-side history, directing users to oe_history_list instead. However, it does not provide guidance on prerequisites or when this tool should be avoided entirely.

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