@@ -60,6 +60,7 @@ For UI dependency upgrades, compare all four views (`get-me`, `issue-write`, `pr
     - Update readme documentation: `script/generate-docs`
     - If renaming a tool, add a deprecation alias (see [Tool Renaming Guide](docs/tool-renaming.md))
     - For toolset and icon configuration, see [Toolsets and Icons Guide](docs/toolsets-and-icons.md)
+    - For typed tool registration and compatibility schemas, see [Typed Tool Schemas](docs/typed-tool-schemas.md)
 6. Push to your fork and [submit a pull request][pr] targeting the `main` branch
 7. Pat yourself on the back and wait for your pull request to be reviewed and merged.
 
 
@@ -0,0 +1,61 @@
+# Typed tool schemas
+
+Typed tool registrations use concrete Go input and output types with the MCP
+Go SDK's `mcp.AddTool` path. The SDK infers schemas when the tool definition
+does not provide them, validates arguments before the handler runs, and
+validates typed output. Keep business rules that JSON Schema cannot express
+in the handler or a preflight callback.
+
+Input inference unwraps one pointer level, matching the SDK's object input
+contract. Output pointers retain nullable schemas and may return JSON null.
+
+```go
+tool := github.NewToolWithSchemaOptions[workflowInput, workflowOutput](
+    toolset,
+    mcp.Tool{Name: "list_workflow_runs"},
+    scopeAccess,
+    inventory.TypedSchemaOptions{
+        InputEnums: []inventory.SchemaEnum{
+            {Path: "status", Values: github.WorkflowStatusValues()},
+        },
+    },
+    listWorkflowRuns,
+)
+```
+
+`SchemaEnum.Path` addresses inferred properties with dot-separated names and
+uses `items` to descend into array elements. `EnumSchema` creates a standalone
+string enum schema, while `WithEnum` returns a cloned explicit schema with an
+enum applied at a path. Inferred and explicit schema helpers cache immutable
+schemas; do not mutate the returned pointers.
+
+When compatibility requires a broader runtime input contract than the one
+advertised to clients, provide `ValidationInputSchema`. The tool's declared
+`InputSchema` remains visible while the SDK validates calls against the
+runtime-only schema. Use `Preflight` for checks that need raw arguments or
+request dependencies before typed decoding; it may return a derived context
+for the handler. Input normalizers are only for compatibility transformations,
+not a replacement for schema validation.
+
+The SDK applies defaults from the runtime input schema before decoding. If an
+omitted field must remain omitted, build the runtime schema with
+`inventory.CloneSchemaWithoutDefaults` before applying validation-only
+changes. Use `inventory.CloneSchema` when deriving other runtime-only schema
+variants so numeric bound pointers and nested metadata are detached as well as
+subschemas. Default removal visits each child once per parent. The advertised
+schema can retain its defaults; the constructor caches the runtime schema
+without mutating either caller-owned schema.
+
+The output schema and `structuredContent` are exposed only for a negotiated,
+SDK-supported protocol version `2026-07-28` or later. Unknown versions are
+treated as legacy, including unsupported future dates; older, absent, and
+malformed versions also retain the legacy text result. Normal `Inventory.RegisterTools` and
+`ServerTool.RegisterFunc` registrations select behavior per request. Use
+`RegisterToolsForProtocolEra` or `RegisterFuncForProtocolEra` only when the
+protocol era is already known before server construction, such as a stateless
+request-scoped server.
+
+If a handler intentionally returns non-JSON text or content blocks, set
+`PreserveHandlerContent` in `TypedSchemaOptions`, or call
+`inventory.PreserveToolHandlerContent(ctx)` from the handler middleware for
+request-dependent output such as CSV.
@@ -24,6 +24,12 @@ type MCPMethodInfo struct {
 	ItemName string
 	// RawArguments contains the unmaterialized tool arguments for tools/call requests.
 	RawArguments json.RawMessage
+	// NormalizedArguments contains canonical arguments prepared by HTTP scope
+	// middleware so tool adapters do not rerun non-idempotent normalizers.
+	NormalizedArguments json.RawMessage
+	// ArgumentsNormalized distinguishes an intentionally empty normalized value
+	// from a request that has not been normalized.
+	ArgumentsNormalized bool
 	// ProtocolVersion and ClientCapabilities describe the requesting MCP client
 	// when stateless HTTP parsing makes them available before registration.
 	ProtocolVersion    string
 
@@ -311,13 +311,13 @@ Use this tool to list workflows in a repository, or list workflow runs, jobs, an
 					"page": {
 						Type:        "number",
 						Description: "Page number for pagination (default: 1)",
-						Minimum:     jsonschema.Ptr(1.0),
+						Minimum:     new(1.0),
 					},
 					"perPage": {
 						Type:        "number",
 						Description: "Results per page for pagination (default: 30, max: 100)",
-						Minimum:     jsonschema.Ptr(1.0),
-						Maximum:     jsonschema.Ptr(100.0),
+						Minimum:     new(1.0),
+						Maximum:     new(100.0),
 					},
 				},
 				Required: []string{"method", "owner", "repo"},
@@ -536,7 +536,7 @@ func ActionsRunTrigger(t translations.TranslationHelperFunc) inventory.ServerToo
 			Annotations: &mcp.ToolAnnotations{
 				Title:           t("TOOL_ACTIONS_RUN_TRIGGER_USER_TITLE", "Trigger GitHub Actions workflow actions"),
 				ReadOnlyHint:    false,
-				DestructiveHint: jsonschema.Ptr(true),
+				DestructiveHint: new(true),
 			},
 			InputSchema: &jsonschema.Schema{
 				Type: "object",
 
@@ -57,7 +57,7 @@ var issueCommentVisibilityTarget = commentVisibilityTarget{
 			"comment_id": {
 				Type:        "number",
 				Description: "The numeric ID of the issue or pull request conversation comment",
-				Minimum:     jsonschema.Ptr(1.0),
+				Minimum:     new(1.0),
 			},
 		}
 	},
@@ -84,7 +84,7 @@ var pullRequestReviewCommentVisibilityTarget = commentVisibilityTarget{
 			"comment_id": {
 				Type:        "number",
 				Description: "The numeric pull request review comment ID. Use the number from a #discussion_r... anchor, not the GraphQL thread node ID (PRRT_...).",
-				Minimum:     jsonschema.Ptr(1.0),
+				Minimum:     new(1.0),
 			},
 		}
 	},
@@ -111,12 +111,12 @@ var pullRequestReviewVisibilityTarget = commentVisibilityTarget{
 			"pullNumber": {
 				Type:        "number",
 				Description: "The pull request number",
-				Minimum:     jsonschema.Ptr(1.0),
+				Minimum:     new(1.0),
 			},
 			"review_id": {
 				Type:        "number",
 				Description: "The numeric ID of the pull request review",
-				Minimum:     jsonschema.Ptr(1.0),
+				Minimum:     new(1.0),
 			},
 		}
 	},
@@ -175,8 +175,8 @@ func commentVisibilityTool(t translations.TranslationHelperFunc, target commentV
 			Annotations: &mcp.ToolAnnotations{
 				Title:           t("TOOL_"+strings.ToUpper(name)+"_USER_TITLE", titleAction+" "+target.title),
 				ReadOnlyHint:    false,
-				DestructiveHint: jsonschema.Ptr(false),
-				OpenWorldHint:   jsonschema.Ptr(true),
+				DestructiveHint: new(false),
+				OpenWorldHint:   new(true),
 			},
 			InputSchema: &jsonschema.Schema{
 				Type:       "object",
 
@@ -563,7 +563,7 @@ func AssignCopilotToIssueWithIntent(t translations.TranslationHelperFunc) invent
 						Type: "string",
 						Description: "One concise sentence explaining what specifically about the issue led to choosing Copilot. " +
 							"State the concrete signal (e.g. 'Well-scoped task with clear acceptance criteria').",
-						MaxLength: jsonschema.Ptr(280),
+						MaxLength: new(280),
 					},
 					"confidence": {
 						Type:        "string",
 
@@ -42,16 +42,14 @@ type csvOutputDocument struct {
 	rows     []map[string]string
 }
 
-// withCSVOutput wraps the handler of every default-toolset list_* tool so that,
-// at request time, it checks the csv_output feature flag and converts the JSON
-// text response to CSV when enabled. The tool's schema, name, and scope are
-// unchanged — only the response payload format differs.
+// withCSVOutput adds dependency-aware middleware to every default-toolset
+// list_* tool so that it converts JSON text to CSV when the feature is enabled.
 func withCSVOutput(tools []inventory.ServerTool) []inventory.ServerTool {
 	for i := range tools {
 		if !isCSVOutputTool(tools[i]) {
 			continue
 		}
-		tools[i].HandlerFunc = wrapHandlerWithCSVOutput(tools[i].HandlerFunc)
+		tools[i].AddHandlerMiddleware(csvOutputMiddleware)
 	}
 	return tools
 }
@@ -68,18 +66,18 @@ func isCSVOutputTool(tool inventory.ServerTool) bool {
 	return strings.HasPrefix(tool.Tool.Name, "list_")
 }
 
-func wrapHandlerWithCSVOutput(next inventory.HandlerFunc) inventory.HandlerFunc {
-	return func(deps any) mcp.ToolHandler {
-		handler := next(deps)
-		csvDeps, _ := deps.(ToolDependencies)
+func csvOutputMiddleware(deps any) inventory.ToolHandlerMiddleware {
+	csvDeps, _ := deps.(ToolDependencies)
+	return func(next mcp.ToolHandler) mcp.ToolHandler {
 		return func(ctx context.Context, req *mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-			result, err := handler(ctx, req)
+			result, err := next(ctx, req)
 			if err != nil || result == nil || result.IsError {
 				return result, err
 			}
 			if csvDeps == nil || !csvDeps.IsFeatureEnabled(ctx, FeatureFlagCSVOutput) {
-				return result, nil
+				return result, err
 			}
+			inventory.PreserveToolHandlerContent(ctx)
 			return convertJSONTextResultToCSV(result), nil
 		}
 	}
 
@@ -4,6 +4,7 @@ import (
 	"context"
 	"encoding/csv"
 	"encoding/json"
+	"errors"
 	"strings"
 	"testing"
 
@@ -126,6 +127,114 @@ func TestCSVOutputPreservesOriginalJSONWhenFlagOff(t *testing.T) {
 	assert.JSONEq(t, jsonResponse, text.Text)
 }
 
+func TestCSVOutputMiddlewareAppliesToTypedToolRegistration(t *testing.T) {
+	type row struct {
+		Number int `json:"number"`
+	}
+	tools := withCSVOutput([]inventory.ServerTool{
+		inventory.NewServerToolWithContextHandler(
+			mcp.Tool{Name: "list_typed_things"},
+			ToolsetMetadataRepos,
+			func(context.Context, *mcp.CallToolRequest, struct{}) (*mcp.CallToolResult, []row, error) {
+				return &mcp.CallToolResult{
+					Content: []mcp.Content{&mcp.TextContent{Text: `[{"number":1}]`}},
+				}, []row{{Number: 1}}, nil
+			},
+		),
+	})
+	deps := newCSVOutputTestDeps(true)
+	server := mcp.NewServer(&mcp.Implementation{Name: "test-server", Version: "v0.0.1"}, nil)
+	tools[0].RegisterFunc(server, deps)
+
+	serverTransport, clientTransport := mcp.NewInMemoryTransports()
+	serverSession, err := server.Connect(context.Background(), serverTransport, nil)
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = serverSession.Close() })
+	client := mcp.NewClient(&mcp.Implementation{Name: "test-client", Version: "v0.0.1"}, nil)
+	clientSession, err := client.Connect(context.Background(), clientTransport, nil)
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = clientSession.Close() })
+
+	result, err := clientSession.CallTool(context.Background(), &mcp.CallToolParams{Name: "list_typed_things"})
+	require.NoError(t, err)
+	require.False(t, result.IsError)
+	assert.JSONEq(t, `[{"number":1}]`, mustMarshalCSVJSON(t, result.StructuredContent))
+	assert.Contains(t, textResult(t, result), "number\n1")
+}
+
+func TestCSVOutputTypedArrayPreservesLegacyProtocolResult(t *testing.T) {
+	type row struct {
+		Number int `json:"number"`
+	}
+	type object struct {
+		Number int `json:"number"`
+	}
+	tools := withCSVOutput([]inventory.ServerTool{
+		inventory.NewServerToolWithContextHandler(
+			mcp.Tool{Name: "list_typed_things"},
+			ToolsetMetadataRepos,
+			func(context.Context, *mcp.CallToolRequest, struct{}) (*mcp.CallToolResult, []row, error) {
+				return &mcp.CallToolResult{
+					Content: []mcp.Content{&mcp.TextContent{Text: `[{"number":1}]`}},
+				}, []row{{Number: 1}}, nil
+			},
+		),
+		inventory.NewServerToolWithContextHandler(
+			mcp.Tool{Name: "get_typed_thing"},
+			ToolsetMetadataRepos,
+			func(context.Context, *mcp.CallToolRequest, struct{}) (*mcp.CallToolResult, object, error) {
+				return &mcp.CallToolResult{
+					Content: []mcp.Content{&mcp.TextContent{Text: `{"number":1}`}},
+				}, object{Number: 1}, nil
+			},
+		),
+	})
+	deps := newCSVOutputTestDeps(true)
+	server := mcp.NewServer(&mcp.Implementation{Name: "test-server", Version: "v0.0.1"}, nil)
+	server.AddReceivingMiddleware(func(next mcp.MethodHandler) mcp.MethodHandler {
+		return func(ctx context.Context, method string, request mcp.Request) (mcp.Result, error) {
+			if method == "server/discover" {
+				return nil, errors.New("legacy client uses initialize")
+			}
+			return next(ctx, method, request)
+		}
+	})
+	for _, tool := range tools {
+		tool.RegisterFunc(server, deps)
+	}
+
+	serverTransport, clientTransport := mcp.NewInMemoryTransports()
+	serverSession, err := server.Connect(context.Background(), serverTransport, nil)
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = serverSession.Close() })
+	client := mcp.NewClient(&mcp.Implementation{Name: "test-client", Version: "v0.0.1"}, nil)
+	clientSession, err := client.Connect(context.Background(), clientTransport, nil)
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = clientSession.Close() })
+	require.Equal(t, "2025-11-25", clientSession.InitializeResult().ProtocolVersion)
+
+	list, err := clientSession.ListTools(context.Background(), nil)
+	require.NoError(t, err)
+	require.Len(t, list.Tools, 2)
+	for _, tool := range list.Tools {
+		assert.Nil(t, tool.OutputSchema, "legacy tools/list must hide typed output schemas")
+	}
+
+	listResult, err := clientSession.CallTool(context.Background(), &mcp.CallToolParams{Name: "list_typed_things"})
+	require.NoError(t, err)
+	require.False(t, listResult.IsError)
+	assert.Nil(t, listResult.StructuredContent)
+	require.Len(t, listResult.Content, 1, "CSV text must not be duplicated by the SDK's JSON array fallback")
+	assert.Equal(t, "number\n1\n", textResult(t, listResult))
+
+	objectResult, err := clientSession.CallTool(context.Background(), &mcp.CallToolParams{Name: "get_typed_thing"})
+	require.NoError(t, err)
+	require.False(t, objectResult.IsError)
+	assert.Nil(t, objectResult.StructuredContent)
+	require.Len(t, objectResult.Content, 1)
+	assert.Equal(t, `{"number":1}`, textResult(t, objectResult))
+}
+
 func TestCSVOutputVariantMovesMetadataToPreamble(t *testing.T) {
 	csvText, err := jsonTextToCSV(`{
 		"issues": [
@@ -152,6 +261,13 @@ func TestCSVOutputVariantMovesMetadataToPreamble(t *testing.T) {
 	assert.NotContains(t, row, "totalCount")
 }
 
+func mustMarshalCSVJSON(t *testing.T, value any) string {
+	t.Helper()
+	data, err := json.Marshal(value)
+	require.NoError(t, err)
+	return string(data)
+}
+
 func TestJSONTextToCSVFlattensPrimaryRows(t *testing.T) {
 	csvText, err := jsonTextToCSV(`{
 		"discussions": [
 
@@ -214,6 +214,14 @@ func (d BaseDeps) IsFeatureEnabled(ctx context.Context, flag string) bool {
 // This avoids creating closures at registration time, which is important for performance
 // in servers that create a new server instance per request (like the remote server).
 //
+// Use concrete input and output structs for migrated tools; registration then
+// delegates schema inference and validation to mcp.AddTool. For example, define
+// `type SearchInput struct { Query string `json:"query"` }` and a concrete
+// `SearchOutput`, then use `NewTool[SearchInput, SearchOutput](...)`. Keep Out
+// as any for tools that must retain the raw registration path. A final optional
+// inventory.InputNormalizer argument can canonicalize legacy wire values
+// (such as case-insensitive enums) before strict SDK schema validation.
+//
 // The handler function receives deps extracted from context via MustDepsFromContext.
 // Ensure ContextWithDeps is called to inject deps before any tool handlers are invoked.
 //
@@ -223,11 +231,33 @@ func NewTool[In, Out any](
 	tool mcp.Tool,
 	scopeAccess inventory.ScopeAccess,
 	handler func(ctx context.Context, deps ToolDependencies, req *mcp.CallToolRequest, args In) (*mcp.CallToolResult, Out, error),
+	inputNormalizers ...inventory.InputNormalizer,
+) inventory.ServerTool {
+	return NewToolWithSchemaOptions(
+		toolset,
+		tool,
+		scopeAccess,
+		inventory.TypedSchemaOptions{},
+		handler,
+		inputNormalizers...,
+	)
+}
+
+// NewToolWithSchemaOptions is like NewTool, with options for schema inference,
+// runtime-only input validation schemas, and pre-decode compatibility checks.
+// The original tool schema remains the schema advertised to clients.
+func NewToolWithSchemaOptions[In, Out any](
+	toolset inventory.ToolsetMetadata,
+	tool mcp.Tool,
+	scopeAccess inventory.ScopeAccess,
+	schemaOptions inventory.TypedSchemaOptions,
+	handler func(ctx context.Context, deps ToolDependencies, req *mcp.CallToolRequest, args In) (*mcp.CallToolResult, Out, error),
+	inputNormalizers ...inventory.InputNormalizer,
 ) inventory.ServerTool {
-	st := inventory.NewServerToolWithContextHandler(tool, toolset, func(ctx context.Context, req *mcp.CallToolRequest, args In) (*mcp.CallToolResult, Out, error) {
+	st := inventory.NewServerToolWithContextHandlerAndSchemaOptions(tool, toolset, func(ctx context.Context, req *mcp.CallToolRequest, args In) (*mcp.CallToolResult, Out, error) {
 		deps := MustDepsFromContext(ctx)
 		return handler(ctx, deps, req, args)
-	})
+	}, schemaOptions, inputNormalizers...)
 	st.ScopeAccess = scopeAccess
 	return st
 }
Original file line number	Diff line number	Diff line change
`@@ -42,16 +42,14 @@ type csvOutputDocument struct {`
`42`	`42`	`rows []map[string]string`
`43`	`43`	`}`
`44`	`44`
`45`		`-// withCSVOutput wraps the handler of every default-toolset list_* tool so that,`
`46`		`-// at request time, it checks the csv_output feature flag and converts the JSON`
`47`		`-// text response to CSV when enabled. The tool's schema, name, and scope are`
`48`		`-// unchanged — only the response payload format differs.`
	`45`	`+// withCSVOutput adds dependency-aware middleware to every default-toolset`
	`46`	`+// list_* tool so that it converts JSON text to CSV when the feature is enabled.`
`49`	`47`	`func withCSVOutput(tools []inventory.ServerTool) []inventory.ServerTool {`
`50`	`48`	`for i := range tools {`
`51`	`49`	`if !isCSVOutputTool(tools[i]) {`
`52`	`50`	`continue`
`53`	`51`	`}`
`54`		`- tools[i].HandlerFunc = wrapHandlerWithCSVOutput(tools[i].HandlerFunc)`
	`52`	`+ tools[i].AddHandlerMiddleware(csvOutputMiddleware)`
`55`	`53`	`}`
`56`	`54`	`return tools`
`57`	`55`	`}`
`@@ -68,18 +66,18 @@ func isCSVOutputTool(tool inventory.ServerTool) bool {`
`68`	`66`	`return strings.HasPrefix(tool.Tool.Name, "list_")`
`69`	`67`	`}`
`70`	`68`
`71`		`-func wrapHandlerWithCSVOutput(next inventory.HandlerFunc) inventory.HandlerFunc {`
`72`		`- return func(deps any) mcp.ToolHandler {`
`73`		`- handler := next(deps)`
`74`		`- csvDeps, _ := deps.(ToolDependencies)`
	`69`	`+func csvOutputMiddleware(deps any) inventory.ToolHandlerMiddleware {`
	`70`	`+ csvDeps, _ := deps.(ToolDependencies)`
	`71`	`+ return func(next mcp.ToolHandler) mcp.ToolHandler {`
`75`	`72`	`return func(ctx context.Context, req mcp.CallToolRequest) (mcp.CallToolResult, error) {`
`76`		`- result, err := handler(ctx, req)`
	`73`	`+ result, err := next(ctx, req)`
`77`	`74`	`if err != nil \|\| result == nil \|\| result.IsError {`
`78`	`75`	`return result, err`
`79`	`76`	`}`
`80`	`77`	`if csvDeps == nil \|\| !csvDeps.IsFeatureEnabled(ctx, FeatureFlagCSVOutput) {`
`81`		`- return result, nil`
	`78`	`+ return result, err`
`82`	`79`	`}`
	`80`	`+ inventory.PreserveToolHandlerContent(ctx)`
`83`	`81`	`return convertJSONTextResultToCSV(result), nil`
`84`	`82`	`}`
`85`	`83`	`}`