Repository contains 29 tools across 4 MCP servers (Kubernetes, PDF, PostgreSQL, Redash). Tool definitions exist with schemas and input parameters, but quality is inconsistent. Most tools lack descriptions that meet the 50-200 char LLM-optimized baseline (baseline avg: 194 chars). Many descriptions are vague placeholders (e.g., 'Pod name pattern to search for') without actionable context. Parameter descriptions vary widely, some tools document constraints well (e.g., label_selector with example), others are minimal stubs. Output schemas are not explicitly documented in the source, forcing LLMs to infer result structure. Error handling guidance is absent from tool definitions. Security concerns present: tool definitions do not indicate permission requirements, and the exec_in_pod and mcp__execute_query tools expose dangerous capabilities without confirmation patterns. Schema completeness is moderate, most tools show input types and property descriptions, but several lack enum constraints where appropriate (e.g., Redash visualization types, Kubernetes field_selector). A few tools have composite/object parameters (write_pdf.content, position objects) with incomplete nested documentation.
CRITICAL: exec_in_pod and mcp__execute_query expose unrestricted command/SQL execution without permission gates, injection guards, or input validation. LLMs can be tricked into running arbitrary commands or SQL.
Output schemas are not documented in tool definitions. LLMs cannot infer what fields to expect in responses, forcing them to guess at downstream data extraction and chaining.
Expand all tool descriptions to 50-200 chars following LLM-optimized patterns. Template: '[VERB] [WHAT], used when [WHEN/DEPENDENCY]. Returns [FIELD] + [FIELD]. Requires [PERMISSION].' Example: 'Delete a pod from Kubernetes. Use when pod is stuck or needs restart. Returns deletion status. Requires pods/delete permission in target namespace.'
Add output schemas to every tool. Document return fields, types, and constraints. Example for get_pods: '{"pods": [{"name": string, "namespace": string, "status": "Running"|"Pending"|"Failed", "ready_containers": number}], "total": number}'
Convert free-form string parameters to enums where values are known. For create_visualization.type, enforce: {"enum": ["table", "chart", "counter", "number", "pivot", "map", "scatter", "line", "bar"]} and document in description.
Add confirmation patterns for destructive operations. Before executing kill_pod or delete_query, return a summary message requiring explicit approval: 'Are you sure you want to delete query #42 (Monthly Revenue Report)? This cannot be undone. Type CONFIRM to proceed.'
Rename PostgreSQL tools: drop 'mcp__' prefix. Use get_database_info, list_tables, get_table_structure, execute_query for consistency with Kubernetes/PDF/Redash tools.
Add pagination to all list tools. Include limit (default 20, max 100), offset, and total count in responses. Example: 'Returns paginated list of queries (limit 20 by default). Use offset to navigate. If total > limit, paginate in subsequent calls.'
Document permission requirements for each tool. Declare required scopes or IAM actions. Example for mcp__execute_query: 'Requires database:read or database:write depending on query type (SELECT = read, INSERT/UPDATE/DELETE = write). No permission = 403 error.'
Score history
Overall score trend
↑ 22 points across a rubric change (v1 → v2)
57/100
Scored
Grade
Overall
Spec posture
Rubric
2026-09-22
D
57
2026-07-28+
v2
2026-03-09
F
35
-
v1
writeauthsource verified52/100
Name of the pod
execute_queryread onlyauthsource verified68/100
Execute a query in Redash
find_podsread onlyauthsource verified60/100
Pod name pattern to search for (supports wildcards, e.g. 'nginx*')
get_dashboardread onlyauthsource verified66/100
Get details for a specific dashboard in Redash by ID
get_data_sourceread onlyauth50/100
Get details for a specific Redash data source by ID
get_data_source_schemaread onlyauth50/100
Get the schema (tables and columns) for a Redash data source
Tool descriptions are too short (avg ~38 chars, baseline 194 chars). Most are placeholder stubs that only name a parameter instead of explaining WHAT the tool does, WHEN to use it, or what it RETURNS.
Pagination not documented or missing from list tools (list_queries, list_dashboards, list_data_sources, mcp__list_tables). Large result sets risk context window exhaustion.
Nested/object parameters (write_pdf.content, add_widget_to_dashboard.position) lack detailed schema documentation. Sub-properties (text, formFields; x, y, width, height) are implied but not formally constrained or described.
Error handling guidance absent from tool definitions. No documentation of retryable vs fatal errors, timeout behavior, or recovery actions (e.g., 'Query not found, call list_queries() first').
No permission scope documentation. Tools do not declare what IAM/RBAC permissions they require (e.g., 'read:pods', 'write:queries'). Agents cannot plan with least-privilege constraints.
Add input validation and error recovery guidance. Example for find_pods: 'Returns error if namespace does not exist. Try get_pods() with default namespace first. Returns []. wildcard must be *. SQL injection: use mcp__execute_query with parameterized queries only.'
Document output size limits and result capping. Example: 'Returns up to 50 pod names. If > 50 pods exist, paginate using label_selector=<key>=<value>. Timeouts: max 30s. Returns partial results + timeout warning if exceeded.'
For tools like read_pdf and write_pdf, clarify when to use file paths vs base64. Example: 'Pass file_path for local files (< 50MB). Pass base64_content for in-memory or remote PDFs. Returns base64 if outputPath not specified; else writes file and returns file_path.'
Add dry-run/preview mode to creation tools (create_query, create_dashboard, create_visualization). Example: 'Include dry_run=true to preview changes without persisting. Returns 200 OK + preview object. Omit or false to persist permanently.'
Document chaining requirements: ensure output fields match downstream tool input params. Example: 'create_query returns query_id. Pass query_id to execute_query() or create_visualization(query_id=...). Missing query_id means creation failed.'
Add rate limiting and quota guidance. Example: 'Redash API: 100 calls/min per user. If exceeded, returns 429 Too Many Requests. Retry after 60s. Kubernetes: no hard limit, but etcd load may degrade; avoid polling > 1 call/sec.'
Sanitize dangerous parameters against injection attacks. For exec_in_pod, validate command: reject shell metacharacters (|, &, $, `;`), require allowlist of safe commands, or enforce array-based command+args. Log all executions for audit.