Module tools 

Tool definition and registry.

Tools allow the LLM to perform actions in the real world. This module provides:

• Tool trait - Define custom tools the LLM can call
• ToolName trait - Marker trait for strongly-typed tool names
• PrimitiveToolName - Tool names for SDK’s built-in tools
• DynamicToolName - Tool names created at runtime (MCP bridges)
• ToolRegistry - Collection of available tools
• ToolContext - Context passed to tool execution
• ListenExecuteTool - Tools that listen for updates, then execute later

Implementing a Tool

use agent_sdk::{Tool, ToolContext, ToolResult, ToolTier, PrimitiveToolName};

struct MyTool;

// No #[async_trait] needed - Rust 1.75+ supports native async traits
impl Tool<MyContext> for MyTool {
    type Name = PrimitiveToolName;

    fn name(&self) -> PrimitiveToolName { PrimitiveToolName::Read }
    fn display_name(&self) -> &'static str { "My Tool" }
    fn description(&self) -> &'static str { "Does something useful" }
    fn input_schema(&self) -> Value { json!({ "type": "object" }) }
    fn tier(&self) -> ToolTier { ToolTier::Observe }

    async fn execute(&self, ctx: &ToolContext<MyContext>, input: Value) -> Result<ToolResult> {
        Ok(ToolResult::success("Done!"))
    }
}

Structs

DynamicToolName

Dynamic tool name for runtime-created tools (MCP bridges, subagents).

SimpleToolAdapter

Adapter that turns any SimpleTool into a full Tool with Name = DynamicToolName.

ToolContext

Context passed to tool execution

ToolRegistry

Registry of available tools.

TypedToolAdapter

Adapter that turns any TypedTool into a full Tool.

Enums

ErasedToolStatus

Type-erased status for the agent loop.

ListenStopReason

Reason for stopping a listen session.

ListenToolUpdate

Update emitted from a listen() stream.

PrimitiveToolName

Tool names for SDK’s built-in primitive tools.

ToolStatus

Status update from an async tool operation.

Traits

AsyncTool

A tool that performs long-running async operations.

ErasedAsyncTool

Type-erased async tool trait for registry storage.

ErasedListenTool

Type-erased listen/execute tool trait for registry storage.

ErasedTool

Type-erased tool trait for registry storage.

ListenExecuteTool

A tool whose runtime has two phases:

ProgressStage

Marker trait for tool progress stages (type-safe, like ToolName).

SimpleTool

An ergonomic Tool whose name is a plain string.

Tool

Definition of a tool that can be called by the agent.

ToolLogic

The execute-only half of a tool, used as the target of the #[derive(Tool)] / #[derive(TypedTool)] ergonomics macros.

ToolName

Marker trait for tool names.

TypedTool

A tool whose model-emitted arguments are validated against a typed, deserializable Input before execute runs.

Functions

invalid_tool_input_result

Synthesise the structured validation-error ToolResult returned to the model when its arguments fail to deserialize into a TypedTool::Input.

stage_to_string

Helper to get string representation of a progress stage via serde.

tool_name_from_str

Parse a tool name from string via serde.

tool_name_to_string

Helper to get string representation of a tool name via serde.

validate_tool_input

Deserialize raw model args into a typed Input, or synthesise the structured validation-error result.