docs: add Pods "Agent tools" page documenting the Pods skill

docs.json

@@ -295,6 +295,7 @@
           "docs/user-documentation/pods/conversations",
           "docs/user-documentation/pods/files",
           "docs/user-documentation/pods/frames",
+          "docs/user-documentation/pods/agent-tools",
           "docs/user-documentation/pods/admin-controls",
           {
             "group": "Examples",

docs/user-documentation/pods/agent-tools.mdx

@@ -0,0 +1,94 @@
+---
+title: "Agent tools"
+description: "The full list of tools agents get through the Pods skill to work with Pods, conversations, tasks, files, and settings."
+---
+
+A core principle of Pods: **everything a human can do, an agent can do**. This is made possible by the **Pods skill**, which is available to all agents by default, including the global Dust agent, agents invoked inside a Pod, and triggered agents. The Pods skill provides a set of **tools**: the individual actions listed on this page.
+
+<Info>
+**A note on naming.** You may hear these referred to as "Pod tools". The precise naming: agents have one **Pods skill**, and that skill provides the **tools** below. Each individual action, such as `create_tasks`, is a tool.
+</Info>
+
+There is nothing to enable or configure: when an agent works in or around a Pod, it picks the right tool on its own. The tool names below are the ones shown in the agent's tool execution details during a run, so you can also use this page to follow what an agent did.
+
+## Pod management
+
+### Finding and creating Pods
+
+| Tool               | What it does                                                                                            |
+| ------------------ | ------------------------------------------------------------------------------------------------------- |
+| `list_pods`        | List the Pods the agent can access: the user's Pods by default, or all Open Pods in the workspace        |
+| `create_pod`       | Create a new Pod (Restricted by default), optionally with initial members and a set of starter tasks     |
+| `get_information`  | Read a Pod's metadata: URL, title, description, visibility, pinned Frame, and linked Company Data        |
+| `edit_information` | Update a Pod's title, description, or visibility (Open or Restricted)                                    |
+
+### Members
+
+| Tool             | What it does                                                        |
+| ---------------- | -------------------------------------------------------------------- |
+| `list_members`   | List everyone in the Pod with their role (Member or Editor)          |
+| `update_members` | Invite, add, remove, promote, or demote Pod members and Editors      |
+
+### Conversations
+
+| Tool                          | What it does                                                                          |
+| ----------------------------- | -------------------------------------------------------------------------------------- |
+| `create_conversation`         | Start a new conversation in the Pod, optionally triggering another agent on a task      |
+| `add_message_to_conversation` | Post a follow-up message to an existing Pod conversation                                |
+| `list_conversations`          | List recent Pod conversations, optionally unread ones only or with full transcripts     |
+| `move_conversation`           | Move a conversation into a Pod, or out of a Pod back to personal conversations          |
+
+### Knowledge
+
+| Tool                        | What it does                                                                              |
+| --------------------------- | ------------------------------------------------------------------------------------------ |
+| `semantic_search`           | Search Pod files, linked Company Data, and Pod conversation transcripts by meaning          |
+| `retrieve_recent_documents` | Fetch the most recently added or updated documents in the Pod's knowledge                   |
+| `add_content_node`          | Link a document or folder from Company Data to the Pod's knowledge                          |
+| `remove_content_node`       | Unlink a Company Data reference from the Pod                                                |
+
+### Pod settings
+
+| Tool                | What it does                                                                                |
+| ------------------- | --------------------------------------------------------------------------------------------- |
+| `set_pinned_frame`  | Pin a [Frame](/docs/user-documentation/pods/frames) as the Pod banner, or unpin the current one |
+| `set_default_agent` | Set or reset the agent that handles new conversations started in the Pod                        |
+
+## Tasks
+
+| Tool               | What it does                                                                                       |
+| ------------------ | ---------------------------------------------------------------------------------------------------- |
+| `list_tasks`       | List the Pod's tasks, filtered by assignee (mine or all) and status (open, done, or all)              |
+| `create_tasks`     | Create up to 30 tasks at once, assigned to a Pod member or left unassigned                            |
+| `update_tasks`     | Update task descriptions, assignees, and states, including marking tasks done                         |
+| `start_task_agent` | Start an agent on an open task: creates the linked conversation and moves the task to **In progress** |
+
+See [Tasks](/docs/user-documentation/pods/tasks) for how these show up in the Tasks tab, including syncing with external tools like Jira, Asana, or Linear.
+
+## Files
+
+Agents work with Pod files through Dust's shared file system tools rather than Pod-specific tools. Inside a Pod, these let an agent:
+
+- List and browse the Pod's files and folders
+- Read file contents
+- Create new files, including agent-generated artifacts such as [Frames](/docs/user-documentation/pods/frames)
+- Edit, copy, move, and delete existing files
+- Import a file into the Pod from a URL
+
+Files created or updated by agents appear in the [Files tab](/docs/user-documentation/pods/files) and are immediately available to all Pod members and other agents.
+
+## Permissions
+
+Agent tools follow the same permission model as the Dust interface: an agent acting on behalf of a user can only do what that user could do themselves.
+
+- A Restricted Pod the user is not a member of is not accessible to their agents
+- Managing membership, settings, visibility, and the pinned Frame requires the user to be a Pod **Editor**
+
+See [Members and roles](/docs/user-documentation/pods/members-and-roles) for the full role breakdown, and [Admin controls](/docs/user-documentation/pods/admin-controls) for workspace-level policies.
+
+## See it in action
+
+These tools are what make Pods a natural target for automations: a triggered agent can post a daily brief into a Pod, open a conversation when a ticket arrives, or keep Pod tasks in sync with an external tool.
+
+- [Conversations](/docs/user-documentation/pods/conversations) and [Tasks](/docs/user-documentation/pods/tasks): concrete patterns
+- Examples: [Ticket handling and support knowledge](/docs/user-documentation/pods/examples/ticket-handling-and-support-knowledge), [One Pod per customer](/docs/user-documentation/pods/examples/one-pod-per-customer), [Competitive intelligence](/docs/user-documentation/pods/examples/competitive-intelligence)

docs/user-documentation/pods/conversations.mdx

@@ -15,7 +15,7 @@ The **Conversations tab** lists all conversations created inside the Pod. Every
 
 **As an agent:**
 
-Agents can create and post to conversations in a Pod directly, for example to share a progress update, post a weekly summary, or surface findings from a background task. These conversations appear in the same list and are visible to all members. This is made possible by the **Pods skill**, which is available to all agents by default. See the [Overview](/docs/user-documentation/pods/overview) for more details.
+Agents can create and post to conversations in a Pod directly, for example to share a progress update, post a weekly summary, or surface findings from a background task. These conversations appear in the same list and are visible to all members. This is made possible by the **Pods skill**, which is available to all agents by default. See [Agent tools](/docs/user-documentation/pods/agent-tools) for the full list of tools the skill provides.
 
 <Info>
 **Every conversation in a Pod is automatically indexed. Agents can search and reference past conversations as context, without you doing anything.**
@@ -37,7 +37,7 @@ It is possible to have an external event (a ticket, a webhook, a scheduled trigg
 This is done by setting up a **triggered agent** and instructing it to create or post to a specific Pod:
 
 1. Create a triggered agent (e.g. from a Jira webhook, a Slack trigger, or the wake-up tool)
-2. In the agent's instructions, specify which Pod to post into. The agent can look it up by name using the Pods skill's list tool
+2. In the agent's instructions, specify which Pod to post into. The agent can look it up by name using the Pods skill's `list_pods` tool
 3. When triggered, the agent creates a conversation in the target Pod with the relevant context
 
 Common patterns:

docs/user-documentation/pods/files.mdx

@@ -16,7 +16,7 @@ The **Files tab** is the shared knowledge library of the Pod. It holds uploaded
 
 **As an agent:**
 
-Agents can upload files to the Pod directly, for example to save a report, store a generated document, or persist output from a workflow. Files created by agents appear in the same list and are immediately available to all members and other agents. This is made possible by the **Pods skill**, which is available to all agents by default. See the [Overview](/docs/user-documentation/pods/overview) for more details.
+Agents can upload files to the Pod directly, for example to save a report, store a generated document, or persist output from a workflow. Files created by agents appear in the same list and are immediately available to all members and other agents. This is made possible by the **Pods skill**, which is available to all agents by default. See [Agent tools](/docs/user-documentation/pods/agent-tools) for the full list of tools the skill provides.
 
 ## How to organise files into folders
 

docs/user-documentation/pods/overview.mdx

@@ -13,12 +13,16 @@ A core principle of Pods: **everything a human can do, an agent can do**. Agents
 
 ## The Pods skill
 
-Agents interact with Pods through the **Pods skill**, which is available to all agents by default, including the global Dust agent, agents invoked inside a Pod, and triggered agents. It lets agents:
+Agents interact with Pods through the **Pods skill**, which is available to all agents by default, including the global Dust agent, agents invoked inside a Pod, and triggered agents. The skill provides a set of tools that let agents:
 
 - List and look up Pods by name
 - Create and post to conversations in a Pod
 - Create, pick up, progress, and complete tasks
 - Upload and read files in the Pod's Files tab
+- Search the Pod's knowledge and link data from Company Data
+- Create Pods and manage members, settings, and the pinned Frame (with Editor permissions)
+
+For the complete list of tools and what each one does, see [Agent tools](/docs/user-documentation/pods/agent-tools).
 
 This makes Pods a natural target for automations: a triggered agent can post a daily brief into a Pod, open a conversation when a ticket arrives, or keep Pod tasks in sync with an external tool. See [Conversations](/docs/user-documentation/pods/conversations) and [Tasks](/docs/user-documentation/pods/tasks) for concrete patterns.
 
@@ -42,4 +46,5 @@ Every Pod member is either a **Member** or an **Editor**. Members participate in
 - [Tasks](/docs/user-documentation/pods/tasks): define, assign, and automate work
 - [Files](/docs/user-documentation/pods/files): build the Pod's shared knowledge library
 - [Frames](/docs/user-documentation/pods/frames): pin live dashboards as the Pod banner
+- [Agent tools](/docs/user-documentation/pods/agent-tools): the full list of tools agents get through the Pods skill
 - Examples: [Shared asset library](/docs/user-documentation/pods/examples/shared-asset-library), [One Pod per customer](/docs/user-documentation/pods/examples/one-pod-per-customer), [Initiative and project management](/docs/user-documentation/pods/examples/initiative-and-project-management), and more

docs/user-documentation/pods/tasks.mdx

@@ -5,7 +5,7 @@ title: "Tasks"
 
 The **Tasks tab** is where work gets defined, assigned, and executed. Tasks are lightweight items that describe something that needs to happen. Any Pod member can create them, assign them, and start an agent on them. Agents can do the same: create tasks, start working on them, and mark them done, all without a human in the loop.
 
-This reflects a core principle of Pods: **everything a human can do, an agent can do**. Agents interact with Tasks through the **Pods skill**, which is available to all agents by default. See the [Overview](/docs/user-documentation/pods/overview) for more details.
+This reflects a core principle of Pods: **everything a human can do, an agent can do**. Agents interact with Tasks through the **Pods skill**, which is available to all agents by default. See [Agent tools](/docs/user-documentation/pods/agent-tools) for the full list of tools the skill provides.
 
 
 ## How to create a task