diff --git a/sdk/arch/tool-system.mdx b/sdk/arch/tool-system.mdx
index 114a89318..e4766d0cc 100644
--- a/sdk/arch/tool-system.mdx
+++ b/sdk/arch/tool-system.mdx
@@ -428,7 +428,8 @@ flowchart TB
    - Wraps the MCP tool metadata in `MCPToolDefinition`
    - Uses generic `MCPToolAction` as the action type (NOT dynamic models yet)
 5. **Add to Agent** - All `MCPToolDefinition` instances are added to agent's `tools_map` during `initialize()` (bypasses ToolRegistry)
-6. **Lazy Validation** - Dynamic Pydantic models are generated lazily when:
+6. **Reconcile Changes** - When a server sends `notifications/tools/list_changed`, the SDK re-lists the server and atomically reconciles that client's tools in the running agent. Added tools appear, changed schemas replace their prior definitions, and removed tools disappear without altering historical tool-call events.
+7. **Lazy Validation** - Dynamic Pydantic models are generated lazily when:
    - `action_from_arguments()` is called (argument validation)
    - `to_openai_tool()` is called (schema export to LLM)
 
@@ -465,6 +466,24 @@ agent = Agent(
 )
 ```
 
+### Refreshing Tools After an MCP Server Restart
+
+Servers can change their advertised tools after a deployment or restart. Refresh
+the conversation between runs to reconnect every configured MCP client and
+reconcile the latest `tools/list` snapshot:
+
+```python
+conversation.refresh_mcp_tools()
+conversation.send_message("Use the newly deployed tools")
+conversation.run()
+```
+
+The same method works for local and remote conversations. Added tools become
+available, changed definitions replace their previous schemas, and removed tools
+are no longer exposed to subsequent LLM requests. Live MCP connections also
+perform this reconciliation automatically when they receive
+`notifications/tools/list_changed`.
+
 ## Component Relationships
 
 ```mermaid
@@ -501,7 +520,7 @@ flowchart TB
 
 **Relationship Characteristics:**
 - **Native → Registry → tools_map**: Native tools resolved via `ToolRegistry`
-- **MCP → tools_map**: MCP tools bypass registry, added directly during `initialize()`
+- **MCP → tools_map**: MCP tools bypass registry, are added during `initialize()`, and are reconciled after `tools/list_changed` notifications
 - **tools_map → LLM**: Generate schemas describing all available capabilities
 - **Agent → tools_map**: Execute actions, receive observations
 - **tools_map → Conversation**: Read state for context-aware execution