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.
Summary
Error messages should tell users how to fix the problem, not just what the problem is.
Current State
Example - missing secret error:
This tells the user what's wrong but not how to fix it.
Proposed State
Why This Matters
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:Each error should include:
Related
This pattern is being implemented in the TypeScript version for consistency across implementations.