Skip to main content

Tool Validation

The current tool-validation policy does three things:

Phase and verdicts​

  • Phase: pre-execution / input-stage policy evaluation
  • Verdicts: allow or block

Configuration​

pack:
  name: tool-validation-example-1
  version: "1.0.0"
  enabled: true

policies:
  chain:
    - tool-validation

policy:
  tool-validation:
    declared_tools:
      - web_search
      - database_query
    schemas:
      database_query:
        type: object
        properties:
          table:
            type: string
        required:
          - table
    allow_undeclared: false
    semantic_validation:
      enabled: true
      endpoint: https://validator.example.com/judge
      model: judge
      secret_key_ref:
        env: KEEPTRUSTS_VALIDATOR_API_KEY
      timeout_ms: 3000

Supported fields​

FieldTypeDefaultNotes
declared_toolsstring[][]Allowlist for requested tool names.
schemasobject{}Map of tool names to JSON Schemas.
allow_undeclaredbooleanfalseWhen false, undeclared tool names block the request.
semantic_validation.enabledbooleanfalseEnables the external semantic validator call.
semantic_validation.endpointstring—Required when semantic validation is enabled.
semantic_validation.modelstring—Sent in the validator payload. If omitted, the runtime falls back to judge.
semantic_validation.secret_key_refobject—Use secret_key_ref.env for the bearer token environment variable.
semantic_validation.timeout_msinteger3000Request timeout for the validator call.

What the policy validates​

Requested tools​

The policy extracts tool names from:

  • OpenAI-style tools[*].function.name
  • MCP-bridge-style tools[*].name

Schemas​

Configured schemas are compiled with the JSON Schema library (Draft 7).

Important: the policy checks that the schemas themselves are valid JSON Schemas. It does not validate actual tool-call arguments against those schemas.

Semantic validation​

When enabled, the policy POSTs a payload containing:

  • declared_tools
  • schemas
  • the request's tools array

The response must either:

  • include a top-level valid: true|false, or
  • include OpenAI-style choices[0].message.content JSON with a valid field

Any validator error, timeout, malformed response, or valid: false result blocks the request.

Behavior notes​

  • Semantic validation is currently fail-closed, not fail-open.
  • allow_undeclared: true allows undeclared tool names but still records them in the policy details payload.
  • Because this policy does not validate arguments against schemas, pair it with Tool Security or an external semantic validator if you need payload-level scrutiny.

Minimal valid example​

policy:
  tool-validation:
    declared_tools:
      - search

Next steps​