Search documents using natural language. Semantic similarity engine identifies relevant files by meaning, not just keywords, to return useful results.
Search documents using semantic similarity. Connects to the Semantic Search Engine to find relevant documents based on a natural language query.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of results to return | |
| query | Yes | Natural language search query |
Changes observed during successful MCP inspections.
v1.0.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover safety with readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds the useful detail that the tool connects to an external Semantic Search Engine, implying external dependency, but it does not describe result structure, pagination, or other behavioral caveats. This is acceptable 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?
Two short sentences cover purpose and context without filler. The core action is front-loaded in the first sentence, and the second sentence adds necessary context about the connection to the Semantic Search Engine and natural language queries.
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 simple two-parameter, read-only search tool, the description is nearly complete. It states what it searches, how it searches, and what kind of query to provide. The only gap is that there is no output schema and the description does not explicitly describe the return shape, though 'find relevant documents' implies a list of matching documents.
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 100%, so the baseline is 3. The description adds value by explaining that the query is interpreted semantically and should be a natural language expression, not a keyword syntax. The limit parameter is already fully documented in the schema, so no further compensation is needed.
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 uses a specific verb and resource: 'Search documents using semantic similarity.' It clearly differentiates from sibling tools like toad_run_eval, toad_system_status, and prompt-related tools, so an agent can identify this as the document search tool without ambiguity.
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 establishes clear usage context: use this tool for semantic similarity search over documents with a natural language query. It does not explicitly list exclusions or alternative tools, but the sibling tools are topically distinct, so no conflicting usage guidance is needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.