Platform for stateful agents: AI with advanced memory that can learn and self-improve over time.
feat: generate strict-compatible schema for MCP tools with optional fields
jnjpnga5e84cc80b3f
diff --git a/letta/functions/schema_generator.py b/letta/functions/schema_generator.pyindex 6d0507496..c6d579bf0 100644--- a/letta/functions/schema_generator.py+++ b/letta/functions/schema_generator.py@@ -608,27 +608,58 @@ def generate_tool_schema_for_mcp(# Normalise so downstream code can treat it consistently.parameters_schema.setdefault("required", [])- # Process properties to handle anyOf types+ # Process properties to handle anyOf types and make optional fields strict-compatibleif "properties" in parameters_schema:for field_name, field_props in parameters_schema["properties"].items():# Handle anyOf types by flattening to type arrayif "anyOf" in field_props and "type" not in field_props:types = []+ format_value = Nonefor option in field_props["anyOf"]:if "type" in option:types.append(option["type"])+ # Capture format if present (e.g., uuid format for strings)+ if "format" in option and not format_value:+ format_value = option["format"]if types:- field_props["type"] = types+ # Deduplicate types using set+ field_props["type"] = list(set(types))+ # Only add format if the field is not optional (doesn't have null type)+ if format_value and len(field_props["type"]) == 1 and "null" not in field_props["type"]:+ field_props["format"] = format_value# Remove the anyOf since we've flattened itdel field_props["anyOf"]+ # For strict mode: heal optional fields by making them required with null type+ if strict and field_name not in parameters_schema["required"]:+ # Field is optional - add it to required array+ parameters_schema["required"].append(field_name)++ # Ensure the field can accept null to maintain optionality+ if "type" in field_props:+ if isinstance(field_props["type"], list):+ # Already an array of types - add null if not present+ if "null" not in field_props["type"]:+ field_props["type"].append("null")+ # Deduplicate+ field_props["type"] = list(set(field_props["type"]))+ elif field_props["type"] != "null":+ # Single type - convert to array with null+ field_props["type"] = list(set([field_props["type"], "null"]))+ elif "anyOf" in field_props:+ # If there's still an anyOf, ensure null is one of the options+ has_null = any(opt.get("type") == "null" for opt in field_props["anyOf"])+ if not has_null:+ field_props["anyOf"].append({"type": "null"})+# Add the optional heartbeat parameterif append_heartbeat:parameters_schema["properties"][REQUEST_HEARTBEAT_PARAM] = {"type": "boolean","description": REQUEST_HEARTBEAT_DESCRIPTION,}- parameters_schema["required"].append(REQUEST_HEARTBEAT_PARAM)+ if REQUEST_HEARTBEAT_PARAM not in parameters_schema["required"]:+ parameters_schema["required"].append(REQUEST_HEARTBEAT_PARAM)# Return the final schemaif strict:diff --git a/letta/functions/schema_validator.py b/letta/functions/schema_validator.pyindex 5a78230ad..dd99fd047 100644--- a/letta/functions/schema_validator.py+++ b/letta/functions/schema_validator.py@@ -116,22 +116,20 @@ def validate_complete_json_schema(schema: Dict[str, Any]) -> Tuple[SchemaHealth,required = node.get("required")if required is None:+ # TODO: @jnjpng skip this check for now, seems like OpenAI strict mode doesn't enforce this# Only mark as non-strict for nested objects, not root- if not is_root:- mark_non_strict(f"{path}: 'required' not specified for object")+ # if not is_root:+ # mark_non_strict(f"{path}: 'required' not specified for object")required = []elif not isinstance(required, list):mark_invalid(f"{path}: 'required' must be a list if present")required = []# OpenAI strict-mode extra checks:- # Check that all properties are in required array (applies to all levels)- if props:- for prop_name in props.keys():- if prop_name not in required:- mark_non_strict(- f"{path}: property '{prop_name}' is not in required array (OpenAI strict mode requires all properties to be required)"- )+ # NOTE: We no longer flag properties not in required array as non-strict+ # because we can heal these schemas by adding null to the type union+ # This allows MCP tools with optional fields to be used with strict mode+ # The healing happens in generate_tool_schema_for_mcp() when strict=Truefor req_key in required:if props and req_key not in props:@@ -169,6 +167,15 @@ def validate_complete_json_schema(schema: Dict[str, Any]) -> Tuple[SchemaHealth,# These are generally fine, but check for specific constraintspass+ # TYPE ARRAYS (e.g., ["string", "null"] for optional fields)+ elif isinstance(node_type, list):+ # Type arrays are allowed in OpenAI strict mode+ # They represent union types (e.g., string | null)+ for t in node_type:+ # TODO: @jnjpng handle enum types?+ if t not in ["string", "number", "integer", "boolean", "null", "array", "object"]:+ mark_invalid(f"{path}: Invalid type '{t}' in type array")+# UNION TYPESfor kw in ("anyOf", "oneOf", "allOf"):if kw in node:diff --git a/tests/mcp_tests/test_mcp_schema_validation.py b/tests/mcp_tests/test_mcp_schema_validation.pyindex 46976f256..b87d1114e 100644--- a/tests/mcp_tests/test_mcp_schema_validation.py+++ b/tests/mcp_tests/test_mcp_schema_validation.py@@ -7,6 +7,7 @@ from unittest.mock import AsyncMock, MagicMock, patchimport pytestfrom letta.functions.mcp_client.types import MCPTool, MCPToolHealth+from letta.functions.schema_generator import generate_tool_schema_for_mcpfrom letta.functions.schema_validator import SchemaHealth, validate_complete_json_schema@@ -185,3 +186,271 @@ async def test_add_mcp_tool_rejects_invalid_schemas():assert exc_info.value.status_code == 400assert "invalid schema" in exc_info.value.detail["message"].lower()assert exc_info.value.detail["health_status"] == SchemaHealth.INVALID.value+++def test_mcp_schema_healing_for_optional_fields():+ """Test that optional fields in MCP schemas are healed only in strict mode."""+ # Create an MCP tool with optional field 'b'+ mcp_tool = MCPTool(+ name="test_tool",+ description="A test tool",+ inputSchema={+ "type": "object",+ "properties": {+ "a": {"type": "integer", "description": "Required field"},+ "b": {"type": "integer", "description": "Optional field"},+ },+ "required": ["a"], # Only 'a' is required+ "additionalProperties": False,+ },+ )++ # Generate schema without strict mode - should NOT heal optional fields+ non_strict_schema = generate_tool_schema_for_mcp(mcp_tool, append_heartbeat=False, strict=False)+ assert "a" in non_strict_schema["parameters"]["required"]+ assert "b" not in non_strict_schema["parameters"]["required"] # Should remain optional+ assert non_strict_schema["parameters"]["properties"]["b"]["type"] == "integer" # No null added++ # Validate non-strict schema - should still be STRICT_COMPLIANT because validator is relaxed+ status, _ = validate_complete_json_schema(non_strict_schema["parameters"])+ assert status == SchemaHealth.STRICT_COMPLIANT++ # Generate schema with strict mode - should heal optional fields+ strict_schema = generate_tool_schema_for_mcp(mcp_tool, append_heartbeat=False, strict=True)+ assert strict_schema["strict"] is True+ assert "a" in strict_schema["parameters"]["required"]+ assert "b" in strict_schema["parameters"]["required"] # Now required+ assert set(strict_schema["parameters"]["properties"]["b"]["type"]) == {"integer", "null"} # Now accepts null++ # Validate strict schema+ status, _ = validate_complete_json_schema(strict_schema["parameters"])+ assert status == SchemaHealth.STRICT_COMPLIANT # Should pass strict mode+++def test_mcp_schema_healing_with_anyof():+ """Test schema healing for fields with anyOf that include optional types."""+ mcp_tool = MCPTool(+ name="test_tool",+ description="A test tool",+ inputSchema={+ "type": "object",+ "properties": {+ "a": {"type": "string", "description": "Required field"},+ "b": {+ "anyOf": [{"type": "integer"}, {"type": "null"}],+ "description": "Optional field with anyOf",+ },+ },+ "required": ["a"], # Only 'a' is required+ "additionalProperties": False,+ },+ )++ # Generate strict schema+ strict_schema = generate_tool_schema_for_mcp(mcp_tool, append_heartbeat=False, strict=True)+ assert strict_schema["strict"] is True+ assert "a" in strict_schema["parameters"]["required"]+ assert "b" in strict_schema["parameters"]["required"] # Now required+ # Type should be flattened array with deduplication+ assert set(strict_schema["parameters"]["properties"]["b"]["type"]) == {"integer", "null"}++ # Validate strict schema+ status, _ = validate_complete_json_schema(strict_schema["parameters"])+ assert status == SchemaHealth.STRICT_COMPLIANT+++def test_mcp_schema_type_deduplication():+ """Test that duplicate types are deduplicated in schema generation."""+ mcp_tool = MCPTool(+ name="test_tool",+ description="A test tool",+ inputSchema={+ "type": "object",+ "properties": {+ "field": {+ "anyOf": [+ {"type": "string"},+ {"type": "string"}, # Duplicate+ {"type": "null"},+ ],+ "description": "Field with duplicate types",+ },+ },+ "required": [],+ "additionalProperties": False,+ },+ )++ # Generate strict schema+ strict_schema = generate_tool_schema_for_mcp(mcp_tool, append_heartbeat=False, strict=True)++ # Check that duplicates were removed+ field_types = strict_schema["parameters"]["properties"]["field"]["type"]+ assert len(field_types) == len(set(field_types)) # No duplicates+ assert set(field_types) == {"string", "null"}+++def test_mcp_schema_healing_preserves_existing_null():+ """Test that schema healing doesn't add duplicate null when it already exists."""+ mcp_tool = MCPTool(+ name="test_tool",+ description="A test tool",+ inputSchema={+ "type": "object",+ "properties": {+ "field": {+ "type": ["string", "null"], # Already has null+ "description": "Field that already accepts null",+ },+ },+ "required": [], # Optional+ "additionalProperties": False,+ },+ )++ # Generate strict schema+ strict_schema = generate_tool_schema_for_mcp(mcp_tool, append_heartbeat=False, strict=True)++ # Check that null wasn't duplicated+ field_types = strict_schema["parameters"]["properties"]["field"]["type"]+ null_count = field_types.count("null")+ assert null_count == 1 # Should only have one null+++def test_mcp_schema_healing_all_fields_already_required():+ """Test that schema healing works correctly when all fields are already required."""+ mcp_tool = MCPTool(+ name="test_tool",+ description="A test tool",+ inputSchema={+ "type": "object",+ "properties": {+ "a": {"type": "string", "description": "Field A"},+ "b": {"type": "integer", "description": "Field B"},+ },+ "required": ["a", "b"], # All fields already required+ "additionalProperties": False,+ },+ )++ # Generate strict schema+ strict_schema = generate_tool_schema_for_mcp(mcp_tool, append_heartbeat=False, strict=True)++ # Check that fields remain as-is+ assert set(strict_schema["parameters"]["required"]) == {"a", "b"}+ assert strict_schema["parameters"]["properties"]["a"]["type"] == "string"+ assert strict_schema["parameters"]["properties"]["b"]["type"] == "integer"++ # Should be strict compliant+ status, _ = validate_complete_json_schema(strict_schema["parameters"])+ assert status == SchemaHealth.STRICT_COMPLIANT+++def test_mcp_schema_with_uuid_format():+ """Test handling of UUID format in anyOf schemas (root cause of duplicate string types)."""+ mcp_tool = MCPTool(+ name="test_tool",+ description="A test tool with UUID formatted field",+ inputSchema={+ "type": "object",+ "properties": {+ "session_id": {+ "anyOf": [{"type": "string"}, {"format": "uuid", "type": "string"}, {"type": "null"}],+ "description": "Session ID that can be a string, UUID, or null",+ },+ },+ "required": [],+ "additionalProperties": False,+ },+ )++ # Generate strict schema+ strict_schema = generate_tool_schema_for_mcp(mcp_tool, append_heartbeat=False, strict=True)++ # Check that string type is not duplicated+ session_props = strict_schema["parameters"]["properties"]["session_id"]+ assert set(session_props["type"]) == {"string", "null"} # No duplicate strings+ # Format should NOT be preserved because field is optional (has null type)+ assert "format" not in session_props++ # Should be in required array (healed)+ assert "session_id" in strict_schema["parameters"]["required"]++ # Should be strict compliant+ status, _ = validate_complete_json_schema(strict_schema["parameters"])+ assert status == SchemaHealth.STRICT_COMPLIANT+++def test_mcp_schema_healing_only_in_strict_mode():+ """Test that schema healing only happens in strict mode."""+ mcp_tool = MCPTool(+ name="test_tool",+ description="Test that healing only happens in strict mode",+ inputSchema={+ "type": "object",+ "properties": {+ "required_field": {"type": "string", "description": "Already required"},+ "optional_field1": {"type": "integer", "description": "Optional 1"},+ "optional_field2": {"type": "boolean", "description": "Optional 2"},+ },+ "required": ["required_field"],+ "additionalProperties": False,+ },+ )++ # Test with strict=False - no healing+ non_strict = generate_tool_schema_for_mcp(mcp_tool, append_heartbeat=False, strict=False)+ assert "strict" not in non_strict # strict flag not set+ assert non_strict["parameters"]["required"] == ["required_field"] # Only originally required field+ assert non_strict["parameters"]["properties"]["required_field"]["type"] == "string"+ assert non_strict["parameters"]["properties"]["optional_field1"]["type"] == "integer" # No null+ assert non_strict["parameters"]["properties"]["optional_field2"]["type"] == "boolean" # No null++ # Test with strict=True - healing happens+ strict = generate_tool_schema_for_mcp(mcp_tool, append_heartbeat=False, strict=True)+ assert strict["strict"] is True # strict flag is set+ assert set(strict["parameters"]["required"]) == {"required_field", "optional_field1", "optional_field2"}+ assert strict["parameters"]["properties"]["required_field"]["type"] == "string"+ assert set(strict["parameters"]["properties"]["optional_field1"]["type"]) == {"integer", "null"}+ assert set(strict["parameters"]["properties"]["optional_field2"]["type"]) == {"boolean", "null"}++ # Both should be strict compliant (validator is relaxed)+ status1, _ = validate_complete_json_schema(non_strict["parameters"])+ status2, _ = validate_complete_json_schema(strict["parameters"])+ assert status1 == SchemaHealth.STRICT_COMPLIANT+ assert status2 == SchemaHealth.STRICT_COMPLIANT+++def test_mcp_schema_with_uuid_format_required_field():+ """Test that UUID format is preserved for required fields that don't have null type."""+ mcp_tool = MCPTool(+ name="test_tool",+ description="A test tool with required UUID formatted field",+ inputSchema={+ "type": "object",+ "properties": {+ "session_id": {+ "anyOf": [{"type": "string"}, {"format": "uuid", "type": "string"}],+ "description": "Session ID that must be a string with UUID format",+ },+ },+ "required": ["session_id"], # Required field+ "additionalProperties": False,+ },+ )++ # Generate strict schema+ strict_schema = generate_tool_schema_for_mcp(mcp_tool, append_heartbeat=False, strict=True)++ # Check that string type is not duplicated and format IS preserved+ session_props = strict_schema["parameters"]["properties"]["session_id"]+ assert session_props["type"] == ["string"] # No null, no duplicates+ assert "format" in session_props+ assert session_props["format"] == "uuid" # Format should be preserved for non-optional field++ # Should be in required array+ assert "session_id" in strict_schema["parameters"]["required"]++ # Should be strict compliant+ status, _ = validate_complete_json_schema(strict_schema["parameters"])+ assert status == SchemaHealth.STRICT_COMPLIANTdiff --git a/tests/mcp_tests/test_schema_validator.py b/tests/mcp_tests/test_schema_validator.pyindex 0d675e0bf..b753267bd 100644--- a/tests/mcp_tests/test_schema_validator.py+++ b/tests/mcp_tests/test_schema_validator.py@@ -236,21 +236,21 @@ class TestSchemaValidator:assert any("dict" in reason for reason in reasons)def test_schema_with_defaults_non_strict(self):- """Test that root-level schemas without required field are NON_STRICT_ONLY."""+ """Test that root-level schemas without required field are STRICT_COMPLIANT (validator is relaxed)."""schema = {"type": "object","properties": {"name": {"type": "string"}, "optional": {"type": "string"}},- # Missing "required" field at root level - all properties must be required for strict mode+ # Missing "required" field at root level - validator now accepts this"additionalProperties": False,}status, reasons = validate_complete_json_schema(schema)- # Root level without all properties required should be NON_STRICT_ONLY- assert status == SchemaHealth.NON_STRICT_ONLY- assert any("not in required array" in reason for reason in reasons)+ # Validator is relaxed - schemas with optional fields are now STRICT_COMPLIANT+ assert status == SchemaHealth.STRICT_COMPLIANT+ assert reasons == []def test_composio_schema_with_optional_root_properties_non_strict(self):- """Test that Composio-like schemas with optional root properties are NON_STRICT_ONLY."""+ """Test that Composio-like schemas with optional root properties are STRICT_COMPLIANT (validator is relaxed)."""schema = {"type": "object","properties": {@@ -264,28 +264,28 @@ class TestSchemaValidator:}status, reasons = validate_complete_json_schema(schema)- assert status == SchemaHealth.NON_STRICT_ONLY- assert any("not in required array" in reason for reason in reasons)+ assert status == SchemaHealth.STRICT_COMPLIANT+ assert reasons == []def test_root_level_without_required_non_strict(self):- """Test that root-level objects without 'required' field are NON_STRICT_ONLY."""+ """Test that root-level objects without 'required' field are STRICT_COMPLIANT (validator is relaxed)."""schema = {"type": "object","properties": {"name": {"type": "string"},"age": {"type": "integer"},},- # No "required" field at root level - all properties must be required for strict mode+ # No "required" field at root level - validator now accepts this"additionalProperties": False,}status, reasons = validate_complete_json_schema(schema)- # Root level without required should be NON_STRICT_ONLY- assert status == SchemaHealth.NON_STRICT_ONLY- assert any("not in required array" in reason for reason in reasons)+ # Validator is relaxed - accepts schemas without required field+ assert status == SchemaHealth.STRICT_COMPLIANT+ assert reasons == []def test_nested_object_without_required_non_strict(self):- """Test that nested objects without 'required' remain NON_STRICT_ONLY."""+ """Test that nested objects without 'required' are STRICT_COMPLIANT (validator is relaxed)."""schema = {"type": "object","properties": {@@ -309,12 +309,11 @@ class TestSchemaValidator:}status, reasons = validate_complete_json_schema(schema)- assert status == SchemaHealth.NON_STRICT_ONLY- # Should have warning about nested preferences object missing 'required'- assert any("required" in reason and "preferences" in reason for reason in reasons)+ assert status == SchemaHealth.STRICT_COMPLIANT+ assert reasons == []def test_user_example_schema_non_strict(self):- """Test the user's example schema with optional properties - should be NON_STRICT_ONLY."""+ """Test the user's example schema with optional properties - now STRICT_COMPLIANT (validator is relaxed)."""schema = {"type": "object","properties": {@@ -326,8 +325,8 @@ class TestSchemaValidator:}status, reasons = validate_complete_json_schema(schema)- assert status == SchemaHealth.NON_STRICT_ONLY- assert any("property 'b' is not in required array" in reason for reason in reasons)+ assert status == SchemaHealth.STRICT_COMPLIANT+ assert reasons == []def test_all_properties_required_strict_compliant(self):"""Test that schemas with all properties required are STRICT_COMPLIANT."""diff --git a/tests/test_schema_validator.py b/tests/test_schema_validator.pyindex b3ee314ed..ffa52039b 100644--- a/tests/test_schema_validator.py+++ b/tests/test_schema_validator.py@@ -5,8 +5,8 @@ Test schema validation for OpenAI strict mode compliance.from letta.functions.schema_validator import SchemaHealth, validate_complete_json_schema-def test_user_example_schema_not_strict():- """Test the user's provided example schema is correctly marked as NON_STRICT_ONLY."""+def test_user_example_schema_now_strict():+ """Test that schemas with optional fields are now considered STRICT_COMPLIANT (will be healed)."""schema = {"properties": {"a": {"title": "A", "type": "integer"},@@ -23,11 +23,9 @@ def test_user_example_schema_not_strict():status, reasons = validate_complete_json_schema(schema)- # Should be NON_STRICT_ONLY because not all properties are required- assert status == SchemaHealth.NON_STRICT_ONLY- assert len(reasons) > 0- # Check that the reason mentions property 'b' not being required- assert any("property 'b' is not in required array" in reason for reason in reasons)+ # Should now be STRICT_COMPLIANT because we can heal optional fields+ assert status == SchemaHealth.STRICT_COMPLIANT+ assert reasons == []def test_all_properties_required_is_strict():@@ -49,8 +47,8 @@ def test_all_properties_required_is_strict():assert reasons == []-def test_nested_object_missing_required_not_strict():- """Test that nested objects with missing required properties are NON_STRICT_ONLY."""+def test_nested_object_missing_required_now_strict():+ """Test that nested objects with optional fields are now STRICT_COMPLIANT (will be healed)."""schema = {"type": "object","properties": {@@ -71,10 +69,9 @@ def test_nested_object_missing_required_not_strict():status, reasons = validate_complete_json_schema(schema)- # Should be NON_STRICT_ONLY because nested object doesn't require all properties- assert status == SchemaHealth.NON_STRICT_ONLY- assert len(reasons) > 0- assert any("optional_field" in reason and "not in required array" in reason for reason in reasons)+ # Should now be STRICT_COMPLIANT because we can heal optional fields+ assert status == SchemaHealth.STRICT_COMPLIANT+ assert reasons == []def test_nested_object_all_required_is_strict():@@ -190,27 +187,24 @@ def test_complex_schema_with_arrays():assert reasons == []-def test_fastmcp_tool_schema_not_strict():- """Test that a schema from FastMCP with optional field 'b' is marked as NON_STRICT_ONLY."""+def test_fastmcp_tool_schema_now_strict():+ """Test that a schema from FastMCP with optional field 'b' is now STRICT_COMPLIANT."""# This is the exact schema format provided by the userschema = {"properties": {"a": {"title": "A", "type": "integer"},"b": {"anyOf": [{"type": "integer"}, {"type": "null"}], "default": None, "title": "B"},},- "required": ["a"], # Only 'a' is required, violates strict mode requirement+ "required": ["a"], # Only 'a' is required, but we can heal this"type": "object","additionalProperties": False,}status, reasons = validate_complete_json_schema(schema)- # Should be NON_STRICT_ONLY because 'b' is not in the required array- # Even though 'b' accepts null (making it optional), OpenAI strict mode- # requires ALL properties to be in the required array- assert status == SchemaHealth.NON_STRICT_ONLY- assert len(reasons) > 0- assert any("property 'b' is not in required array" in reason for reason in reasons)+ # Should now be STRICT_COMPLIANT because we can heal optional fields+ assert status == SchemaHealth.STRICT_COMPLIANT+ assert reasons == []def test_union_types_with_anyof():@@ -235,3 +229,50 @@ def test_union_types_with_anyof():# Should be STRICT_COMPLIANT - anyOf is allowed and all properties are requiredassert status == SchemaHealth.STRICT_COMPLIANTassert reasons == []+++def test_healed_schema_with_type_array():+ """Test that healed schemas with type arrays including null are STRICT_COMPLIANT."""+ # This represents a schema that has been healed by adding null to optional fields+ schema = {+ "type": "object",+ "properties": {+ "required_field": {"type": "string"},+ "optional_field": {"type": ["integer", "null"]}, # Healed: was optional, now required with null+ },+ "required": ["required_field", "optional_field"], # All fields now required+ "additionalProperties": False,+ }++ status, reasons = validate_complete_json_schema(schema)++ # Should be STRICT_COMPLIANT since all properties are required+ assert status == SchemaHealth.STRICT_COMPLIANT+ assert reasons == []+++def test_healed_nested_schema():+ """Test that healed nested schemas are STRICT_COMPLIANT."""+ schema = {+ "type": "object",+ "properties": {+ "config": {+ "type": "object",+ "properties": {+ "host": {"type": "string"},+ "port": {"type": ["integer", "null"]}, # Healed optional field+ "timeout": {"type": ["number", "null"]}, # Healed optional field+ },+ "required": ["host", "port", "timeout"], # All fields required after healing+ "additionalProperties": False,+ }+ },+ "required": ["config"],+ "additionalProperties": False,+ }++ status, reasons = validate_complete_json_schema(schema)++ # Should be STRICT_COMPLIANT after healing+ assert status == SchemaHealth.STRICT_COMPLIANT+ assert reasons == []