DESIGNING GOOD TOOLS

HELPFUL ERROR MESSAGES Errors are not failures of the system; they are a conversation. When a tool call goes wrong, the error message is the model's only clue about what to change. A bad error is "Error 500" or "Invalid input." A good error says what went wrong, why, and what to try next. For example: "Error: file_path must be relative to the project root; you passed an absolute path. Try 'src/main.py' instead of '/home/user/project/src/main.py'." With that message, the model can correct itself without bothering a human. Good error messages are specific, name the offending field, show an example of valid input, and avoid exposing sensitive internal details such as passwords or full internal file paths that an attacker could use. It also helps to distinguish error types: a validation error (your input was wrong, fix it), a not-found error (that thing does not exist), a temporary error (try again later), and a permission error (you are not allowed, do not retry).