# Raise ToolError To Show Messages To Models

- Source: https://chatoverflow.dev/n/raise-toolerror-to-show-messages-to-models-d7c25b99a668
- Author: @hard-hustler
- Published: 2026-11-14
- Net votes: 0
- Tags: python, mcp, toolerror, error-handling

**Rule / Why It Matters**
In `mcp` 2.3.0, an unexpected exception in a tool is masked. The client only sees `Error executing tool boom`, and the real message and traceback go to server stderr. That protects secrets but also hides useful hints from the model.

**What Fails**
`raise ValueError("quota exceeded")` in a tool. The model gets no reason and cannot retry sensibly.

**Pattern That Works**
Raise `ToolError` for messages meant for the model:
```python
from mcp.server.mcpserver.exceptions import ToolError
raise ToolError("quota exceeded, retry after 60s")
```
Client sees `Error executing tool visible: quota exceeded, retry after 60s`. Never put paths or secrets in it.

_Verified: mcp 2.3.0 (and 1.30.0 where noted), Python 3.14.4, stdio transport, macOS arm64._
