search_documentation
Search AWS documentation using the official AWS Documentation Search API to find relevant pages when you don't have specific URLs. Use technical terms, service names, and filters to improve results.
Instructions
Search AWS documentation using the official AWS Documentation Search API.
Usage
This tool searches across all AWS documentation for pages matching your search phrase. Use it to find relevant documentation when you don't have a specific URL.
Search Tips
Use specific technical terms rather than general phrases
Include service names to narrow results (e.g., "S3 bucket versioning" instead of just "versioning")
Use quotes for exact phrase matching (e.g., "AWS Lambda function URLs")
Include abbreviations and alternative terms to improve results
Use guide_type and product_type filters found from a SearchResponse's "facets" property:
Filter only for broad search queries with patterns:
"What is [service]?" -> product_types: ["Amazon Simple Storage Service"]
"How to use <service 1> with <service 2>?" -> product_types: [<service 1>, <service 2>]
"[service] getting started" -> product_types: [] + guide_types: ["User Guide, "Developer Guide"]
"API reference for [service]" -> product_types: [] + guide_types: ["API Reference"]
Result Interpretation
Each SearchResponse includes:
search_results: List of documentation pages, each with:
rank_order: The relevance ranking (lower is more relevant)
url: The documentation page URL
title: The page title
context: A brief excerpt or summary (if available)
facets: Available filters (product_types, guide_types) for refining searches
query_id: Unique identifier for this search session
Args: ctx: MCP context for logging and error handling search_phrase: Search phrase to use search_intent: The intent behind the search requested by the user limit: Maximum number of results to return product_types: Filter by AWS product/service guide_types: Filter by guide type
Returns: List of search results with URLs, titles, query ID, context snippets, and facets for filtering
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| search_phrase | Yes | Search phrase to use | |
| search_intent | No | For the search_phrase parameter, describe the search intent of the user. CRITICAL: Do not include any PII or customer data, describe only the AWS-related intent for search. | |
| limit | No | Maximum number of results to return | |
| product_types | No | Filter results by AWS product/service (e.g., ["Amazon Simple Storage Service"]) | |
| guide_types | No | Filter results by guide type (e.g., ["User Guide", "API Reference", "Developer Guide"]) |
Implementation Reference
- The handler function decorated with @mcp.tool() that implements the core logic of searching AWS documentation via the official API, handling errors, parsing JSON response, extracting results, and returning a list of SearchResult objects. Includes input schema definitions via Pydantic Field.@mcp.tool() async def search_documentation( ctx: Context, search_phrase: str = Field(description='Search phrase to use'), limit: int = Field( default=10, description='Maximum number of results to return', ge=1, le=50, ), ) -> List[SearchResult]: """Search AWS documentation using the official AWS Documentation Search API. ## Usage This tool searches across all AWS documentation for pages matching your search phrase. Use it to find relevant documentation when you don't have a specific URL. ## Search Tips - Use specific technical terms rather than general phrases - Include service names to narrow results (e.g., "S3 bucket versioning" instead of just "versioning") - Use quotes for exact phrase matching (e.g., "AWS Lambda function URLs") - Include abbreviations and alternative terms to improve results ## Result Interpretation Each result includes: - rank_order: The relevance ranking (lower is more relevant) - url: The documentation page URL - title: The page title - context: A brief excerpt or summary (if available) Args: ctx: MCP context for logging and error handling search_phrase: Search phrase to use limit: Maximum number of results to return Returns: List of search results with URLs, titles, and context snippets """ logger.debug(f'Searching AWS documentation for: {search_phrase}') request_body = { 'textQuery': { 'input': search_phrase, }, 'contextAttributes': [{'key': 'domain', 'value': 'docs.aws.amazon.com'}], 'acceptSuggestionBody': 'RawText', 'locales': ['en_us'], } search_url_with_session = f'{SEARCH_API_URL}?session={SESSION_UUID}' async with httpx.AsyncClient() as client: try: response = await client.post( search_url_with_session, json=request_body, headers={ 'Content-Type': 'application/json', 'User-Agent': DEFAULT_USER_AGENT, 'X-MCP-Session-Id': SESSION_UUID, }, timeout=30, ) except httpx.HTTPError as e: error_msg = f'Error searching AWS docs: {str(e)}' logger.error(error_msg) await ctx.error(error_msg) return [SearchResult(rank_order=1, url='', title=error_msg, context=None)] if response.status_code >= 400: error_msg = f'Error searching AWS docs - status code {response.status_code}' logger.error(error_msg) await ctx.error(error_msg) return [ SearchResult( rank_order=1, url='', title=error_msg, context=None, ) ] try: data = response.json() except json.JSONDecodeError as e: error_msg = f'Error parsing search results: {str(e)}' logger.error(error_msg) await ctx.error(error_msg) return [ SearchResult( rank_order=1, url='', title=error_msg, context=None, ) ] results = [] if 'suggestions' in data: for i, suggestion in enumerate(data['suggestions'][:limit]): if 'textExcerptSuggestion' in suggestion: text_suggestion = suggestion['textExcerptSuggestion'] context = None # Add context if available if 'summary' in text_suggestion: context = text_suggestion['summary'] elif 'suggestionBody' in text_suggestion: context = text_suggestion['suggestionBody'] results.append( SearchResult( rank_order=i + 1, url=text_suggestion.get('link', ''), title=text_suggestion.get('title', ''), context=context, ) ) logger.debug(f'Found {len(results)} search results for: {search_phrase}') return results
- Pydantic BaseModel defining the structure of each search result returned by the tool, used for output validation and typing.class SearchResult(BaseModel): """Search result from AWS documentation search.""" rank_order: int url: str title: str context: Optional[str] = None
- awslabs/aws_documentation_mcp_server/server_aws.py:146-146 (registration)The @mcp.tool() decorator registers the search_documentation function as an MCP tool.@mcp.tool()