Skip to content

The open-source agent harness - the runtime layer that turns an LLM into a working agent.

docs: consolidate Create-an-Agent into one page + refresh capability screenshots (#267)

shubhamagarwal-create1cc859341560
diff --git a/docs/api/overview.mdx b/docs/api/overview.mdx
index 3a83a68bc..b58514213 100644
--- a/docs/api/overview.mdx
+++ b/docs/api/overview.mdx
@@ -102,7 +102,7 @@ flowchart LR
| **Turn 3** | Jane (or a support rep) | Approval: allow `process_refund` | Agent runs the refund and sends a confirmation. |
<Note>
- A turn can also end paused when the agent asks a clarifying question ([`tool.response_required`](/create-agent/ask-user-questions))
+ A turn can also end paused when the agent asks a clarifying question ([`tool.response_required`](/create-agent/overview#ask-user-questions))
or needs MCP OAuth ([`mcp.auth_required`](/mcp-servers#in-chat-authentication)). You resume with a new turn, just like
Turn 3 above.
</Note>
@@ -345,8 +345,8 @@ Turn `input` accepts three item types:
| `type` | Purpose |
| -------------------- | ------------------------------------------------------------------------------------------- |
| `user.message` | A message. `content` is a string or an array of `text` / `file` parts (files as data URIs). |
-| `user.tool_approval` | An [approval decision](/create-agent/tool-approval) for a paused tool call. |
-| `user.tool_response` | An [answer](/create-agent/ask-user-questions) for a paused client-side tool call. |
+| `user.tool_approval` | An [approval decision](/create-agent/overview#tool-approval) for a paused tool call. |
+| `user.tool_response` | An [answer](/create-agent/overview#ask-user-questions) for a paused client-side tool call. |
A single turn cannot mix `user.message` items with approval or tool-response items.
@@ -394,7 +394,7 @@ for await (const { data: event } of resume) {
}
```
-The same pattern applies to [`tool.response_required`](/create-agent/ask-user-questions) (resume with `user.tool_response`) and [`mcp.auth_required`](/mcp-servers#in-chat-authentication) (resume after the user completes OAuth).
+The same pattern applies to [`tool.response_required`](/create-agent/overview#ask-user-questions) (resume with `user.tool_response`) and [`mcp.auth_required`](/mcp-servers#in-chat-authentication) (resume after the user completes OAuth).
## Reconnects, cancel, and history
diff --git a/docs/api/turn-events.mdx b/docs/api/turn-events.mdx
index ea5cc6d34..13f99da68 100644
--- a/docs/api/turn-events.mdx
+++ b/docs/api/turn-events.mdx
@@ -98,7 +98,7 @@ The result of a tool the harness executed, linked to its call by `tool_call_id`:
### `tool.approval_required`
-A tool call needs [human approval](/create-agent/tool-approval) before it can run. The turn ends after this event; resume with a `user.tool_approval` input.
+A tool call needs [human approval](/create-agent/overview#tool-approval) before it can run. The turn ends after this event; resume with a `user.tool_approval` input.
| Field | Description |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -106,7 +106,7 @@ A tool call needs [human approval](/create-agent/tool-approval) before it can ru
### `tool.response_required`
-A client-side tool (e.g. [`ask_user_question`](/create-agent/ask-user-questions)) needs a result from your app. Same shape as `tool.approval_required`; resume with a `user.tool_response` input.
+A client-side tool (e.g. [`ask_user_question`](/create-agent/overview#ask-user-questions)) needs a result from your app. Same shape as `tool.approval_required`; resume with a `user.tool_response` input.
## Subagent threads
diff --git a/docs/api/use-agent.mdx b/docs/api/use-agent.mdx
index bc15e6559..edb1eeb40 100644
--- a/docs/api/use-agent.mdx
+++ b/docs/api/use-agent.mdx
@@ -378,7 +378,7 @@ rl.close();
### Handle tool approvals
-When a tool call is configured to require [human approval](/create-agent/tool-approval), the agent emits a [`tool.approval_required`](/api/turn-events#tool-approval-required) event and the turn ends. Each event carries a `threadId` and the `toolCalls` awaiting a decision — a single turn can emit more than one (for example, when parallel threads each call a gated tool), so collect all of them. Resume by creating a new turn with one `user.tool_approval` item per pending tool call — allow it, or deny it with an optional reason.
+When a tool call is configured to require [human approval](/create-agent/overview#tool-approval), the agent emits a [`tool.approval_required`](/api/turn-events#tool-approval-required) event and the turn ends. Each event carries a `threadId` and the `toolCalls` awaiting a decision — a single turn can emit more than one (for example, when parallel threads each call a gated tool), so collect all of them. Resume by creating a new turn with one `user.tool_approval` item per pending tool call — allow it, or deny it with an optional reason.
Each pending tool-call ref carries the `sourceEventId` of the [`model.message`](/api/turn-events#model-message) that emitted the tool call. Keep the same `id`-keyed [event index](#handling-event-delta-while-streaming) you build while streaming, then look up `events.get(sourceEventId)` to read the tool's name and arguments.
@@ -447,7 +447,7 @@ rl.close();
### Answer agent questions
-When the agent needs input it cannot safely assume, it can ask the user a structured question via the built-in client-side [`ask_user_question`](/create-agent/ask-user-questions) tool. Since the tool runs on your side, the agent emits a [`tool.response_required`](/api/turn-events#tool-response-required) event and the turn ends. The pending tool call's `arguments` carry the `question` and its `options`. Collect the user's answer and resume by creating a new turn with one `user.tool_response` item per pending tool call.
+When the agent needs input it cannot safely assume, it can ask the user a structured question via the built-in client-side [`ask_user_question`](/create-agent/overview#ask-user-questions) tool. Since the tool runs on your side, the agent emits a [`tool.response_required`](/api/turn-events#tool-response-required) event and the turn ends. The pending tool call's `arguments` carry the `question` and its `options`. Collect the user's answer and resume by creating a new turn with one `user.tool_response` item per pending tool call.
```typescript
import { createInterface } from 'node:readline/promises';
diff --git a/docs/chat-ui.mdx b/docs/chat-ui.mdx
index cfd17a976..fcd71a43b 100644
--- a/docs/chat-ui.mdx
+++ b/docs/chat-ui.mdx
@@ -22,7 +22,7 @@ When you run TrueForge ([Quickstart](/quickstart)), open the app URL (for exampl
- Agent composer and [Agent Library](/agent-library)
- Streaming chat with tool calls, approvals, and ask-user-questions
- Settings for [models](/models), [connectors](/mcp-servers), [skills](/skills), and [sandbox](/sandbox)
-- [Generative UI](/create-agent/generative-ui) rendering out of the box
+- [Generative UI](/create-agent/overview#generative-ui) rendering out of the box
<Frame caption="The bundled chat UI — a streaming response with an expanded agent-steps panel: reasoning, tool calls, and a subagent.">
<img src="/images/chat-ui.png" alt="TrueForge chat UI with an agent response and an expanded agent-steps panel including a subagent" />
diff --git a/docs/create-agent/agent-spec.mdx b/docs/create-agent/agent-spec.mdx
index 3d1036e92..12e3eef5d 100644
--- a/docs/create-agent/agent-spec.mdx
+++ b/docs/create-agent/agent-spec.mdx
@@ -69,7 +69,7 @@ Optional array. Each entry attaches a [configured MCP server](/mcp-servers) by n
| `enable_tools` | `["@all"]` | Tools exposed to the agent: `@all`, `@read-only`, or literal tool names. |
| `disable_tools` | `[]` | Tools subtracted from the enabled set. |
| `preload_tools` | `[]` | Tools loaded eagerly into context while the rest stay deferred. |
-| `require_approval_for_tools` | `["@write", "@destructive"]` | Tools that pause for [human approval](/create-agent/tool-approval): `@all`, `@write`, `@destructive`, or literal names. |
+| `require_approval_for_tools` | `["@write", "@destructive"]` | Tools that pause for [human approval](/create-agent/overview#tool-approval): `@all`, `@write`, `@destructive`, or literal names. |
| `preload` | `false` | Load all tool schemas upfront instead of [on demand](/key-features/deferred-tool-loading). |
The `@read-only`, `@write`, and `@destructive` selectors are resolved from the tool annotations published by the MCP server.
@@ -98,8 +98,8 @@ Runtime behavior. Every field has a default, so `config` can be omitted entirely
| `sandbox` | `{ "enabled": false }` | [Sandbox](/sandbox) for code execution, files, and skills. |
| `dynamic_sub_agents` | `{ "enabled": true }` | [Subagents](/key-features/subagents). |
| `context_management` | all enabled | [Compaction](/key-features/overview#context-compaction) and [large tool response offloading](/key-features/large-tool-responses). |
-| `generative_ui` | `{ "enabled": true }` | [Generative UI](/create-agent/generative-ui) (OpenUI blocks). |
-| `ask_user_questions` | `{ "enabled": true }` | The [`ask_user_question`](/create-agent/ask-user-questions) tool. |
+| `generative_ui` | `{ "enabled": true }` | [Generative UI](/create-agent/overview#generative-ui) (OpenUI blocks). |
+| `ask_user_questions` | `{ "enabled": true }` | The [`ask_user_question`](/create-agent/overview#ask-user-questions) tool. |
### `config.sandbox`
diff --git a/docs/create-agent/ask-user-questions.mdx b/docs/create-agent/ask-user-questions.mdx
deleted file mode 100644
index 36b10476c..000000000
--- a/docs/create-agent/ask-user-questions.mdx
+++ /dev/null
@@ -1,33 +0,0 @@
----
-title: 'Configure Ask User Questions'
-sidebarTitle: 'Ask User Questions'
-description: 'Let the agent ask structured multiple-choice questions and pause until the user answers.'
----
-
-Agents often hit decision points they should not guess — which environment to deploy to, which of several matches the user meant, or what an ambiguous required field should be. **Ask User Questions** pauses the agent, shows a multiple-choice prompt, and resumes with the chosen answer.
-
-It is **enabled by default**.
-
-## Configuring
-
-<Note>
- Enabling or disabling Ask User Questions (`config.ask_user_questions`) is configured via the **API / SDK** today. The
- chat UI already renders questions and collects answers. See the [agent spec](/create-agent/agent-spec#config).
-</Note>
-
-## How it feels in chat
-
-The agent asks a structured question with options. The user picks one (or types a free-form answer). The agent continues from where it paused.
-
-<Frame caption="The chat UI renders the question and options as a selectable card.">
- <img src="/images/ask-user-questions.png" alt="Chat UI showing an agent question with multiple-choice options" />
-</Frame>
-
-## When to use it
-
-- Choosing a target environment, cluster, account, or workspace
-- Disambiguating multiple matches ("I found 3 services named `api` — which one?")
-- Filling required fields the user did not specify
-- Picking a strategy before a destructive or expensive step
-
-Skip it when the agent can confidently infer the answer from context — over-asking turns the agent into a form.
diff --git a/docs/create-agent/generative-ui.mdx b/docs/create-agent/generative-ui.mdx
deleted file mode 100644
index f9415b622..000000000
--- a/docs/create-agent/generative-ui.mdx
+++ /dev/null
@@ -1,36 +0,0 @@
----
-title: 'Configure Generative UI'
-sidebarTitle: 'Generative UI'
-description: 'Let the agent respond with interactive charts, tables, cards, and forms instead of plain text.'
----
-
-Plain text works for short answers. For dashboards, comparisons, and structured data, **Generative UI** lets the agent stream interactive components — charts, tables, cards, forms — that the chat UI renders as React.
-
-It is **enabled by default**, and the bundled chat UI renders it out of the box.
-
-## Configuring
-
-<Note>
- Enabling or disabling Generative UI (`config.generative_ui`) is configured via the **API / SDK** today. Runtime
- rendering in the chat UI works without extra setup when the feature is enabled. See the
- [agent spec](/create-agent/agent-spec#config).
-</Note>
-
-## How it works
-
-The agent embeds a small OpenUI snippet in its normal response. The client detects it and renders real components as tokens stream in — no arbitrary code execution; only registered components can appear.
-
-<Frame caption="A Generative UI dashboard with summary cards, a chart, and a table.">
- <img src="/images/generative-ui.png" alt="Rendered Generative UI dashboard with cards, chart, and table" />
-</Frame>
-
-## When to use it
-
-| Use case | What the agent renders |
-| --- | --- |
-| Dashboards | KPI cards, charts, comparison tables |
-| Tables | Sortable logs, resources, result sets |
-| Charts | Bar, line, pie patterns faster than prose |
-| Forms | Guided inputs for the next action |
-
-Skip it for short explanations, bullet lists, or code blocks where markdown is enough.
diff --git a/docs/create-agent/overview.mdx b/docs/create-agent/overview.mdx
index e72f18396..152e07d98 100644
--- a/docs/create-agent/overview.mdx
+++ b/docs/create-agent/overview.mdx
@@ -1,6 +1,6 @@
---
title: 'Create an Agent'
-sidebarTitle: 'Select resources'
+sidebarTitle: 'Overview'
description: 'Pick a model, attach MCP servers and skills, write instructions, and save a reusable agent.'
---
@@ -12,39 +12,72 @@ An agent is a saved combination of:
2. **MCP servers** — which tools it can call
3. **Skills** — which procedures it can load
4. **Instructions** — the system prompt for this agent's role
-5. **Optional config** — sandbox, tool approvals, ask-user-questions, generative UI
+5. **Configuration** — sandbox, tool approvals, ask-user-questions, generative UI
-## In the UI
+## Build it in the UI
1. Open TrueForge and use the composer to create or edit an agent.
-2. **Select a model** from the providers you configured under Settings → Models.
+2. **Select a model** from the providers you configured under Settings → Models. Switching it later is a one-click change — no new API keys in the agent definition.
3. **Attach connectors** (MCP servers) the agent should use. Prefer only the servers it needs.
4. **Attach skills** if the agent should follow specialized procedures (requires [sandbox](/sandbox) enabled on the agent).
5. Write focused **instructions** — role, audience, and behavior. Put long playbooks in skills, not the prompt.
6. **Save** the agent so it appears in the [Agent Library](/agent-library).
<Frame caption="Save a reusable agent from the composer.">
- <img src="/images/quickstart-save-agent.png" alt="Save agent dialog in the TrueForge composer" />
+ <img src="/images/create-agent-save.png" alt="The Save agent dialog with a name, instructions, and a configuration summary of model, connectors, and skills" />
</Frame>
-## Selecting models, MCP servers, and skills
+## Configure capabilities
-| Resource | What you choose | Tips |
-| --- | --- | --- |
-| Model | One model from configured providers | Switch anytime without changing credentials |
-| MCP servers | Zero or more connectors by name | Smaller tool surface → better tool-call quality |
-| Skills | Zero or more registered skills by name | Enable sandbox when attaching skills |
+Beyond model, tools, and skills, you can tune how the agent behaves at runtime. **Generative UI**, **Ask clarifying questions**, and **Dynamic sub-agents** are toggles in the composer's **Capabilities** tab — all on by default. **Tool approval** is a per-tool policy (below).
-Switching the model is a one-click (or one-field) change. No new API keys in the agent definition.
+<Frame caption="The composer's Capabilities tab: Generative UI, Dynamic sub-agents, and Ask clarifying questions — all on by default.">
+ <img src="/images/create-agent-capabilities.png" alt="The composer Capabilities tab with Generative UI, Dynamic sub-agents, and Ask clarifying questions toggled on" />
+</Frame>
+
+### Tool approval
+
+Some actions — deploying, deleting data, sending refunds — shouldn't run without explicit consent. **Tool approval** (human in the loop) pauses the agent before a sensitive MCP tool call, shows the tool name and arguments, and resumes only after the user approves or denies. Safe read-only tools stay autonomous.
+
+Approval policy is set **per MCP server**. The default gates write and destructive tools — anything the server doesn't mark read-only; you can also list specific tools or gate every tool ([`mcp_servers`](/create-agent/agent-spec#mcp_servers)).
+
+<Frame caption="The chat UI pauses on a sensitive tool call with Allow / Deny.">
+ <img src="/images/hitl.png" alt="Chat UI pausing on a tool call, showing the request payload with Allow and Deny buttons" />
+</Frame>
+
+Use approvals for state changes, irreversible actions, production impact, external communications, or expensive operations. Skip them for safe reads (list, fetch, search). Approval doesn't replace authorization — it only decides whether a pending call should proceed.
+
+### Ask user questions
+
+Agents often hit decision points they shouldn't guess — which environment to deploy to, which of several matches the user meant, or what an ambiguous required field should be. **Ask User Questions** pauses the agent, shows a multiple-choice prompt, and resumes with the chosen answer. It's on by default; toggle it in the composer's **Capabilities** tab.
+
+<Frame caption="The chat UI renders the question and options as a selectable card.">
+ <img src="/images/ask-user-questions.png" alt="Chat UI showing an agent question with multiple-choice options and a Submit button" />
+</Frame>
+
+Good for: choosing a target environment or account, disambiguating multiple matches, filling required fields the user didn't specify, or picking a strategy before a destructive step. Skip it when the agent can confidently infer the answer — over-asking turns the agent into a form.
+
+### Generative UI
+
+For dashboards, comparisons, and structured data, **Generative UI** lets the agent stream interactive components — charts, tables, cards, forms — that the chat UI renders as React. It's on by default; toggle it in the composer's **Capabilities** tab. The agent embeds a small OpenUI snippet in its response; the client renders real components as tokens stream in — no arbitrary code execution, only registered components.
+
+<Frame caption="A Generative UI response with a chart rendered inline in chat.">
+ <img src="/images/generative-ui.png" alt="Rendered Generative UI response with an inline bar chart comparing options" />
+</Frame>
+
+| Use case | What the agent renders |
+| --- | --- |
+| Dashboards | KPI cards, charts, comparison tables |
+| Tables | Sortable logs, resources, result sets |
+| Charts | Bar, line, pie patterns faster than prose |
+| Forms | Guided inputs for the next action |
+
+Skip it for short explanations, bullet lists, or code blocks where markdown is enough.
-## Related configuration
+### Dynamic sub-agents
-These knobs are available on the agent today primarily through the **API / SDK** (not yet fully exposed in the builder UI):
+For multi-step work across several sources, the agent can delegate focused subtasks to parallel **subagents** and merge only their results — keeping its own context clean. On by default. See [Subagents](/key-features/subagents) for how it works.
-| Capability | Default | Docs |
-| --- | --- | --- |
-| [Tool approval](/create-agent/tool-approval) | Write/destructive tools pause for approval | Configure which tools require confirmation |
-| [Ask User Questions](/create-agent/ask-user-questions) | Enabled | Let the agent ask structured multiple-choice questions |
-| [Generative UI](/create-agent/generative-ui) | Enabled | Let the agent render charts, tables, and cards |
+## Agent spec reference
-For the full field list, see the [Agent Spec reference](/create-agent/agent-spec).
+For the full field list — `model`, `instructions`, `mcp_servers`, `skills`, `config`, and more — see the [Agent Spec reference](/create-agent/agent-spec).
diff --git a/docs/create-agent/tool-approval.mdx b/docs/create-agent/tool-approval.mdx
deleted file mode 100644
index b9952bd82..000000000
--- a/docs/create-agent/tool-approval.mdx
+++ /dev/null
@@ -1,33 +0,0 @@
----
-title: 'Configure Tool Approval'
-sidebarTitle: 'Tool approval'
-description: 'Pause sensitive MCP tool calls so the user can approve or deny before they run.'
----
-
-Some actions — deploying, deleting data, sending refunds — should not run without explicit consent. **Tool approval** (human in the loop) pauses the agent before a sensitive MCP tool call, shows the tool name and arguments, and resumes only after the user approves or denies.
-
-Safe read-only tools stay autonomous. Write and destructive tools get a checkpoint.
-
-## Configuring which tools require approval
-
-<Note>
- Today, configuring `require_approval_for_tools` (and related enable/disable tool lists) is done via the **API / SDK**
- when you create or update an agent. The chat UI already handles the Approve / Deny experience at runtime, but the
- builder does not yet expose the full approval policy editor. See the [agent spec](/create-agent/agent-spec#mcp_servers).
-</Note>
-
-Approval policy is set **per MCP server** on the agent. The default is write and destructive tools — any tool the MCP server does not mark as read-only, or marks as destructive. You can also list specific tool names, or gate every tool.
-
-## How it feels in chat
-
-When a gated tool is requested, the bundled chat UI pauses the run and shows **Approve / Deny** with the request payload. Approve to execute; deny to return a reason to the agent so it can adjust its plan.
-
-<Frame caption="The chat UI pauses on a sensitive tool call with Approve / Deny.">
- <img src="/images/hitl.png" alt="Chat UI pausing on a tool call with Approve and Deny buttons" />
-</Frame>
-
-## When to use approvals
-
-Use them for state changes, irreversible actions, production impact, external communications, or expensive operations. Skip them for safe reads (list, fetch, search) where confirmation only adds friction.
-
-Approvals do not replace authorization — the user still needs access to the underlying tool; approval only decides whether this pending call should proceed.
diff --git a/docs/docs.json b/docs/docs.json
index 968a5043c..2a5aedfd4 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -1,6 +1,11 @@
{
"$schema": "https://mintlify.com",
"theme": "mint",
+ "redirects": [
+ { "source": "/create-agent/tool-approval", "destination": "/create-agent/overview#tool-approval" },
+ { "source": "/create-agent/ask-user-questions", "destination": "/create-agent/overview#ask-user-questions" },
+ { "source": "/create-agent/generative-ui", "destination": "/create-agent/overview#generative-ui" }
+ ],
"name": "TrueForge",
"logo": {
"light": "/logo/light.svg",
@@ -44,13 +49,7 @@
},
{
"group": "Create an Agent",
- "pages": [
- "create-agent/overview",
- "create-agent/tool-approval",
- "create-agent/ask-user-questions",
- "create-agent/generative-ui",
- "create-agent/agent-spec"
- ]
+ "pages": ["create-agent/overview", "create-agent/agent-spec"]
},
"agent-library",
{
diff --git a/docs/images/ask-user-questions.png b/docs/images/ask-user-questions.png
index 8a133cdc5..c96a7ee6b 100644
Binary files a/docs/images/ask-user-questions.png and b/docs/images/ask-user-questions.png differ
diff --git a/docs/images/create-agent-capabilities.png b/docs/images/create-agent-capabilities.png
new file mode 100644
index 000000000..0e7f84204
Binary files /dev/null and b/docs/images/create-agent-capabilities.png differ
diff --git a/docs/images/create-agent-save.png b/docs/images/create-agent-save.png
new file mode 100644
index 000000000..cb0d6c5cd
Binary files /dev/null and b/docs/images/create-agent-save.png differ
diff --git a/docs/images/generative-ui.png b/docs/images/generative-ui.png
index aede05b14..6aaf15626 100644
Binary files a/docs/images/generative-ui.png and b/docs/images/generative-ui.png differ
diff --git a/docs/images/hitl.png b/docs/images/hitl.png
index 4b9e87b27..91327a640 100644
Binary files a/docs/images/hitl.png and b/docs/images/hitl.png differ
diff --git a/docs/introduction.mdx b/docs/introduction.mdx
index cf21e0494..d51264ace 100644
--- a/docs/introduction.mdx
+++ b/docs/introduction.mdx
@@ -56,7 +56,7 @@ flowchart LR
Runs the agent loop. When a user sends a message, the server:
- Plans the turn, calls the model, and executes tools — streaming every step back
-- Pauses for [human approval](/create-agent/tool-approval) on sensitive actions
+- Pauses for [human approval](/create-agent/overview#tool-approval) on sensitive actions
- Keeps context lean on long tasks with [key features](/key-features/overview) like subagents and compaction
- Persists sessions, so conversations survive reconnects and restarts
diff --git a/docs/key-features/code-mode.mdx b/docs/key-features/code-mode.mdx
index 44b80d87c..c735147a8 100644
--- a/docs/key-features/code-mode.mdx
+++ b/docs/key-features/code-mode.mdx
@@ -55,7 +55,7 @@ sequenceDiagram
Code Mode is available whenever the agent's [sandbox](/sandbox) is enabled. The agent decides at runtime whether a task is worth running in code or whether a single direct tool call is enough. Before writing a script, it can call [`get_tool_output_schema`](/key-features/deferred-tool-loading#how-it-works) so it knows the exact shape of a tool's response instead of guessing keys from raw JSON.
<Note>
- [Approval policies](/create-agent/tool-approval) still apply in Code Mode — a script that calls a tool matching
+ [Approval policies](/create-agent/overview#tool-approval) still apply in Code Mode — a script that calls a tool matching
`require_approval_for_tools` pauses for user approval just like a direct tool call.
</Note>
diff --git a/docs/key-features/overview.mdx b/docs/key-features/overview.mdx
index 0a9d5ee2e..95928bab0 100644
--- a/docs/key-features/overview.mdx
+++ b/docs/key-features/overview.mdx
@@ -10,9 +10,9 @@ TrueForge is more than model + tools. These harness features keep long agent run
| --- | --- |
| [Sandbox as a tool](/sandbox) | Isolated code/file execution without putting secrets or the agent loop inside the sandbox |
| [Context engineering](#what-is-context-engineering) | Progressive skills, deferred tools, subagents, offloading, Code Mode, compaction |
-| [Tool approval](/create-agent/tool-approval) | Pause before write/destructive MCP tools |
-| [Ask User Questions](/create-agent/ask-user-questions) | Structured clarification mid-run |
-| [Generative UI](/create-agent/generative-ui) | Charts, tables, and cards streamed into chat |
+| [Tool approval](/create-agent/overview#tool-approval) | Pause before write/destructive MCP tools |
+| [Ask User Questions](/create-agent/overview#ask-user-questions) | Structured clarification mid-run |
+| [Generative UI](/create-agent/overview#generative-ui) | Charts, tables, and cards streamed into chat |
| [In-chat MCP OAuth](/mcp-servers#in-chat-authentication) | Connect button when a connector needs authorization |
## Sandbox as a tool
diff --git a/docs/key-features/subagents.mdx b/docs/key-features/subagents.mdx
index 314696de2..7deca87df 100644
--- a/docs/key-features/subagents.mdx
+++ b/docs/key-features/subagents.mdx
@@ -65,7 +65,7 @@ flowchart LR
<Note>
- **Shared tools and sandbox** — subagents have access to the same MCP tools and sandbox environment as the root
agent. - **No user interaction** — subagents cannot ask the user questions. Only the root agent talks to the user.
- Subagent tool calls that require [approval](/create-agent/tool-approval) still pause for the user, though. - **No nesting** —
+ Subagent tool calls that require [approval](/create-agent/overview#tool-approval) still pause for the user, though. - **No nesting** —
subagents cannot create other subagents. Delegation is one level deep. - **Parallel execution** — multiple subagents
run concurrently. The root agent waits for all of them before continuing.
</Note>
diff --git a/docs/mcp-servers.mdx b/docs/mcp-servers.mdx
index cc69afa3f..8f54e598d 100644
--- a/docs/mcp-servers.mdx
+++ b/docs/mcp-servers.mdx
@@ -57,5 +57,5 @@ If a server uses OAuth and the user has not yet authorized it, the turn pauses a
## Next steps
- Attach MCP servers when you [create an agent](/create-agent/overview).
-- Configure which tools need [approval](/create-agent/tool-approval) (API today).
+- Configure which tools need [approval](/create-agent/overview#tool-approval) (API today).
- Keep tool schemas lean with [deferred loading](/key-features/deferred-tool-loading) in Key Features.