Improve Error Messages Throughout the Codebase

[naji247]

Overview

Many error messages in the codebase are generic or lack context, making it difficult for users to understand what went wrong and how to fix it. We need more descriptive, actionable error messages.

Current State

Several places in the code use generic error messages like:

• "Error tracking tool"
• "Critical error"
• "Failed to initialize"

These don't provide enough information for users to diagnose and fix issues.

Requirements

Improve error messages to include:

1. What went wrong - Clear description of the error
2. Why it happened - Context about the cause
3. How to fix it - Actionable steps or hints
4. Where it occurred - Module/function context

Examples of Improvements Needed

Before: "Error tracking tool"
After: "Failed to track tool 'my_tool': Tool registration must occur before first use"

Before: "Failed to initialize exporter"
After: "Failed to initialize OTLP exporter: Invalid endpoint URL 'not-a-url'. Please provide a valid HTTP/HTTPS URL"

Why This Matters

• Reduces user frustration when things go wrong
• Decreases support burden
• Helps users self-diagnose issues
• Improves overall developer experience
• Makes debugging faster

Acceptance Criteria

• Identify at least 10 generic error messages
• Replace with descriptive, actionable messages
• Include relevant context (values, settings, etc.)
• Maintain consistent error message format
• Don't expose sensitive information
• Update any related tests

Getting Started

1. Search for generic error strings in the codebase
2. Look for Exception raises and error logs
3. Understand the context of each error
4. Write clear, helpful replacement messages
5. Test that new messages appear correctly

Notes

• Keep messages concise but informative
• Use consistent formatting across all messages
• Consider adding error codes for common issues
• Think about the user's perspective
• Don't include internal implementation details users won't understand