MCPTroubleshooter has three tools with basic schemas and descriptions, but significant gaps prevent production use. All tools have descriptions (10-50 chars, below the 50-200 char baseline for LLM optimization), and input schemas are present but minimal. The 'read-mcp-logs' tool has a reasonable schema with 'lines' (number, default 100) and 'serverName' (string, optional), but descriptions lack actionable context. 'analyze-mcp-logs' and 'read-mcp-config' have even sparser parameter documentation. No output schemas are documented, LLMs cannot predict what fields to expect or chain results to downstream tools. Error handling returns isError flags and text, but lacks recovery guidance (e.g., 'Try installing Claude Desktop' or 'Check permissions'). No tool annotations (readOnlyHint, idempotentHint) despite all three being read-only operations. Parameter descriptions do not explain format, constraints, or when to use each tool vs. alternatives.

• Expand tool descriptions to 80-150 chars. Example: 'read-mcp-logs: Retrieve the last N lines from MCP server logs. Use this to diagnose connection, initialization, or spawn errors. Optionally filter by server name. Returns raw log text; call analyze-mcp-logs for pattern matching.'
• Document output schemas for each tool. E.g., read-mcp-logs returns {content: [{type: 'text', text: string}], isError?: boolean}. analyze-mcp-logs returns {content: [{type: 'text', text: string}], analysisResults: [{file: string, findings: [{pattern, description, occurrences, examples}]}]}.
• Add constraints to parameters: 'lines' (1-1000, default 100), 'serverName' (optional, case-insensitive substring match). Document in descriptions.
• Enhance error messages with recovery steps. E.g., 'Log directory not found at ~/.config/Claude/logs. Ensure Claude Desktop is installed and has run at least once. Logs are created after the first MCP server connection.'
• Add tool annotations: readOnlyHint=true and idempotentHint=true to all three tools to signal safe retry behavior.