Struct ToolExecutionError 

pub struct ToolExecutionError { /* private fields */ }

One public envelope for every tool execution failure.

It carries normalized policy fields, separate operator-facing diagnostics and model-visible output, and an optional concrete source that can be downcast. Explicit constructors use the diagnostic message as model-visible output so deliberately authored validation failures remain actionable. Self::from_error instead treats an arbitrary source as operator-only and exposes safe kind-level feedback. Use Self::with_model_feedback or Self::with_model_output to provide a purpose-built presentation.

Implementations

impl ToolExecutionError

pub fn new( kind: ToolErrorKind, message: impl Into<String>, ) -> ToolExecutionError

Construct an error with an explicit normalized kind.

pub fn invalid_args(message: impl Into<String>) -> ToolExecutionError

Invalid arguments.

pub fn timeout(message: impl Into<String>) -> ToolExecutionError

Timeout.

pub fn cancelled(message: impl Into<String>) -> ToolExecutionError

Cancellation.

pub fn not_found(message: impl Into<String>) -> ToolExecutionError

Missing tool or resource.

pub fn permission_denied(message: impl Into<String>) -> ToolExecutionError

An authorization or permission failure.

This is an ordinary execution error. Use Self::refused when the tool intentionally declines the operation so hooks and telemetry can preserve the refusal as a distinct disposition.

pub fn refused(message: impl Into<String>) -> ToolExecutionError

An intentional, tool-authored refusal.

Refusals use the normalized ToolErrorKind::PermissionDenied kind but remain distinct from permission failures in ToolResult.

pub fn rate_limited(message: impl Into<String>) -> ToolExecutionError

Rate limit.

pub fn provider(message: impl Into<String>) -> ToolExecutionError

Upstream provider failure.

pub fn network(message: impl Into<String>) -> ToolExecutionError

Network failure.

pub fn other(message: impl Into<String>) -> ToolExecutionError

Catch-all failure.

pub fn from_error<E>(error: E) -> ToolExecutionError

where E: Error + WasmCompatSend + WasmCompatSync + 'static,

Build a safely presented Other error from a concrete source.

The source’s display string remains available as the operator-facing Self::message and the source remains downcastable, but the model sees only the stable feedback for ToolErrorKind::Other. Passing an existing ToolExecutionError preserves its classification and presentation.

pub fn with_model_feedback( self, feedback: impl Into<String>, ) -> ToolExecutionError

Replace the model-visible output with literal text feedback.

pub fn with_model_output(self, output: ToolOutput) -> ToolExecutionError

Replace the model-visible output with canonical JSON or multimodal content.

pub fn redact_model_feedback(self) -> ToolExecutionError

Replace potentially sensitive diagnostics with stable, kind-specific model feedback.

Explicit error constructors make messages model-visible by default to keep failures actionable. Call this when an explicitly constructed error’s operator diagnostic may contain secrets; Self::from_error already uses this safe presentation for arbitrary source errors.

pub fn with_retryable(self, retryable: bool) -> ToolExecutionError

Override the retryability hint.

pub fn with_code(self, code: impl Into<String>) -> ToolExecutionError

Attach an application/provider code.

pub fn with_http_status(self, status: u16) -> ToolExecutionError

Attach an HTTP status.

pub fn with_source<E>(self, source: E) -> ToolExecutionError

where E: Error + WasmCompatSend + WasmCompatSync + 'static,

Preserve a concrete source for later downcasting.

pub const fn kind(&self) -> ToolErrorKind

Normalized kind.

pub fn message(&self) -> &str

Operator-facing message.

pub fn model_feedback(&self) -> Option<&str>

Literal model feedback, when the presentation is exactly one plain text block.

Use Self::model_output for JSON or multimodal feedback.

pub fn model_output(&self) -> &ToolOutput

Canonical model-visible presentation for this error.

pub const fn retryable(&self) -> Option<bool>

Retryability hint.

pub fn code(&self) -> Option<&str>

Application/provider code.

pub const fn http_status(&self) -> Option<u16>

HTTP status.

pub const fn is_refusal(&self) -> bool

Whether the tool intentionally refused the operation.

pub fn downcast_ref<E>(&self) -> Option<&E>

where E: Error + WasmCompatSend + WasmCompatSync + 'static,

Downcast the concrete source to E.

pub fn is<E>(&self) -> bool

where E: Error + WasmCompatSend + WasmCompatSync + 'static,

Whether the concrete source has type E.

Trait Implementations

impl Clone for ToolExecutionError

fn clone(&self) -> ToolExecutionError

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ToolExecutionError

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

Formats the value using the given formatter.

impl Display for ToolExecutionError

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

Formats the value using the given formatter.

impl Error for ToolExecutionError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<MissingToolContext> for ToolExecutionError

fn from(error: MissingToolContext) -> Self

Converts to this type from the input type.