Introspection Tools

Most of these tools carry the introspection capability, selected by @introspection and by the current @default selector; each section states its capability. The discover_capability and run_capability sections are the exception: they carry no capability tag and must be named explicitly in a profile’s tool list.

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	Required	Description
`message`	string	Yes	Text to echo back

Output:

{
  "message": "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", "marlin"],
  "providers": {
    "pi": ["openai", "anthropic", "google", "groq"],
    "vercel": ["openai", "anthropic", "google", "groq"],
    "marlin": ["openai", "anthropic", "openrouter"]
  },
  "capabilityBundles": ["@default", "@introspection", "@fs", "..."],
  "modelFormat": {
    "pi": "<provider>:<modelId>; ...",
    "claude": "SDK-native id from list_models ..."
  }
}

list_models

Lists the actual model ids a provider currently serves. It hits the provider’s own /models endpoint at call time using the runner’s per-provider API key, so the returned ids are real and current rather than guesses from training data. Call this before setting a profile’s model field; the provider name comes from runner_info.providers, and the returned ids are the modelId portion of <provider>:<modelId>. Capability: introspection Input:

Field	Type	Required	Description
`provider`	string	Yes	One of `openai`, `anthropic`, `google`, `groq`

Output:

{
  "provider": "anthropic",
  "models": [
    { "id": "claude-sonnet-4-6", "displayName": "Claude Sonnet 4.6", "ownedBy": "anthropic", "createdAt": "2026-03-01" }
  ],
  "truncated": false,
  "fetchedAt": "2026-09-06T10:00:00Z"
}

The list is capped at 50 entries per provider (truncated: true if more exist). Unpriced models are withheld from the results; when everything for a provider is withheld, a note field explains why.

session_info

Returns identity fields for the current session. Capability: introspection Input: {} (no parameters) Output:

{
  "sessionId": "sess-a1b2c3d4-e5f6g7h8",
  "profileName": "researcher"
}

The response does not identify which runner served the session; runner identity is infrastructure detail and is not exposed to agents.

profile_info

Returns identity and sizing information for the current session’s profile. Capability: introspection Input: {} (no parameters) Output:

{
  "name": "researcher",
  "runtime": "vercel",
  "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: a bare JSON array, sorted by name and capped at 100 entries.

[
  { "name": "general", "runtime": "vercel", "model": "openai:gpt-4o", "description": "..." },
  { "name": "researcher", "runtime": "vercel", "model": "anthropic:claude-sonnet-4-6", "description": "..." },
  { "name": "reviewer", "runtime": "claude", "model": "anthropic:claude-sonnet-4-6", "description": "..." }
]

list_sessions

Lists active sessions from the conductor. Conductor-backed. Capability: introspection Input: {} (no parameters) Output: a bare JSON array, sorted newest-first and capped at 100 entries. Each entry also carries recent-run metadata: createdAt, lastUsedAt, lastPrompt (truncated to 200 characters), lastRunStartedAt, lastRunFinishedAt (omitted while a run is in progress), lastRunStatus (ok, error, cancelled, or running), and runCount.

[
  {
    "id": "sess-a1b2c3d4-e5f6g7h8",
    "profile": "researcher",
    "runtime": "vercel",
    "status": "idle",
    "createdAt": "2026-04-25T09:00:00Z",
    "lastUsedAt": "2026-04-25T10:00:00Z",
    "lastPrompt": "Summarize the latest release notes",
    "lastRunStartedAt": "2026-04-25T09:55:00Z",
    "lastRunFinishedAt": "2026-04-25T09:58:00Z",
    "lastRunStatus": "ok",
    "runCount": 4
  }
]

list_mcp_servers

Lists all entries in the MCP server catalog. Conductor-backed. Capability: introspection Input: {} (no parameters) Output: a bare JSON array, sorted by name. There is no url field.

[
  {
    "name": "company-db",
    "transport": "http",
    "description": "Internal company database",
    "toolNames": ["query", "schema"]
  }
]

platform_catalog

One-shot discovery call that returns this tenant’s skills, MCP servers, profiles, and pods in a single request, sparing an agent four sequential list_* calls. Call this before create_profile, create_pool, or attach_skill so the agent references real names instead of inventing them. Conductor-backed. Capability: introspection Input:

Field	Type	Required	Description
`kinds`	string[]	No	Subset of `skills`, `mcpServers`, `profiles`, `pools` to fetch. Omit or leave empty to fetch all four.

Output:

{
  "skills": { "items": [{ "name": "code-review", "description": "..." }], "truncated": false },
  "mcpServers": { "items": [{ "name": "company-db", "transport": "http", "description": "...", "toolNames": ["query"] }], "truncated": false },
  "profiles": { "items": [{ "name": "researcher", "runtime": "vercel", "model": "anthropic:claude-sonnet-4-6", "description": "..." }], "truncated": false },
  "pools": { "items": [{ "name": "support", "members": ["researcher"], "description": "..." }], "truncated": false }
}

Each present catalog is capped at 100 entries (truncated: true if more exist); a per-catalog errors map reports partial failures without failing the whole call.

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.

discover_capability

Finds a small set of actions that can satisfy an intent across the connected-app capabilities attached to the current profile. This is the newer, intent-based facade for the same connected-app surface as search_connected_app_tools and call_connected_app_tool; the codebase refers to that older pair as the legacy facade. Requires session context. Conductor-backed. Capability: none. This tool carries no capability tag, so a profile must name it explicitly; it is not pulled in by any @-sentinel, including @default or @introspection. Input:

Field	Type	Required	Description
`intent`	string	Yes	Describe the external action needed. 1 to 1000 characters.
`limit`	integer	No	Maximum action cards to return, 1 to 5. Defaults to 3.

Output: a bounded list of opaque actionId action cards ranked for the given intent, for a follow-up run_capability call.

run_capability

Runs an opaque action returned by discover_capability with the supplied parameters. Requires session context. Conductor-backed. Capability: none. Same facade as discover_capability: name it explicitly in the profile’s tool list, since no @-sentinel selects it. Input:

Field	Type	Required	Description
`actionId`	string	Yes	An action id from `discover_capability`, matching `^act_[A-Za-z0-9_-]{32,}$`
`params`	object	No	Parameters for the action; defaults to `{}`

A structured needs_input or needs_confirmation outcome is returned as a successful result rather than an error, so the caller can handle it explicitly.

topology_info

Reports the conductor’s view of the runner pool: each runner’s identifying hash, its active session count, and its health. Capability: introspection Input: {} (no parameters) Output:

{
  "runners": [
    {
      "hash": "a1b2c3d4",
      "sessions": 3,
      "healthy": true
    }
  ]
}

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	No	Maximum number of results to return. Optional; if omitted, the field is not sent to Tavily and the result count follows Tavily’s own default.

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

​list_models

​session_info

​profile_info

​run_info

​usage_info

​list_profiles

​list_sessions

​list_mcp_servers

​platform_catalog

​search_connected_app_tools

​call_connected_app_tool

​discover_capability

​run_capability

​topology_info

​web_search

​web_extract

time_now

echo

math_add

runner_info

list_models

session_info

profile_info

run_info

usage_info

list_profiles

list_sessions

list_mcp_servers

platform_catalog

search_connected_app_tools

call_connected_app_tool

discover_capability

run_capability

topology_info

web_search

web_extract