ApiResponseOfAgentToolKqlQueryResult

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/contraforce/json-schema/contraforce-api-response-of-agent-tool-kql-query-result-schema.json",
  "title": "ApiResponseOfAgentToolKqlQueryResult",
  "description": "Standard v2 API response envelope for single-item responses.",
  "x-generated": "2026-11-04",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/contraforce-agent-tools-api-openapi.yml#/components/schemas/ApiResponseOfAgentToolKqlQueryResult",
  "type": "object",
  "properties": {
    "data": {
      "description": "Result of an agent KQL execution tool call. Returns true-columnar rows (parallel arrays\nindexed against the List<string> AgentToolKqlQueryResult.Columns header) — far more token-efficient than a\nper-row dictionary because column names are written exactly once.",
      "$ref": "#/$defs/AgentToolKqlQueryResult"
    },
    "meta": {
      "$ref": "#/$defs/ResponseMeta"
    }
  },
  "$defs": {
    "AgentToolKqlQueryResult": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean",
          "description": "True when the query ran. False for KQL syntax errors, schema mismatches, upstream Log Analytics failures, or XDR-only workspaces — the failure reason is in `summary`."
        },
        "summary": {
          "type": [
            "null",
            "string"
          ],
          "description": "Compact human-readable digest: 'Query returned N rows.' or 'Query returned X rows; showing first N (truncated).' or a one-line failure reason."
        },
        "row_count": {
          "pattern": "^-?(?:0|[1-9]\\d*)$",
          "type": [
            "integer",
            "string"
          ],
          "description": "Number of rows actually returned (after server-side truncation). When `truncated` is true, this is less than the total rows the query matched.",
          "format": "int32"
        },
        "truncated": {
          "type": "boolean",
          "description": "True when the query produced more rows than were returned (hit the row cap). The agent should narrow the query (tighter time range, more selective filters, project fewer columns) rather than attempt pagination — these tools have no pagination contract. Omitted when false."
        },
        "columns": {
          "type": [
            "null",
            "array"
          ],
          "items": {
            "type": "string"
          },
          "description": "Column names in order. Index into each row in `rows` using the position of the column name here. Columns whose values were null/empty across every projected row are auto-pruned."
        },
        "rows": {
          "type": [
            "null",
            "array"
          ],
          "items": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "description": "Result rows as parallel arrays aligned to `columns`. Position-aligned: rows[r][c] is the value of columns[c] for row r. Values are stringified — booleans become 'true'/'false', objects/arrays become compact JSON, oversized cells are truncated with a `…(N more)` suffix."
        }
      },
      "description": "Result of an agent KQL execution tool call. Returns true-columnar rows (parallel arrays\nindexed against the List<string> AgentToolKqlQueryResult.Columns header) — far more token-efficient than a\nper-row dictionary because column names are written exactly once."
    },
    "ResponseMeta": {
      "type": "object",
      "properties": {
        "requestId": {
          "type": [
            "null",
            "string"
          ]
        },
        "timestamp": {
          "type": [
            "null",
            "string"
          ]
        }
      }
    }
  }
}