Rich tool call rendering: readable arguments and responses, post previews, path-identical metadata

conversation/content_block.go

@@ -50,6 +50,18 @@ type ContentBlock struct {
 	Status       string          `json:"status,omitempty"`
 	Shared       *bool           `json:"shared,omitempty"` // pointer to distinguish unset from false
 
+	// Title is the resolved human-readable tool display name (see
+	// llm.ToolCall.Title). Persisted so a reloaded conversation renders the
+	// same tool name that the live websocket event showed. Left visible to
+	// non-requesters (name-equivalent).
+	Title string `json:"title,omitempty"`
+
+	// Description is the tool description (see llm.ToolCall.Description).
+	// Plumbing-only in this pass — persisted for live/persisted parity and
+	// future display, but not rendered anywhere yet. Left visible to
+	// non-requesters (name-equivalent).
+	Description string `json:"description,omitempty"`
+
 	// UserInteraction is the persisted form of llm.Tool.UserInteraction.
 	UserInteraction string `json:"user_interaction,omitempty"`
 
@@ -105,10 +117,13 @@ func Int64Ptr(v int64) *int64 { return &v }
 
 // FilterForNonRequester returns a new slice of content blocks with private
 // tool data redacted. Tool use blocks with shared != true have their Input
-// field set to nil. Tool result blocks with shared != true have their Content
-// field set to empty string. All other block types pass through unchanged.
-// The original slice and its elements are never mutated.
-// Returns nil if the input is nil.
+// and MCPBareName fields cleared. Tool result blocks with shared != true have
+// their Content field set to empty string. Name, Title, ServerOrigin, and
+// Description are intentionally left visible to non-requesters (they are
+// tool-identity metadata, not user/model data — mirroring redactToolCalls on
+// the live path so the two paths render identically). All other block types
+// pass through unchanged. The original slice and its elements are never
+// mutated. Returns nil if the input is nil.
 func FilterForNonRequester(blocks []ContentBlock) []ContentBlock {
 	if blocks == nil {
 		return nil
@@ -133,10 +148,13 @@ func FilterForNonRequester(blocks []ContentBlock) []ContentBlock {
 }
 
 // SanitizeForDisplay returns a new slice of content blocks with LLM-generated
-// string fields sanitized against Unicode bidi/spoofing attacks. Tool use
-// blocks have their Input field sanitized, and tool result blocks have their
-// Content field sanitized. The original slice is never mutated.
-// Returns nil if the input is nil.
+// and MCP-server-supplied string fields sanitized against Unicode bidi/spoofing
+// attacks. Tool use blocks have their Input, Title, and Description fields
+// sanitized, and tool result blocks have their Content field sanitized. The
+// Title/Description sanitization is defense in depth: MCP metadata is already
+// sanitized at capture (mcp/user_clients.go GetTools), but old persisted turns
+// predate that and this path also covers any non-MCP writer. The original slice
+// is never mutated. Returns nil if the input is nil.
 func SanitizeForDisplay(blocks []ContentBlock) []ContentBlock {
 	if blocks == nil {
 		return nil
@@ -150,6 +168,12 @@ func SanitizeForDisplay(blocks []ContentBlock) []ContentBlock {
 			if len(block.Input) > 0 {
 				result[i].Input = json.RawMessage(llm.SanitizeNonPrintableChars(string(block.Input)))
 			}
+			if block.Title != "" {
+				result[i].Title = llm.SanitizeNonPrintableChars(block.Title)
+			}
+			if block.Description != "" {
+				result[i].Description = llm.SanitizeNonPrintableChars(block.Description)
+			}
 		case BlockTypeToolResult:
 			if block.Content != "" {
 				result[i].Content = llm.SanitizeNonPrintableChars(block.Content)

conversation/content_block_test.go

@@ -110,6 +110,22 @@ func TestContentBlockMarshalUnmarshal(t *testing.T) {
 			},
 			expected: `{"type":"tool_use","id":"tc_02","name":"read_file","input":{"path":"/etc/passwd"},"status":"pending","shared":false}`,
 		},
+		{
+			name: "tool_use block with title/description/mcp_bare_name",
+			block: ContentBlock{
+				Type:         BlockTypeToolUse,
+				ID:           "tc_03",
+				Name:         "mattermost__create_post",
+				ServerOrigin: "embedded://mattermost",
+				MCPBareName:  "create_post",
+				Title:        "Create Post",
+				Description:  "Create a new post in Mattermost.",
+				Input:        json.RawMessage(`{"channel_id":"c1"}`),
+				Status:       StatusPending,
+				Shared:       BoolPtr(true),
+			},
+			expected: `{"type":"tool_use","id":"tc_03","name":"mattermost__create_post","server_origin":"embedded://mattermost","input":{"channel_id":"c1"},"mcp_bare_name":"create_post","status":"pending","shared":true,"title":"Create Post","description":"Create a new post in Mattermost."}`,
+		},
 	}
 
 	for _, tt := range tests {
@@ -194,6 +210,8 @@ func TestFilterForNonRequesterRedactsApprovalMetadata(t *testing.T) {
 		Type:        BlockTypeToolUse,
 		ID:          "tc_private",
 		Name:        "jira__get_issue",
+		Title:       "Get Issue",
+		Description: "Get a Jira issue",
 		Input:       json.RawMessage(`{"key":"MM-1"}`),
 		MCPBareName: "get_issue",
 		Status:      StatusPending,
@@ -205,6 +223,12 @@ func TestFilterForNonRequesterRedactsApprovalMetadata(t *testing.T) {
 	require.Len(t, result, 1)
 	assert.Nil(t, result[0].Input)
 	assert.Empty(t, result[0].MCPBareName)
+	// Title/Description are tool-identity metadata (name-equivalent): they stay
+	// visible to non-requesters, matching redactToolCalls on the live path so
+	// the call renders identically live and after reload.
+	assert.Equal(t, "Get Issue", result[0].Title)
+	assert.Equal(t, "Get a Jira issue", result[0].Description)
+	assert.Equal(t, "jira__get_issue", result[0].Name)
 	assert.NotNil(t, blocks[0].Input, "original block must not be mutated")
 	assert.Equal(t, "get_issue", blocks[0].MCPBareName, "original block must not be mutated")
 }
@@ -331,3 +355,43 @@ func TestFilterForNonRequesterDoesNotMutateOriginal(t *testing.T) {
 	assert.Equal(t, originalInputCopy, original[0].Input)
 	assert.Equal(t, originalContentCopy, original[1].Content)
 }
+
+func TestSanitizeForDisplaySanitizesTitleAndDescription(t *testing.T) {
+	// U+202E (right-to-left override) is a classic bidi spoofing character.
+	blocks := []ContentBlock{{
+		Type:        BlockTypeToolUse,
+		ID:          "tc1",
+		Name:        "jira__get_issue",
+		Title:       "Get\u202eIssue",
+		Description: "Get\u202ean issue",
+		Input:       json.RawMessage("{\"key\":\"MM\u202e-1\"}"),
+		Status:      StatusPending,
+	}}
+
+	result := SanitizeForDisplay(blocks)
+
+	require.Len(t, result, 1)
+	assert.Equal(t, "Get[U+202E]Issue", result[0].Title)
+	assert.Equal(t, "Get[U+202E]an issue", result[0].Description)
+	assert.Contains(t, string(result[0].Input), "[U+202E]")
+
+	// Original is not mutated.
+	assert.Equal(t, "Get\u202eIssue", blocks[0].Title)
+	assert.Equal(t, "Get\u202ean issue", blocks[0].Description)
+}
+
+func TestSanitizeForDisplayLeavesCleanTitleAndDescription(t *testing.T) {
+	blocks := []ContentBlock{{
+		Type:        BlockTypeToolUse,
+		ID:          "tc1",
+		Name:        "jira__get_issue",
+		Title:       "Get Issue",
+		Description: "Get a Jira issue",
+	}}
+
+	result := SanitizeForDisplay(blocks)
+
+	require.Len(t, result, 1)
+	assert.Equal(t, "Get Issue", result[0].Title)
+	assert.Equal(t, "Get a Jira issue", result[0].Description)
+}

conversation/convert.go

@@ -87,6 +87,8 @@ func BlocksToPost(
 				Arguments:    arguments,
 				MCPBareName:  block.MCPBareName,
 				Status:       StatusFromString(block.Status),
+				Title:        block.Title,
+				Description:  block.Description,
 			}
 			if redactToolUse {
 				toolCall.MCPBareName = ""
@@ -268,6 +270,8 @@ func PostToBlocks(post llm.Post, shared bool) []ContentBlock {
 			MCPBareName:  tc.MCPBareName,
 			Status:       StatusToString(tc.Status),
 			Shared:       BoolPtr(shared),
+			Title:        tc.Title,
+			Description:  tc.Description,
 		})
 
 		if tc.Result != "" {

conversation/convert_test.go

@@ -231,7 +231,6 @@ func TestBlocksToPost_RedactUnshared(t *testing.T) {
 		assert.JSONEq(t, `{}`, args["t-nilshared"])
 		for _, tc := range got.ToolUse {
 			if tc.ID == "t-private" {
-				assert.Nil(t, tc.Schema)
 				assert.Empty(t, tc.MCPBareName)
 				assert.Empty(t, tc.Description)
 			}
@@ -246,16 +245,11 @@ func TestPostToBlocksPreservesToolIdentityMetadata(t *testing.T) {
 			ID:           "tc1",
 			Name:         "jira__get_issue",
 			Description:  "Get a Jira issue",
+			Title:        "Get Issue",
 			ServerOrigin: "https://jira.example.com",
 			Arguments:    json.RawMessage(`{"key":"MM-1"}`),
-			Schema: map[string]any{
-				"type": "object",
-				"properties": map[string]any{
-					"key": map[string]any{"type": "string"},
-				},
-			},
-			MCPBareName: "get_issue",
-			Status:      llm.ToolCallStatusPending,
+			MCPBareName:  "get_issue",
+			Status:       llm.ToolCallStatusPending,
 		}},
 	}
 
@@ -266,11 +260,13 @@ func TestPostToBlocksPreservesToolIdentityMetadata(t *testing.T) {
 	assert.Equal(t, "jira__get_issue", blocks[0].Name)
 	assert.Equal(t, "https://jira.example.com", blocks[0].ServerOrigin)
 	assert.Equal(t, "get_issue", blocks[0].MCPBareName)
+	assert.Equal(t, "Get Issue", blocks[0].Title)
+	assert.Equal(t, "Get a Jira issue", blocks[0].Description)
 
 	data, err := json.Marshal(blocks[0])
 	require.NoError(t, err)
 	assert.NotContains(t, string(data), "input_schema")
-	assert.NotContains(t, string(data), "tool_description")
+	assert.NotContains(t, string(data), "\"schema\"")
 }
 
 func TestBlocksToPostRehydratesToolCatalogMetadata(t *testing.T) {
@@ -290,6 +286,7 @@ func TestBlocksToPostRehydratesToolCatalogMetadata(t *testing.T) {
 	toolStore.AddTools([]llm.Tool{{
 		Name:         "jira__get_issue",
 		Description:  "Get a Jira issue",
+		Title:        "Get Issue",
 		Schema:       schema,
 		ServerOrigin: "https://jira.example.com",
 	}})
@@ -303,8 +300,7 @@ func TestBlocksToPostRehydratesToolCatalogMetadata(t *testing.T) {
 	assert.Equal(t, "https://jira.example.com", toolCall.ServerOrigin)
 	assert.Equal(t, "get_issue", toolCall.MCPBareName)
 	assert.Equal(t, "Get a Jira issue", toolCall.Description)
-	require.IsType(t, json.RawMessage{}, toolCall.Schema)
-	assert.JSONEq(t, `{"type":"object","properties":{"key":{"type":"string"}}}`, string(toolCall.Schema.(json.RawMessage)))
+	assert.Equal(t, "Get Issue", toolCall.Title)
 }
 
 func TestPostToBlocks(t *testing.T) {

conversation/helpers.go

@@ -112,6 +112,8 @@ func toolUseBlocks(
 			Status:          StatusToString(tc.Status),
 			Shared:          BoolPtr(shared),
 			UserInteraction: tc.UserInteraction,
+			Title:           tc.Title,
+			Description:     tc.Description,
 		})
 	}
 

conversation/helpers_test.go

@@ -65,9 +65,9 @@ func TestToolUseBlocksPreservesApprovalMetadata(t *testing.T) {
 		ID:           "tc1",
 		Name:         "jira__get_issue",
 		Description:  "Get a Jira issue",
+		Title:        "Get Issue",
 		ServerOrigin: "https://jira.example.com",
 		Arguments:    json.RawMessage(`{"key":"MM-1"}`),
-		Schema:       json.RawMessage(`{"type":"object"}`),
 		MCPBareName:  "get_issue",
 		Status:       llm.ToolCallStatusPending,
 	}}, false)
@@ -77,6 +77,8 @@ func TestToolUseBlocksPreservesApprovalMetadata(t *testing.T) {
 	assert.Equal(t, "jira__get_issue", blocks[0].Name)
 	assert.Equal(t, "https://jira.example.com", blocks[0].ServerOrigin)
 	assert.Equal(t, "get_issue", blocks[0].MCPBareName)
+	assert.Equal(t, "Get Issue", blocks[0].Title)
+	assert.Equal(t, "Get a Jira issue", blocks[0].Description)
 }
 
 func TestUnmarshalBlocks(t *testing.T) {

llm/tools.go

@@ -33,6 +33,20 @@ type Tool struct {
 	Schema      any
 	Resolver    ToolResolver
 
+	// Title is an optional human-readable display name supplied by an MCP
+	// server (see the MCP spec's display-name precedence: title >
+	// annotations.title > name). Empty for built-in tools and for MCP tools
+	// that do not declare one. Captured from MCP metadata in
+	// mcp/user_clients.go GetTools and Unicode-sanitized at capture.
+	Title string
+
+	// Annotations carries optional MCP tool annotations. Captured from MCP
+	// metadata but not consumed yet: the safety hints are display-only trust
+	// signals that are intentionally not surfaced in this pass (the MCP spec
+	// warns clients not to trust annotations from untrusted servers). Nil for
+	// built-in tools and MCP tools that declare none.
+	Annotations *ToolAnnotations
+
 	// ServerOrigin identifies the MCP server this tool came from (the BaseURL).
 	// Empty for built-in (non-MCP) tools. Used for auto-approval decisions.
 	ServerOrigin string
@@ -50,6 +64,21 @@ type Tool struct {
 	CallMetadata map[string]any
 }
 
+// ToolAnnotations mirrors the subset of the MCP SDK's mcp.ToolAnnotations that
+// this plugin captures. All fields are hints supplied by the MCP server and are
+// NOT trusted for security decisions (per the MCP spec). Title participates in
+// display-name resolution; the safety hints are captured for future use but not
+// displayed in this pass.
+type ToolAnnotations struct {
+	// Title is a human-readable display name (lower precedence than Tool.Title).
+	Title string
+	// ReadOnlyHint indicates the tool does not modify its environment.
+	ReadOnlyHint bool
+	// DestructiveHint indicates the tool may perform destructive updates.
+	// A nil pointer means the server did not declare the hint.
+	DestructiveHint *bool
+}
+
 // UserInteractionSelect identifies tools answered by the user picking from a
 // set of options presented in the Mattermost UI.
 const UserInteractionSelect = "select"
@@ -244,11 +273,18 @@ type ToolCall struct {
 	Name        string          `json:"name"`
 	Description string          `json:"description"`
 	Arguments   json.RawMessage `json:"arguments"`
-	Schema      any             `json:"schema,omitempty"`
 	Result      string          `json:"result"`
 	Status      ToolCallStatus  `json:"status"`
 	MCPBareName string          `json:"mcp_bare_name,omitempty"`
 
+	// Title is the resolved human-readable display name for MCP tools that
+	// declare one (precedence: Tool.Title > Tool.Annotations.Title >
+	// prettified bare name, resolved at capture). Empty for built-in tools and
+	// MCP tools without a declared title; the webapp then prettifies the bare
+	// name. Carried on both the live (websocket) and persisted paths, and left
+	// visible to non-requesters (name-equivalent).
+	Title string `json:"title,omitempty"`
+
 	// UserInteraction mirrors Tool.UserInteraction so the webapp can render
 	// the matching interaction UI (e.g. a question card) for pending calls.
 	UserInteraction string `json:"user_interaction,omitempty"`
@@ -437,9 +473,11 @@ type EnrichToolCallOptions struct {
 	BareNameFallback bool
 }
 
-// EnrichToolCall fills a tool call's Description, Schema, ServerOrigin, and
+// EnrichToolCall fills a tool call's Description, Title, ServerOrigin, and
 // MCPBareName from the resolved store entry. MCPBareName is only set for MCP
-// tools (those with a server origin); builtins are left untouched.
+// tools (those with a server origin); builtins are left untouched. Title and
+// Description follow the same overwrite semantics: rehydration trusts the store
+// (OverwriteDescription), approval preserves any value already present.
 func EnrichToolCall(tc *ToolCall, store *ToolStore, opts EnrichToolCallOptions) {
 	if tc == nil || store == nil {
 		return
@@ -455,7 +493,9 @@ func EnrichToolCall(tc *ToolCall, store *ToolStore, opts EnrichToolCallOptions)
 	if opts.OverwriteDescription || tc.Description == "" {
 		tc.Description = tool.Description
 	}
-	tc.Schema = tool.Schema
+	if opts.OverwriteDescription || tc.Title == "" {
+		tc.Title = tool.Title
+	}
 	tc.UserInteraction = tool.UserInteraction
 	if tc.ServerOrigin == "" {
 		tc.ServerOrigin = lookup.ServerOrigin