Skip to main content

Tool Validation

The tool-validation policy block does three input-stage checks:

  1. It checks requested tool names against declared_tools.
  2. It compiles each configured JSON Schema.
  3. It can call an external semantic validator.

This policy-stage check does not validate arguments in a subsequent tool call that the model generates. Use a supported pre-dispatch tool workflow when each actual action must have argument validation.

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: VERDICTAN_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_undeclaredbooleanfalseA value of false blocks undeclared tool names.
semantic_validation.enabledbooleanfalseEnables the external semantic validator call.
semantic_validation.endpointstring—Necessary when semantic validation is enabled.
semantic_validation.modelstring—Sent in the validator payload. If not specified, 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 gets tool names from:

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

Schemas​

The policy compiles configured schemas with the JSON Schema library (Draft 7).

Important: The policy checks each JSON Schema. It does not validate tool-call arguments against the schema.

Semantic validation​

When enabled, the policy POSTs a payload containing:

  • declared_tools
  • schemas
  • the request's tools array

The response must have one of these shapes:

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

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

Behavior notes​

  • Semantic validation blocks on an error.
  • allow_undeclared: true allows undeclared tool names but continues to record them in the policy details payload.
  • Use Tool Security for pattern checks on the serialized input request.
  • Use pre-dispatch validation when each actual tool-call argument must match its schema.

Minimal correct example​

policy:
  tool-validation:
    declared_tools:
      - search

Next steps​