A simple web search implementation using DuckDuckGo API
Single tool with adequate naming and basic schema, but significant gaps in parameter descriptions, output documentation, and error handling guidance. Tool description is good (203 chars, within baseline 194 avg), but parameter descriptions are minimal. No output schema documented. Error handling is present but not recovery-focused. Rate limiting exists but not described to LLM.
Performs a web search using the DuckDuckGo API, ideal for general queries, news, articles, and online content. Use this for broad information gathering, recent events, or when you need diverse web sources. Supports content filtering and region-specific searches. Maximum 20 results per request.
Output schema not documented. Tool returns formatted markdown text, but LLM has no explicit schema showing what fields are present, structure, or how to parse results downstream.
'count' parameter description is minimal ('Number of results (1-20, default 10)') and lacks guidance on behavior (e.g., what if count exceeds available results? Does it gracefully degrade?).
Rate limit implementation (1 req/sec, 15k/month) exists in code but is NOT exposed in tool description or parameter constraints. LLM cannot plan around rate limits or understand retry behavior. Rate limits should be transparent in tool metadata or error messages.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | C | 62 | 2026-07-28+ | v2 |
| 2026-03-09 | F | 46 | - | v1 |
Error messages are generic ('DuckDuckGo API error: {status}', 'Rate limit exceeded', 'Invalid arguments'). Per recovery-guide pattern, errors should include actionable next steps: 'Rate limit exceeded. Wait 1 second before retrying.' or 'Invalid query. Keep queries under 400 chars.'
Query parameter constraint ('max 400 chars') is mentioned in description but not enforced via JSON Schema (no maxLength property). LLM cannot validate before calling. Schema should include `"maxLength": 400`.
No pagination support documented or implemented. Tool description states 'Maximum 20 results per request' but DuckDuckGo API returns variable counts (instant answer + related topics). If LLM requests count=20, no guarantee 20 results are returned. Pagination or result guarantees should be explicit.