The Pinot MCP server has solid fundamentals: all 31 tools are explicitly registered with schemas and descriptions. However, there are critical issues that prevent a higher score. First, the server defines duplicate/near-duplicate tools (list_tables vs list-tables, pause_consumption appears 3 times across files, resume_consumption appears 3 times). This violates the single-responsibility principle and forces LLMs to disambiguate between functionally identical tools. Second, naming is inconsistent: some tools use snake_case (list_tables, get_table_size), others use kebab-case (list-tables, table-details, segment-list), and parameter names vary (table_name vs tableName, partition_group_ids vs partitions). Third, while descriptions exist for all tools, many lack critical detail about when to use them, prerequisites, or how they relate to similar tools. For example, update_table_config and confirm_update_table_config lack clear documentation of the confirmation token workflow. Fourth, some parameter descriptions are minimal (e.g., 'Table configuration updates' for the config parameter in update_table_config). Fifth, output schemas are not consistently documented in the visible code, while tool descriptions mention what they return, full schema documentation is absent. Error handling descriptions are sparse, tools don't explain what happens on failure or how to recover. The server does implement tool annotations (seen in imports: ToolAnnotations, readOnlyHint, destructiveHint), which is positive. Overall: good structure, but consistency and clarity issues prevent this from being production-grade.

• Consolidate duplicate tools. Choose ONE canonical naming scheme (snake_case is standard for MCP tools per community baselines). Merge mcp_pinot/server.py and mcp_pinot_ops/server.py into a single tool registry or clearly document why they must be separate.
• Standardize parameter naming across all tools. Use table_name (not tableName), always use snake_case, and apply consistently across all 31 tools.
• Expand parameter descriptions. For update_table_config's 'config' parameter, specify example fields (e.g., 'JSON object with keys like: retention, segmentSize, indexingConfig. See get_table_config for current structure.'). For force_commit, document the format of 'partitions' and 'segments' (comma-separated IDs, no spaces?).
• Document output schemas. For each tool, add a brief schema block (even in the description) like: 'Returns: {tables: [{name: string, type: string}], totalCount: number}'. This lets LLMs know what fields to expect.
• Add error recovery guidance to all tool descriptions. Example for read_query: 'On timeout: the query may still be running. Retry with a shorter limit. On authentication error: check Pinot credentials. On invalid SQL: simplify the query or use get_schema to validate column names.'
• Document the confirmation workflow clearly. In update_table_config: 'Returns a short-lived token. Call confirm_update_table_config with this token within 5 minutes to apply changes. Token expires after one use or 5 minutes, whichever is first.'
• Add enum constraints to free-form string parameters. For force_commit's 'partitions', use format 'Comma-separated partition group IDs (e.g., "partition_0,partition_1")'.

Inferred effective spec: 2026-07-28+.

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