Enum ToolOutcome 

#[non_exhaustive]
pub enum ToolOutcome {
    Success,
    Error(ToolFailure),
    Skipped,
    Denied,
}

The structured outcome of a tool call: what happened, independent of the model-visible text.

This is Rig’s answer to “was that a success or an error?” without inspecting the result string. It mirrors Pydantic AI’s outcome: 'success' | 'failed' | 'denied' and the Vercel AI SDK’s tool-result vs tool-error distinction.

Skipped vs Denied

Both mean the tool body did not run, but they come from opposite sides — the framework vs. the tool — and are not synonyms:

• Skipped is produced by the framework when a ToolCall hook returns Flow::Skip. Approval-policy denials use Flow::Skip, so they surface as Skipped, not Denied — there is no Flow::Deny. A policy that wants to distinguish its denials from other skips can key off the skip reason it supplied, or attach its own metadata.
• Denied is authored by the tool, via ToolReturn::denied / ToolExecutionResult::denied — the tool ran its own check and refused the call (e.g. an internal authorization check). This is the tool-side counterpart to a hook skip: tools express refusal as Denied, not Skipped (there is no tool-authored skip constructor).

So is_skipped means “a hook skipped the call” and is_denied means “the tool refused it” — unambiguously, because the split is enforced by the type system: a tool authors a ToolReturnOutcome, which has no Skipped variant, and the observed Skipped outcome can be produced only inside the crate (the framework). A tool cannot construct a return or a ToolExecutionResult that claims to have been skipped.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Success

The tool ran and produced output normally.

Error(ToolFailure)

The tool failed. Carries the structured ToolFailure; the model still receives ToolExecutionResult::model_output as feedback.

Skipped

The tool body did not run because a ToolCall hook returned Flow::Skip. This is a framework outcome and includes approval-policy denials, which are expressed as Flow::Skip (see the type-level note).

Denied

A tool declared the call denied by returning ToolReturn::denied / ToolExecutionResult::denied — it ran its own check and refused. This is not produced by a hook Flow::Skip (those are Skipped); it is the tool-side counterpart to a skip (see the type-level note).

Implementations

impl ToolOutcome

pub const fn as_str(&self) -> &'static str

A stable, machine-friendly identifier for the outcome, for tracing/metrics.

pub const fn is_success(&self) -> bool

Whether the tool ran successfully.

pub const fn is_error(&self) -> bool

Whether the tool failed.

pub const fn is_skipped(&self) -> bool

Whether a hook skipped the call (Flow::Skip) before execution — a framework outcome that includes approval-policy denials (see the type-level note).

pub const fn is_denied(&self) -> bool

Whether a tool refused the call (via ToolReturn::denied). Hook / approval-policy Flow::Skip denials are Skipped, not Denied (see the type-level note).

pub const fn failure(&self) -> Option<&ToolFailure>

The ToolFailure if this is an Error, else None.

pub const fn error_kind(&self) -> Option<ToolFailureKind>

The ToolFailureKind if this is an Error, else None.

pub fn is_error_kind(&self, kind: ToolFailureKind) -> bool

Whether this is an Error of exactly kind.

The predicate a hook uses to react to a specific failure class:

use rig_core::tool::{ToolFailure, ToolFailureKind, ToolOutcome};

let outcome = ToolOutcome::Error(ToolFailure::timeout("slow upstream"));
assert!(outcome.is_error_kind(ToolFailureKind::Timeout));
assert!(!outcome.is_error_kind(ToolFailureKind::NotFound));

Trait Implementations

impl Clone for ToolOutcome

fn clone(&self) -> ToolOutcome

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ToolOutcome

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Eq for ToolOutcome

impl From<ToolReturnOutcome> for ToolOutcome

fn from(outcome: ToolReturnOutcome) -> Self

Converts to this type from the input type.

impl PartialEq for ToolOutcome

fn eq(&self, other: &ToolOutcome) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for ToolOutcome