ApiResponseOfAgentToolUserDetailsResult

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/contraforce/json-schema/contraforce-api-response-of-agent-tool-user-details-result-schema.json",
  "title": "ApiResponseOfAgentToolUserDetailsResult",
  "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/ApiResponseOfAgentToolUserDetailsResult",
  "type": "object",
  "properties": {
    "data": {
      "description": "Result of an agent user-lookup tool call. Returns a token-efficient view of a Microsoft\nGraph user with only the fields that have proven useful in incident analysis — full\nGraph payloads include large arrays of identities, business phones, and password change\nmetadata that bloat LLM context without changing decisions.",
      "$ref": "#/$defs/AgentToolUserDetailsResult"
    },
    "meta": {
      "$ref": "#/$defs/ResponseMeta"
    }
  },
  "$defs": {
    "AgentToolUserDetailsResult": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean",
          "description": "True when the user was found in Microsoft Graph. False when the user does not exist, when the Gamebooks-for-Identity module is disabled for the workspace, or when Graph returned an error — reason in `summary`."
        },
        "summary": {
          "type": [
            "null",
            "string"
          ],
          "description": "Compact one-line human-readable digest: '{DisplayName}, {JobTitle} in {Department} ({OfficeLocation}). UPN: {UPN}.' — fields omitted when null."
        },
        "user_id": {
          "type": [
            "null",
            "string"
          ],
          "description": "Azure AD object ID of the resolved user. Echoes the request input — useful for chained calls."
        },
        "display_name": {
          "type": [
            "null",
            "string"
          ],
          "description": "Display name (first + last) of the user."
        },
        "user_principal_name": {
          "type": [
            "null",
            "string"
          ],
          "description": "User Principal Name (UPN), typically the user's email-like sign-in name (e.g. alice@contoso.com)."
        },
        "mail": {
          "type": [
            "null",
            "string"
          ],
          "description": "Primary SMTP email address. May differ from the UPN."
        },
        "job_title": {
          "type": [
            "null",
            "string"
          ],
          "description": "Job title from the user's directory profile. Useful for assessing whether the account is privileged (e.g. 'Domain Admin', 'CFO')."
        },
        "department": {
          "type": [
            "null",
            "string"
          ],
          "description": "Department from the user's directory profile."
        },
        "office_location": {
          "type": [
            "null",
            "string"
          ],
          "description": "Office location from the user's directory profile. Useful when correlating sign-in geolocation against expected location."
        },
        "mobile_phone": {
          "type": [
            "null",
            "string"
          ],
          "description": "Mobile phone number from the user's directory profile."
        }
      },
      "description": "Result of an agent user-lookup tool call. Returns a token-efficient view of a Microsoft\nGraph user with only the fields that have proven useful in incident analysis — full\nGraph payloads include large arrays of identities, business phones, and password change\nmetadata that bloat LLM context without changing decisions."
    },
    "ResponseMeta": {
      "type": "object",
      "properties": {
        "requestId": {
          "type": [
            "null",
            "string"
          ]
        },
        "timestamp": {
          "type": [
            "null",
            "string"
          ]
        }
      }
    }
  }
}