Skip to content
Ctrl/⌘ K

MCP

MCP agent status tool

Poll a background agent run with its response-only session proof.

Overview

Read a background agent run using the id and one-time session proof returned by run_agent.

Use the typed search tools for web retrieval. Use list_models before BYOK query-builder or agent calls, and configure a provider key at the returned setup_url when requested. When a tool error's structured content includes error.validation, correct every listed RFC 6901 issue before retrying and never repeat an unchanged rejected input.

Input schema

MCP agent status tool input
Name
id
Required
Yes
Type
string
Description
See the public contract for this field.
Constraints
Name
session_secret
Required
Yes
Type
string
Description
See the public contract for this field.
Constraints

Output schema

Returns structured JSON from the shared public API service.

MCP agent status tool output fields
Name
agent_session_id
Required
Yes
Type
string
Description
Non-secret execution correlation id from the signed runtime session.
Name
state
Required
Yes
Type
AgentRuntimeState
Description
Closed runtime lifecycle state.
Name
program_digest
Required
Yes
Type
string
Description
Pinned semantic program digest.
Name
output
Required
Yes
Type
RequiredNullableSchema
Description
Present only for a successful terminal run.
Name
error
Required
Yes
Type
RequiredNullableSchema2
Description
Present only for a failed terminal run.
Name
usage
Required
Yes
Type
UsageReport
Description
Provider usage accumulated so far.

Tool errors

Tool execution failures set isError to true. When error.validation is present, correct every RFC 6901 issue before retrying and do not repeat unchanged input.

Request json 
{
  "error": {
    "code": "invalid_request",
    "reason": "malformed_request",
    "message": "invalid request: request body violates the public contract",
    "recovery": null,
    "agent_session_id": null,
    "validation": {
      "contract": "SearchPostRequest",
      "issues": [
        {
          "code": "required",
          "path": "/query",
          "suggestion": "Add the required `query` field."
        }
      ],
      "truncated": false
    }
  },
  "request_id": "00000000-0000-0000-0000-000000000000"
}

Behavior

This tool is read-only, non-destructive, and idempotent.

Commands