render tool errors as llmxml

Success output speaks llmxml (ADR 1.3); errors were the one surface
breaking the dialect, reaching the model as bare prose. Receiving
middleware rewraps in-band error text as
<error tool="NAME">message</error> at one choke point covering SDK
argument validation, client-side refusals, and Gerrit API passthrough
alike; per-handler wrapping would miss validation errors, which never
reach handler code.

Protocol-level failures (unknown tool) stay JSON-RPC errors; the MCP
isError flag is untouched. Error shape is pinned by golden files
alongside success renders.

Author: xobotyi

cmd/go-gerrit-mcp/main.go

@@ -53,6 +53,7 @@ func run(lgr *slog.Logger) error {
 		&mcp.Implementation{Name: serverName, Version: version},
 		&mcp.ServerOptions{Instructions: instructions},
 	)
+	srv.AddReceivingMiddleware(tools.WrapErrors)
 
 	enabled, err := registry.Resolve(cfg)
 	if err != nil {

design-docs/adr/1.3-llmxml-output.md

@@ -16,3 +16,10 @@ per-file comment threads and diff hunks). XML-style tags delimit nested structur
 review data needs and what models parse reliably. The format is a published
 behavior contract — user prompts and workflows will come to depend on its shape — so changing it later is a breaking
 change, hence the record.
+
+**Amended 2026-07-11 — errors speak the dialect too.** Every in-band tool-call error — argument validation, client-side
+refusals, Gerrit API passthrough — reaches the model as `<error tool="NAME">message</error>`, applied uniformly by
+server middleware rather than per tool, so failure output never forces a parsing-mode switch. The MCP `isError` flag is
+untouched (llmxml is the model-facing layer, not the transport signal), and protocol-level failures such as an unknown
+tool name remain plain JSON-RPC errors. The error shape is part of the same published contract as success renders and
+is pinned by golden files.

internal/tools/error-middleware.go

@@ -0,0 +1,47 @@
+package tools
+
+import (
+	"context"
+
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+
+	"dev.gaijin.team/go/go-gerrit-mcp/internal/llmxml"
+)
+
+// WrapErrors is receiving middleware that re-renders in-band tool-call errors
+// as llmxml, so error output speaks the same dialect as success output
+// (ADR 1.3). Placed on the server it covers every error class uniformly:
+// SDK argument validation, client-side refusals, and Gerrit API passthrough.
+// Protocol-level failures (e.g. unknown tool) are JSON-RPC errors and pass
+// through untouched.
+func WrapErrors(next mcp.MethodHandler) mcp.MethodHandler {
+	return func(ctx context.Context, method string, req mcp.Request) (mcp.Result, error) {
+		res, err := next(ctx, method, req)
+		if err != nil {
+			return res, err
+		}
+
+		call, ok := req.(*mcp.CallToolRequest)
+		if !ok {
+			return res, nil
+		}
+
+		out, ok := res.(*mcp.CallToolResult)
+		if !ok || !out.IsError || len(out.Content) != 1 {
+			return res, nil
+		}
+
+		text, ok := out.Content[0].(*mcp.TextContent)
+		if !ok {
+			return res, nil
+		}
+
+		wrapped := llmxml.NewElement("error", llmxml.Attr("tool", call.Params.Name)).
+			WrapText(text.Text).
+			String()
+
+		out.Content = []mcp.Content{&mcp.TextContent{Text: wrapped}}
+
+		return out, nil
+	}
+}

internal/tools/error-middleware_test.go

@@ -0,0 +1,57 @@
+package tools_test
+
+import (
+	"testing"
+
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+	"github.com/stretchr/testify/require"
+)
+
+// errorText extracts the sole text content of an error result.
+func errorText(t *testing.T, res *mcp.CallToolResult) string {
+	t.Helper()
+
+	require.True(t, res.IsError)
+	require.Len(t, res.Content, 1)
+
+	text, ok := res.Content[0].(*mcp.TextContent)
+	require.True(t, ok)
+
+	return text.Text
+}
+
+// Tool errors are a product contract like success renders (ADR 1.3): every
+// in-band error class reaches the model wrapped as llmxml. Validation errors
+// originate in the SDK before handler code runs; refusals originate in
+// handlers — the middleware must cover both.
+func Test_WrapErrors(t *testing.T) {
+	t.Parallel()
+
+	t.Run("argument validation error is llmxml", func(t *testing.T) {
+		t.Parallel()
+
+		cs, _ := fakeGerrit(t, "")
+
+		res, err := cs.CallTool(t.Context(), &mcp.CallToolParams{
+			Name:      "search_changes",
+			Arguments: map[string]any{},
+		})
+		require.NoError(t, err)
+
+		golden(t, "error-validation", errorText(t, res))
+	})
+
+	t.Run("handler refusal is llmxml", func(t *testing.T) {
+		t.Parallel()
+
+		cs, _ := transitionSession(t, ")]}'\n{}")
+
+		res, err := cs.CallTool(t.Context(), &mcp.CallToolParams{
+			Name:      "transition_change",
+			Arguments: map[string]any{"change": "123", "action": "merge"},
+		})
+		require.NoError(t, err)
+
+		golden(t, "error-refusal", errorText(t, res))
+	})
+}

internal/tools/get-change_test.go

@@ -65,6 +65,8 @@ func session(t *testing.T, gerritHandler http.HandlerFunc) *mcp.ClientSession {
 	require.NoError(t, err)
 
 	mcpServer := mcp.NewServer(&mcp.Implementation{Name: "test", Version: "0"}, nil)
+	mcpServer.AddReceivingMiddleware(tools.WrapErrors)
+
 	for _, tool := range tools.All(client) {
 		tool.Register(mcpServer)
 	}

internal/tools/testdata/error-refusal.golden

@@ -0,0 +1,3 @@
+<error tool="transition_change">
+unknown action, expected submit, abandon, restore, wip, or ready (action=merge)
+</error>

internal/tools/testdata/error-validation.golden

@@ -0,0 +1,3 @@
+<error tool="search_changes">
+validating "arguments": validating root: required: missing properties: ["query"]
+</error>