fix: return isError for argument validation failures

[blackwell-systems]

Fixes #1952.

Problem

When tool argument unmarshalling fails (wrong types, malformed JSON), the handler returns (nil, err) which the SDK converts to a JSON-RPC protocol error (-32603). Agents cannot see protocol errors in their context window, so they cannot self-correct.

Fix

Return isError: true with the validation error message instead of a Go error. Two sites in server_tool.go:

• NewServerTool (line 135)
• NewServerToolWithContextHandler (line 159)

Before:

if err := json.Unmarshal(req.Params.Arguments, &arguments); err != nil {
    return nil, err // protocol error: agent sees nothing
}

After:

if err := json.Unmarshal(req.Params.Arguments, &arguments); err != nil {
    return &mcp.CallToolResult{
        Content: []mcp.Content{&mcp.TextContent{Text: fmt.Sprintf("invalid arguments: %s", err)}},
        IsError: true,
    }, nil // tool execution error: agent sees the message and can retry
}

Tests

• TestNewServerTool_InvalidArguments_ReturnsIsError
• TestNewServerToolWithContextHandler_InvalidArguments_ReturnsIsError
• TestNewServerTool_ValidArguments_Succeeds

[SamMorrowDrums]

LGTM. Worth noting that this is now the spec-recommended behaviour, not just a pragmatic choice.

The 2025-11-25 spec sharpened the Error Handling section since the older 2025-06-18 revision. It now draws the line at the CallToolRequest schema rather than the tool's inputSchema:

• Protocol Errors → "Malformed requests (requests that fail to satisfy [CallToolRequest schema])"
• Tool Execution Errors (isError: true) → "Input validation errors (e.g., date in wrong format, value out of range)"

And it adds the rationale this PR is built on:

Tool Execution Errors contain actionable feedback that language models can use to self-correct and retry with adjusted parameters. Protocol Errors indicate issues with the request structure itself that models are less likely to be able to fix. Clients SHOULD provide tool execution errors to language models to enable self-correction.

json.Unmarshal failures into the typed argument struct are exactly the "input validation" case the spec calls out — so the previous return nil, err path was the wrong mechanism under the current spec, and this PR aligns the server with it.

Both call sites are updated symmetrically, the response shape is well-formed (TextContent + IsError: true, returning a nil Go error so the SDK doesn't also emit a JSON-RPC error), and the tests cover both handler variants plus the happy path.

[SamMorrowDrums]

@blackwell-systems some lint failures.

[SamMorrowDrums]

@blackwell-systems still some similar lint failures. You can run locally to avoid discovering this in CI naturally. There are scripts in repo etc.

[SamMorrowDrums]

re-created pr with you as co-author, I do not have time for iterating on linter failures multiple times in a row. thank you for contribution.