Mixed quality across 12 tools. Strengths: all tools have descriptions (10 - 100 chars), all have explicit input schemas with Zod validation, clear naming following verb_noun convention. Critical weaknesses: descriptions are extremely terse (mostly 20 - 60 chars, below the 50 - 200 char LLM-optimized baseline); NO output schemas documented anywhere (users cannot predict response structure); NO error handling guidance (tools throw bare errors like 'Server not found'); parameter descriptions are sparse (many params have single-word descriptions like 'Rancher server identifier'); NO tool annotations (destructiveHint, readOnlyHint, idempotentHint); dangerous k8s_raw tool (IRREVERSIBLE risk) lacks confirm/dry-run pattern. Naming is good (rancher_servers_list, rancher_clusters_list follow conventions), but tool composition could be tighter, server management (add/remove/list) mixes with discovery (clusters/nodes/projects), making LLM planning harder.
NO output schemas documented. Users and LLMs cannot predict response structure. For example, rancher_clusters_list returns JSON but no schema specifies fields like 'data[]', 'pagination', or what cluster objects contain. This forces LLMs to guess downstream field names and breaks tool chaining.
Descriptions are extremely terse (20 - 60 chars, well below LLM-optimized baseline of 50 - 200). Examples: 'Return clusters from selected Rancher server' (45 chars); 'Return nodes (v3/nodes)' (23 chars); 'Check /v3 endpoint' (18 chars). These lack WHEN to use, WHAT the tool does uniquely, and prerequisites. LLMs cannot distinguish rancher_clusters_list from rancher_projects_list without more context.
rancher_clusters_listrancher_nodes_list
Recommendations
Add explicit output schemas to all tools. For rancher_clusters_list, document: { data: [ { id: string; name: string; status: string; ... } ]; pagination: { total: number; continue?: string } }. This enables LLMs to chain tools correctly.
Expand tool descriptions to 80 - 150 chars. Example for rancher_clusters_list: 'List Rancher clusters in a managed server with optional pagination and field filtering. Use this to discover clusters before requesting detailed metadata. Accepts summary mode to return a smaller response.'
Implement tool annotations. Emit destructiveHint for rancher_servers_remove (type: 'write'), readOnlyHint for all query tools, idempotentHint for stateless endpoints. Add a hints field to the tool definition in registerTool().
Add confirmation/dry-run for k8s_raw. Support a 'dry_run' parameter that calls with ?dryRun=All for non-GET requests. Document: 'Set dry_run=true to validate the request without executing it. This prevents accidental deletions.'
Enrich error messages with recovery hints. When getClient(serverId) fails, return: 'Rancher server "<serverId>" not found. Available servers: [list]. Call rancher_servers_list to see options or rancher_servers_add to register a new one.'
Enhance parameter descriptions with constraints. For limit (optional number), write: 'Maximum items to return (1 - 500, default 50). Higher limits may increase response time.' For continueToken, write: 'Pagination cursor from a previous response. Pass this to fetch the next page without repeating earlier results.'
k8s_raw tool (IRREVERSIBLE risk, supports DELETE/PUT/PATCH) lacks confirmation or dry-run pattern. An LLM could delete all pods in production with a single call. No guard, no rollback path, no audit trail hint in the description.
NO tool annotations (destructiveHint, readOnlyHint, idempotentHint). The server defines risk levels (READ_ONLY, WRITE, IRREVERSIBLE) in comments but does not emit them as tool.hints in the MCP response. LLMs cannot detect which tools are safe to retry or dangerous without parsing descriptions.
Parameter descriptions are often single words or trivial. Examples: 'Rancher server identifier' (repeated for serverId in 10+ tools), 'Cluster identifier', 'Result limit', 'Pagination token'. These lack context on format, constraints, or when to use them. Per the rubric, params must explain the expected format and range.
No error guidance. Tools throw 'Rancher server not found' but do not suggest 'Call rancher_servers_list to see available servers.' Bare errors leave LLMs unable to recover. Per the rubric, errors must guide the next step.
k8s_raw description is vague and unsafe: 'Arbitrary request to /api or /apis (DANGEROUS), use carefully' (53 chars). Does not explain what 'arbitrary' means, which HTTP methods are allowed, rate limits, or when an LLM should NOT call it. The all-caps 'DANGEROUS' relies on natural language rather than structured hints.
k8s_raw
Separate concerns: move rancher_servers_* tools into a 'server_management' group (or separate resource type) so LLMs don't confuse setup with discovery. Alternatively, prefix server-management tools with 'server_' and discovery with 'rancher_'.
Add idempotence guarantees to tool descriptions. E.g., 'rancher_servers_add is idempotent: calling it twice with the same id overwrites the first registration.' This tells agents they can safely retry on transient errors.
Document pagination requirements. For tools with autoContinue=true, explain: 'If autoContinue is false (default), use continueToken and maxPages to manually iterate. If true, the tool fetches all pages automatically (be careful with large result sets).'
Add missing descriptions to rancher_servers_add optional parameters. For insecureSkipTlsVerify, write: 'Set to true only if the Rancher server uses a self-signed or internal CA certificate (SECURITY RISK; not recommended for production).' For caCertPemBase64, write: 'Base64-encoded PEM certificate of a custom CA. Use this if the Rancher server is behind a corporate proxy or uses an internal PKI.'