Update API docs

llama_stack/apis/agents/agents.py

@@ -152,7 +152,17 @@ Step = Annotated[
 
 @json_schema_type
 class Turn(BaseModel):
-    """A single turn in an interaction with an Agentic System."""
+    """A single turn in an interaction with an Agentic System.
+
+    :param turn_id: Unique identifier for the turn within a session
+    :param session_id: Unique identifier for the conversation session
+    :param input_messages: List of messages that initiated this turn
+    :param steps: Ordered list of processing steps executed during this turn
+    :param output_message: The model's generated response containing content and metadata
+    :param output_attachments: (Optional) Files or media attached to the agent's response
+    :param started_at: Timestamp when the turn began
+    :param completed_at: (Optional) Timestamp when the turn finished, if completed
+    """
 
     turn_id: str
     session_id: str
@@ -167,7 +177,13 @@ class Turn(BaseModel):
 
 @json_schema_type
 class Session(BaseModel):
-    """A single session of an interaction with an Agentic System."""
+    """A single session of an interaction with an Agentic System.
+
+    :param session_id: Unique identifier for the conversation session
+    :param session_name: Human-readable name for the session
+    :param turns: List of all turns that have occurred in this session
+    :param started_at: Timestamp when the session was created
+    """
 
     session_id: str
     session_name: str
@@ -232,6 +248,13 @@ class AgentConfig(AgentConfigCommon):
 
 @json_schema_type
 class Agent(BaseModel):
+    """An agent instance with configuration and metadata.
+
+    :param agent_id: Unique identifier for the agent
+    :param agent_config: Configuration settings for the agent
+    :param created_at: Timestamp when the agent was created
+    """
+
     agent_id: str
     agent_config: AgentConfig
     created_at: datetime
@@ -253,6 +276,14 @@ class AgentTurnResponseEventType(StrEnum):
 
 @json_schema_type
 class AgentTurnResponseStepStartPayload(BaseModel):
+    """Payload for step start events in agent turn responses.
+
+    :param event_type: Type of event being reported
+    :param step_type: Type of step being executed
+    :param step_id: Unique identifier for the step within a turn
+    :param metadata: (Optional) Additional metadata for the step
+    """
+
     event_type: Literal[AgentTurnResponseEventType.step_start] = AgentTurnResponseEventType.step_start
     step_type: StepType
     step_id: str
@@ -261,6 +292,14 @@ class AgentTurnResponseStepStartPayload(BaseModel):
 
 @json_schema_type
 class AgentTurnResponseStepCompletePayload(BaseModel):
+    """Payload for step completion events in agent turn responses.
+
+    :param event_type: Type of event being reported
+    :param step_type: Type of step being executed
+    :param step_id: Unique identifier for the step within a turn
+    :param step_details: Complete details of the executed step
+    """
+
     event_type: Literal[AgentTurnResponseEventType.step_complete] = AgentTurnResponseEventType.step_complete
     step_type: StepType
     step_id: str
@@ -269,6 +308,14 @@ class AgentTurnResponseStepCompletePayload(BaseModel):
 
 @json_schema_type
 class AgentTurnResponseStepProgressPayload(BaseModel):
+    """Payload for step progress events in agent turn responses.
+
+    :param event_type: Type of event being reported
+    :param step_type: Type of step being executed
+    :param step_id: Unique identifier for the step within a turn
+    :param delta: Incremental content changes during step execution
+    """
+
     model_config = ConfigDict(protected_namespaces=())
 
     event_type: Literal[AgentTurnResponseEventType.step_progress] = AgentTurnResponseEventType.step_progress
@@ -280,18 +327,36 @@ class AgentTurnResponseStepProgressPayload(BaseModel):
 
 @json_schema_type
 class AgentTurnResponseTurnStartPayload(BaseModel):
+    """Payload for turn start events in agent turn responses.
+
+    :param event_type: Type of event being reported
+    :param turn_id: Unique identifier for the turn within a session
+    """
+
     event_type: Literal[AgentTurnResponseEventType.turn_start] = AgentTurnResponseEventType.turn_start
     turn_id: str
 
 
 @json_schema_type
 class AgentTurnResponseTurnCompletePayload(BaseModel):
+    """Payload for turn completion events in agent turn responses.
+
+    :param event_type: Type of event being reported
+    :param turn: Complete turn data including all steps and results
+    """
+
     event_type: Literal[AgentTurnResponseEventType.turn_complete] = AgentTurnResponseEventType.turn_complete
     turn: Turn
 
 
 @json_schema_type
 class AgentTurnResponseTurnAwaitingInputPayload(BaseModel):
+    """Payload for turn awaiting input events in agent turn responses.
+
+    :param event_type: Type of event being reported
+    :param turn: Turn data when waiting for external tool responses
+    """
+
     event_type: Literal[AgentTurnResponseEventType.turn_awaiting_input] = AgentTurnResponseEventType.turn_awaiting_input
     turn: Turn
 
@@ -310,21 +375,47 @@ register_schema(AgentTurnResponseEventPayload, name="AgentTurnResponseEventPaylo
 
 @json_schema_type
 class AgentTurnResponseEvent(BaseModel):
+    """An event in an agent turn response stream.
+
+    :param payload: Event-specific payload containing event data
+    """
+
     payload: AgentTurnResponseEventPayload
 
 
 @json_schema_type
 class AgentCreateResponse(BaseModel):
+    """Response returned when creating a new agent.
+
+    :param agent_id: Unique identifier for the created agent
+    """
+
     agent_id: str
 
 
 @json_schema_type
 class AgentSessionCreateResponse(BaseModel):
+    """Response returned when creating a new agent session.
+
+    :param session_id: Unique identifier for the created session
+    """
+
     session_id: str
 
 
 @json_schema_type
 class AgentTurnCreateRequest(AgentConfigOverridablePerTurn):
+    """Request to create a new turn for an agent.
+
+    :param agent_id: Unique identifier for the agent
+    :param session_id: Unique identifier for the conversation session
+    :param messages: List of messages to start the turn with
+    :param documents: (Optional) List of documents to provide to the agent
+    :param toolgroups: (Optional) List of tool groups to make available for this turn
+    :param stream: (Optional) Whether to stream the response
+    :param tool_config: (Optional) Tool configuration to override agent defaults
+    """
+
     agent_id: str
     session_id: str
 
@@ -342,6 +433,15 @@ class AgentTurnCreateRequest(AgentConfigOverridablePerTurn):
 
 @json_schema_type
 class AgentTurnResumeRequest(BaseModel):
+    """Request to resume an agent turn with tool responses.
+
+    :param agent_id: Unique identifier for the agent
+    :param session_id: Unique identifier for the conversation session
+    :param turn_id: Unique identifier for the turn within a session
+    :param tool_responses: List of tool responses to submit to continue the turn
+    :param stream: (Optional) Whether to stream the response
+    """
+
     agent_id: str
     session_id: str
     turn_id: str
@@ -351,13 +451,21 @@ class AgentTurnResumeRequest(BaseModel):
 
 @json_schema_type
 class AgentTurnResponseStreamChunk(BaseModel):
-    """streamed agent turn completion response."""
+    """Streamed agent turn completion response.
+
+    :param event: Individual event in the agent turn response stream
+    """
 
     event: AgentTurnResponseEvent
 
 
 @json_schema_type
 class AgentStepResponse(BaseModel):
+    """Response containing details of a specific agent step.
+
+    :param step: The complete step data and execution details
+    """
+
     step: Step
 
 

llama_stack/apis/agents/openai_responses.py

@@ -18,18 +18,37 @@ from llama_stack.schema_utils import json_schema_type, register_schema
 
 @json_schema_type
 class OpenAIResponseError(BaseModel):
+    """Error details for failed OpenAI response requests.
+
+    :param code: Error code identifying the type of failure
+    :param message: Human-readable error message describing the failure
+    """
+
     code: str
     message: str
 
 
 @json_schema_type
 class OpenAIResponseInputMessageContentText(BaseModel):
+    """Text content for input messages in OpenAI response format.
+
+    :param text: The text content of the input message
+    :param type: Content type identifier, always "input_text"
+    """
+
     text: str
     type: Literal["input_text"] = "input_text"
 
 
 @json_schema_type
 class OpenAIResponseInputMessageContentImage(BaseModel):
+    """Image content for input messages in OpenAI response format.
+
+    :param detail: Level of detail for image processing, can be "low", "high", or "auto"
+    :param type: Content type identifier, always "input_image"
+    :param image_url: (Optional) URL of the image content
+    """
+
     detail: Literal["low"] | Literal["high"] | Literal["auto"] = "auto"
     type: Literal["input_image"] = "input_image"
     # TODO: handle file_id
@@ -46,6 +65,14 @@ register_schema(OpenAIResponseInputMessageContent, name="OpenAIResponseInputMess
 
 @json_schema_type
 class OpenAIResponseAnnotationFileCitation(BaseModel):
+    """File citation annotation for referencing specific files in response content.
+
+    :param type: Annotation type identifier, always "file_citation"
+    :param file_id: Unique identifier of the referenced file
+    :param filename: Name of the referenced file
+    :param index: Position index of the citation within the content
+    """
+
     type: Literal["file_citation"] = "file_citation"
     file_id: str
     filename: str
@@ -54,6 +81,15 @@ class OpenAIResponseAnnotationFileCitation(BaseModel):
 
 @json_schema_type
 class OpenAIResponseAnnotationCitation(BaseModel):
+    """URL citation annotation for referencing external web resources.
+
+    :param type: Annotation type identifier, always "url_citation"
+    :param end_index: End position of the citation span in the content
+    :param start_index: Start position of the citation span in the content
+    :param title: Title of the referenced web resource
+    :param url: URL of the referenced web resource
+    """
+
     type: Literal["url_citation"] = "url_citation"
     end_index: int
     start_index: int
@@ -122,6 +158,13 @@ class OpenAIResponseMessage(BaseModel):
 
 @json_schema_type
 class OpenAIResponseOutputMessageWebSearchToolCall(BaseModel):
+    """Web search tool call output message for OpenAI responses.
+
+    :param id: Unique identifier for this tool call
+    :param status: Current status of the web search operation
+    :param type: Tool call type identifier, always "web_search_call"
+    """
+
     id: str
     status: str
     type: Literal["web_search_call"] = "web_search_call"
@@ -129,6 +172,15 @@ class OpenAIResponseOutputMessageWebSearchToolCall(BaseModel):
 
 @json_schema_type
 class OpenAIResponseOutputMessageFileSearchToolCall(BaseModel):
+    """File search tool call output message for OpenAI responses.
+
+    :param id: Unique identifier for this tool call
+    :param queries: List of search queries executed
+    :param status: Current status of the file search operation
+    :param type: Tool call type identifier, always "file_search_call"
+    :param results: (Optional) Search results returned by the file search operation
+    """
+
     id: str
     queries: list[str]
     status: str
@@ -138,6 +190,16 @@ class OpenAIResponseOutputMessageFileSearchToolCall(BaseModel):
 
 @json_schema_type
 class OpenAIResponseOutputMessageFunctionToolCall(BaseModel):
+    """Function tool call output message for OpenAI responses.
+
+    :param call_id: Unique identifier for the function call
+    :param name: Name of the function being called
+    :param arguments: JSON string containing the function arguments
+    :param type: Tool call type identifier, always "function_call"
+    :param id: (Optional) Additional identifier for the tool call
+    :param status: (Optional) Current status of the function call execution
+    """
+
     call_id: str
     name: str
     arguments: str
@@ -148,6 +210,17 @@ class OpenAIResponseOutputMessageFunctionToolCall(BaseModel):
 
 @json_schema_type
 class OpenAIResponseOutputMessageMCPCall(BaseModel):
+    """Model Context Protocol (MCP) call output message for OpenAI responses.
+
+    :param id: Unique identifier for this MCP call
+    :param type: Tool call type identifier, always "mcp_call"
+    :param arguments: JSON string containing the MCP call arguments
+    :param name: Name of the MCP method being called
+    :param server_label: Label identifying the MCP server handling the call
+    :param error: (Optional) Error message if the MCP call failed
+    :param output: (Optional) Output result from the successful MCP call
+    """
+
     id: str
     type: Literal["mcp_call"] = "mcp_call"
     arguments: str
@@ -158,6 +231,13 @@ class OpenAIResponseOutputMessageMCPCall(BaseModel):
 
 
 class MCPListToolsTool(BaseModel):
+    """Tool definition returned by MCP list tools operation.
+
+    :param input_schema: JSON schema defining the tool's input parameters
+    :param name: Name of the tool
+    :param description: (Optional) Description of what the tool does
+    """
+
     input_schema: dict[str, Any]
     name: str
     description: str | None = None
@@ -165,6 +245,14 @@ class MCPListToolsTool(BaseModel):
 
 @json_schema_type
 class OpenAIResponseOutputMessageMCPListTools(BaseModel):
+    """MCP list tools output message containing available tools from an MCP server.
+
+    :param id: Unique identifier for this MCP list tools operation
+    :param type: Tool call type identifier, always "mcp_list_tools"
+    :param server_label: Label identifying the MCP server providing the tools
+    :param tools: List of available tools provided by the MCP server
+    """
+
     id: str
     type: Literal["mcp_list_tools"] = "mcp_list_tools"
     server_label: str
@@ -206,11 +294,34 @@ class OpenAIResponseTextFormat(TypedDict, total=False):
 
 @json_schema_type
 class OpenAIResponseText(BaseModel):
+    """Text response configuration for OpenAI responses.
+
+    :param format: (Optional) Text format configuration specifying output format requirements
+    """
+
     format: OpenAIResponseTextFormat | None = None
 
 
 @json_schema_type
 class OpenAIResponseObject(BaseModel):
+    """Complete OpenAI response object containing generation results and metadata.
+
+    :param created_at: Unix timestamp when the response was created
+    :param error: (Optional) Error details if the response generation failed
+    :param id: Unique identifier for this response
+    :param model: Model identifier used for generation
+    :param object: Object type identifier, always "response"
+    :param output: List of generated output items (messages, tool calls, etc.)
+    :param parallel_tool_calls: Whether tool calls can be executed in parallel
+    :param previous_response_id: (Optional) ID of the previous response in a conversation
+    :param status: Current status of the response generation
+    :param temperature: (Optional) Sampling temperature used for generation
+    :param text: Text formatting configuration for the response
+    :param top_p: (Optional) Nucleus sampling parameter used for generation
+    :param truncation: (Optional) Truncation strategy applied to the response
+    :param user: (Optional) User identifier associated with the request
+    """
+
     created_at: int
     error: OpenAIResponseError | None = None
     id: str
@@ -231,6 +342,13 @@ class OpenAIResponseObject(BaseModel):
 
 @json_schema_type
 class OpenAIDeleteResponseObject(BaseModel):
+    """Response object confirming deletion of an OpenAI response.
+
+    :param id: Unique identifier of the deleted response
+    :param object: Object type identifier, always "response"
+    :param deleted: Deletion confirmation flag, always True
+    """
+
     id: str
     object: Literal["response"] = "response"
     deleted: bool = True
@@ -238,18 +356,39 @@ class OpenAIDeleteResponseObject(BaseModel):
 
 @json_schema_type
 class OpenAIResponseObjectStreamResponseCreated(BaseModel):
+    """Streaming event indicating a new response has been created.
+
+    :param response: The newly created response object
+    :param type: Event type identifier, always "response.created"
+    """
+
     response: OpenAIResponseObject
     type: Literal["response.created"] = "response.created"
 
 
 @json_schema_type
 class OpenAIResponseObjectStreamResponseCompleted(BaseModel):
+    """Streaming event indicating a response has been completed.
+
+    :param response: The completed response object
+    :param type: Event type identifier, always "response.completed"
+    """
+
     response: OpenAIResponseObject
     type: Literal["response.completed"] = "response.completed"
 
 
 @json_schema_type
 class OpenAIResponseObjectStreamResponseOutputItemAdded(BaseModel):
+    """Streaming event for when a new output item is added to the response.
+
+    :param response_id: Unique identifier of the response containing this output
+    :param item: The output item that was added (message, tool call, etc.)
+    :param output_index: Index position of this item in the output list
+    :param sequence_number: Sequential number for ordering streaming events
+    :param type: Event type identifier, always "response.output_item.added"
+    """
+
     response_id: str
     item: OpenAIResponseOutput
     output_index: int
@@ -259,6 +398,15 @@ class OpenAIResponseObjectStreamResponseOutputItemAdded(BaseModel):
 
 @json_schema_type
 class OpenAIResponseObjectStreamResponseOutputItemDone(BaseModel):
+    """Streaming event for when an output item is completed.
+
+    :param response_id: Unique identifier of the response containing this output
+    :param item: The completed output item (message, tool call, etc.)
+    :param output_index: Index position of this item in the output list
+    :param sequence_number: Sequential number for ordering streaming events
+    :param type: Event type identifier, always "response.output_item.done"
+    """
+
     response_id: str
     item: OpenAIResponseOutput
     output_index: int
@@ -268,6 +416,16 @@ class OpenAIResponseObjectStreamResponseOutputItemDone(BaseModel):
 
 @json_schema_type
 class OpenAIResponseObjectStreamResponseOutputTextDelta(BaseModel):
+    """Streaming event for incremental text content updates.
+
+    :param content_index: Index position within the text content
+    :param delta: Incremental text content being added
+    :param item_id: Unique identifier of the output item being updated
+    :param output_index: Index position of the item in the output list
+    :param sequence_number: Sequential number for ordering streaming events
+    :param type: Event type identifier, always "response.output_text.delta"
+    """
+
     content_index: int
     delta: str
     item_id: str
@@ -278,6 +436,16 @@ class OpenAIResponseObjectStreamResponseOutputTextDelta(BaseModel):
 
 @json_schema_type
 class OpenAIResponseObjectStreamResponseOutputTextDone(BaseModel):
+    """Streaming event for when text output is completed.
+
+    :param content_index: Index position within the text content
+    :param text: Final complete text content of the output item
+    :param item_id: Unique identifier of the completed output item
+    :param output_index: Index position of the item in the output list
+    :param sequence_number: Sequential number for ordering streaming events
+    :param type: Event type identifier, always "response.output_text.done"
+    """
+
     content_index: int
     text: str  # final text of the output item
     item_id: str
@@ -288,6 +456,15 @@ class OpenAIResponseObjectStreamResponseOutputTextDone(BaseModel):
 
 @json_schema_type
 class OpenAIResponseObjectStreamResponseFunctionCallArgumentsDelta(BaseModel):
+    """Streaming event for incremental function call argument updates.
+
+    :param delta: Incremental function call arguments being added
+    :param item_id: Unique identifier of the function call being updated
+    :param output_index: Index position of the item in the output list
+    :param sequence_number: Sequential number for ordering streaming events
+    :param type: Event type identifier, always "response.function_call_arguments.delta"
+    """
+
     delta: str
     item_id: str
     output_index: int
@@ -297,6 +474,15 @@ class OpenAIResponseObjectStreamResponseFunctionCallArgumentsDelta(BaseModel):
 
 @json_schema_type
 class OpenAIResponseObjectStreamResponseFunctionCallArgumentsDone(BaseModel):
+    """Streaming event for when function call arguments are completed.
+
+    :param arguments: Final complete arguments JSON string for the function call
+    :param item_id: Unique identifier of the completed function call
+    :param output_index: Index position of the item in the output list
+    :param sequence_number: Sequential number for ordering streaming events
+    :param type: Event type identifier, always "response.function_call_arguments.done"
+    """
+
     arguments: str  # final arguments of the function call
     item_id: str
     output_index: int
@@ -306,6 +492,14 @@ class OpenAIResponseObjectStreamResponseFunctionCallArgumentsDone(BaseModel):
 
 @json_schema_type
 class OpenAIResponseObjectStreamResponseWebSearchCallInProgress(BaseModel):
+    """Streaming event for web search calls in progress.
+
+    :param item_id: Unique identifier of the web search call
+    :param output_index: Index position of the item in the output list
+    :param sequence_number: Sequential number for ordering streaming events
+    :param type: Event type identifier, always "response.web_search_call.in_progress"
+    """
+
     item_id: str
     output_index: int
     sequence_number: int
@@ -322,6 +516,14 @@ class OpenAIResponseObjectStreamResponseWebSearchCallSearching(BaseModel):
 
 @json_schema_type
 class OpenAIResponseObjectStreamResponseWebSearchCallCompleted(BaseModel):
+    """Streaming event for completed web search calls.
+
+    :param item_id: Unique identifier of the completed web search call
+    :param output_index: Index position of the item in the output list
+    :param sequence_number: Sequential number for ordering streaming events
+    :param type: Event type identifier, always "response.web_search_call.completed"
+    """
+
     item_id: str
     output_index: int
     sequence_number: int
@@ -366,6 +568,14 @@ class OpenAIResponseObjectStreamResponseMcpCallArgumentsDone(BaseModel):
 
 @json_schema_type
 class OpenAIResponseObjectStreamResponseMcpCallInProgress(BaseModel):
+    """Streaming event for MCP calls in progress.
+
+    :param item_id: Unique identifier of the MCP call
+    :param output_index: Index position of the item in the output list
+    :param sequence_number: Sequential number for ordering streaming events
+    :param type: Event type identifier, always "response.mcp_call.in_progress"
+    """
+
     item_id: str
     output_index: int
     sequence_number: int
@@ -374,12 +584,24 @@ class OpenAIResponseObjectStreamResponseMcpCallInProgress(BaseModel):
 
 @json_schema_type
 class OpenAIResponseObjectStreamResponseMcpCallFailed(BaseModel):
+    """Streaming event for failed MCP calls.
+
+    :param sequence_number: Sequential number for ordering streaming events
+    :param type: Event type identifier, always "response.mcp_call.failed"
+    """
+
     sequence_number: int
     type: Literal["response.mcp_call.failed"] = "response.mcp_call.failed"
 
 
 @json_schema_type
 class OpenAIResponseObjectStreamResponseMcpCallCompleted(BaseModel):
+    """Streaming event for completed MCP calls.
+
+    :param sequence_number: Sequential number for ordering streaming events
+    :param type: Event type identifier, always "response.mcp_call.completed"
+    """
+
     sequence_number: int
     type: Literal["response.mcp_call.completed"] = "response.mcp_call.completed"
 
@@ -442,6 +664,12 @@ WebSearchToolTypes = ["web_search", "web_search_preview", "web_search_preview_20
 
 @json_schema_type
 class OpenAIResponseInputToolWebSearch(BaseModel):
+    """Web search tool configuration for OpenAI response inputs.
+
+    :param type: Web search tool type variant to use
+    :param search_context_size: (Optional) Size of search context, must be "low", "medium", or "high"
+    """
+
     # Must match values of WebSearchToolTypes above
     type: Literal["web_search"] | Literal["web_search_preview"] | Literal["web_search_preview_2025_03_11"] = (
         "web_search"
@@ -453,6 +681,15 @@ class OpenAIResponseInputToolWebSearch(BaseModel):
 
 @json_schema_type
 class OpenAIResponseInputToolFunction(BaseModel):
+    """Function tool configuration for OpenAI response inputs.
+
+    :param type: Tool type identifier, always "function"
+    :param name: Name of the function that can be called
+    :param description: (Optional) Description of what the function does
+    :param parameters: (Optional) JSON schema defining the function's parameters
+    :param strict: (Optional) Whether to enforce strict parameter validation
+    """
+
     type: Literal["function"] = "function"
     name: str
     description: str | None = None
@@ -462,6 +699,15 @@ class OpenAIResponseInputToolFunction(BaseModel):
 
 @json_schema_type
 class OpenAIResponseInputToolFileSearch(BaseModel):
+    """File search tool configuration for OpenAI response inputs.
+
+    :param type: Tool type identifier, always "file_search"
+    :param vector_store_ids: List of vector store identifiers to search within
+    :param filters: (Optional) Additional filters to apply to the search
+    :param max_num_results: (Optional) Maximum number of search results to return (1-50)
+    :param ranking_options: (Optional) Options for ranking and scoring search results
+    """
+
     type: Literal["file_search"] = "file_search"
     vector_store_ids: list[str]
     filters: dict[str, Any] | None = None
@@ -470,16 +716,37 @@ class OpenAIResponseInputToolFileSearch(BaseModel):
 
 
 class ApprovalFilter(BaseModel):
+    """Filter configuration for MCP tool approval requirements.
+
+    :param always: (Optional) List of tool names that always require approval
+    :param never: (Optional) List of tool names that never require approval
+    """
+
     always: list[str] | None = None
     never: list[str] | None = None
 
 
 class AllowedToolsFilter(BaseModel):
+    """Filter configuration for restricting which MCP tools can be used.
+
+    :param tool_names: (Optional) List of specific tool names that are allowed
+    """
+
     tool_names: list[str] | None = None
 
 
 @json_schema_type
 class OpenAIResponseInputToolMCP(BaseModel):
+    """Model Context Protocol (MCP) tool configuration for OpenAI response inputs.
+
+    :param type: Tool type identifier, always "mcp"
+    :param server_label: Label to identify this MCP server
+    :param server_url: URL endpoint of the MCP server
+    :param headers: (Optional) HTTP headers to include when connecting to the server
+    :param require_approval: Approval requirement for tool calls ("always", "never", or filter)
+    :param allowed_tools: (Optional) Restriction on which tools can be used from this server
+    """
+
     type: Literal["mcp"] = "mcp"
     server_label: str
     server_url: str
@@ -500,17 +767,37 @@ register_schema(OpenAIResponseInputTool, name="OpenAIResponseInputTool")
 
 
 class ListOpenAIResponseInputItem(BaseModel):
+    """List container for OpenAI response input items.
+
+    :param data: List of input items
+    :param object: Object type identifier, always "list"
+    """
+
     data: list[OpenAIResponseInput]
     object: Literal["list"] = "list"
 
 
 @json_schema_type
 class OpenAIResponseObjectWithInput(OpenAIResponseObject):
+    """OpenAI response object extended with input context information.
+
+    :param input: List of input items that led to this response
+    """
+
     input: list[OpenAIResponseInput]
 
 
 @json_schema_type
 class ListOpenAIResponseObject(BaseModel):
+    """Paginated list of OpenAI response objects with navigation metadata.
+
+    :param data: List of response objects with their input context
+    :param has_more: Whether there are more results available beyond this page
+    :param first_id: Identifier of the first item in this page
+    :param last_id: Identifier of the last item in this page
+    :param object: Object type identifier, always "list"
+    """
+
     data: list[OpenAIResponseObjectWithInput]
     has_more: bool
     first_id: str