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

# Introspection Tools

> Platform tools for runner/session metadata, profile discovery, usage, topology, and web lookup.

These tools carry the `introspection` capability. They are selected by `@introspection` and by the current `@default` selector.

***

## time\_now

Returns the current time in an optional IANA timezone.

**Capability:** `introspection`

**Input:**

| Field      | Type   | Description                  |
| ---------- | ------ | ---------------------------- |
| `timezone` | string | IANA timezone, default `UTC` |

**Output:**

```json theme={null}
{
  "iso": "2026-04-25T10:00:00Z",
  "timezone": "UTC"
}
```

**Example profile tools:** `["time_now"]`

***

## echo

Echoes back the provided text. Useful for testing tool connectivity.

**Capability:** `introspection`

**Input:**

| Field  | Type   | Description  |
| ------ | ------ | ------------ |
| `text` | string | Text to echo |

**Output:**

```json theme={null}
{
  "echo": "Hello, world!"
}
```

***

## math\_add

Adds two numbers.

**Capability:** `introspection`

**Input:**

| Field | Type   | Description    |
| ----- | ------ | -------------- |
| `a`   | number | First operand  |
| `b`   | number | Second operand |

**Output:**

```json theme={null}
{
  "sum": 42
}
```

***

## runner\_info

Returns the platform reference data an agent needs before authoring a
profile: valid runtimes, model providers per runtime, capability bundle
names, and the model-string format per runtime.

It deliberately reports no runner identity (hostname, pid, or URLs). The
tool is reachable by any agent with the introspection capability and
therefore by that agent's end users, and agents repeat its payload
verbatim, so runner identity here leaks infrastructure addresses to
tenants and misleads sandbox-worker agents into describing the runner as
their own host.

**Capability:** `introspection`

**Input:** `{}` (no parameters)

**Output:**

```json theme={null}
{
  "startedAt": "2026-04-25T10:00:00Z",
  "runtimes": ["pi", "vercel", "claude", "codex"],
  "providers": {
    "pi": ["openai", "anthropic", "google", "groq"],
    "vercel": ["openai", "anthropic", "google", "groq"]
  },
  "capabilityBundles": ["@default", "@introspection", "@fs", "..."],
  "modelFormat": {
    "pi": "<provider>:<modelId>; ...",
    "claude": "SDK-native id from list_models ..."
  }
}
```

***

## session\_info

Returns identity fields for the current session.

**Capability:** `introspection`

**Input:** `{}` (no parameters)

**Output:**

```json theme={null}
{
  "sessionId": "sess-a1b2c3d4-e5f6g7h8",
  "profileName": "researcher",
  "runnerHash": "a1b2c3d4"
}
```

***

## profile\_info

Returns identity and sizing information for the current session's profile.

**Capability:** `introspection`

**Input:** `{}` (no parameters)

**Output:**

```json theme={null}
{
  "name": "researcher",
  "runtime": "general",
  "model": "anthropic:claude-sonnet-4-6",
  "systemPromptLength": 29,
  "skills": [],
  "toolNames": ["@default", "web_search", "web_extract"],
  "mcpServerNames": []
}
```

***

## run\_info

Returns status and event counts for the current run. Conductor-backed.

**Capability:** `introspection`

**Input:** `{}` (requires run context)

**Output:**

```json theme={null}
{
  "runId": "run-f3a9b72c",
  "startedAt": "2026-04-25T10:00:00Z",
  "elapsedSec": 42,
  "eventCounts": { "assistant": 3, "tool_call": 1, "result": 1 }
}
```

<Note>
  Requires `CONDUCTOR_BASE_URL` to be set on the runner so it knows how to reach the conductor.
</Note>

***

## usage\_info

Returns token and estimated-cost totals for the current run. Conductor-backed.

**Capability:** `introspection`

**Input:** `{}` (requires run context)

**Output:**

```json theme={null}
{
  "inputTokens": 15420,
  "outputTokens": 3280,
  "totalTokens": 18700,
  "estimatedCostUsd": 0.42
}
```

***

## list\_profiles

Lists all profiles registered on the conductor. Conductor-backed.

**Capability:** `introspection`

**Input:** `{}` (no parameters)

**Output:**

```json theme={null}
{
  "profiles": [
    { "name": "general", "runtime": "general" },
    { "name": "researcher", "runtime": "general" },
    { "name": "reviewer", "runtime": "claude" }
  ]
}
```

***

## list\_sessions

Lists active sessions from the conductor. Conductor-backed.

**Capability:** `introspection`

**Input:** `{}` (no parameters)

**Output:**

```json theme={null}
{
  "sessions": [
    {
      "id": "sess-a1b2c3d4-e5f6g7h8",
      "profile": "researcher",
      "runtime": "general",
      "status": "idle"
    }
  ]
}
```

***

## list\_mcp\_servers

Lists all entries in the MCP server catalog. Conductor-backed.

**Capability:** `introspection`

**Input:** `{}` (no parameters)

