Static source inference · medium confidence · detected: Logging
Deprecated protocol patterns detected
Summary
news-mcp exhibits significant definition quality gaps. While all 8 tools are registered via FastMCP's add_tool() and transport is correctly set to Streamable HTTP, the source code provided does NOT show tool implementations with explicit parameter schemas, descriptions, or output documentation. Only tool names are visible in server.py. Without seeing the actual tool functions (search.py, query.py, sources.py), I cannot verify that parameters have types, that descriptions are present and LLM-optimized, or that output schemas are documented. The database schema (alembic migrations) shows good data structure, but that does not translate to tool definition quality. The server also lacks error handling patterns, output structure guidance, and parameter validation rules visible in the provided code.
NO tool definitions visible in source code. Only tool names appear in server.py mcp.add_tool() calls. Actual function signatures, parameter schemas, descriptions, and output types are not shown in the provided code excerpt.
No input parameter schemas are visible in the provided code. Cannot verify parameter types, descriptions, enums, defaults, or validation rules.
Recommendations
URGENT: Provide the actual tool function definitions from src/tools/search.py, src/tools/query.py, and src/tools/sources.py with explicit parameter schemas, descriptions, and return types. Use FastMCP decorators or inline docstrings to document each parameter.
Add a 10 - 100 character description to each tool explaining WHAT it does, WHEN to use it, and any dependencies. Example: 'search_news: Search the news database by keyword, date range, source, or category. Use this first to find relevant articles before querying details.'
Add a description to every input parameter explaining what it controls. Parameter names alone are ambiguous, 'query' could be text, SQL, or entity name. Describe expected formats, ranges, and valid values.
Document the output schema for each tool. For list_* tools, specify: What fields does each item have? What types? Does it return a total count or a next_cursor for pagination? For search_news and query_news, what metadata is included?
Implement pagination for all list_* tools. Accept 'limit' (default 20, max 100) and 'offset' or 'cursor' parameters. Return a total_count or next_cursor so agents can fetch more results without guessing.
Add error handling that tells agents what to do next. Instead of bare error codes, return: 'No articles found matching query. Try a simpler search term or expand the date range.' This prevents dead-ending.
Rename 'query_related_news_graph' to a clearer verb_noun form. Candidates: 'search_related_news', 'get_news_relationships', 'find_news_graph_connections'. Verify it does not duplicate 'query_news' intent.
Spec posture evidence
Inferred effective spec: <=2025-11-25.
Relies on Logging (deprecated) - log to stderr or use OpenTelemetry
No output schemas or return type documentation visible. Tools should document what fields LLMs can expect so they can plan downstream calls and extract data correctly.
Naming of 'query_related_news_graph' is ambiguous. 'query' alone does not convey what action is taken. Does it search, retrieve, filter, or analyze? Consider renaming to 'search_related_news_by_graph', 'get_news_relations', or similar.
No error handling patterns are visible. Tools should return actionable error messages that guide LLMs toward recovery, categorize errors as retryable vs. fatal, and include invalid values and constraints violated.
list_* tools should document pagination behavior (page/offset/limit parameters and total count). Without pagination, large result sets blow the context window.
No idempotency guarantees are stated. Agents retry on ambiguous failures, if these tools modify state, non-idempotent behavior risks duplicate side effects (duplicate articles, duplicate records).
search_newsquery_newsquery_related_news_graph
Validate inputs early (e.g., date format, limit bounds, enum values) and return clear constraint violations. Example: 'Invalid sort_order: got "random", must be: date_asc, date_desc, relevance.'
Document whether tools are idempotent (safe to call multiple times with the same inputs). For search and query tools (read-only), this should be true; confirm in descriptions.
If search_news or query_news accepts filters (source, category, tier, language), document enums or lookup tools. Example: 'source: name of a news source from list_sources(). Common sources: BBC, Reuters, AP.'
Include pagination and result limits in tool descriptions. Example: 'list_sources: Returns up to 100 sources per request. Use limit and offset parameters to page through results.' This prevents context window exhaustion.