Tool authorization
Configuration, evaluation scope, and practical limits for tool_authorization.
tool_authorization is the policy type used by the API and policy editor.
What it checks
Compares the name of a tool span against configured allow and deny lists.
Configure the policy
Create a policy under Dashboard → Security → Policies. Choose this policy type, set the agent scope, and start in warning mode while you measure results. Use blocking only after verifying the application’s decision gate.
The following is the config object, not a complete policy-creation request:
{
"allowed_tools": [
"lookup_demo_record"
],
"blocked_tools": [
"delete_account"
]
}Scope and limits
This provider requires a span with span_type: "tool" and a tool name. The text evaluation endpoint constructs an LLM span; putting a tool name in that endpoint’s input does not authorize a tool execution. An omitted allow list imposes no allow-list restriction; an empty allow list denies every named tool.
Recording a tool span after execution cannot stop its side effects. Enforce tool names, arguments, user permissions and resource scope in your application before execution. A read-only demo lookup with a post-result text check is not a substitute for this authorization boundary.
Verify before rollout
Test a representative safe input, a synthetic positive case, and an unavailable-detector case. Inspect evaluation_status, errors, policies_evaluated, findings and allowed. A clean empty finding list is useful only when the required checks completed.
The policy mode determines the decision: warning findings can coexist with allowed: true. Your application must act on a blocking decision before the protected operation. Evaluation does not automatically redact text or cancel an operation that already happened.