This MCP server exposes 20 YDB operations with mixed quality. All tools have basic descriptions and declared input parameters with types, which is a positive baseline. However, critical gaps emerge: (1) descriptions are uniformly generic and often under 100 characters, lacking the 50-200 character optimized range for LLM reasoning; (2) parameter descriptions are minimal and do not explain constraints, formats, or dependencies; (3) output schemas are NOT documented in the provided tool definitions, we can infer they exist from function names, but the actual response structures are not declared anywhere in the source; (4) there is no evidence of error handling guidance, tools report success/failure but lack recovery hints; (5) destructive operations (local_ydb_sql, local_ydb_apply_schema, local_ydb_permissions, local_ydb_cleanup_storage) have NO confirmation or dry-run support documented; (6) the 'profile' parameter appears in ALL 20 tools but is never explained, what defines a valid profile? Is it a filename, environment variable, or system identifier? This ambiguity is pervasive. The server follows a basic mono-parameter design (mostly just 'profile', with a few adding 'schema', 'query', 'dumpId', 'count', 'container', 'path') which reduces compositional flexibility. Per-tool assessment shows most tools scoring 45-55; none reach 70+.
Output schemas are not documented. Tool definitions declare names and input parameters, but response structures are not declared anywhere in the source code. LLMs cannot plan downstream tool calls or extract the right data when output structure is opaque.
Document the output schema for each tool. For read-only tools, specify the fields and structure returned (e.g., local_ydb_status_report returns {status: string, nodes: number, storage_mb: number, ...}). For mutation tools, specify success/error response structure.
Expand the 'profile' parameter description to explain: what it represents (config file name, environment var, or system identifier?), where profiles are discovered (call local_ydb_inventory?), format constraints (alphanumeric only? max length?), and what error message is returned if invalid.
Rewrite tool descriptions to LLM-optimized length (50-200 chars) that state WHAT, WHEN, and VALUE. Example: 'Generate a status report showing current node count, storage usage, and tenant health. Use this to diagnose deployment issues or verify prerequisites before mutations. Returns {status: string, nodes: number, storage_mb: number}.'
Add actionable parameter descriptions. Example for local_ydb_sql: 'SQL query to execute against the current tenant. Supports SELECT, INSERT, UPDATE, DELETE, CREATE TABLE. Queries run in a transaction; auto-rollback on error. Example: SELECT * FROM my_table WHERE id = 1'
Implement and document dry-run or confirmation support for destructive operations. Either add a 'confirm' boolean parameter (default false) or implement a two-step pattern: call local_ydb_sql_plan(profile, query) to validate, then local_ydb_sql_execute(profile, query) to run.
Enumerate available profiles and their settings. Either add a list_profiles() tool or document how to discover them (e.g., 'Profiles are stored in ~/.config/local-ydb/profiles.json').
The 'profile' parameter appears in ALL 20 tools but is never explained. Description states only 'Profile name to check prerequisites for' (or similar), with no guidance on what constitutes a valid profile, where they are stored, how to discover available profiles, or what happens if the profile does not exist.
Destructive and irreversible operations lack confirmation or dry-run support. Tools local_ydb_sql (DESTRUCTIVE), local_ydb_apply_schema (DESTRUCTIVE), local_ydb_permissions (DESTRUCTIVE), local_ydb_restore_tenant (DESTRUCTIVE), and local_ydb_cleanup_storage (DESTRUCTIVE) can cause permanent data loss or service disruption without any documented safeguard. Agents may accidentally invoke these with malformed queries or wrong profiles.
Descriptions are uniformly generic and below LLM-optimized length (50-200 chars). Most descriptions are 20-45 characters and do not explain WHAT the tool does, WHEN to use it, or what it returns. For example, 'Check YDB prerequisites and system configuration' provides no actionable guidance for an LLM deciding between similar check_* tools.
Parameter descriptions lack actionable constraints and format guidance. Parameters like 'schema' (in local_ydb_apply_schema), 'query' (in local_ydb_sql), and 'dumpId' (in local_ydb_restore_tenant) are described only with their name, with no guidance on expected format, syntax, constraints, or valid values. An LLM cannot reliably construct correct SQL or schema changes without this detail.
No evidence of error handling guidance. Tool definitions state Risk levels (READ_ONLY, WRITE, DESTRUCTIVE) but provide no recovery hints, e.g., if local_ydb_scheme fails because the path does not exist, should the LLM call local_ydb_inventory first? If local_ydb_sql fails, should it retry or ask the user for corrected syntax?
Numeric parameter constraints are missing. local_ydb_add_dynamic_nodes accepts 'count' with no documented minimum, maximum, or valid range. An LLM could pass count=1000 or count=-5, causing API errors or nonsensical operations.
Tools follow a mono-parameter design (most only accept 'profile') with limited composability. The server provides many read-only diagnostic tools (check_*, *_check, *_status) that return different views of the same system, but without documented output fields, LLMs cannot understand when to call which tool or how to compose them into a coherent troubleshooting workflow.
Add recovery hints to error handling. Document in each tool's description what common errors mean and what to try next. Example: 'If the profile is invalid, call list_profiles() to see available profiles. If the database is unreachable, run local_ydb_healthcheck first.'
Constrain numeric parameters. For local_ydb_add_dynamic_nodes, specify 'count must be 1-100 (adding more than 100 nodes at once exceeds recommended limits).'
Consider splitting multi-concern tools. For example, local_ydb_dump_tenant (create dump) and local_ydb_list_dumps (list available) are already separate, which is good. But local_ydb_apply_schema (apply) and local_ydb_scheme (retrieve) could benefit from a local_ydb_validate_schema tool to let agents check syntax before applying.
Document which tools are safe to retry (idempotent) and which have side effects. Use tool annotations (if supported by the SDK) to mark readOnlyHint=true for diagnostics and destructiveHint=true for mutations.
Consider adding a 'format' or 'output_format' parameter to read-only tools (e.g., local_ydb_container_logs) to let agents request structured (JSON) vs. plaintext (logs), reducing post-processing burden.