diff --git a/docs/v3/documentation/features/chat.mdx b/docs/v3/documentation/features/chat.mdx
index 0e380580..7493e791 100644
--- a/docs/v3/documentation/features/chat.mdx
+++ b/docs/v3/documentation/features/chat.mdx
@@ -43,6 +43,32 @@ console.log(answer);
 
 The chat endpoint searches through the peer's representation--all the conclusions Honcho has reasoned about them--and synthesizes a natural language answer.
 
+## Reasoning Level
+
+Use `reasoning_level` to trade off speed against depth for a specific chat request. It is optional and defaults to `low`. Accepted values are `minimal`, `low`, `medium`, `high`, and `max`.
+
+The reasoning level controls which model the request is routed to, the tools used by the agent, the thinking budget, the maximum tool-iteration count, and output token limits.
+
+| Level | When to use | Notes |
+|-------|-------------|-------|
+| `minimal` | Fast factual lookups | Smallest prefetch window and minimal tools for lower cost. |
+| `low` | Default balance | Standard tool set and budgets. |
+| `medium` | Multi-step or ambiguous questions | Calls fewer tools than `low`, but thinks harder and longer. |
+| `high` | Complex synthesis across sources | Thinks like `medium`, but uses more tools. |
+| `max` | Deep research, most complex queries | Highest thinking budget, max iterations. |
+
+<CodeGroup>
+```python Python
+query = "Summarize the user's long-term goals."
+answer = peer.chat(query, reasoning_level="high")
+```
+
+```typescript TypeScript
+const query = "Summarize the user's long-term goals.";
+const answer = await peer.chat(query, { reasoningLevel: "high" });
+```
+</CodeGroup>
+
 ## Streaming Responses
 
 For longer answers, use streaming to get incremental responses:
diff --git a/docs/v3/documentation/reference/sdk.mdx b/docs/v3/documentation/reference/sdk.mdx
index d65b983e..967f39ff 100644
--- a/docs/v3/documentation/reference/sdk.mdx
+++ b/docs/v3/documentation/reference/sdk.mdx
@@ -259,6 +259,7 @@ print(f"Workspace: {alice.workspace_id}")
 response = alice.chat("What did I have for breakfast?")
 response = alice.chat("What do I know about Bob?", target="bob")
 response = alice.chat("What happened in session-1?", session="session-1")
+response = alice.chat("Summarize what matters most to me.", reasoning_level="high")
 
 # Add content to a session with a peer
 session = honcho.session("session-1")
@@ -305,6 +306,9 @@ const targetResponse = await alice.chat("What do I know about Bob?", { target: "
 const sessionResponse = await alice.chat("What happened in session-1?", {
   sessionId: "session-1"
 });
+const deeperResponse = await alice.chat("Summarize what matters most to me.", {
+  reasoningLevel: "high"
+});
 
 // Chat with streaming support
 const streamResponse = await alice.chat("Tell me a story", { stream: true });