search
Perform web searches to find information, images, videos, or news with customizable parameters like region, safe search, and time limits. Returns structured results with titles, URLs, and snippets for comprehensive research.
Instructions
Search the web using DuckDuckGo.
This tool performs a web search using DuckDuckGo and returns structured results
including titles, URLs, and body snippets.
Args:
query: The search query string
max_results: Maximum number of results to return (1-50)
region: Region code for localized results (optional)
safesearch: Safe search filtering level
timelimit: Time limit for results (day, week, month, year)
Returns:
SearchResponse with query, results, and total count
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| max_results | No | Maximum number of results to return (1-50) | |
| categories | No | Result type to search: text (default), images, videos, or news | text |
| region | No | Region code (e.g., 'us-en', 'uk-en', 'de-de') | |
| safesearch | No | Safe search level | off |
| timelimit | No | Time limit for results |
Implementation Reference
- src/duckduckgo/mcp.py:134-247 (handler)The handler function that executes the 'search' tool logic, performing DuckDuckGo web searches (text, news, images, videos) using the ddgs library and returning structured SearchResponse.def search_tool( query: str, max_results: Annotated[ int, Field(ge=1, le=50, description="Maximum number of results to return (1-50)"), ] = 10, categories: Annotated[ Literal["text", "images", "videos", "news"], Field(description="Result type to search: text (default), images, videos, or news"), ] = "text", region: Annotated[ str | None, Field(description="Region code (e.g., 'us-en', 'uk-en', 'de-de')"), ] = None, safesearch: Annotated[ Literal["on", "moderate", "off"], Field(description="Safe search level"), ] = "off", timelimit: Annotated[ Literal["day", "week", "month", "year"] | None, Field(description="Time limit for results"), ] = None, ) -> SearchResponse: """Search the web using DuckDuckGo. This tool performs a web search using DuckDuckGo and returns structured results including titles, URLs, and body snippets. Args: query: The search query string max_results: Maximum number of results to return (1-50) region: Region code for localized results (optional) safesearch: Safe search filtering level timelimit: Time limit for results (day, week, month, year) Returns: SearchResponse with query, results, and total count """ # map timelimit values to ddgs parameters tl = ( { "day": "d", "week": "w", "month": "m", "year": "y", }.get(timelimit.strip().lower(), None) if timelimit else None ) client = DDGS() region_param = region or "us-en" if categories == "text": raw_results = client.text( query, max_results=max_results, region=region_param, safesearch=safesearch, timelimit=tl, ) elif categories == "news": raw_results = client.news( query, max_results=max_results, region=region_param, safesearch=safesearch, timelimit=tl, ) elif categories == "images": raw_results = client.images( query, max_results=max_results, region=region_param, safesearch=safesearch, timelimit=tl, ) elif categories == "videos": raw_results = client.videos( query, max_results=max_results, region=region_param, safesearch=safesearch, timelimit=tl, ) else: # Fallback to text in case of unexpected value raw_results = client.text( query, max_results=max_results, region=region_param, safesearch=safesearch, timelimit=tl, ) # Convert to structured results results: list[SearchResult] = [] for result in raw_results: title = result.get("title", "No title") # Prefer common link keys across result types url = ( result.get("href") or result.get("url") or result.get("content") # videos or result.get("image") # images direct link or "No URL" ) body = ( result.get("body") or result.get("description") # videos or "No body" ) results.append(SearchResult(title=title, url=url, body=body)) return SearchResponse(query=query, results=results, total_results=len(results))
- src/duckduckgo/mcp.py:96-102 (schema)Pydantic model defining the output schema of the search tool response.class SearchResponse(BaseModel): """Response containing search results.""" query: str = Field(description="The search query that was executed") results: list[SearchResult] = Field(description="List of search results") total_results: int = Field(description="Total number of results returned")
- src/duckduckgo/mcp.py:88-94 (schema)Pydantic model defining the schema for individual search results used in the tool output.class SearchResult(BaseModel): """A single search result from DuckDuckGo.""" title: str = Field(description="The title of the search result") url: str = Field(description="The URL of the search result") body: str = Field(description="The body/snippet of the search result")
- src/duckduckgo/mcp.py:133-133 (registration)FastMCP decorator that registers the search_tool function as the MCP tool named 'search'.@mcp.tool(name="search")