> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adam.new/llms.txt
> Use this file to discover all available pages before exploring further.

# Run Adam tools from your AI client

> Let a connected client run individual tools in an Adam task, follow durable results, and recover without duplicating work.

Your AI client can control individual Adam tools inside a task you own. This gives the client access to Adam's execution environment while keeping the work, files, and history in one task. Each direct tool call runs without starting an Adam agent loop.

To have Adam's agent plan and perform the work instead, [delegate an Adam task](https://docs.adam.new/mcp/overview.md#delegate-an-engineering-task).

## Before you begin

* [Connect your client](https://docs.adam.new/mcp/connect.md) to the intended Adam workspace.
* Grant `tasks:read`, `tasks:write`, and `tools:execute` for the full discovery, execution, and result-reading workflow. Add file or project permissions when those operations are needed.
* Use a main task you own. A shared task you can view or edit is not sufficient for this direct execution path. If the task belongs to a project, you also need project edit access.
* Confirm that your workspace allows API/MCP access and full execution, and that the requested operation has the required integrations, workstation, license, and Adam usage.

> [!NOTE]
>
> `tools:execute` grants broad execution authority: commands, workspace files, connected accounts, paired devices, stored credentials, and billable tools. It is broader than the individual project, task, and file read/write permissions. Enable it for clients you intend to give that authority. Workspace owners and admins control it under **Admin > API & MCP > Allow full harness execution**.

## Start with discovery

```text title="Inspect tools without running them" wrap theme={null}
In my Adam task [task ID], read the current state and list the available tools and their input requirements. Identify which tools could inspect [model or file] and any unavailable-tool reasons. Do not execute tools, create a new task, or start an Adam agent.
```

Discovery returns tool names, input schemas, an `available` flag, and an optional `unavailableReason`. It does not run the tools or provision compute. An available tool still needs its application, credentials, runtime, and other prerequisites when executed.

## Run a controlled operation

```text title="Use Adam tools in the same task" wrap theme={null}
Continue my Adam task [task ID] using its tools. First inspect the current task and files, then discover the current tool schemas. Use an available read-only operation to report the units and overall dimensions of [model]. Keep the source unchanged and save the findings in this task. Wait for each operation's result before deciding the next step.
```

For new work, the client can create a task with your design brief without starting Adam's agent. Creating that task does not select a model, perform inference, or provision compute. Subsequent tool execution may consume usage, and some tools can start additional work.

### Tool sequence

| Step | MCP tool | Required permissions |
| - | - | - |
| Identify the workspace | `adam_get_context` | An authenticated, allowed connection |
| Create a task for client-driven work | `adam_create_external_task` | `tasks:write` |
| Discover tools and their schemas | `adam_list_task_tools` | `tasks:read` |
| Queue one operation | `adam_call_task_tool` | `tasks:write` and `tools:execute` |
| Read the operation's status and result | `adam_get_tool_call` | `tasks:read` and `tools:execute` |
| Inspect a child task started by a tool | `adam_get_subagent` | `tasks:read` and `tools:execute` |

Use an existing task when continuing work. Pass the saved request as `prompt` when creating a new external task, then use the exact tool name and input schema returned by discovery. Do not create a new task for each operation.

Creating an external task and queuing a tool call require an `idempotencyKey`. Use a new key for a new operation and reuse the same key and input when retrying that operation. Keep the returned tool-call ID to retrieve its outcome. The Adam task ID, tool-call ID, and any MCP Tasks transport handle are different identifiers. Direct calls are tracked with `adam_get_tool_call`, not MCP Tasks handles.

## Read the result before continuing

| Tool-call status | What to do |
| - | - |
| `queued` or `running` | Check the same call ID until it finishes. |
| `succeeded` | Inspect the output and generated files before starting dependent work. |
| `failed` | Read the returned error and check the affected document before retrying a possible change. |
| `unknown` | Treat the outcome as unresolved. The operation may have taken effect. Inspect the model, files, or child-task state; do not automatically repeat it with a new key. |

Results can be truncated, and file access depends on the connection's permissions. Use returned file resources to open or download outputs. If a tool launched a child task, `adam_get_subagent` can look it up using the parent task and either the child task ID or the launch tool-call ID.

## Continue with Adam's agent

Wait for active work to finish, then ask the client to send the next instruction to the same Adam task. Sending a message starts Adam's agent for that turn. After it finishes, your client can resume direct tools in the same task. Ask to show the task explicitly if you want its panel; polling its state does not open one.

## Recover from access or execution errors

* **Execution tools are missing:** inspect your granted scopes and the workspace's **Allow full harness execution** setting. Reconnecting cannot override an administrator's restriction.
* **Task not found or project access denied:** verify the workspace, task ownership, and project edit access. Direct tools require a main task you own.
* **Work is already running:** follow the existing operation instead of starting competing work in the same task.
* **An application is unavailable:** use its [connection guide](https://docs.adam.new/supported-software.md). A tool's presence does not prove the native application is ready.
* **Usage or subscription is required:** review [billing](https://docs.adam.new/admin/billing.md) and the operation's requirements. Inspect the existing call before submitting another.

For connection and rate-limit failures, see [MCP troubleshooting](https://docs.adam.new/mcp/connect.md#troubleshooting).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.