**Output:**

```json theme={null}
{
  "servers": [
    {
      "name": "company-db",
      "transport": "http",
      "url": "https://db.internal/mcp"
    }
  ]
}
```

***

## search\_connected\_app\_tools

Searches the tools exposed by a connected app attached to the current profile. The result includes exact tool names and input schemas for a follow-up `call_connected_app_tool` request. Conductor-backed.

**Capability:** `introspection`

**Input:**

| Field   | Type    | Required | Description                                               |
| ------- | ------- | -------- | --------------------------------------------------------- |
| `app`   | string  | Yes      | Connected app slug, such as `gmail`                       |
| `query` | string  | Yes      | Keywords that must appear in the tool name or description |
| `limit` | integer | No       | Maximum matches, from 1 to 20; defaults to 5              |

The profile must contain the matching managed reference, such as `catalog://composio-gmail`. Search returns a tool-level error when the app is not attached.

***

## call\_connected\_app\_tool

Executes one connected-app tool through the tenant-isolated MCP bridge. Search first, then pass the exact returned tool name and arguments that conform to its input schema. Conductor-backed.

**Capability:** `introspection`

**Input:**

| Field       | Type   | Required | Description                                              |
| ----------- | ------ | -------- | -------------------------------------------------------- |
| `app`       | string | Yes      | Connected app slug, such as `gmail`                      |
| `name`      | string | Yes      | Exact tool name returned by `search_connected_app_tools` |
| `arguments` | object | No       | Tool-specific arguments; defaults to `{}`                |

The bridge keeps provider credentials out of the profile, worker run envelope, and sidecar.

***

## topology\_info

Returns the current runner pool view. Conductor-backed. Reading this tool
triggers on-demand probes down the topology tree; it is observation-driven so
idle runners and sidecars can still scale to zero. Do not treat it as a
continuously polled metric.

The result uses the tenant-facing topology shape: runner and sidecar addresses,
PIDs, and Node versions are omitted, and each sidecar `instanceId` is reduced
to its distinguishing suffix. Infrastructure addresses in probe errors are
also redacted.

**Capability:** `introspection`

**Input:** `{}` (no parameters)

**Output:**

```json theme={null}
{
  "runners": [
    {
      "hash": "a1b2c3d4",
      "capabilities": ["claude", "general"],
      "healthy": true,
      "activeSessions": 3,
      "state": "live",
      "capabilitiesKnown": true,
      "process": {
        "heapInuseBytes": 52428800,
        "numGoroutine": 42,
        "uptimeSeconds": 86400
      },
      "sessionsByRuntime": { "general": 2, "claude": 1 },
      "sidecars": [
        {
          "runtime": "general",
          "mode": "sidecar",
          "state": "live",
          "activeSessions": 2,
          "observedInstances": [
            {
              "instanceId": "worker-01",
              "runsServed": 18,
              "lastProbedAt": "2026-08-03T09:00:00Z",
              "memory": { "rssBytes": 104857600 },
              "cpu": { "userMicros": 1200000 }
            }
          ]
        }
      ]
    }
  ]
}
```

`state` describes runner membership (`live`, `draining`, or `unreachable`),
which is separate from point-in-time `healthy` status. `process`,
`sessionsByRuntime`, and `sidecars` are `null` when the runner did not answer
the topology probe; render those values as unknown, not zero. A sidecar's
`cold` state means configured but quiet, not broken. `observedInstances` is a
lower bound on replicas: connection pooling can hide idle workers, and slots
sharing a sidecar process can report the same process, so do not sum it as a
replica count. Repeated reads within the short topology-cache window may be
served from the shared cache rather than re-probing the fleet.

***

## web\_search

Searches the web using the Tavily API.

**Capability:** `introspection`

**Requires:** `TAVILY_API_KEY` set on the runner.

**Input:**

| Field         | Type    | Required | Description                        |
| ------------- | ------- | -------- | ---------------------------------- |
| `query`       | string  | ✓        | Search query                       |
| `max_results` | integer | —        | Max results to return (default: 5) |

**Output:**

```json theme={null}
{
  "results": [
    {
      "title": "Top AI Agent Frameworks in 2026",
      "url": "https://example.com/ai-frameworks",
      "content": "The top AI agent frameworks...",
      "score": 0.94
    }
  ]
}
```

***

## web\_extract

Extracts readable content from one or more URLs using Tavily.

**Capability:** `introspection`

**Requires:** `TAVILY_API_KEY` set on the runner.

**Input:**

| Field  | Type      | Required | Description                  |
| ------ | --------- | -------- | ---------------------------- |
| `urls` | string\[] | ✓        | URLs to extract content from |

**Output:**

```json theme={null}
{
  "content": [
    {
      "url": "https://example.com/page",
      "text": "Full page content..."
    }
  ]
}
```

<Tip>
  Combine `web_search` and `web_extract` for deep research: search first to discover URLs, then extract for full content.
</Tip>