diff --git a/sdk/arch/mcp.mdx b/sdk/arch/mcp.mdx
index 80443712..41d9fa45 100644
--- a/sdk/arch/mcp.mdx
+++ b/sdk/arch/mcp.mdx
@@ -273,6 +273,18 @@ flowchart TB
 6. **Observation Creation:** Wrap in `MCPToolObservation`
 7. **Error Handling:** Catch exceptions, return error observations
 
+MCP tools can return two kinds of data beyond their text and image content:
+`structuredContent`, machine-readable result data for clients that render or
+process it, and result `_meta`, protocol metadata about the call.
+`MCPToolObservation` preserves both in the `structured_content` and
+`result_meta` fields. They serialize with the observation, so API and websocket
+clients receive them, but they are not sent to the model.
+
+Masking follows the same rules as text output: when a conversation is attached,
+registered secrets inside these fields are replaced before the observation is
+persisted or delivered, walking nested keys and values. If a field cannot be
+masked safely, it is dropped rather than delivered unmasked.
+
 ### MCPToolExecutor
 
 Executors bridge SDK actions to MCP calls: