The web-search tool has a bare-bones definition that lacks critical documentation. The tool is explicitly registered in src/main.ts with FastMCP (line 24-46), so it is not inferred. However, the definition is severely deficient: the description is vague and generic (8 words, 'Search the web for a topic'), the parameter lacks a description (null), and there is no documented output schema. The input schema is present and uses Zod validation (SearchSchema.parse(args) on line 34), but the parameter 'topic' has no description field, leaving LLMs without clarity on what constitutes a valid topic. The tool does not validate against 54 Agentic Tool Patterns: no idempotency hint, no permission gate, no clear recovery guidance for errors (when res is falsy or organic.length === 0, the response is a generic text message, not actionable guidance). The implementation returns JSON-stringified results as plain text (line 46: 'text: JSON.stringify(results)'), forcing LLMs to parse unstructured output. Error handling returns 'Failed to retrieve results' or 'No results found' without guidance on root cause or next steps.

• Add a detailed description for the 'topic' parameter: 'The search query (e.g. "weather in New York"). String, 1-500 characters. Supports natural language and boolean operators (AND, OR, NOT).'
• Expand the tool description to 50-200 characters: 'Search the web using the Serper API and return top 10 organic results. Requires SERPER_API_KEY environment variable. Use for current events, factual lookups, and real-time information not in training data.'
• Document the output schema in the tool description or as a JSON example: Returns an array of objects: [{title (string), snippet (string), link (string)}, ...]. Max 10 results per call.
• Add parameter constraints: Zod schema already validates string type, but add .min(1).max(500) to enforce length limits. Update parameter description to reflect constraints.
• Improve error responses: Replace 'Failed to retrieve results' with 'API error: SERPER_API_KEY may be invalid or quota exceeded. Verify the key in environment variables.' Replace 'No results found' with 'No results for query: {topic}. Try a broader search term or check for typos.'
• Add pagination support: Accept optional 'page' (default 1) and 'limit' (default 10, max 50) parameters to enable multi-page result retrieval and let LLMs control result volume.
• Return structured output: Instead of JSON.stringify(results), use MCP's content protocol to return structured objects with title, snippet, link fields (not as a single text blob).
• Add tool annotations: Use 'readOnlyHint: true' in FastMCP tool registration to signal that this tool does not modify state and is safe to retry idempotently.