Audit error messages for actionable fix instructions #703
Description
Summary
Error messages should tell users how to fix the problem, not just what the problem is.
Current State
Example - missing secret error:
Tool 'tool_name' cannot be executed because it requires the following secrets that are not available: API_KEY
This tells the user what's wrong but not how to fix it.
Proposed State
✗ Missing secret 'API_KEY'
Tool 'fetch_data' requires this secret but it's not configured.
To fix, either:
1. Add to .env file: API_KEY=your_key_here
2. Set environment var: export API_KEY=your_key_here
Then restart the server.
Why This Matters
- Reduces friction - Users don't have to search docs or guess
- Better DX - Errors become self-service documentation
- Fewer support questions - The answer is in the error
Inspiration
Elm and Rust compilers are famous for helpful error messages. Every error should answer: "What do I do now?"
Scope
Audit all user-facing errors in arcade-mcp-server:
- Missing secrets - Show how to set them
- Invalid tool input - Show expected shape vs received
- Authorization failures - Explain the auth flow
- Transport errors - Suggest common fixes (port in use, etc.)
- Configuration errors - Show valid options
Each error should include:
- Clear problem statement
- Specific context (which tool, which field, what value)
- Concrete fix instructions
- Next step (e.g., "Then restart the server")
Related
This pattern is being implemented in the TypeScript version for consistency across implementations.