feat: Tool output schema support in db and service layer (IBM#1263)

* feat: Add outputSchema field support to tools

- Add output_schema column to Tool database model (db.py)
- Add output_schema field to Tool Pydantic model (models.py)
- Add output_schema field to ToolCreate, ToolUpdate, and ToolRead schemas
- Support both 'output_schema' and 'outputSchema' (camelCase) via alias
- Create database migration to add output_schema column to tools table
- Field is optional (nullable) to maintain backward compatibility

This resolves the issue where outputSchema was documented but not
actually stored or returned when listing/describing tools to clients.

Signed-off-by: Matt Sanchez <mattsanchez@ibm.com>

* feat(output-schema): add default output_schema and improve field handling

- Add default empty object schema for output_schema in ToolCreate
  (previously None, now {"type": "object", "properties": {}})
- Pass output_schema through gateway_service and tool_service
- Add output_schema update support in tool update operations
- Refactor alembic migration: organize imports and use double quotes
  for consistency

This ensures output_schema is properly initialized and can be updated
across all tool operations, improving schema validation capabilities.

* Code Review and test fix

Signed-off-by: Mihai Criveti <crivetimihai@gmail.com>

---------

Signed-off-by: Matt Sanchez <mattsanchez@ibm.com>
Signed-off-by: Mihai Criveti <crivetimihai@gmail.com>
Co-authored-by: Matt Sanchez <mattsanchez@ibm.com>
Co-authored-by: Mihai Criveti <crivetimihai@gmail.com>

Author: 3 people

enable_payload_logging.md

@@ -141,4 +141,4 @@ The logging middleware automatically masks sensitive information:
    tail -f logs/mcpgateway.log
    ```
 
-Now you can see the full request payloads (with sensitive data masked) to debug tool registration and other API issues.
+Now you can see the full request payloads (with sensitive data masked) to debug tool registration and other API issues.

mcpgateway/alembic/versions/9aaa90ad26d9_add_output_schema_to_tools.py

@@ -0,0 +1,33 @@
+# -*- coding: utf-8 -*-
+"""add_output_schema_to_tools
+
+Revision ID: 9aaa90ad26d9
+Revises: 9c99ec6872ed
+Create Date: 2025-10-15 17:29:38.801771
+
+"""
+
+# Standard
+from typing import Sequence, Union
+
+# Third-Party
+from alembic import op
+import sqlalchemy as sa
+
+# revision identifiers, used by Alembic.
+revision: str = "9aaa90ad26d9"
+down_revision: Union[str, Sequence[str], None] = "9c99ec6872ed"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    # Add output_schema column to tools table
+    op.add_column("tools", sa.Column("output_schema", sa.JSON(), nullable=True))
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    # Remove output_schema column from tools table
+    op.drop_column("tools", "output_schema")

mcpgateway/db.py

@@ -1570,6 +1570,7 @@ class Tool(Base):
     request_type: Mapped[str] = mapped_column(String(20), default="SSE")
     headers: Mapped[Optional[Dict[str, str]]] = mapped_column(JSON)
     input_schema: Mapped[Dict[str, Any]] = mapped_column(JSON)
+    output_schema: Mapped[Optional[Dict[str, Any]]] = mapped_column(JSON, nullable=True)
     annotations: Mapped[Optional[Dict[str, Any]]] = mapped_column(JSON, default=lambda: {})
     created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utc_now)
     updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utc_now, onupdate=utc_now)

mcpgateway/middleware/request_logging_middleware.py

@@ -42,7 +42,7 @@ def mask_sensitive_data(data):
     """
     if isinstance(data, dict):
         return {k: ("******" if k.lower() in SENSITIVE_KEYS else mask_sensitive_data(v)) for k, v in data.items()}
-    elif isinstance(data, list):
+    if isinstance(data, list):
         return [mask_sensitive_data(i) for i in data]
     return data
 
@@ -64,7 +64,7 @@ def mask_jwt_in_cookies(cookie_header):
     for cookie in cookie_header.split(";"):
         cookie = cookie.strip()
         if "=" in cookie:
-            name, value = cookie.split("=", 1)
+            name, _ = cookie.split("=", 1)
             name = name.strip()
             # Mask JWT tokens and other sensitive cookies
             if any(sensitive in name.lower() for sensitive in ["jwt", "token", "auth", "session"]):

mcpgateway/models.py

@@ -468,6 +468,7 @@ class Tool(CommonAttributes):
         requestType (str): The HTTP method used to invoke the tool (GET, POST, PUT, DELETE, SSE, STDIO).
         headers (Dict[str, Any]): A JSON object representing HTTP headers.
         input_schema (Dict[str, Any]): A JSON Schema for validating the tool's input.
+        output_schema (Optional[Dict[str, Any]]): A JSON Schema for validating the tool's output.
         annotations (Optional[Dict[str, Any]]): Tool annotations for behavior hints.
         auth_username (Optional[str]): The username for basic authentication.
         auth_password (Optional[str]): The password for basic authentication.
@@ -485,6 +486,7 @@ class Tool(CommonAttributes):
     request_type: str = "SSE"
     headers: Optional[Dict[str, Any]] = Field(default_factory=dict)
     input_schema: Dict[str, Any] = Field(default_factory=lambda: {"type": "object", "properties": {}})
+    output_schema: Optional[Dict[str, Any]] = Field(default=None, description="JSON Schema for validating the tool's output")
     annotations: Optional[Dict[str, Any]] = Field(default_factory=dict, description="Tool annotations for behavior hints")
     auth_username: Optional[str] = None
     auth_password: Optional[str] = None

mcpgateway/schemas.py

@@ -389,6 +389,7 @@ class ToolCreate(BaseModel):
         request_type (Literal["GET", "POST", "PUT", "DELETE", "PATCH"]): HTTP method to be used for invoking the tool.
         headers (Optional[Dict[str, str]]): Additional headers to send when invoking the tool.
         input_schema (Optional[Dict[str, Any]]): JSON Schema for validating tool parameters. Alias 'inputSchema'.
+        output_schema (Optional[Dict[str, Any]]): JSON Schema for validating tool output. Alias 'outputSchema'.
         annotations (Optional[Dict[str, Any]]): Tool annotations for behavior hints such as title, readOnlyHint, destructiveHint, idempotentHint, openWorldHint.
         jsonpath_filter (Optional[str]): JSON modification filter.
         auth (Optional[AuthenticationValues]): Authentication credentials (Basic or Bearer Token or custom headers) if required.
@@ -406,6 +407,7 @@ class ToolCreate(BaseModel):
     request_type: Literal["GET", "POST", "PUT", "DELETE", "PATCH", "SSE", "STDIO", "STREAMABLEHTTP"] = Field("SSE", description="HTTP method to be used for invoking the tool")
     headers: Optional[Dict[str, str]] = Field(None, description="Additional headers to send when invoking the tool")
     input_schema: Optional[Dict[str, Any]] = Field(default_factory=lambda: {"type": "object", "properties": {}}, description="JSON Schema for validating tool parameters", alias="inputSchema")
+    output_schema: Optional[Dict[str, Any]] = Field(default=None, description="JSON Schema for validating tool output", alias="outputSchema")
     annotations: Optional[Dict[str, Any]] = Field(
         default_factory=dict,
         description="Tool annotations for behavior hints (title, readOnlyHint, destructiveHint, idempotentHint, openWorldHint)",
@@ -767,6 +769,7 @@ class ToolUpdate(BaseModelWithConfigDict):
     request_type: Optional[Literal["GET", "POST", "PUT", "DELETE", "PATCH"]] = Field(None, description="HTTP method to be used for invoking the tool")
     headers: Optional[Dict[str, str]] = Field(None, description="Additional headers to send when invoking the tool")
     input_schema: Optional[Dict[str, Any]] = Field(None, description="JSON Schema for validating tool parameters")
+    output_schema: Optional[Dict[str, Any]] = Field(None, description="JSON Schema for validating tool output")
     annotations: Optional[Dict[str, Any]] = Field(None, description="Tool annotations for behavior hints")
     jsonpath_filter: Optional[str] = Field(None, description="JSON path filter for rpc tool calls")
     auth: Optional[AuthenticationValues] = Field(None, description="Authentication credentials (Basic or Bearer Token or custom headers) if required")
@@ -1032,6 +1035,7 @@ class ToolRead(BaseModelWithConfigDict):
     integration_type: str
     headers: Optional[Dict[str, str]]
     input_schema: Dict[str, Any]
+    output_schema: Optional[Dict[str, Any]] = Field(None)
     annotations: Optional[Dict[str, Any]]
     jsonpath_filter: Optional[str]
     auth: Optional[AuthenticationValues]

mcpgateway/services/export_service.py

@@ -294,6 +294,7 @@ async def _export_tools(self, db: Session, tags: Optional[List[str]], include_in
                 "description": tool.description,
                 "headers": tool.headers or {},
                 "input_schema": tool.input_schema or {"type": "object", "properties": {}},
+                "output_schema": tool.output_schema,
                 "annotations": tool.annotations or {},
                 "jsonpath_filter": tool.jsonpath_filter,
                 "tags": tool.tags or [],

mcpgateway/services/gateway_service.py

@@ -596,6 +596,7 @@ async def register_gateway(
                     request_type=tool.request_type,
                     headers=tool.headers,
                     input_schema=tool.input_schema,
+                    output_schema=tool.output_schema,
                     annotations=tool.annotations,
                     jsonpath_filter=tool.jsonpath_filter,
                     auth_type=auth_type,

mcpgateway/services/import_service.py

@@ -954,6 +954,7 @@ def _convert_to_tool_create(self, tool_data: Dict[str, Any]) -> ToolCreate:
             request_type=tool_data.get("request_type", "GET"),
             headers=tool_data.get("headers"),
             input_schema=tool_data.get("input_schema"),
+            output_schema=tool_data.get("output_schema"),
             annotations=tool_data.get("annotations"),
             jsonpath_filter=tool_data.get("jsonpath_filter"),
             auth=auth_info,
@@ -982,6 +983,7 @@ def _convert_to_tool_update(self, tool_data: Dict[str, Any]) -> ToolUpdate:
             request_type=tool_data.get("request_type"),
             headers=tool_data.get("headers"),
             input_schema=tool_data.get("input_schema"),
+            output_schema=tool_data.get("output_schema"),
             annotations=tool_data.get("annotations"),
             jsonpath_filter=tool_data.get("jsonpath_filter"),
             auth=auth_info,

mcpgateway/services/tool_service.py

@@ -467,6 +467,7 @@ async def register_tool(
                 request_type=tool.request_type,
                 headers=tool.headers,
                 input_schema=tool.input_schema,
+                output_schema=tool.output_schema,
                 annotations=tool.annotations,
                 jsonpath_filter=tool.jsonpath_filter,
                 auth_type=auth_type,
@@ -1247,6 +1248,8 @@ async def update_tool(
                 tool.headers = tool_update.headers
             if tool_update.input_schema is not None:
                 tool.input_schema = tool_update.input_schema
+            if tool_update.output_schema is not None:
+                tool.output_schema = tool_update.output_schema
             if tool_update.annotations is not None:
                 tool.annotations = tool_update.annotations
             if tool_update.jsonpath_filter is not None: