mcpcheck defines 5 tools with clear, domain-specific purposes (linting, rule documentation, config fixing). All tools have descriptions (avg ~80 chars) and input schemas with required fields. However, parameter descriptions are sparse or missing entirely, most params lack guidance on format, constraints, or expected values. Output schemas are undocumented; LLMs cannot predict what fields to extract from responses. Error handling is minimal; no recovery guidance or actionable error messages visible. Tool names are verb-forward and unambiguous, but descriptions could be more LLM-optimized (e.g., 'lint_config' lacks 'when to use' context). No tool annotations (readOnlyHint/destructiveHint) despite clear risk profiles (fix_config is WRITE, others are READ_ONLY).

• Add detailed parameter descriptions to all tools. For 'path': 'Absolute or tilde-expanded path to the MCP config file (e.g., ~/.config/mcp.json or /etc/mcp/config.json). Required.' For 'rule_id': 'Rule identifier (e.g., mcp/no-hardcoded-secrets) or "all" to retrieve all rules.'
• Document output schemas for each tool. E.g., lint_config returns {issues: [{severity: string, rule_id: string, line: number, message: string}], total: number}. Include field types and meanings.
• Add tool annotations: mark fix_config with destructiveHint=true; mark lint_config, explain_rule, list_rules, stats_config with readOnlyHint=true. This enables agents to reason about safety.
• Implement error handling with recovery guidance. E.g., 'Path not found: /path/to/config.json. Ensure the file exists and path is absolute or tilde-expanded.' For invalid rule_id: 'Unknown rule: xyz. Call list_rules() to see available rules.'
• Add a dry-run mode to fix_config or require explicit confirmation before write=true. E.g., add a 'confirm' parameter or return a preview of changes and ask for approval before writing.