Agents and automation
Agents tools for assistants (MCP)
The 4 tools an assistant can call for Agents over MCP: what each one does, the scopes it needs, its arguments and an example call.
The agents your account runs in its own networks: enrol one, list and read them, run a check on one, and revoke or delete it. It also records what each service runs against its repository's latest commit, and the account's engineering work. Use it to see what your agents can reach and to keep a record of what was shipped where. An assistant calls these tools over MCP; the same operations over HTTP are in the Agents API. Tools for assistants lists every product, and MCP shows how to connect an assistant.
agents_list_agents
List agents. The account's agents, newest first.
Scopes: mcp:read, agents:read · reads only
| Argument | Type | What it is |
|---|---|---|
account_id | string | The account's id; an alias of org_id. Leave both out for the caller's own account. |
org_id | string | |
page_size | integer | Agents per page: 0 means 50, above 200 is read as 200. |
page_token | string | The previous page's next_page_token: opaque and URL-safe; anything else is INVALID_ARGUMENT. |
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "agents_list_agents",
"arguments": {
"page_size": 20
}
}
}agents_get_agent
Get agent. One agent.
Scopes: mcp:read, agents:read · reads only
| Argument | Type | What it is |
|---|---|---|
account_id | string | The account's id; an alias of org_id. Leave both out for the caller's own account. |
agent_id | string | |
org_id | string |
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "agents_get_agent",
"arguments": {
"agent_id": "agt_01JD8Z3QK4W5X6Y7Z8A9B0C1D2"
}
}
}agents_list_deployments
List deployments. What each service runs per environment against the head of its repository's default branch: a summary (services, current, behind, unknown), then each service's commit, when it was deployed and its state. behind means merged work waits for a deploy; unknown means no head is recorded. Filter by environment or status; 0 means 100 per page, at most 500.
Scopes: mcp:read, agents:read · reads only
| Argument | Type | What it is |
|---|---|---|
account_id | string | The account's id; an alias of org_id. Leave both out for the caller's own account. |
environment | string | Only this environment; every environment when empty. |
org_id | string | |
page_size | integer | Deployments per page: 0 means 100, above 500 is read as 500. |
page_token | string | The previous page's next_page_token: opaque and URL-safe; anything else is INVALID_ARGUMENT. |
status | string | Only this state: "current", "behind" or "unknown"; all when empty. |
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "agents_list_deployments",
"arguments": {
"page_size": 20
}
}
}agents_list_work
List work. The account's engineering work, newest first: changes opened and merged, checks passed or failed, deployments, decisions moved, each with who did it (person, ai, agent or automation), when, and a link. Filter by kind (change, check, deployment, decision, release, note) and from (RFC 3339); 0 means 50 per page, at most 200.
Scopes: mcp:read, agents:read · reads only
| Argument | Type | What it is |
|---|---|---|
account_id | string | The account's id; an alias of org_id. Leave both out for the caller's own account. |
from | string | Only work after this RFC 3339 time; all when empty. |
kind | string | Only this kind; every kind when empty. |
org_id | string | |
page_size | integer | Lines per page: 0 means 50, above 200 is read as 200. |
page_token | string | The previous page's next_page_token: opaque and URL-safe. |
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "agents_list_work",
"arguments": {
"page_size": 20
}
}
}