This MCP server wraps a Python API client for the MVR (Minimum Viable Relationships) service. Tools are present with descriptions and some parameter schemas, but critical gaps undermine quality. Most tool descriptions are under 100 chars and lack actionable context (e.g., 'Verify API authentication status' does not explain when to call it or what to do with the result). Parameter schemas are incomplete: many complex objects like 'subject', 'market_scope', and 'evidence_pack' are typed as generic 'object' with minimal field documentation. No output schemas are documented. Error handling is basic (MVRApiError exists but lacks recovery guidance). Tool naming follows verb_noun convention (auth_check, entity_resolve) but some names are vague (context_compile, decision_check). No tool annotations (readOnlyHint, destructiveHint, idempotentHint) are present. The server appears to be a thin wrapper around an external API without agent-specific optimization.

• Expand tool descriptions to 80 - 150 chars. Include WHAT the tool does, WHEN to call it, and WHAT to do with the result. Example: 'Verify API authentication status. Call this first to confirm credentials are valid before attempting other operations. Returns auth status and remaining quota.'
• Document output schemas for all tools. Specify field names, types, and meanings. Example for entity_resolve: '{canonical_name: string, entity_id: string, country: string, confidence: number (0-1), alternatives: [{name, confidence}]}'
• Replace generic 'object' parameter types with explicit field schemas. For 'subject', document: {entity_name: string (required), entity_archetype: enum (retail_chain|...), country: string (ISO 3166-1 alpha-2)}
• Add tool annotations: mark all tools with readOnlyHint=true (all are read-only per Risk field). This signals to LLMs that retries are safe.
• Enhance error messages with recovery guidance. Instead of 'MVR API HTTP 429', return 'Rate limited. Retry after 30 seconds. If quota exhausted, contact [email protected].'