Update messages and tools sections

Author: anbuzin

docs/ai-python/content/docs/basics/messages-and-events.mdx

@@ -6,20 +6,38 @@ summary: Construct messages, add files, read outputs, serialize history, handle
 ---
 
 Messages and events make up AI SDK for Python's data model. Events are used
-to communicate transient streaming state, while messages are used to accumulate, 
+to communicate transient streaming state, while messages are used to accumulate,
 store, and pass around non-streaming state.
 
-Both are Pydantic models, so you can pattern-match, serialize, and persist them 
+Both are Pydantic models, so you can pattern-match, serialize, and persist them
 when your app needs that.
 
 ## Build messages
 
 Messages store the conversation history you send to the model. Each message
-represents a turn in the conversation and is made up of `Part`'s:
+represents a turn in the conversation and is made up of `Part` values:
 
-> insert flowchart of what the message is made out of
+```python
+class Message:
+    role: "system" | "user" | "assistant" | "tool" | "internal"
+    parts: list[Part]
+    ...
+
+
+Part = (
+    TextPart
+    | ReasoningPart
+    | ToolCallPart
+    | ToolResultPart
+    | BuiltinToolCallPart
+    | BuiltinToolReturnPart
+    | FilePart
+    | HookPart
+)
+
+```
 
-Use builtin factory functions to quickly construct frequently used shapes of 
+Use built-in factory functions to quickly construct frequently used shapes of
 messages:
 
 ```python
@@ -38,7 +56,7 @@ restored = [ai.messages.Message.model_validate(item) for item in encoded]
 
 ## Add files and multimodal input
 
-File parts let you send images, audio, or documents when the provider supports 
+File parts let you send images, audio, or documents when the provider supports
 them.
 
 ```python
@@ -61,17 +79,17 @@ print(message.tool_calls)
 print(message.files)
 ```
 
-When working with structured outputs, use `get_output` to get the final assistant
-message wrapped into the provided Pydantic model. 
+When working with structured outputs, use `get_output` to get the final
+assistant message wrapped into the provided Pydantic model.
 
 ```python
 forecast = message.get_output(Forecast)
 ```
 
 ## Handle stream events
 
-Streams and agents both yield event objects from `ai.events`. Applications can handle
-each kind of event as they see fit:
+Streams and agents both yield event objects from `ai.events`. Applications can
+handle each kind of event as they see fit:
 
 ```python
 if isinstance(event, ai.events.TextDelta):
@@ -83,6 +101,43 @@ arrive through `ToolStart`, `ToolDelta`, and `ToolEnd` events. Provider-executed
 tools use the `BuiltinToolStart`, `BuiltinToolDelta`, `BuiltinToolEnd`, and
 `BuiltinToolResult` events.
 
+```text
+StreamStart
+
+    # text output
+    TextStart
+    TextDelta ...
+    TextEnd
+
+    # reasoning output
+    ReasoningStart
+    ReasoningDelta ...
+    ReasoningEnd
+
+    # host-executed tool call
+    ToolStart
+    ToolDelta ...
+    ToolEnd
+
+    # provider-executed tool call
+    BuiltinToolStart
+    BuiltinToolDelta ...
+    BuiltinToolEnd
+    BuiltinToolResult
+
+    # generated file
+    FileEvent
+
+StreamEnd
+```
+
+```text
+# Agent runs can also interleave:
+ToolCallResult          # emitted after a Python tool finishes
+PartialToolCallResult   # emitted while a streaming tool or subagent yields
+HookEvent               # emitted when a hook is pending, resolved, or cancelled
+```
+
 ```python
 async with ai.stream(model, messages, tools=tools) as stream:
     async for event in stream:
@@ -96,6 +151,9 @@ Agents can also emit tool results, hook events, and partial tool output. You can
 ignore events you do not need, or route them into your application UI,
 observability pipeline, or durable workflow.
 
+Every event also carries a reference to a `ai.Message` that has partial content
+accumulated from the stream *so far*.
+
 ## Track usage
 
 Providers attach usage to events when they report it. The latest value is also

docs/ai-python/content/docs/basics/tools.mdx

@@ -5,7 +5,7 @@ type: guide
 summary: Define function tools, design schemas, handle tool errors, use schema-only tools, provider tools, and MCP tools.
 ---
 
-AI SDK for Python supports multiple types of tools, inlcuding function tools
+AI SDK for Python supports multiple types of tools, including function tools
 defined in code using `@ai.tool`, as well as built-in provider-side tools.
 
 ## Declare function tools
@@ -52,7 +52,7 @@ use those when your tools need to return partial output, e.g. when wrapping
 subagents.
 
 Streaming tools require a special return type in order to get correctly
-handled by the SDK, since partial outputs need to be accumulated, passed though,
+handled by the SDK, since partial outputs need to be accumulated, passed through,
 and the LLM needs to receive an accumulated result. That return type must be
 a subtype of `ai.Aggregator`.
 
@@ -71,13 +71,20 @@ async def draft_reply(topic: str) -> ai.StreamingTextTool:
 Use `ai.StreamingStatusTool[T]` when intermediate yields are progress updates
 and the last yielded value is the final result.
 
-The agent emits `PartialToolCallResult` events for those values, then sends 
+The agent emits `PartialToolCallResult` events for those values, then sends
 the aggregated result back to the model on the next turn.
 
 ## Understand tool anatomy
 
-> provide a diagram of ai.Tool, AgentTool, provider tools, etc.
-> mention that tools contain spec and params, and which tools have which
+`ai.Tool` represents tools of all kinds in the SDK.
+
+Each tool carries an optional `spec`, which is a description consumed by the 
+model, as well as a `tool_config` that contains tool-specific execution config 
+(e.g. retry policy).
+
+`AgentTool` wraps `ai.Tool` together with its corresponding Python function,
+which allows `agent.run` to find and call that function when the model requests
+to do so.
 
 Pass `ai.Tool` objects directly to `ai.stream` when you want the model to emit
 tool calls but you do not want the SDK to execute them: