BitDive MCP server provides 11 tools for distributed tracing and performance monitoring. Tools are well-named with clear verb prefixes (get_, list_, find_, compare_), and descriptions are substantive (average ~150 chars). However, critical gaps undermine production readiness: (1) input schemas lack type declarations for most parameters, parameters are documented in description text but not formalized as JSON Schema with 'type' fields; (2) no output schema documentation, callers cannot know what fields to expect from responses, forcing LLMs to guess at response structure; (3) no error handling guidance, tools raise HTTP exceptions but provide no recovery instructions or error classification; (4) mcp_token parameter exposed in every tool despite being a secret (should be server-injected); (5) parameter constraints (e.g., limit ranges, format specs) stated informally in descriptions rather than as formal schema constraints (minItems, maxItems, pattern, enum). These gaps are systematic and affect all 11 tools, keeping the server in the 'Fair' category despite good naming and descriptions.

• Add explicit JSON Schema definitions to all tool parameters. Use Pydantic models or FastMCP's @mcp.tool() 'inputSchema' argument to declare types (string, integer, boolean, array), required fields, minItems, maxItems, and patterns. Example: limit: {type: 'integer', minimum: 1, maximum: 1000, description: '...'} instead of informal description text.
• Document output schema for each tool. Create a simple schema or example response object showing expected fields and types. E.g., get_system_heatmap returns {modules: [{name: string, methods: [...], call_count: integer}], ...}. Include this in tool descriptions or docstrings.
• Remove mcp_token from all tool parameters. Initialize the server with BITDIVE_MCP_TOKEN env variable at startup. If multi-tenant token rotation is required, use a server-level authentication callback or configuration file, NOT per-call tool parameters.
• Add error handling and recovery guidance. Wrap tool logic in try/except blocks; catch HTTP 4xx/5xx and timeout errors; return structured error responses with error_type ('not_found', 'unauthorized', 'timeout', 'rate_limited'), message, and recovery_hint (e.g., 'Check BITDIVE_MCP_TOKEN and retry' or 'Call list_recent_calls() to find a valid call_id'). See pattern:recovery-guide.
• Formalize parameter constraints in schema. Replace informal limits like 'default: 100' with schema constraints. E.g., find_calls_by_method(limit: {type: 'integer', minimum: 1, maximum: 10000, default: 100}).
• Add pagination metadata to list responses. Document whether responses include total_count, next_cursor, or has_more. For tools returning arrays (list_recent_calls, find_calls_by_method), cap results at 50-100 items by default and offer next_cursor pagination.