MCP server exposing the SCOUTS-AI web search API as a single web_search tool for AI agents.
Single tool 'web_search' has a well-crafted description (234 chars) that explains WHAT (search via SCOUTS-AI), WHEN (fresh context, citations), and key constraints (page>1 unreliable, rate limits). All three parameters (query, lang, page) have type definitions and descriptions. Input schema is complete with proper types and ranges. Error handling is comprehensive, ToolError wraps domain exceptions (InvalidQueryError, RateLimitedError, UpstreamUnavailableError, ApiError) with actionable recovery hints (e.g., 'retry after Xs'). Output schema is documented in the docstring and returns structured JSON with typed fields (title, url, content, publishedAt, engine). Naming follows verb_noun pattern (web_search). No critical gaps, but output schema could be more formally declared in the tool registration (currently only in docstring). Baseline: avg tool description 194 chars (this is 234 ✓), avg params 4 (this has 3 ✓), 100% of A+ tools have documented return types (present but informal ✓).
Search the public web via SCOUTS-AI and return compact JSON results. Use this when the user asks a question that requires current information, fresh context, or citations from the open web. No API key required. Returns at most 10 results per page. `page=1` is the reliable default; `page>1` may return an empty list because the upstream provider does not always paginate.
Output schema not formally declared in FastMCP tool registration. Currently documented only in docstring; should be explicit in @server.tool() or return type annotation for LLM visibility.
Parameter 'query' lacks explicit length constraint in schema (1-512 chars stated in description but not in JSON Schema minLength/maxLength).
Parameter 'page' lacks explicit range constraint in schema (1-10 stated in description but not in JSON Schema minimum/maximum).
No tool annotations (readOnlyHint, destructiveHint, idempotentHint) declared. web_search is read-only and idempotent, should be annotated for agent planning.
Inferred effective spec: <=2025-11-25.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | C | 64 | <=2025-11-25 | v2 |