Introspection Tools

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:

{
  "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:

{
  "echo": "Hello, world!"
}

math_add

Adds two numbers. Capability: introspection Input:

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

Output:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

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

Requires CONDUCTOR_BASE_URL to be set on the runner so it knows how to reach the conductor.

usage_info

Returns token and estimated-cost totals for the current run. Conductor-backed. Capability: introspection Input: {} (requires run context) Output:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "content": [
    {
      "url": "https://example.com/page",
      "text": "Full page content..."
    }
  ]
}

Combine web_search and web_extract for deep research: search first to discover URLs, then extract for full content.

​time_now

​echo

​math_add

​runner_info

​session_info

​profile_info

​run_info

​usage_info

​list_profiles

​list_sessions

​list_mcp_servers

​search_connected_app_tools

​call_connected_app_tool

​topology_info

​web_search

​web_extract

time_now

echo

math_add

runner_info

session_info

profile_info

run_info

usage_info

list_profiles

list_sessions

list_mcp_servers

search_connected_app_tools

call_connected_app_tool

topology_info

web_search

web_extract