Scan a tool call before execution — scan_tool

scan_tool_call() validates tool-call intent and arguments before an application executes the tool. It serializes the tool name and arguments, scans that text with scan_prompt(), and adds an explicit finding when the tool is outside an allowlist.

Usage

scan_tool_call(
  tool_name,
  arguments = list(),
  allowed_tools = NULL,
  policy = "enterprise_default",
  reviewer = NULL,
  checks = "rules",
  redaction = NULL,
  scanners = scanner_options(),
  show_tokens = FALSE
)

Arguments

tool_name: Tool name requested by a model or orchestrator.
arguments: Tool arguments as a list, data frame, character string, or other JSON-serializable value.
allowed_tools: Optional character vector of approved tool names.
policy: A shieldr_policy or built-in policy name.
reviewer: Optional reviewer function or object with $chat().
checks: One of "rules", "nlp", "llm", or "both".
redaction: Optional redaction strategy from redaction_strategy().
scanners: Optional scanner configuration from scanner_options().
show_tokens: Whether to attach token counts when ellmer is available.

Value

A shieldr_report.

Details

This helper does not execute tools. It is designed to sit immediately before an application-level dispatcher. Use allowed_tools for a simple allowlist, and use normal policy rules or custom rules to validate argument content.

The returned shieldr_report() stores stage = "tool_call" and tool_name in metadata, so audit logs can distinguish tool input checks from prompt, context, and output checks.

Examples

report <- scan_tool_call(
  "send_email",
  list(to = "neel@example.com", body = "hello"),
  allowed_tools = c("search_docs", "send_email")
)

report$action
#> [1] "redact"