MEmetorial
Tool Calls

Create tool call

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

post/tool-calls

Request

  • Base URL
    https://api.metorial.com
  • Auth
    HTTP bearer

Headers

Metorial-Versionstring
Example:2025-01-01

Pin the dated API version for this request, e.g. 2025-01-01. Defaults to the version configured for the environment.

Request body

tool_idstring required

The ID of the tool to call

inputobject required

Input data to pass to the tool

metadataobject

Optional metadata for the tool call

session_idstring required

The ID of the session to which this tool call belongs

Response

Successful response

object'session.tool_call' required

String representing the object's type

idstring required

Unique tool call identifier

tool_keystring required

The key identifying the tool that was called

type'tool_call' | 'mcp_control' | 'mcp_message' | 'unknown' required

The type of the tool call

status'waiting_for_response' | 'failed' | 'succeeded' required

Current status of the tool call

source'client' | 'provider' required

Source of the tool call

transport'tool_call' | 'mcp' | 'metorial_protocol' | 'system' required

Transport protocol used

session_idstring required

Parent session ID

message_idstring required

Associated session message ID

session_provider_idstring nullable required

Session provider ID

connection_idstring nullable required

Session connection ID

provider_run_idstring nullable required

Provider run ID

inputobject nullable required

Input data passed to the tool call. Bodies larger than 16 KB in list responses, or larger than 1 MB when retrieving by ID, are replaced with a session.message.omitted_body object.

outputobject nullable required

Output data returned from the tool call. Bodies larger than 16 KB in list responses, or larger than 1 MB when retrieving by ID, are replaced with a session.message.omitted_body object.

created_atstring date-time required

Timestamp when created

Example response

{
  "id": "tcl_8hJkLmNpQrStUvWx",
  "tool_key": "create_issue",
  "session_id": "ses_4dEfGhJkLmNpQrSt",
  "message_id": "smg_3cDeFgHjKlMnPqRs",
  "session_provider_id": "spr_3cDeFgHjKlMnPqRs",
  "connection_id": "scn_2bCdEfGhJkLmNpQr",
  "provider_run_id": "prn_8hJkLmNpQrStUvWx",
  "sender_participant": {
    "id": "spt_5eFgHjKlMnPqRsTu",
    "identifier": "claude-desktop",
    "name": "Claude Desktop",
    "data": {
      "identifier": "claude-desktop",
      "name": "Claude Desktop"
    },
    "provider_id": "pro_5gHjKlMnPqRsTuVw",
    "created_at": "2025-09-15T10:30:00.000Z"
  },
  "responder_participant": {
    "id": "spt_5eFgHjKlMnPqRsTu",
    "identifier": "claude-desktop",
    "name": "Claude Desktop",
    "data": {
      "identifier": "claude-desktop",
      "name": "Claude Desktop"
    },
    "provider_id": "pro_5gHjKlMnPqRsTuVw",
    "created_at": "2025-09-15T10:30:00.000Z"
  },
  "tool": {
    "id": "pto_5jKlMnPqRsTuVwXy",
    "key": "create_issue",
    "name": "Create Issue",
    "description": "Creates a new issue in a GitHub repository",
    "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": {
    "id": "ser_6fGhJkLmNpQrStUv",
    "code": "CONNECTION_TIMEOUT",
    "message": "Connection timed out after 30 seconds",
    "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"
  },
  "created_at": "2025-09-15T10:30:00.000Z"
}

Changes

No recorded changes to this operation across all 1 revision of this API.