% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/tool_guardrails.R
\name{scan_tool_call}
\alias{scan_tool_call}
\title{Scan a tool call before execution}
\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{
\item{tool_name}{Tool name requested by a model or orchestrator.}

\item{arguments}{Tool arguments as a list, data frame, character string, or
other JSON-serializable value.}

\item{allowed_tools}{Optional character vector of approved tool names.}

\item{policy}{A \code{shieldr_policy} or built-in policy name.}

\item{reviewer}{Optional reviewer function or object with \verb{$chat()}.}

\item{checks}{One of \code{"rules"}, \code{"nlp"}, \code{"llm"}, or \code{"both"}.}

\item{redaction}{Optional redaction strategy from \code{\link[=redaction_strategy]{redaction_strategy()}}.}

\item{scanners}{Optional scanner configuration from \code{\link[=scanner_options]{scanner_options()}}.}

\item{show_tokens}{Whether to attach token counts when \code{ellmer} is available.}
}
\value{
A \code{shieldr_report}.
}
\description{
\code{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 \code{\link[=scan_prompt]{scan_prompt()}}, and adds an explicit finding when the
tool is outside an allowlist.
}
\details{
This helper does not execute tools. It is designed to sit immediately before
an application-level dispatcher. Use \code{allowed_tools} for a simple allowlist,
and use normal policy rules or custom rules to validate argument content.

The returned \code{\link[=shieldr_report]{shieldr_report()}} stores \code{stage = "tool_call"} and \code{tool_name}
in \code{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
}
