feat: add optional outputSchema support for tool specifications

- Add outputSchema as optional field in ToolSpec using NotRequired
- Filter outputSchema unconditionally in streaming.py before passing to models
- Add outputSchema support to MCP agent tool adapter
- Add tests for outputSchema functionality
- Addresses PR #818 review comments

Author: Vamil Gandhi

src/strands/event_loop/streaming.py

@@ -2,7 +2,7 @@
 
 import json
 import logging
-from typing import Any, AsyncGenerator, AsyncIterable, Optional
+from typing import Any, AsyncGenerator, AsyncIterable, Optional, cast
 
 from ..models.model import Model
 from ..types._events import (
@@ -346,7 +346,17 @@ async def stream_messages(
     logger.debug("model=<%s> | streaming messages", model)
 
     messages = remove_blank_messages_content_text(messages)
-    chunks = model.stream(messages, tool_specs if tool_specs else None, system_prompt)
+
+    # TODO(#780): Remove outputSchema filtering once model-specific behavior handling is implemented.
+    # For now, we filter out outputSchema from all tool specs to ensure compatibility with all model providers.
+    # Some providers (e.g., Bedrock) will throw validation errors if they receive unknown fields.
+    filtered_tool_specs = None
+    if tool_specs:
+        filtered_tool_specs = cast(
+            list[ToolSpec], [{k: v for k, v in spec.items() if k != "outputSchema"} for spec in tool_specs]
+        )
+
+    chunks = model.stream(messages, filtered_tool_specs, system_prompt)
 
     async for event in process_stream(chunks):
         yield event

src/strands/tools/mcp/mcp_agent_tool.py

@@ -54,18 +54,24 @@ def tool_spec(self) -> ToolSpec:
         """Get the specification of the tool.
 
         This method converts the MCP tool specification to the agent framework's
-        ToolSpec format, including the input schema and description.
+        ToolSpec format, including the input schema, description, and optional output schema.
 
         Returns:
             ToolSpec: The tool specification in the agent framework format
         """
         description: str = self.mcp_tool.description or f"Tool which performs {self.mcp_tool.name}"
-        return {
+
+        spec: ToolSpec = {
             "inputSchema": {"json": self.mcp_tool.inputSchema},
             "name": self.mcp_tool.name,
             "description": description,
         }
 
+        if self.mcp_tool.outputSchema:
+            spec["outputSchema"] = {"json": self.mcp_tool.outputSchema}
+
+        return spec
+
     @property
     def tool_type(self) -> str:
         """Get the type of the tool.

src/strands/types/tools.py

@@ -9,7 +9,7 @@
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, Any, AsyncGenerator, Awaitable, Callable, Literal, Protocol, Union
 
-from typing_extensions import TypedDict
+from typing_extensions import NotRequired, TypedDict
 
 from .media import DocumentContent, ImageContent
 
@@ -27,11 +27,15 @@ class ToolSpec(TypedDict):
         description: A human-readable description of what the tool does.
         inputSchema: JSON Schema defining the expected input parameters.
         name: The unique name of the tool.
+        outputSchema: Optional JSON Schema defining the expected output format.
+            Note: Not all model providers support this field. Providers that don't
+            support it should filter it out before sending to their API.
     """
 
     description: str
     inputSchema: JSONSchema
     name: str
+    outputSchema: NotRequired[JSONSchema]
 
 
 class Tool(TypedDict):

tests/strands/tools/mcp/test_mcp_agent_tool.py

@@ -13,6 +13,7 @@ def mock_mcp_tool():
     mock_tool.name = "test_tool"
     mock_tool.description = "A test tool"
     mock_tool.inputSchema = {"type": "object", "properties": {}}
+    mock_tool.outputSchema = None  # MCP tools can have optional outputSchema
     return mock_tool
 
 
@@ -58,6 +59,16 @@ def test_tool_spec_without_description(mock_mcp_tool, mock_mcp_client):
     assert tool_spec["description"] == "Tool which performs test_tool"
 
 
+def test_tool_spec_with_output_schema(mock_mcp_tool, mock_mcp_client):
+    mock_mcp_tool.outputSchema = {"type": "object", "properties": {"result": {"type": "string"}}}
+
+    agent_tool = MCPAgentTool(mock_mcp_tool, mock_mcp_client)
+    tool_spec = agent_tool.tool_spec
+
+    assert "outputSchema" in tool_spec
+    assert tool_spec["outputSchema"]["json"] == {"type": "object", "properties": {"result": {"type": "string"}}}
+
+
 @pytest.mark.asyncio
 async def test_stream(mcp_agent_tool, mock_mcp_client, alist):
     tool_use = {"toolUseId": "test-123", "name": "test_tool", "input": {"param": "value"}}