{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/roark/json-schema/roark-append-tool-invocations-request-schema.json",
  "title": "AppendToolInvocationsRequest",
  "description": "Attach tool invocations to an existing call, optionally (re)scoring metrics over them.",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/roark-call-api-openapi.yml#/components/schemas/AppendToolInvocationsRequest",
  "type": "object",
  "properties": {
    "toolInvocations": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Name of the tool that was invoked"
          },
          "description": {
            "type": "string",
            "description": "Description of when the tool should be invoked"
          },
          "parameters": {
            "type": "object",
            "additionalProperties": {
              "anyOf": [
                {
                  "type": "object",
                  "properties": {
                    "description": {
                      "type": "string"
                    },
                    "type": {
                      "type": "string",
                      "enum": [
                        "string",
                        "number",
                        "boolean"
                      ]
                    },
                    "value": {}
                  }
                },
                {}
              ]
            },
            "description": "Parameters provided to the tool during invocation"
          },
          "result": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "object",
                "additionalProperties": {}
              }
            ],
            "description": "Result returned by the tool after execution. Can be a string or a JSON object"
          },
          "startOffsetMs": {
            "type": "integer",
            "minimum": 0,
            "maximum": 2147483647,
            "description": "Offset in milliseconds from the start of the call when the tool was invoked"
          },
          "endOffsetMs": {
            "type": "integer",
            "minimum": 0,
            "maximum": 2147483647,
            "description": "Offset in milliseconds from the start of the call when the tool execution completed. Used to calculate duration of the tool execution"
          },
          "agent": {
            "type": "object",
            "properties": {
              "roarkId": {
                "type": "string",
                "format": "uuid",
                "description": "The Roark ID of the agent"
              },
              "customId": {
                "type": "string",
                "description": "The custom ID set on the agent"
              }
            },
            "description": "Metadata about the agent that invoked this tool - used to match which agent from the agents array this tool invocation belongs to"
          }
        },
        "required": [
          "name",
          "parameters",
          "result",
          "startOffsetMs"
        ]
      },
      "minItems": 1,
      "maxItems": 500,
      "description": "Tool invocations that fired during the call, to attach to it. Max 500 per request. Re-sending an invocation already present on the call (same tool name and timing) is skipped, so retries are safe."
    },
    "metrics": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          }
        },
        "required": [
          "id"
        ]
      },
      "minItems": 1,
      "maxItems": 20,
      "description": "Optional. Metric definitions to (re)score on this call after the tool invocations are attached, e.g. the Tool Invocation Analysis metrics. Triggers a metric collection job (billed, credit-gated) and requires the 'metric:create' permission. Omit to attach tools without scoring. Max 20."
    }
  },
  "required": [
    "toolInvocations"
  ]
}