Static source inference · medium confidence · evidence: Streamable HTTP
Current-spec patterns detected
Summary
The server has 9 tools with clear naming conventions (mostly verb_noun style) and documented input parameters via type hints. However, descriptions are uneven in quality and brevity, parameter descriptions vary in completeness, and output schemas are not explicitly documented. The server demonstrates basic structure but falls short of production-grade tool definition standards. Average per-tool score: 58.
Output schemas are not documented in code or docstrings. LLMs cannot plan downstream actions without knowing return fields. Baselines show 100% of A+ tools document return types.
get_tmdb_trending_media_tool is defined as a bare async function without @mcp.tool decorator, making it unregistered and invisible to the MCP server. Caps tool definition quality to 50 (inferred only).
Destructive operation (delete_from_my_watchlist_tool) lacks explicit state-change declaration in description and has no confirmation/dry-run pattern. Agents must know irreversible operations carry risk.
delete_from_my_watchlist_tool
Recommendations
Add explicit output schema documentation to every tool docstring. Format: 'Returns: {field_name (type): description, ...}'. Example for search_media_from_title_tmdb_tool: 'Returns: [{id (int): TMDB ID, title (str): media title, release_date (str): ISO 8601 date or null, overview (str): brief summary, media_type (str): 'movie' or 'tv'}, ...]'
Fix get_tmdb_trending_media_tool registration by adding @mcp.tool decorator before the async def statement. Without it, the tool is invisible to FastMCP.
Add context: when to call vs related tools, what format IDs are, and dependencies. Example for get_tmdb_media_details_tool: 'Fetch detailed information (budget, revenue, crew, cast, ratings) for a specific movie or TV series by TMDB ID. Use after search_media_from_title_tmdb_tool to get IDs. Returns full metadata needed for watchlist decisions.'
Replace 'filters' parameter in discover_tmdb_media_tool with constrained enum or documented whitelist of valid TMDB filter keys (e.g., with_genres, sort_by, with_keywords, vote_average.gte, release_date.gte). If API supports arbitrary filters, document the top 10 most common and warn that others may fail.
Add pagination parameters to get_my_watchlist_tool: 'limit' (default 20, max 100) and 'offset' (default 0). Update description to include: 'Returns up to [limit] items. Use offset to fetch subsequent pages. Include total_count in response.'
Add explicit state-change declarations to tool descriptions. update_my_watchlist_item_tool: 'Modifies the status and/or watched date of a watchlist item. Watchlist items are updated immediately, this operation cannot be undone, but you can call this again with different values.' delete_from_my_watchlist_tool: 'Permanently removes a film from the local watchlist. This action is irreversible.'
Score history
Overall score trend
↑ 17 points across a rubric change (v1 → v2)
66/100
Scored
Grade
Overall
Spec posture
Rubric
2026-09-22
C
66
2026-07-28+
v2
2026-03-09
F
49
-
v1
67/100
Fetches trending media from TMDB for a given time window.
discover_tmdb_media_tool accepts 'filters' as free-form Dict[str, Any] with no constraint. Description includes an example but no enum or schema constraint. LLMs will hallucinate invalid filter keys. Should constrain to known TMDB filter parameters or provide an enum.
Tool descriptions include example filter values and parameters in text (e.g., 'e.g., {"with_genres": "28", "sort_by": "popularity.desc"}' in discover_tmdb_media_tool). Per pattern:tool-description guidance, examples in descriptions cause LLMs to reuse them literally. Use constraints (enums, regex patterns) instead.
Watchlist tools use non-standard 'my_' prefix in names (add_media_to_my_watchlist_tool, update_my_watchlist_item_tool, delete_from_my_watchlist_tool, get_my_watchlist_tool). Standard convention is verb_noun without possessive. Names should be add_watchlist, update_watchlist_item, delete_watchlist_item, get_watchlist.
get_my_watchlist_tool likely returns many results but has no pagination parameters (limit, offset, page_size) documented. Per pattern:paginated-result, tools returning lists should support pagination to prevent context window exhaustion.
Error handling in _call_api() returns unstructured error objects without recovery guidance (pattern:recovery-guide). LLM receives raw HTTP status codes and error text but no actionable next step. E.g., 'Request to http://localhost:8000/api/search failed' tells the agent nothing.
Tool descriptions are uniformly short (50-60 chars average). Baseline for A+ tools is 194 chars. Descriptions like 'Fetches detailed information for any movie or tv series by given TMDB ID' lack context about when to use this tool vs search, what format IDs are, or dependency hints.
Implement confirmation pattern for delete_from_my_watchlist_tool. Offer a dry-run flag or require explicit confirmation. Example: Add optional 'confirm' parameter (default false). If false, return: '{"status": "needs_confirmation", "message": "Delete film_id 123 from watchlist?", "input_required": true}' so agent can ask user before destructive action.
Rename watchlist tools to drop 'my_' and use standard verb_noun: get_watchlist, add_watchlist, update_watchlist_item, delete_watchlist_item. This matches baseline naming conventions and disambiguates from personal/shared contexts.
Enhance error handling in _call_api() with recovery guidance. Instead of raw error text, return: '{"error": true, "code": "api_unavailable", "message": "TMDB API at localhost:8000 is not responding. Check that the FastAPI server is running on port 8000.", "retry": true}'
Add idempotency hint to add_media_to_my_watchlist_tool description: 'Adding the same film_id twice results in the first add succeeding; the second silently succeeds (idempotent). Safe to retry on transient failures.'
Document that all TMDB endpoints (search, details, trending, genres, discover) require an active TMDB API account and valid API key configured server-side. State in tool descriptions or server-level instructions.