Struct ToolError

Source

pub struct ToolError {
    pub message: String,
    /* private fields */
}

Expand description

An error returned from a tool execution.

The error message is sent back to the model as the tool’s error response. Structured metadata can be attached for hooks and logging — it is not sent to the model.

Implements From<String> and From<&str> for ergonomic construction.

§Example

use llm_tool::ToolError;
use serde::Serialize;

let err: ToolError = "something went wrong".into();
assert_eq!(err.to_string(), "something went wrong");

let err = ToolError::new(format!("failed to read {}", "file.txt"));
assert!(err.to_string().contains("file.txt"));

// Structured metadata from a typed struct (preferred)
#[derive(Serialize)]
struct HttpErrorMeta {
    status_code: u16,
    url: String,
}

let err = ToolError::new("HTTP request failed")
    .with_metadata(&HttpErrorMeta {
        status_code: 503,
        url: "https://example.com".into(),
    })
    .unwrap();
assert_eq!(err.metadata()["status_code"], 503);

// Single ad-hoc entry
let err = ToolError::new("timeout").with_meta("retry_after_secs", serde_json::json!(30));
assert_eq!(err.metadata()["retry_after_secs"], 30);

Fields§

§message: String

Human-readable error message sent to the model.

Implementations§

Source §

impl ToolError

Source

pub const ERROR_KIND_KEY: &'static str = "error_kind"

Metadata key identifying the structured category of an error.

Source

pub const KIND_NOT_REGISTERED: &'static str = "not_registered"

ERROR_KIND_KEY value used by not_found to mark a registry-lookup miss.

Source

pub const KIND_DESTRUCTIVE_BATCH: &'static str = "destructive_in_parallel_batch"

ERROR_KIND_KEY value used by destructive_in_parallel_batch when a destructive tool is rejected during parallel batch execution.

Source

pub fn new(message: impl Into<String>) -> Self

Create a new tool error with no metadata.

Source

pub fn not_found(kind: RegistryItem, name: &str) -> Self

Construct an error for a registry lookup that found no entry named name of the given RegistryItem.

The human-readable message is suitable to hand back to the model so it can self-correct (e.g. retry with a valid name). An ERROR_KIND_KEY metadata field is attached — never sent to the model — so hosts can still distinguish a routing miss from a genuine execution failure for telemetry or policy decisions. Prefer is_not_found over inspecting the metadata directly.

§Example

use llm_tool::{RegistryItem, ToolError};

let err = ToolError::not_found(RegistryItem::Tool, "add_nummbers");
assert!(err.to_string().contains("add_nummbers"));
assert!(err.is_not_found());

Source

pub fn destructive_in_parallel_batch(tool_name: &str) -> Self

Construct a typed error when a tool with ToolEffect::Destructive is rejected in unconfirmed parallel batch dispatch.

Source

pub fn with_meta(self, key: impl Into<String>, value: Value) -> Self

Attach a single metadata key-value pair. Chainable.

For attaching multiple fields at once, prefer with_metadata with a typed struct.

Source

pub fn with_metadata<T: Serialize>(self, value: &T) -> Result<Self, Self>

Attach structured metadata from a serializable value.

The value is serialized to a JSON object and its fields are merged into the metadata map. See ToolOutput::with_metadata for details.

§Errors

Returns Err(self) if value doesn’t serialize to a JSON object.

Source

pub const fn metadata(&self) -> &HashMap<String, Value>

The structured metadata map.

Source

pub fn is_not_found(&self) -> bool

Whether this error denotes a registry-lookup miss, i.e. it was produced by not_found.

Lets hosts branch on “the model asked for something that isn’t registered” versus “a registered handler failed” without matching on message strings.

§Example

use llm_tool::{RegistryItem, ToolError};

assert!(ToolError::not_found(RegistryItem::Prompt, "summarize").is_not_found());
assert!(!ToolError::new("handler blew up").is_not_found());

Source