PolarDB-X MCP server has critical gaps in definition quality. Of 3 tools, only 'query' has a meaningful input schema with parameter description. The other two tools ('inspect database status', 'show all commands') have empty input schemas and lack parameter documentation. All tool descriptions are extremely brief (10-33 chars), falling well below the 10-1024 character baseline and the 50-200 char LLM-optimization range. No tool output schemas are documented. The 'query' tool lacks a description for its 'sql' parameter. Security mechanisms exist (read-only mode enforcement) but are not exposed as tool metadata or annotations. Error handling is basic and does not provide recovery guidance.
Tool descriptions are critically short (<35 chars). LLM cannot determine when to select each tool. 'Inspect the status of PolarDB-X' does not explain what 'status' means (performance metrics? connection count? schema changes?). 'Show all commands SQL' is ambiguous, all commands for what? Does it require parameters?
Two of three tools ('inspect database status', 'show all commands') have empty input schemas (empty properties object). Per scoring rules, schema score MUST be 0 for missing schemas. These tools cannot be validated by clients and provide no type information.
The 'sql' parameter in 'query' tool lacks a description. LLM cannot determine format, constraints, or safety requirements (e.g., is SQL injection possible? What statements are allowed?).
query
Recommendations
Expand each tool description to 50-200 characters. For 'query': 'Execute a SQL SELECT, DESC, EXPLAIN, SHOW, or WITH statement against PolarDB-X. Statements are validated in read-only mode to prevent modifications. Use inspect_database_status or list_supported_commands for common administrative queries.' For 'inspect database status': 'Retrieve performance and operational metrics for the PolarDB-X database, including connection count, query statistics, and schema information.' For 'show all commands': 'List all supported SQL commands and keywords available in PolarDB-X, useful for discovering what operations are allowed.'
Add parameter descriptions. For 'query.sql': 'SQL statement string to execute. Must begin with SELECT, WITH, SHOW, DESC, DESCRIBE, EXPLAIN, or USE (read-only mode). Maximum 10,000 characters. Parameterized queries with ? placeholders are not yet supported, pass literal values only.'
Add input schemas for 'inspect database status' and 'show all commands'. Even though they take no parameters, document this explicitly: 'inputSchema: { type: "object", properties: {}, required: [] }'.
Document output schemas for all tools. Add to tool descriptions or a separate outputs section: 'Returns: { results: [{ column1: string, column2: number, ... }], rowCount: number, executionTimeMs: number }'.
Rename tools for clarity: 'query' → 'execute_sql' or 'run_sql'; 'inspect database status' → 'get_database_metrics' or 'get_database_status'; 'show all commands' → 'list_supported_sql_commands'.
No output schemas documented for any tool. Tool description should state what fields are returned, their types, and what they represent. Current responses are raw JSON strings, LLM must parse unstructured text to extract chaining IDs.
Tool names lack action verbs. 'inspect database status' and 'show all commands' do not start with clear verbs (should be 'get_database_status' or 'list_supported_commands').
No error handling guidance. If query fails (syntax error, timeout, permission denied), error messages do not tell LLM what to do next. Per pattern:recovery-guide, errors must suggest alternatives or indicate if retry is safe.
No tool annotations (readOnlyHint, destructiveHint, idempotentHint). Server enforces read-only mode internally but does not expose this to clients via tool metadata. LLM cannot distinguish between safe and risky operations.
Composition issue: 'query' tool is too generic and accepts arbitrary SQL. While 'inspect database status' and 'show all commands' wrap specific queries, they duplicate functionality already available through 'query'. Consider removing redundant tools or making them more focused (e.g., 'get_performance_metrics' vs 'show stats').
inspect database statusshow all commands
Add error handling guidance in the 'query' tool description: 'Errors: SQL syntax errors return 400 with 'Syntax error at line X', check statement format. Permission denied (read-only violation) returns 403, use list_supported_sql_commands to see allowed operations. Timeout errors (>30s) are retryable after simplifying the query.'
Consider adding tool annotations (via updated SDK if available): mark 'query' with readOnlyHint=true when POLARDB_X_READ_ONLY=true to signal to clients this tool does not modify data.
Consolidate tools. If 'inspect database status' always runs 'show stats' and 'show all commands' always runs 'show help', remove them and document how to invoke these via the generic 'query' tool: 'Use execute_sql("SHOW STATS") for database metrics, execute_sql("SHOW HELP") for supported commands.'
Add per-parameter type constraints. For 'query.sql', document: 'Type: string. Constraint: 1-10000 characters, must match regex ^(SELECT|WITH|SHOW|DESC|DESCRIBE|EXPLAIN|USE)\\s, no multi-statement (;) allowed unless commented.'
Return structured JSON objects instead of stringified results. Currently responses are wrapped as '{ content: [{ type: "text", text: JSON.stringify(...) }] }'. Return parsed objects in a 'data' field so LLM can navigate fields directly.