MetorialDocs

Tool Calls

Tool calls represent individual tool invocations within a session. They track the input, output, and status of each tool execution.

The Tool Call object

tool_call.json
{
  "object": "session.tool_call",
  "id": "tcl_8hJkLmNpQrStUvWx",
  "tool_key": "create_issue",
  "type": "tool_call",
  "status": "waiting_for_response",
  "source": "client",
  "transport": "tool_call",
  "session_id": "ses_4dEfGhJkLmNpQrSt",
  "message_id": "smg_3cDeFgHjKlMnPqRs",
  "session_provider_id": "spr_3cDeFgHjKlMnPqRs",
  "connection_id": "scn_2bCdEfGhJkLmNpQr",
  "provider_run_id": "prn_8hJkLmNpQrStUvWx",
  "sender_participant": {
    "object": "session.participant",
    "id": "spt_5eFgHjKlMnPqRsTu",
    "type": "unknown",
    "identifier": "claude-desktop",
    "name": "Claude Desktop",
    "data": {
      "identifier": "claude-desktop",
      "name": "Claude Desktop"
    },
    "provider_id": "pro_5gHjKlMnPqRsTuVw",
    "connection_type": "mcp",
    "agent_id": "example_agent_id",
    "agent_instance_id": "example_agent_instance_id",
    "identity_actor_id": "example_identity_actor_id",
    "identity_id": "example_identity_id",
    "agent_actor_id": "example_agent_actor_id",
    "agent_client_id": "example_agent_client_id",
    "consumer_id": "example_consumer_id",
    "created_at": "2025-09-15T10:30:00.000Z"
  },
  "responder_participant": {
    "object": "session.participant",
    "id": "spt_5eFgHjKlMnPqRsTu",
    "type": "unknown",
    "identifier": "claude-desktop",
    "name": "Claude Desktop",
    "data": {
      "identifier": "claude-desktop",
      "name": "Claude Desktop"
    },
    "provider_id": "pro_5gHjKlMnPqRsTuVw",
    "connection_type": "mcp",
    "agent_id": "example_agent_id",
    "agent_instance_id": "example_agent_instance_id",
    "identity_actor_id": "example_identity_actor_id",
    "identity_id": "example_identity_id",
    "agent_actor_id": "example_agent_actor_id",
    "agent_client_id": "example_agent_client_id",
    "consumer_id": "example_consumer_id",
    "created_at": "2025-09-15T10:30:00.000Z"
  },
  "tool": {
    "object": "provider.tool",
    "id": "pto_5jKlMnPqRsTuVwXy",
    "key": "create_issue",
    "name": "Create Issue",
    "description": "Creates a new issue in a GitHub repository",
    "capabilities": {},
    "constraints": [
      "example_constraints"
    ],
    "instructions": [
      "example_instructions"
    ],
    "input_schema": {
      "type": "json_schema",
      "schema": {}
    },
    "output_schema": {
      "type": "json_schema",
      "schema": {}
    },
    "tags": {
      "destructive": false,
      "read_only": false
    },
    "specification_id": "psp_9gHjKlMnPqRsTuVw",
    "provider_id": "pro_5gHjKlMnPqRsTuVw",
    "created_at": "2025-09-15T10:30:00.000Z",
    "updated_at": "2026-01-10T14:45:00.000Z"
  },
  "error": {
    "object": "session.error",
    "id": "ser_6fGhJkLmNpQrStUv",
    "code": "CONNECTION_TIMEOUT",
    "message": "Connection timed out after 30 seconds",
    "data": {},
    "status": "processing",
    "session_id": "ses_4dEfGhJkLmNpQrSt",
    "provider_run_id": "prn_8hJkLmNpQrStUvWx",
    "connection_id": "scn_8hJkLmNpQrStUvWx",
    "group_id": "seg_7gHjKlMnPqRsTuVw",
    "similar_error_count": 5,
    "created_at": "2025-09-15T10:30:00.000Z"
  },
  "input": {},
  "output": {},
  "created_at": "2025-09-15T10:30:00.000Z"
}
object"session.tool_call"required
idstringrequired
tool_keystringrequired
type"tool_call" | "mcp_control" | "mcp_message" | "unknown"required
status"waiting_for_response" | "failed" | "succeeded"required
source"client" | "provider"required
transport"tool_call" | "mcp" | "metorial_protocol" | "system"required
session_idstringrequired
message_idstringrequired
session_provider_idstringrequirednullable
connection_idstringrequirednullable
provider_run_idstringrequirednullable
inputRecord<string, any>requirednullable
outputRecord<string, any>requirednullable
created_atdaterequired

Endpoints

List all tool calls

GET/tool-calls

Returns a paginated list of tool calls across all sessions.

Query parameters

session_template_idstring or string[]optional

Filter by session template ID(s)

session_provider_idstring or string[]optional

Filter by session provider ID(s)

provider_idstring or string[]optional

Filter by provider ID(s)

provider_deployment_idstring or string[]optional

Filter by provider deployment ID(s)

provider_config_idstring or string[]optional

Filter by provider config ID(s)

provider_auth_config_idstring or string[]optional

Filter by provider auth config ID(s)

agent_idstring or string[]optional

Filter by agent ID(s)

actor_idstring or string[]optional

Filter by identity actor ID(s)

consumer_idstring or string[]optional

Filter by consumer ID(s)

identity_idstring or string[]optional

Filter by identity ID(s)

agent_instance_idstring or string[]optional

Filter by agent instance ID(s)

tool_idstring or string[]optional

Filter by tool ID(s)

Example request

curl -X GET "https://api.metorial.com/tool-calls" \
  -H "Authorization: Bearer metorial_sk_io2h4..."

Get tool call

GET/tool-calls/:tool_call_id

Retrieves a specific tool call by ID.

Path parameters

tool_call_idstringrequired

The unique identifier for the tool_call

Example request

curl -X GET "https://api.metorial.com/tool-calls/too_Rm4Mnheq2bfEPhBhP7SY" \
  -H "Authorization: Bearer metorial_sk_io2h4..."

Create tool call

POST/tool-calls

Creates a new tool call in a session by invoking a specific tool.

Request body

tool_idstringrequired

The ID of the tool to call

inputRecord<string, any>required

Input data to pass to the tool

metadataRecord<string, any>optional

Optional metadata for the tool call

session_idstringrequired

The ID of the session to which this tool call belongs

Example request

curl -X POST "https://api.metorial.com/tool-calls" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer metorial_sk_io2h4..." \
  -d '{
  "tool_id": "example_tool_id",
  "input": {},
  "metadata": {},
  "session_id": "example_session_id"
}'