needle_search
Search documents using semantic understanding to find relevant content based on meaning rather than keywords. Understands natural language queries and returns ranked passages with source information.
Instructions
Perform intelligent semantic search across documents in a Needle collection. This tool uses advanced embedding technology to find relevant content based on meaning, not just keywords. The search: - Understands natural language queries - Finds conceptually related content - Returns relevant text passages with source information - Ranks results by semantic relevance
Use this tool when you need to:
- Find specific information within documents
- Answer questions from document content
- Research topics across multiple documents
- Locate relevant passages and their sources
More effective than traditional keyword search for:
- Natural language questions
- Conceptual queries
- Finding related content
Returns matching text passages with their source file IDs.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| collection_id | Yes | The unique collection identifier to search within | |
| query | Yes | Natural language query describing the information you're looking for |
Implementation Reference
- src/needle_mcp/server.py:336-356 (handler)Executes the needle_search tool by validating arguments, calling NeedleClient.collections.search(), formatting results with content and file_id, and returning as JSON TextContent.elif name == "needle_search": if not isinstance(arguments, dict) or not all(k in arguments for k in ["collection_id", "query"]): raise ValueError("Missing required parameters") results = client.collections.search( collection_id=arguments["collection_id"], text=arguments["query"], # Optionally add these parameters if needed: # max_distance=0.8, # Adjust threshold as needed # top_k=5 # Adjust number of results as needed ) result = [{ "content": r.content, "file_id": r.file_id, } for r in results] return [TextContent( type="text", text=json.dumps(result, indent=2, default=str) )]
- src/needle_mcp/server.py:259-272 (schema)Input schema for needle_search tool defining required collection_id and query parameters as strings.inputSchema={ "type": "object", "properties": { "collection_id": { "type": "string", "description": "The unique collection identifier to search within" }, "query": { "type": "string", "description": "Natural language query describing the information you're looking for" } }, "required": ["collection_id", "query"] }
- src/needle_mcp/server.py:237-273 (registration)Registers the needle_search tool with the MCP server via list_tools(), including name, detailed description, and input schema.Tool( name="needle_search", description="""Perform intelligent semantic search across documents in a Needle collection. This tool uses advanced embedding technology to find relevant content based on meaning, not just keywords. The search: - Understands natural language queries - Finds conceptually related content - Returns relevant text passages with source information - Ranks results by semantic relevance Use this tool when you need to: - Find specific information within documents - Answer questions from document content - Research topics across multiple documents - Locate relevant passages and their sources More effective than traditional keyword search for: - Natural language questions - Conceptual queries - Finding related content Returns matching text passages with their source file IDs.""", inputSchema={ "type": "object", "properties": { "collection_id": { "type": "string", "description": "The unique collection identifier to search within" }, "query": { "type": "string", "description": "Natural language query describing the information you're looking for" } }, "required": ["collection_id", "query"] } )