Fix tool schema constraints being silently dropped during OCI conversion

tool.args goes through Pydantic's tool_call_schema re-generation which
strips rich JSON Schema properties (enum, min/max, pattern, format, etc.).
Switch to args_schema.model_json_schema() which preserves the original schema.

GenericProvider: add _sanitize_tool_property() with allowlist of standard
JSON Schema keys, resolves Pydantic v2 anyOf patterns for Optional[T].

CohereProvider: add _enrich_description() to embed constraints (enum,
format, range, pattern) into the description string since
CohereParameterDefinition only supports type/description/is_required.

Author: fede-kamel

libs/oci/langchain_oci/chat_models/providers/cohere.py

@@ -463,6 +463,31 @@ def messages_to_oci_params(
         # Remove keys with None values
         return {k: v for k, v in oci_params.items() if v is not None}
 
+    @staticmethod
+    def _enrich_description(description: str, p_def: Dict[str, Any]) -> str:
+        """Embed schema constraints into the description for Cohere models.
+
+        CohereParameterDefinition only supports type, description, and
+        is_required. Rich schema metadata (enum, format, range, pattern)
+        is embedded into the description string so the LLM can still see
+        and respect these constraints.
+        """
+        parts = [description] if description else []
+        if "enum" in p_def:
+            parts.append(f"Allowed values: {p_def['enum']}")
+        if "format" in p_def:
+            parts.append(f"Format: {p_def['format']}")
+        if "minimum" in p_def or "maximum" in p_def:
+            range_parts = []
+            if "minimum" in p_def:
+                range_parts.append(f"min={p_def['minimum']}")
+            if "maximum" in p_def:
+                range_parts.append(f"max={p_def['maximum']}")
+            parts.append(f"Range: {', '.join(range_parts)}")
+        if "pattern" in p_def:
+            parts.append(f"Pattern: {p_def['pattern']}")
+        return ". ".join(parts) if parts else ""
+
     def convert_to_oci_tool(
         self,
         tool: Union[Dict[str, Any], Type[BaseModel], Callable, BaseTool],
@@ -474,21 +499,31 @@ def convert_to_oci_tool(
         or Pydantic models/callables.
         """
         if isinstance(tool, BaseTool):
+            # Use args_schema.model_json_schema() to get rich properties
+            # (enum, constraints) that tool.args loses via tool_call_schema.
+            if tool.args_schema and hasattr(tool.args_schema, "model_json_schema"):
+                schema = tool.args_schema.model_json_schema()
+                properties = schema.get("properties", {})
+            else:
+                properties = tool.args
+
             return self.oci_tool(
                 name=tool.name,
                 description=OCIUtils.remove_signature_from_tool_description(
                     tool.name, tool.description
                 ),
                 parameter_definitions={
                     p_name: self.oci_tool_param(
-                        description=p_def.get("description", ""),
+                        description=self._enrich_description(
+                            p_def.get("description", ""), p_def
+                        ),
                         type=JSON_TO_PYTHON_TYPES.get(
                             p_def.get("type"),
                             p_def.get("type", "any"),
                         ),
                         is_required="default" not in p_def,
                     )
-                    for p_name, p_def in tool.args.items()
+                    for p_name, p_def in properties.items()
                 },
             )
         elif isinstance(tool, dict):
@@ -502,7 +537,9 @@ def convert_to_oci_tool(
                 description=tool.get("description"),
                 parameter_definitions={
                     p_name: self.oci_tool_param(
-                        description=p_def.get("description", ""),
+                        description=self._enrich_description(
+                            p_def.get("description", ""), p_def
+                        ),
                         type=JSON_TO_PYTHON_TYPES.get(
                             p_def.get("type"),
                             p_def.get("type", "any"),
@@ -524,7 +561,9 @@ def convert_to_oci_tool(
                 ),
                 parameter_definitions={
                     p_name: self.oci_tool_param(
-                        description=p_def.get("description", ""),
+                        description=self._enrich_description(
+                            p_def.get("description", ""), p_def
+                        ),
                         type=JSON_TO_PYTHON_TYPES.get(
                             p_def.get("type"),
                             p_def.get("type", "any"),

libs/oci/langchain_oci/chat_models/providers/generic.py

@@ -378,6 +378,21 @@ def convert_to_oci_tool(
         """
         # Check BaseTool first since it's callable but needs special handling
         if isinstance(tool, BaseTool):
+            # Use args_schema.model_json_schema() if available — it preserves
+            # rich schema metadata (enum, min/max, pattern, etc.) that tool.args
+            # loses via Pydantic re-generation through tool_call_schema.
+            if tool.args_schema and hasattr(tool.args_schema, "model_json_schema"):
+                schema = tool.args_schema.model_json_schema()
+                properties = schema.get("properties", {})
+                required = schema.get("required", [])
+            else:
+                properties = tool.args
+                required = [
+                    p_name
+                    for p_name, p_def in properties.items()
+                    if "default" not in p_def
+                ]
+
             return self.oci_function_definition(
                 name=tool.name,
                 description=OCIUtils.remove_signature_from_tool_description(
@@ -386,17 +401,10 @@ def convert_to_oci_tool(
                 parameters={
                     "type": "object",
                     "properties": {
-                        p_name: {
-                            "type": p_def.get("type", "any"),
-                            "description": p_def.get("description", ""),
-                        }
-                        for p_name, p_def in tool.args.items()
+                        p_name: self._sanitize_tool_property(p_def)
+                        for p_name, p_def in properties.items()
                     },
-                    "required": [
-                        p_name
-                        for p_name, p_def in tool.args.items()
-                        if "default" not in p_def
-                    ],
+                    "required": required,
                 },
             )
         if (isinstance(tool, type) and issubclass(tool, BaseModel)) or callable(tool):
@@ -420,6 +428,89 @@ def convert_to_oci_tool(
             "instance, TypedDict class, or BaseModel type."
         )
 
+    # JSON Schema properties safe to pass through to OCI GenAI API.
+    # OCI's FunctionDefinition.parameters accepts any JSON Schema object.
+    _PASSTHROUGH_KEYS = {
+        "type",
+        "description",
+        "enum",
+        "const",
+        "minimum",
+        "maximum",
+        "exclusiveMinimum",
+        "exclusiveMaximum",
+        "minLength",
+        "maxLength",
+        "pattern",
+        "format",
+        "items",
+        "minItems",
+        "maxItems",
+        "uniqueItems",
+        "properties",
+        "required",
+        "additionalProperties",
+        "default",
+        "examples",
+    }
+
+    @classmethod
+    def _sanitize_tool_property(cls, p_def: Dict[str, Any]) -> Dict[str, Any]:
+        """Sanitize a tool property schema for OCI GenAI API compatibility.
+
+        Preserves JSON-Schema-standard properties (enum, format, min/max,
+        pattern, items, etc.) while resolving Pydantic v2 ``anyOf`` patterns
+        (generated for ``Optional[T]``). Falls back to ``"string"`` for
+        unrecognized schemas.
+
+        Args:
+            p_def: Property definition from tool schema.
+
+        Returns:
+            Sanitized property dict with allowed JSON Schema properties.
+        """
+        allowed = cls._PASSTHROUGH_KEYS
+
+        # Resolve anyOf first (Pydantic v2 Optional[T] pattern)
+        if "anyOf" in p_def and "type" not in p_def:
+            non_null = [
+                t
+                for t in p_def["anyOf"]
+                if not (isinstance(t, dict) and t.get("type") == "null")
+            ]
+            if non_null:
+                resolved = dict(non_null[0])
+            else:
+                resolved = {"type": "string"}
+            # Merge top-level metadata into resolved type
+            for key in allowed:
+                if key in p_def and key not in resolved:
+                    resolved[key] = p_def[key]
+            p_def = resolved
+
+        # Build result with allowed keys only
+        result: Dict[str, Any] = {}
+        for key in allowed:
+            if key in p_def:
+                result[key] = p_def[key]
+
+        # Ensure type and description are always present
+        if "type" not in result:
+            result["type"] = "string"
+        if "description" not in result:
+            result["description"] = ""
+
+        # Recursively sanitize nested items/properties
+        if "items" in result and isinstance(result["items"], dict):
+            result["items"] = cls._sanitize_tool_property(result["items"])
+        if "properties" in result and isinstance(result["properties"], dict):
+            result["properties"] = {
+                k: cls._sanitize_tool_property(v)
+                for k, v in result["properties"].items()
+            }
+
+        return result
+
     def process_tool_choice(
         self,
         tool_choice: Optional[

libs/oci/tests/integration_tests/chat_models/test_tool_schema_constraints.py

@@ -0,0 +1,173 @@
+# Copyright (c) 2026 Oracle and/or its affiliates.
+# Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
+
+"""Integration tests for tool schema constraint preservation.
+
+Verifies that enum, min/max, and other JSON Schema constraints are
+passed through to the model and respected in tool call arguments.
+
+Prerequisites: same as test_tool_calling.py (OCI_COMPARTMENT_ID, auth).
+"""
+
+import os
+from typing import Optional
+
+import pytest
+from langchain_core.messages import AIMessage, HumanMessage, SystemMessage
+from langchain_core.tools import tool
+from pydantic import BaseModel, Field
+
+from langchain_oci.chat_models import ChatOCIGenAI
+
+
+def _create_chat_model(model_id: str) -> ChatOCIGenAI:
+    compartment_id = os.environ.get("OCI_COMPARTMENT_ID")
+    if not compartment_id:
+        pytest.skip("OCI_COMPARTMENT_ID not set")
+
+    region = os.getenv("OCI_REGION", "us-chicago-1")
+    endpoint = f"https://inference.generativeai.{region}.oci.oraclecloud.com"
+    return ChatOCIGenAI(
+        model_id=model_id,
+        service_endpoint=endpoint,
+        compartment_id=compartment_id,
+        model_kwargs={"temperature": 0, "max_tokens": 512},
+        auth_type=os.environ.get("OCI_AUTH_TYPE", "API_KEY"),
+        auth_profile=os.environ.get("OCI_CONFIG_PROFILE", "DEFAULT"),
+        auth_file_location=os.path.expanduser("~/.oci/config"),
+    )
+
+
+class QueryMetricsInput(BaseModel):
+    metric_name: str = Field(
+        description="Infrastructure metric to query",
+        json_schema_extra={"enum": ["cpu", "memory", "disk", "network"]},
+    )
+    duration_hours: int = Field(
+        description="Time window in hours",
+        ge=1,
+        le=168,
+        default=24,
+    )
+    output_format: Optional[str] = Field(
+        description="Output format",
+        default="json",
+        json_schema_extra={"enum": ["json", "csv", "table"]},
+    )
+
+
+@tool(args_schema=QueryMetricsInput)
+def query_metrics(
+    metric_name: str,
+    duration_hours: int = 24,
+    output_format: Optional[str] = "json",
+) -> str:
+    """Query infrastructure metrics for monitoring dashboards."""
+    return f"{metric_name} data for last {duration_hours}h in {output_format} format"
+
+
+VALID_METRICS = {"cpu", "memory", "disk", "network"}
+VALID_FORMATS = {"json", "csv", "table"}
+
+
+@pytest.mark.requires("oci")
+@pytest.mark.parametrize(
+    "model_id",
+    [
+        "meta.llama-4-scout-17b-16e-instruct",
+        "cohere.command-a-03-2025",
+    ],
+)
+def test_enum_constraints_respected(model_id: str):
+    """Model should pick metric_name from the enum values, not hallucinate."""
+    llm = _create_chat_model(model_id)
+    model_with_tools = llm.bind_tools([query_metrics])
+
+    response = model_with_tools.invoke(
+        [
+            SystemMessage(content="Use the query_metrics tool to answer."),
+            HumanMessage(content="Show me the CPU usage for the last 6 hours."),
+        ]
+    )
+
+    assert isinstance(response, AIMessage)
+    assert response.tool_calls, "Model should have made a tool call"
+
+    tc = response.tool_calls[0]
+    assert tc["name"] == "query_metrics"
+
+    args = tc["args"]
+    assert args["metric_name"] in VALID_METRICS, (
+        f"metric_name '{args['metric_name']}' not in enum {VALID_METRICS}"
+    )
+    assert args["metric_name"] == "cpu", "Should have picked 'cpu' from enum"
+
+
+@pytest.mark.requires("oci")
+@pytest.mark.parametrize(
+    "model_id",
+    [
+        "meta.llama-4-scout-17b-16e-instruct",
+        "cohere.command-a-03-2025",
+    ],
+)
+def test_numeric_range_constraints(model_id: str):
+    """duration_hours should be within min=1, max=168."""
+    llm = _create_chat_model(model_id)
+    model_with_tools = llm.bind_tools([query_metrics])
+
+    response = model_with_tools.invoke(
+        [
+            SystemMessage(content="Use the query_metrics tool to answer."),
+            HumanMessage(content="Get memory metrics for the past 48 hours in CSV."),
+        ]
+    )
+
+    assert isinstance(response, AIMessage)
+    assert response.tool_calls, "Model should have made a tool call"
+
+    args = response.tool_calls[0]["args"]
+    assert args["metric_name"] in VALID_METRICS
+    if "duration_hours" in args:
+        assert 1 <= args["duration_hours"] <= 168, (
+            f"duration_hours {args['duration_hours']} outside range [1, 168]"
+        )
+    if "output_format" in args:
+        assert args["output_format"] in VALID_FORMATS, (
+            f"output_format '{args['output_format']}' not in {VALID_FORMATS}"
+        )
+
+
+@pytest.mark.requires("oci")
+@pytest.mark.parametrize(
+    "model_id",
+    [
+        "meta.llama-4-scout-17b-16e-instruct",
+        "cohere.command-a-03-2025",
+    ],
+)
+def test_schema_sent_to_oci_has_constraints(model_id: str):
+    """Verify the converted OCI tool definition actually contains constraints."""
+    llm = _create_chat_model(model_id)
+
+    oci_tool = llm._provider.convert_to_oci_tool(query_metrics)
+
+    # GenericProvider returns FunctionDefinition with .parameters dict
+    # CohereProvider returns CohereTool with .parameter_definitions dict
+    if hasattr(oci_tool, "parameters"):
+        # Generic provider path
+        params = oci_tool.parameters
+        props = params["properties"]
+        assert "enum" in props["metric_name"], (
+            "enum missing from metric_name — constraints not passed through"
+        )
+        assert props["metric_name"]["enum"] == ["cpu", "memory", "disk", "network"]
+        assert props["duration_hours"].get("minimum") == 1
+        assert props["duration_hours"].get("maximum") == 168
+    else:
+        # Cohere provider path — constraints embedded in description
+        param_defs = oci_tool.parameter_definitions
+        desc = param_defs["metric_name"].description
+        assert "cpu" in desc and "memory" in desc, (
+            f"Enum values missing from description: {desc}"
+        )