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 report(&self) -> ErrorReport

The wire form of this error.

impl ToolExecutionError

pub fn is_retryable(&self) -> bool

Whether the tool may reasonably be re-run: the explicit override when one was set, else the kind’s own default (ToolErrorKind::default_retryable); a kind that leaves it to the tool (None) is not retryable on the wire.

impl ToolExecutionError

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 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.

impl ToolExecutionError

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

Construct an error with an explicit normalized kind.

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 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 in Self::message, while the model sees stable ToolErrorKind::Other feedback. Native targets retain the downcastable source; WASM drops it. An existing ToolExecutionError retains 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 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.

Browser wasm keeps no source (see the field): the call is accepted and the source dropped, so tool code stays target-independent.

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<'de> Deserialize<'de> for ToolExecutionError

fn deserialize<__D>( __deserializer: __D, ) -> Result<ToolExecutionError, <__D as Deserializer<'de>>::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

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<ErrorReport> for ToolExecutionError

Rebuilds a tool failure from a dispatch report.

An ErrorKind::Tool report keeps its tool kind; other kinds map to the closest ToolErrorKind. Retryability, code, HTTP status, and refusal are copied, the message is model-visible, and the report is the source().

fn from(report: ErrorReport) -> ToolExecutionError

Converts to this type from the input type.

impl From<ToolContextError> for ToolExecutionError

fn from(error: ToolContextError) -> ToolExecutionError

Converts to this type from the input type.

impl Serialize for ToolExecutionError

fn serialize<__S>( &self, __serializer: __S, ) -> Result<<__S as Serializer>::Ok, <__S as Serializer>::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.