Crate llm_tool 

llm-tool

Framework-agnostic Rust tool definitions for LLM agents.

Write plain Rust functions. Get typed LLM tools with JSON Schemas, automatic deserialization, and instant MCP server support.

Why llm-tool?

• Zero Boilerplate: #[llm_tool] on a function → typed tool with JSON Schema.
• Strongly Typed: Parameters are validated. Missing or extra arguments are caught instantly.
• Framework Agnostic: Use the ToolRegistry to get JSON Schemas for any LLM SDK (OpenAI, Anthropic, Gemini, …).
• MCP Ready: Spin up a fully compliant MCP server in 3 lines with llm-tool-mcp.
• no_std Compatible: Core types work in embedded and WASM targets.

---

⚡ Quick Start

[dependencies]
llm-tool = "0.5"
llm-tool-mcp = "0.5" # Optional: for MCP server support

Define a Tool

Doc comments become tool and parameter descriptions automatically.

use llm_tool::{llm_tool, ToolError, ToolRegistry};

/// Fetches the current weather for a given location.
#[llm_tool]
async fn get_weather(
    /// The city to look up (e.g., "San Francisco, CA").
    location: String,
    /// Whether to use Celsius or Fahrenheit.
    celsius: Option<bool>,
) -> Result<String, ToolError> {
    let temp = if celsius.unwrap_or(true) { "22°C" } else { "72°F" };
    Ok(format!("The weather in {location} is sunny and {temp}."))
}

// Register it! The macro generated a `GetWeather` struct for us.
let registry = ToolRegistry::new().with_tool(GetWeather);

// You can now extract the JSON schema for any LLM SDK...
let definitions = registry.definitions();
assert_eq!(definitions[0].name, "get_weather");

// ...or execute calls directly from JSON arguments!
let ctx = llm_tool::ToolContext::new(None);
let result = registry.dispatch(
    "get_weather",
    serde_json::json!({"location": "London"}),
    &ctx
).await.unwrap();

---

🚀 MCP: Tools, Prompts, and Resources

Use llm-tool-mcp to expose everything over the Model Context Protocol.

/// A Tool for the LLM to execute.
#[llm_tool]
fn restart_server(
    /// Whether to force-restart even if requests are in-flight.
    force: bool,
) -> String {
    format!("Server restarted (force={force}).")
}

/// A Prompt template for the LLM to use.
#[llm_prompt]
fn code_review(
    /// Programming language of the code to review.
    lang: String,
) -> String {
    format!("Please review this {lang} code for security bugs.")
}

/// A Resource for the LLM to read.
#[llm_resource(uri = "file:///config/{app}.json")]
fn get_config(
    /// Application name whose config to retrieve.
    app: String,
) -> String {
    format!(r#"{{"app":"{app}","enabled":true}}"#)
}

// Register tools in the ToolRegistry.
let registry = ToolRegistry::new().with_tool(RestartServer);
assert_eq!(registry.definitions()[0].name, "restart_server");

// Prompts and Resources are registered via llm-tool-mcp:
//   McpServer::new("my-server", "1.0", registry)
//       .with_prompt(CodeReview)
//       .with_resource(GetConfig);

---

🧠 Features

Return Types & Error Handling

Return Result<T, E> or just T. The ? operator works out of the box.

• Auto-Serialization: Return any T: Serialize → automatic JSON response.
• Structured Metadata: Attach hidden metadata to ToolOutput or ToolError (logged but not sent to the LLM).

Context

Add ctx: &ToolContext to any tool function to access shared state, conversation IDs, or typed extensions — automatically hidden from the JSON Schema.

Custom Descriptions

Override doc comments with an inline string — no extra features needed:

#[llm_tool(prompt = "Query the database and return structured results.")]
async fn query_db(
    /// The SQL query to execute.
    query: String,
) -> Result<String, ToolError> {
    Ok(format!("Results for: {query}"))
}

With the md-tmpl feature, you can also load descriptions from .tmpl.md template files (prompt_file = "..."), with compile-time variable substitution and validation. See the md-tmpl docs for details.

---

Documentation

• llm-tool — Return types, tool context, metadata, template descriptions.
• llm-tool-mcp — MCP transports, stdio/TCP, routing.
• md-tmpl — Template syntax, env variables, response templates.

License

Dual-licensed under Apache-2.0 OR MIT.

Structs

EmptyParams

Convenience type for tools that take no parameters.

Json

Wrapper for returning serializable values as JSON tool output.

PromptArgumentDefinition

An argument accepted by a prompt template.

PromptDefinition

Describes a prompt template available in the registry.

PromptOutput

The output returned by rendering a prompt template.

PromptOutputMessage

A rendered message inside a prompt output.

ResourceDefinition

Describes a resource or resource template available in the registry.

ResourceOutput

The output returned by reading a resource.

ToolContext

Context passed to Rust tools during dispatch.

ToolDefinition

Describes a custom tool that can be registered with an agent.

ToolError

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.

ToolOutput

The return value of a Rust tool execution.

ToolRegistry

A registry of named tools available for dynamic dispatch.

Enums

ResourceOutputContent

A content block inside a resource read output.

Traits

ErasedPrompt

Type-erased wrapper enabling heterogeneous prompt storage.

ErasedResource

Type-erased wrapper enabling heterogeneous resource storage.

JsonSchema

A type which can be described as a JSON Schema document.

RustPrompt

A custom prompt template implemented in Rust with strongly-typed parameters.

RustResource

A custom resource or resource template implemented in Rust.

RustTool

A custom tool implemented entirely in Rust with strongly-typed parameters.

Functions

definition_of

Build a ToolDefinition from any RustTool implementor.

definition_of_prompt

Build a PromptDefinition from any RustPrompt implementor.

definition_of_resource

Build a ResourceDefinition from any RustResource implementor.

match_uri_template

Helper to match an incoming URI against a URI template pattern with {variable} placeholders.

Type Aliases

BoxPromptFuture

Type-erased future returned by ErasedPrompt::render_erased.

BoxResourceFuture

Type-erased future returned by ErasedResource::read_erased.

Attribute Macros

llm_prompt

Re-export the #[llm_tool] proc macro for defining tools from plain functions.

llm_resource

Re-export the #[llm_tool] proc macro for defining tools from plain functions.

llm_tool

Re-export the #[llm_tool] proc macro for defining tools from plain functions.

Derive Macros

JsonSchema

Derive macro for JsonSchema trait.