Under what circumstances should a server.ToolHandlerFunc return a non-nil error?

[williammartin]

As per the spec:

Tool errors should be reported within the result object, not as MCP protocol-level errors. This allows the LLM to see and potentially handle the error. When a tool encounters an error ...

This approach allows the LLM to see that an error occurred and potentially take corrective action or request human intervention.

---

The straightforward reading of this is that tools should only ever return valid results that may or may not contain an error. However, the server.ToolHandlerFunc returns error as second value, which gets translated into an INTERNAL_ERROR.

Under what circumstances should a tool return a non-nil error?

[rwjblue-glean]

Hmm, great question. I think that you basically never want to return an error (as you said). The only cases where I could imagine that you do want to return an actual error is if something is absolutely fundamentally broken / wrong (e.g. unrelated to the tool invocation, but something server infrastructure).

[williammartin]

For what it's worth, this seems to be the same conclusion that the go-sdk folks have come to https://github.com/orgs/modelcontextprotocol/discussions/364#discussioncomment-13162153, where their NewTool adapter will wrap all error returns into the in-band error.