Skip to main content
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.

​
Before you begin

  • Connect your client 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.
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

Inspect tools without running them
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

Use Adam tools in the same task
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

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

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. A tool’s presence does not prove the native application is ready.
  • Usage or subscription is required: review billing and the operation’s requirements. Inspect the existing call before submitting another.
For connection and rate-limit failures, see MCP troubleshooting.
Last modified on October 14, 2026