feat: add tool_description_length_policy to upstream MCP provider config

Adds a new optional field `tool_description_length_policy` on each
`upstream_mcp` provider with values `drop` (default), `truncate`, and
`allow`. Default `drop` preserves existing behaviour. `truncate` keeps
the tool and shortens its description to the 2048-char limit. `allow`
skips the length check entirely, exposing the upstream tool unchanged —
intended for compatibility-preserving proxy deployments where dropping
tools solely due to description length would break existing clients.

The sanitizer is restructured so that the length policy and the HTML
policy are evaluated independently: length is applied first, then the
HTML check runs regardless of which length policy was selected. All
other sanitisation checks (name validation, inputSchema structure, HTML
content) remain active under every length policy value.

Author: David Ruzicka

src/generated-schemas.ts

@@ -360,6 +360,7 @@ export const upstreamMcpServerConfigSchema = z.object({
     tools: upstreamMcpToolPolicySchema.optional(),
     timeout_ms: z.number().optional(),
     html_description_policy: z.enum(['allow', 'strip', 'drop']).optional(),
+    tool_description_length_policy: z.enum(['drop', 'truncate', 'allow']).optional(),
     validation_endpoint: z.string().optional(),
     validation_method: z.union([z.literal("HEAD"), z.literal("GET")]).optional(),
     validation_timeout_ms: z.number().optional()

src/mcp/mcp-server.ts

@@ -1906,7 +1906,7 @@ export class MCPServer {
         );
       }
       const rawTools = result.tools;
-      const sanitized = sanitizeToolList(rawTools, this.logger, provider.html_description_policy ?? 'drop');
+      const sanitized = sanitizeToolList(rawTools, this.logger, provider.html_description_policy ?? 'drop', provider.tool_description_length_policy ?? 'drop');
       const policyFiltered = applyProviderToolPolicy(sanitized.tools, provider.tools);
       // Cache sanitized+policy-filtered tool names for tools/call gate enforcement.
       // Tools dropped here (bad description/inputSchema) must not be callable via tools/call.

src/types/profile.ts

@@ -104,6 +104,14 @@ export interface UpstreamMcpServerConfig {
    */
   html_description_policy?: 'allow' | 'strip' | 'drop';
 
+  /**
+   * Controls how upstream tools with descriptions exceeding the internal length limit are handled.
+   * - drop (default): tools with overlong descriptions are dropped
+   * - truncate: description is truncated to the limit; tool is kept
+   * - allow: description length check is skipped; tool passes through unchanged
+   */
+  tool_description_length_policy?: 'drop' | 'truncate' | 'allow';
+
   /** Optional endpoint to validate upstream credentials at session init (fail-fast). */
   validation_endpoint?: string;
   /** HTTP method for validation probe. Default: 'HEAD'. */

src/upstream/upstream-tool-sanitizer.test.ts

@@ -5,6 +5,7 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import type { Logger } from '../core/logger.js';
 import { sanitizeToolList, applyProviderToolPolicy, isToolAllowedByProviderPolicy, isValidUpstreamToolName } from './upstream-tool-sanitizer.js';
+import type { ToolDescriptionLengthPolicy } from './upstream-tool-sanitizer.js';
 import type { Tool } from '@modelcontextprotocol/sdk/types.js';
 
 function makeTool(name: string, description?: string): Tool {
@@ -503,6 +504,125 @@ describe('sanitizeToolList — html_description_policy', () => {
   });
 });
 
+describe('sanitizeToolList — tool_description_length_policy', () => {
+  const LONG_DESC = 'a'.repeat(2049);
+  const EXACT_DESC = 'a'.repeat(2048);
+  let logger: Logger;
+
+  beforeEach(() => {
+    logger = { debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn() };
+  });
+
+  describe('drop (default)', () => {
+    it('drops tool with description > 2048 chars', () => {
+      const tool = makeTool('t', LONG_DESC);
+      const result = sanitizeToolList([tool], logger, 'drop', 'drop');
+      expect(result.tools).toHaveLength(0);
+      expect(result.dropped[0].reason).toBe('tool description too long');
+    });
+
+    it('passes tool with description exactly 2048 chars', () => {
+      const tool = makeTool('t', EXACT_DESC);
+      const result = sanitizeToolList([tool], logger, 'drop', 'drop');
+      expect(result.tools).toHaveLength(1);
+      expect(result.dropped).toHaveLength(0);
+    });
+  });
+
+  describe('truncate', () => {
+    it('keeps tool and truncates description to 2048 chars', () => {
+      const tool = makeTool('t', LONG_DESC);
+      const result = sanitizeToolList([tool], logger, 'drop', 'truncate');
+      expect(result.tools).toHaveLength(1);
+      expect(result.tools[0].description).toHaveLength(2048);
+      expect(result.tools[0].description).toBe(LONG_DESC.slice(0, 2048));
+      expect(result.dropped).toHaveLength(0);
+      expect(logger.warn).not.toHaveBeenCalled();
+    });
+
+    it('does not mutate original tool object', () => {
+      const tool = makeTool('t', LONG_DESC);
+      sanitizeToolList([tool], logger, 'drop', 'truncate');
+      expect(tool.description).toBe(LONG_DESC);
+    });
+
+    it('passes tool with description exactly 2048 chars unchanged', () => {
+      const tool = makeTool('t', EXACT_DESC);
+      const result = sanitizeToolList([tool], logger, 'drop', 'truncate');
+      expect(result.tools).toHaveLength(1);
+      expect(result.tools[0].description).toHaveLength(2048);
+    });
+
+    it('still drops tool with invalid name regardless of truncate policy', () => {
+      const tool = makeTool('bad name!', LONG_DESC);
+      const result = sanitizeToolList([tool], logger, 'drop', 'truncate');
+      expect(result.tools).toHaveLength(0);
+      expect(result.dropped[0].reason).toBe('invalid characters in tool name');
+    });
+
+    it('still drops tool with malformed inputSchema regardless of truncate policy', () => {
+      const tool = { name: 'valid', description: LONG_DESC, inputSchema: null } as unknown as Tool;
+      const result = sanitizeToolList([tool], logger, 'drop', 'truncate');
+      expect(result.tools).toHaveLength(0);
+      expect(result.dropped[0].reason).toBe('malformed tool definition: inputSchema is not an object');
+    });
+  });
+
+  describe('allow', () => {
+    it('passes tool with overlong description through unchanged', () => {
+      const tool = makeTool('t', LONG_DESC);
+      const result = sanitizeToolList([tool], logger, 'drop', 'allow');
+      expect(result.tools).toHaveLength(1);
+      expect(result.tools[0].description).toBe(LONG_DESC);
+      expect(result.dropped).toHaveLength(0);
+      expect(logger.warn).not.toHaveBeenCalled();
+    });
+
+    it('still drops tool with invalid name regardless of allow policy', () => {
+      const tool = makeTool('bad name!', LONG_DESC);
+      const result = sanitizeToolList([tool], logger, 'drop', 'allow');
+      expect(result.tools).toHaveLength(0);
+      expect(result.dropped[0].reason).toBe('invalid characters in tool name');
+    });
+
+    it('still drops tool with malformed inputSchema regardless of allow policy', () => {
+      const tool = { name: 'valid', description: LONG_DESC, inputSchema: null } as unknown as Tool;
+      const result = sanitizeToolList([tool], logger, 'drop', 'allow');
+      expect(result.tools).toHaveLength(0);
+      expect(result.dropped[0].reason).toBe('malformed tool definition: inputSchema is not an object');
+    });
+  });
+
+  describe('interactions with html_description_policy', () => {
+    it('truncate length + strip html: truncates first then strips HTML from truncated string', () => {
+      // desc = '<b>' + 'a' * 2049 + '</b>' = 2056 chars
+      // truncate to 2048: '<b>' + 'a' * 2045 (first 2048 chars)
+      // then strip HTML: 'a' * 2045
+      const desc = '<b>' + 'a'.repeat(2049) + '</b>';
+      const tool = makeTool('t', desc);
+      const result = sanitizeToolList([tool], logger, 'strip', 'truncate');
+      expect(result.tools).toHaveLength(1);
+      expect(result.tools[0].description).toBe('a'.repeat(2045));
+      expect(result.dropped).toHaveLength(0);
+    });
+
+    it('allow length + drop html: still drops tool with HTML chars in description', () => {
+      const tool = makeTool('t', '<b>' + 'a'.repeat(2049) + '</b>');
+      const result = sanitizeToolList([tool], logger, 'drop', 'allow');
+      expect(result.tools).toHaveLength(0);
+      expect(result.dropped[0].reason).toBe('forbidden characters in description');
+    });
+
+    it('allow length + allow html: passes overlong HTML description through unchanged', () => {
+      const desc = '<b>' + 'a'.repeat(2049) + '</b>';
+      const tool = makeTool('t', desc);
+      const result = sanitizeToolList([tool], logger, 'allow', 'allow');
+      expect(result.tools).toHaveLength(1);
+      expect(result.tools[0].description).toBe(desc);
+    });
+  });
+});
+
 describe('applyProviderToolPolicy', () => {
   const tools = [makeTool('alpha'), makeTool('beta'), makeTool('gamma')];
 

src/upstream/upstream-tool-sanitizer.ts

@@ -19,6 +19,7 @@ import type { Logger } from '../core/logger.js';
 import type { UpstreamMcpToolPolicy } from '../types/profile.js';
 
 export type HtmlDescriptionPolicy = 'allow' | 'strip' | 'drop';
+export type ToolDescriptionLengthPolicy = 'drop' | 'truncate' | 'allow';
 
 export interface SanitizationResult {
   tools: Tool[];
@@ -97,15 +98,23 @@ const truncateName = (name: string): string =>
  * Each tool is checked in order:
  *   1. Name length <= 255
  *   2. Name matches [a-zA-Z0-9_-]
- *   3. Description length <= 2048 (if present)
+ *   3. Description length policy (tool_description_length_policy):
+ *      - drop (default): tools with description > 2048 chars are dropped
+ *      - truncate: description is truncated to 2048 chars; tool is kept
+ *      - allow: description length check is skipped; tool passes through unchanged
  *   4. HTML policy (html_description_policy):
  *      - drop (default): tools with <, >, or backtick in description/inputSchema are dropped
  *      - strip: HTML tags stripped from description and inputSchema string values; tool kept
  *      - allow: HTML checks skipped entirely; tool passes through as-is
  *
  * Offending tools are dropped and logged. Safe tools pass through unchanged.
  */
-export function sanitizeToolList(tools: Tool[], logger?: Logger, htmlPolicy: HtmlDescriptionPolicy = 'drop'): SanitizationResult {
+export function sanitizeToolList(
+  tools: Tool[],
+  logger?: Logger,
+  htmlPolicy: HtmlDescriptionPolicy = 'drop',
+  lengthPolicy: ToolDescriptionLengthPolicy = 'drop',
+): SanitizationResult {
   const safe: Tool[] = [];
   const dropped: { name: string; reason: string }[] = [];
 
@@ -131,28 +140,41 @@ export function sanitizeToolList(tools: Tool[], logger?: Logger, htmlPolicy: Htm
       reason = 'invalid characters in tool name';
     } else if (tool.description !== undefined && typeof tool.description !== 'string') {
       reason = 'malformed tool definition: description is not a string';
-    } else if (tool.description && tool.description.length > MAX_DESCRIPTION_LENGTH) {
-      reason = 'tool description too long';
-    } else if (tool.inputSchema !== undefined && (typeof tool.inputSchema !== 'object' || tool.inputSchema === null || Array.isArray(tool.inputSchema))) {
-      reason = 'malformed tool definition: inputSchema is not an object';
-    } else if (htmlPolicy === 'drop') {
-      if (tool.description && DESCRIPTION_FORBIDDEN_CHARS.test(tool.description)) {
-        reason = 'forbidden characters in description';
-        excerpt = firstForbiddenExcerpt(tool.description);
-      } else if (tool.inputSchema && schemaContainsForbiddenChars(tool.inputSchema)) {
-        reason = 'forbidden characters in input schema';
-        const schemaStr = JSON.stringify(tool.inputSchema);
-        excerpt = firstForbiddenExcerpt(schemaStr);
-      }
-    } else if (htmlPolicy === 'strip') {
-      if (tool.description) {
-        tool = { ...tool, description: stripHtmlTags(tool.description) };
+    } else {
+      // Description length policy: applies only to description length, not to other checks.
+      // Evaluated independently so that 'allow'/'truncate' can still fall through to HTML checks.
+      if (tool.description && tool.description.length > MAX_DESCRIPTION_LENGTH) {
+        if (lengthPolicy === 'drop') {
+          reason = 'tool description too long';
+        } else if (lengthPolicy === 'truncate') {
+          tool = { ...tool, description: tool.description.slice(0, MAX_DESCRIPTION_LENGTH) };
+        }
+        // lengthPolicy === 'allow': skip length check, continue to other checks unchanged
       }
-      if (tool.inputSchema) {
-        tool = { ...tool, inputSchema: stripHtmlFromSchema(tool.inputSchema) as Tool['inputSchema'] };
+
+      if (reason === undefined) {
+        if (tool.inputSchema !== undefined && (typeof tool.inputSchema !== 'object' || tool.inputSchema === null || Array.isArray(tool.inputSchema))) {
+          reason = 'malformed tool definition: inputSchema is not an object';
+        } else if (htmlPolicy === 'drop') {
+          if (tool.description && DESCRIPTION_FORBIDDEN_CHARS.test(tool.description)) {
+            reason = 'forbidden characters in description';
+            excerpt = firstForbiddenExcerpt(tool.description);
+          } else if (tool.inputSchema && schemaContainsForbiddenChars(tool.inputSchema)) {
+            reason = 'forbidden characters in input schema';
+            const schemaStr = JSON.stringify(tool.inputSchema);
+            excerpt = firstForbiddenExcerpt(schemaStr);
+          }
+        } else if (htmlPolicy === 'strip') {
+          if (tool.description) {
+            tool = { ...tool, description: stripHtmlTags(tool.description) };
+          }
+          if (tool.inputSchema) {
+            tool = { ...tool, inputSchema: stripHtmlFromSchema(tool.inputSchema) as Tool['inputSchema'] };
+          }
+        }
+        // htmlPolicy === 'allow': skip all HTML checks, pass tool through unchanged
       }
     }
-    // htmlPolicy === 'allow': skip all HTML checks, pass tool through unchanged
 
     if (reason !== undefined) {
       // Coerce non-string names to string for safe logging