Module execution 

Invocation, continuation, and completed-result values. Invocation inputs, resumable transitions, and completed tool outcomes.

Invoke one unique handler, resolve its exact pending interaction, or cancel it. An accepted model-visible failure is ToolResult::is_error, while ToolError reports an operation failure. The caller retains call/name correlation.

Accepted tool failure versus an operation error

An unavailable application record can be a completed model-visible error. Invalid arguments never reach the callback. Neither case supplies an invented successful answer, and the caller retains invocation correlation outside ToolResult.

use tools_kit::{Toolset, ToolsetBackend, ToolHandlerBackend, ToolError};
use tools_kit::declaration::{ToolInfo, ToolName};
use tools_kit::execution::{
    ToolContent, ToolHandlerInput, ToolHandlerOutput, ToolInvocation, ToolResult,
};
use tools_kit::local::ToolRegistration;
use tools_kit::schema::JsonSchema;
let name = ToolName::new("record")?;
let info = ToolInfo::new(name.clone(), JsonSchema::strict(serde_json::json!({
    "type":"object", "required":["key"], "properties":{"key":{"type":"string"}}, "additionalProperties":false
})));
let tools = Toolset::local(vec![ToolRegistration::function(info, |input| async move {
    // The application accepts the key but cannot find its record.
    Ok(ToolResult::text(format!("No record for {}", input.arguments["key"])).with_error(true))
})])?;
let work = async {
    let mut handler = tools.tool_handler(name.clone()).await?;
    let output = handler.step(ToolHandlerInput::Invoke(ToolInvocation {
        call_id: Some("owned-call".into()), arguments: serde_json::json!({"key":"missing"}),
    })).await?;
    let ToolHandlerOutput::Completed(result) = output else { panic!("terminal result expected") };
    assert!(result.is_error);
    assert!(matches!(result.content.as_slice(), [ToolContent::Text { text, .. }] if text.contains("missing")));
    let mut invalid = tools.tool_handler(name).await?;
    let rejected = invalid.step(ToolHandlerInput::Invoke(ToolInvocation {
        call_id: None, arguments: serde_json::json!({}),
    })).await;
    assert!(matches!(rejected, Err(ToolError::InvalidArguments { .. })));
    Ok::<(), ToolError>(())
}.await;
let cleanup = tools.shutdown().await;
if let Err(error) = &cleanup {
    eprintln!("Cleanup failed: {error}");
}
work?;
cleanup?;

Structs

ToolInvocation

Invocation input for one tool handler.

ToolResult

Source-neutral result for a completed tool call. Successful output must include structured content when the declaration has an output schema. Some(Value::Null) is present content and is validated normally; None is missing. An error result remains a completed model-visible outcome.

Enums

ToolContent

Source-neutral content returned by a tool.

ToolHandlerInput

Input to one tool-handler transition.

ToolHandlerOutput

Output from one tool-handler transition.