Reality Defender MCP server has solid foundational structure with 3 well-named, verb-leading tools and clear Pydantic-based schemas. However, descriptions lack specificity about side effects and error recovery, parameter descriptions are sparse, and output schemas are underdocumented. Tool names follow verb_noun convention excellently (reality_defender_validate_image_authenticity, reality_defender_generate_upload_url, reality_defender_get_upload_info), but descriptions are brief (34-56 chars) and lack actionable error guidance. Input schemas are well-typed with Field descriptions in Pydantic models, but response schemas are defined as Pydantic models without explicit documentation of what fields agents should expect. The server handles API key injection via X-Api-Key header correctly (pattern:secret-injection), but lacks per-tool scope declarations and error categorization.

• Expand tool descriptions to 100-200 characters and include: (1) what the tool does, (2) when to use it, (3) required prerequisites, (4) key output fields. Example: 'Validate image or video authenticity using AI models. Returns MANIPULATED, AUTHENTIC, or ANALYZING status with 0-100 confidence score. Required: valid file URL or path and expected file type (image|video|audio|text).'
• Convert 'expected_file_type' parameter to an enum: ['image', 'video', 'audio', 'text']. Update description: 'Type of media being analyzed. Must be one of: image, video, audio, text.'
• Add explicit parameter descriptions for file_path and file_url that state mutual exclusivity: 'file_path: Local file path. Exactly one of file_path or file_url must be provided.' and 'file_url: URL to remote file. Exactly one of file_path or file_url must be provided.'
• Document output schema explicitly in tool descriptions. Add a 'Returns' section: 'Returns { status: MANIPULATED|AUTHENTIC|ANALYZING, score: 0-100 (null if analyzing), models: list of { name, status, score }, file_id: request ID for URL uploads }'
• Add idempotency and side-effect declarations to each tool description. E.g., 'Validate Image Authenticity: Idempotent. Multiple calls with same input return same result. Analyze may be cached server-side.' And 'Generate Upload URL: Non-idempotent. Each call generates a unique upload session; reusing the same URL may fail.'
• Implement structured error responses with recovery guidance. Instead of returning plain Error model, return error responses that include: (1) error category (INVALID_INPUT|MISSING_AUTH|SERVICE_ERROR|NOT_FOUND), (2) detailed message, (3) suggested recovery action. E.g., 'error': 'missing_auth', 'message': 'API key not provided', 'recovery': 'Set REALITY_DEFENDER_API_KEY environment variable or include X-Api-Key header in request'.

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

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