# ToolCall

> Tool calls: every integration run, capability call and agent tool call your platform work made, newest first.

```python
page = noclick.ToolCall.list_page(tool="gmail.*", status="error", user_filter=noclick.ALL_USERS)
```

## noclick.ToolCall

```python
class ToolCall
```

One recorded tool call. `tool_name` is the name policy judges it by: dotted
(`gmail.send_email_message`), or a capability's own (`search`, `fetch`, an agent's too).
`source` is `api` (your own calls), `agent` (your agents' turns) or
`mcp_server` (an MCP client's, through the hosted server `mcp_server_id`).

| Attribute | Type | Description |
| --- | --- | --- |
| `id` | `str` |  |
| `tool_name` | `str` |  |
| `tool_type` | `str | None` |  |
| `operation` | `str | None` |  |
| `status` | `str | None` |  |
| `error` | `str | None` |  |
| `arguments` | `dict[str, Any]` |  |
| `result_preview` | `str | None` |  |
| `duration_ms` | `int | None` |  |
| `credential_id` | `str | None` |  |
| `user_id` | `str | None` |  |
| `agent_id` | `str | None` |  |
| `conversation` | `str | None` |  |
| `execution_id` | `str | None` |  |
| `source` | `str | None` |  |
| `created_at` | `Any` |  |
| `raw` | `dict[str, Any]` | The response JSON exactly as the API sent it. |
| `mcp_server_id` | `str | None` |  |
| `connection` | `str | None` | The connection it ran on, as the account names it (a named connection's name, else its name in the app). |

### ToolCall.list

```python
noclick.ToolCall.list(
    *, agent=None, tool=None, status=None, source=None, since=None, until=None,
    limit=None, user_filter=None, user=..., client=None
) -> list[ToolCall]
```

Every matching call (or the first `limit`). `tool` is a name or a
`*` pattern (`gmail.*`); `status` `success`/`error`;
`source` `api` (your calls), `agent` (your agents' turns) or
`mcp_server` (MCP clients' calls through your hosted servers).

Parameters:

- `agent` (`Any`, default `None`)
- `tool` (`str | None`, default `None`)
- `status` (`str | None`, default `None`)
- `source` (`str | None`, default `None`)
- `since` (`Any`, default `None`)
- `until` (`Any`, default `None`)
- `limit` (`int | None`, default `None`): Return at most this many.
- `user_filter` (`Any`, default `None`): Which users a read covers: `noclick.ALL_USERS`, `noclick.NO_USER`, a `User`, or your id for one. It filters without acting as that user.
- `user` (`Any`, default: the current user): Who the call acts for. Defaults to the user set by `noclick.as_user` (none: the account itself).
- `client` (`Client | None`, default `None`): The client to send with; defaults to the module client built from `NOCLICK_API_KEY`.

Returns: `list[ToolCall]` Every matching call, newest first, fetched page by page.

Usage:

See which Gmail calls your agents got wrong in the last day:

```python
from datetime import datetime, timedelta, timezone

yesterday = datetime.now(timezone.utc) - timedelta(days=1)
for call in noclick.ToolCall.list(tool="gmail.*", status="error", source="agent", since=yesterday):
    print(call.tool_name, call.error)
```

Or one agent's calls, across every user:

```python
support = noclick.Agent.from_name("support")
calls = noclick.ToolCall.list(agent=support, user_filter=noclick.ALL_USERS, limit=50)
```

Or what MCP clients did through a user's hosted server:

```python
server = noclick.McpServer.from_name("crm-tools", user="acme")
for call in noclick.ToolCall.list(source="mcp_server", user="acme", limit=50):
    if call.mcp_server_id == server.id:
        print(call.tool_name, call.status, call.created_at)
```

### ToolCall.list_page

```python
noclick.ToolCall.list_page(
    *, cursor=None, limit=None, agent=None, tool=None, status=None, source=None,
    since=None, until=None, user_filter=None, user=..., client=None
) -> Page
```

One page of matching calls; pass `next_cursor` back as `cursor`.

Parameters:

- `cursor` (`str | None`, default `None`): The `next_cursor` of the page before; omit it for the first page.
- `limit` (`int | None`, default `None`): Return at most this many.
- `agent` (`Any`, default `None`)
- `tool` (`str | None`, default `None`)
- `status` (`str | None`, default `None`)
- `source` (`str | None`, default `None`)
- `since` (`Any`, default `None`)
- `until` (`Any`, default `None`)
- `user_filter` (`Any`, default `None`): Which users a read covers: `noclick.ALL_USERS`, `noclick.NO_USER`, a `User`, or your id for one. It filters without acting as that user.
- `user` (`Any`, default: the current user): Who the call acts for. Defaults to the user set by `noclick.as_user` (none: the account itself).
- `client` (`Client | None`, default `None`): The client to send with; defaults to the module client built from `NOCLICK_API_KEY`.

Returns: `Page` A page whose `data` holds up to `limit` calls (at most 200) and whose `next_cursor`
is `None` on the last page.

Usage:

```python
page = noclick.ToolCall.list_page(status="error", limit=200)
while True:
    for call in page.data:
        print(call.tool_name, call.error)
    if page.next_cursor is None:
        break
    page = noclick.ToolCall.list_page(status="error", limit=200, cursor=page.next_cursor)
```

### ToolCall.summary

```python
noclick.ToolCall.summary(
    *, agent=None, tool=None, status=None, source=None, since=None, until=None,
    user_filter=None, user=..., client=None
) -> ToolCallSummary
```

How many calls match the same filters, and how many errored.

Parameters:

- `agent` (`Any`, default `None`)
- `tool` (`str | None`, default `None`)
- `status` (`str | None`, default `None`)
- `source` (`str | None`, default `None`)
- `since` (`Any`, default `None`)
- `until` (`Any`, default `None`)
- `user_filter` (`Any`, default `None`): Which users a read covers: `noclick.ALL_USERS`, `noclick.NO_USER`, a `User`, or your id for one. It filters without acting as that user.
- `user` (`Any`, default: the current user): Who the call acts for. Defaults to the user set by `noclick.as_user` (none: the account itself).
- `client` (`Client | None`, default `None`): The client to send with; defaults to the module client built from `NOCLICK_API_KEY`.

Returns: `ToolCallSummary` The `total`, split into `success` and `error`.

Usage:

```python
from datetime import datetime, timedelta, timezone

yesterday = datetime.now(timezone.utc) - timedelta(days=1)
counts = noclick.ToolCall.summary(tool="gmail.*", since=yesterday)
print(counts.total, counts.success, counts.error)
```

## noclick.ToolCallSummary

```python
class ToolCallSummary
```

How many calls match, and how many of them errored.

| Attribute | Type | Description |
| --- | --- | --- |
| `total` | `int` |  |
| `success` | `int` |  |
| `error` | `int` |  |
| `raw` | `dict[str, Any]` | The response JSON exactly as the API sent it. |
