This server has fundamental definition quality gaps that prevent reliable agent use. While tool names follow verb conventions (deep_research, quick_search, write_report), parameter documentation is incomplete or absent in several tools. The five tools have been inspected against the source code; tool descriptions are present but lack the specificity needed for robust LLM selection. Most critically: output schemas are not documented anywhere in the visible code, neither in return type hints nor in response structure documentation. The server returns Dict[str,Any] responses without documenting the shape, forcing LLMs to infer structure. Parameters like 'custom_prompt' in write_report lack constraints or validation guidance. The error handling strategy (handle_exception utility) is not visible, making it impossible to verify whether errors guide recovery or just return raw exceptions. No tool is marked with destructive/readonly hints. The deepest issue: tools like get_research_sources and get_research_context depend on research_id from a prior call, but the dependency chain is not documented in either tool's description.

• Add explicit, documented output schemas for all five tools. Define the exact structure returned by deep_research (e.g. {research_id, context, sources: [{url, title, snippet}], source_urls}), quick_search (e.g. {search_id, result_count, results: [{title, url, snippet}]}), write_report (e.g. {report, source_count, costs}), and the two get_* tools. Include this in docstrings and MCP schema metadata.
• For write_report, document how custom_prompt interacts with the prior research. E.g. 'custom_prompt: Optional custom instruction to guide report generation. If provided, this augments (rather than replaces) the analysis. Leave empty to use default report structure.'
• Add dependency hints to get_research_sources and get_research_context. E.g. 'Get the sources and full context for a completed research session. First call deep_research() to initiate a study and obtain a research_id.'
• Distinguish deep_research and quick_search more clearly in descriptions. Explain the cost/quality tradeoff explicitly: 'quick_search: Fast, suitable for topic summaries and link collections. Returns top results in seconds. deep_research: Comprehensive analysis with source cross-checking and synthesis. Takes 30-120 seconds but produces a full report ready for agents to cite.'
• Add readOnlyHint to all five tools (since none modify state). This signals to agents that these tools are safe to call speculatively and can be retried without side effects.
• Verify and document error handling: if research fails, what error structure is returned? Can the agent retry, or is it unrecoverable? Update server.py or utils.py to ensure handle_exception returns a structured error with a classification (retryable, user-fixable, fatal) and actionable recovery steps.

Inferred effective spec: <=2025-11-25.

• Relies on Logging (deprecated) - log to stderr or use OpenTelemetry