The MCP WebScraper has a single tool, scrape_listings, with a clear purpose but significant gaps in definition quality. The tool name follows verb_noun convention and has a reasonable description (186 chars), but the description lacks critical guidance about prerequisites, failure modes, and dependencies on external services. The input schema is present with proper type definitions (string types) and parameter descriptions, but lacks constraints (no enums, ranges, or format specifications). The output schema (ListingResponse) is documented via Pydantic models but not directly described in the tool definition. Error handling returns a fallback empty ListingResponse on failure, providing no guidance to the LLM about retry strategies or what went wrong. The tool is read-only (appropriately marked as READ_ONLY) but lacks security-focused descriptions around secret handling (OpenAI API key loaded from environment). The implementation shows external dependencies (Playwright, OpenAI, BeautifulSoup) that create fragility, timeouts, rate limits, and API failures are possible but undocumented in the tool interface.

• Add a 'Returns' section to the tool docstring explicitly documenting the ListingResponse structure: 'Returns a ListingResponse containing a list of ListingItem objects with fields: title (string), location (string), price (string), bedrooms (string), bathrooms (string), area (string), realtor (string), image_url (string), link (string). All fields are optional (null if not extracted).'
• Enhance the tool description to include prerequisites and failure modes: 'Requires a valid OpenAI API key in OPENAI_API_KEY environment variable. May timeout if the website is slow or blocks the Playwright browser. Returns empty listings list on failure, try again with a different query or clearer extraction instructions.'
• Document the 'query' parameter format: 'City or location to search listings for. Will be URL-encoded and appended to the Colombian real estate site. Examples: Bogota, Medellin, Cali. Only Colombian locations are supported.'
• Add input validation: validate that 'query' is a non-empty string; validate that 'instructions' is a valid, non-malicious prompt (sanitize against prompt injection patterns). Return descriptive errors: 'Invalid query: must be 1-50 characters. Got empty string.' rather than generic exceptions.
• Implement result limiting and pagination: add an optional 'limit' parameter (default 20, max 100) and return a 'has_more' boolean flag in ListingResponse. Document: 'The tool returns up to 'limit' listings to avoid context window exhaustion.'
• Replace generic error handling with structured error responses. Instead of returning empty ListingResponse, return a structured error response (or throw with a detailed message) that tells the LLM: 'Timeout after 10s waiting for website, site may be down. Try again in 30s.' or 'LLM failed to parse HTML, try simpler extraction instructions.'