{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://scoperail.fokalabs.io/method/tool-definition.schema.json",
  "title": "ScopeRail tool definition",
  "description": "Portable metadata for admitting a typed tool into an eligible catalogue. The host system remains responsible for authorization.",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "version",
    "summary",
    "useWhen",
    "doNotUseWhen",
    "eligibility",
    "inputSchema",
    "outputSchema",
    "sideEffect",
    "confirmation",
    "authorization"
  ],
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9._-]{2,79}$",
      "description": "Stable, non-secret identifier."
    },
    "version": {
      "type": "string",
      "minLength": 1,
      "maxLength": 40
    },
    "summary": {
      "type": "string",
      "minLength": 12,
      "maxLength": 400,
      "description": "What the tool does in operational language."
    },
    "useWhen": {
      "type": "array",
      "minItems": 1,
      "maxItems": 12,
      "uniqueItems": true,
      "items": {
        "type": "string",
        "minLength": 3,
        "maxLength": 240
      }
    },
    "doNotUseWhen": {
      "type": "array",
      "minItems": 1,
      "maxItems": 12,
      "uniqueItems": true,
      "items": {
        "type": "string",
        "minLength": 3,
        "maxLength": 240
      }
    },
    "eligibility": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "policyOwner",
        "requiredPermissions",
        "permittedContexts"
      ],
      "properties": {
        "policyOwner": {
          "type": "string",
          "minLength": 2,
          "maxLength": 120,
          "description": "The host component that computes eligibility."
        },
        "requiredPermissions": {
          "type": "array",
          "maxItems": 32,
          "uniqueItems": true,
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160
          }
        },
        "permittedContexts": {
          "type": "array",
          "minItems": 1,
          "maxItems": 32,
          "uniqueItems": true,
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160
          }
        },
        "deniedContexts": {
          "type": "array",
          "maxItems": 32,
          "uniqueItems": true,
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160
          }
        }
      }
    },
    "inputSchema": {
      "type": "object",
      "description": "A JSON Schema for tool arguments."
    },
    "outputSchema": {
      "type": "object",
      "description": "A JSON Schema for the normalized tool result."
    },
    "sideEffect": {
      "type": "string",
      "enum": [
        "none",
        "reversible",
        "consequential"
      ]
    },
    "confirmation": {
      "type": "string",
      "enum": [
        "never",
        "when_consequential",
        "always"
      ]
    },
    "authorization": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "enforcedBy",
        "recheckBeforeExecution"
      ],
      "properties": {
        "enforcedBy": {
          "type": "string",
          "minLength": 2,
          "maxLength": 120
        },
        "recheckBeforeExecution": {
          "type": "boolean"
        }
      }
    },
    "dataClasses": {
      "type": "array",
      "maxItems": 8,
      "uniqueItems": true,
      "items": {
        "type": "string",
        "enum": [
          "public",
          "internal",
          "confidential",
          "restricted"
        ]
      }
    },
    "timeoutMs": {
      "type": "integer",
      "minimum": 1,
      "maximum": 300000
    },
    "cache": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "allowed"
      ],
      "properties": {
        "allowed": {
          "type": "boolean"
        },
        "ttlSeconds": {
          "type": "integer",
          "minimum": 0,
          "maximum": 86400
        },
        "scope": {
          "type": "string",
          "enum": [
            "request",
            "user",
            "tenant",
            "global"
          ]
        }
      }
    },
    "examples": {
      "type": "array",
      "maxItems": 6,
      "description": "Synthetic examples only. Do not include customer data or credentials.",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "request",
          "expectedUse"
        ],
        "properties": {
          "request": {
            "type": "string",
            "minLength": 3,
            "maxLength": 500
          },
          "expectedUse": {
            "type": "boolean"
          },
          "reason": {
            "type": "string",
            "maxLength": 500
          }
        }
      }
    }
  }
}