Clarify aggregators

Author: anbuzin

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

@@ -51,10 +51,21 @@ AI SDK for Python supports tools that are async-generators. You might want to
 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 through,
-and the LLM needs to receive an accumulated result. That return type must be
-a subtype of `ai.Aggregator`.
+Streaming tools use aggregators. An aggregator solves two problems: the tool can
+yield many values over time, but the agent still needs one final tool result;
+and your app may want a rich stored result while the model needs a simpler value
+on the next turn.
+
+The core interface is:
+
+```python
+class Aggregator[Item, Result, ModelInput]:
+    def feed(self, item: Item) -> None: ...
+    def snapshot(self) -> Result: ...
+
+    @classmethod
+    def to_model_input(cls, snapshot: Result) -> ModelInput: ...
+```
 
 Use `ai.StreamingTextTool` when yielded strings should concatenate into the
 tool result:
@@ -71,6 +82,9 @@ 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.
 
+Use `ai.SubAgentTool` when a tool streams events from a nested agent. The stored
+result is a message bundle, and the model sees the final assistant text.
+
 The agent emits `PartialToolCallResult` events for those values, then sends
 the aggregated result back to the model on the next turn.