Struct Tool 

pub struct Tool {
    pub name: String,
    pub title: Option<String>,
    pub description: Option<String>,
    pub output_schema: Option<Value>,
    pub icons: Option<Vec<ToolIcon>>,
    pub annotations: Option<ToolAnnotations>,
    pub meta: Option<Value>,
    pub task_support: TaskSupportMode,
    /* private fields */
}

A complete tool definition with service-based execution.

Tools are implemented as Tower services internally, enabling middleware composition via the builder’s .layer() method. The service is wrapped in [ToolCatchError] to convert any errors (from handlers or middleware) into CallToolResult::error() responses.

Fields

name: String

Tool name (must be 1-128 chars, alphanumeric/underscore/hyphen/dot only)

title: Option<String>

Human-readable title for the tool

description: Option<String>

Description of what the tool does

output_schema: Option<Value>

JSON Schema for the tool’s output (optional)

icons: Option<Vec<ToolIcon>>

Icons for the tool

annotations: Option<ToolAnnotations>

Tool annotations (hints about behavior)

meta: Option<Value>

Validated protocol metadata included in tools/list.

task_support: TaskSupportMode

Task support mode for this tool

Implementations

impl Tool

pub fn with_mcp_app(self, metadata: McpUiToolMeta) -> Result<Self, McpAppError>

Attach typed _meta.ui linkage and visibility to this built tool.

Existing unrelated metadata keys are preserved. A prior ui key is replaced by the typed value.

impl Tool

pub fn builder(name: impl Into<String>) -> ToolBuilder

Create a new tool builder

pub fn definition(&self) -> ToolDefinition

Get the tool definition for tools/list

pub fn with_meta(self, meta: Value) -> Result<Self, MetaValidationError>

Attach validated protocol metadata to this tool definition.

pub fn call(&self, args: Value) -> BoxFuture<'static, CallToolResult>

Call the tool without context

Creates a dummy request context. For full context support, use call_with_context.

pub fn call_with_context( &self, ctx: RequestContext, args: Value, ) -> BoxFuture<'static, CallToolResult>

Call the tool with request context

The context provides progress reporting, cancellation support, and access to client requests (for sampling, etc.).

Note

This method returns CallToolResult directly (not Result<CallToolResult>). Any errors from the handler or middleware are converted to CallToolResult::error() with is_error: true.

pub fn call_outcome( &self, args: Value, ) -> BoxFuture<'static, Result<RequestOutcome<CallToolResult>>>

Call the tool and preserve an SEP-2322 input-required outcome.

pub fn call_outcome_with_context( &self, ctx: RequestContext, args: Value, ) -> BoxFuture<'static, Result<RequestOutcome<CallToolResult>>>

Call the tool with context and preserve an SEP-2322 input-required outcome or protocol-level handler error.

pub fn require_client_capabilities(self, required: ClientCapabilities) -> Self

Require the given client capability shape before this tool may be invoked using the modern per-request protocol.

Required objects are matched recursively. For example, requiring ClientCapabilities { sampling: Some(Default::default()), .. } accepts any advertised sampling capability, including one with additional optional fields.

pub fn required_client_capabilities(&self) -> Option<&ClientCapabilities>

Return the client capability shape required by this tool, if any.

pub fn with_task_preparation<F, Fut>(self, prepare: F) -> Self

where F: Fn(TaskContext, Value) -> Fut + Send + Sync + 'static, Fut: Future<Output = Result<TaskPreparation>> + Send + 'static,

Add a preparation callback for task-backed invocations.

The callback runs exactly once after task ID allocation and before the initial task response. It is skipped for synchronous calls.

pub fn with_typed_task_preparation<I, F, Fut>(self, prepare: F) -> Self

where I: DeserializeOwned + Send + Sync + 'static, F: Fn(TaskContext, I) -> Fut + Send + Sync + 'static, Fut: Future<Output = Result<TaskPreparation>> + Send + 'static,

Add a typed preparation callback to an already-built tool.

pub fn with_guard<G>(self, guard: G) -> Self

where G: Fn(&ToolRequest) -> Result<(), String> + Clone + Send + Sync + 'static,

Apply a guard to this built tool.

The guard runs before the handler and can short-circuit with an error. This is useful for applying the same guard to multiple tools (per-group pattern):

use tower_mcp::{ToolBuilder, CallToolResult};
use tower_mcp::tool::ToolRequest;
use schemars::JsonSchema;
use serde::Deserialize;

#[derive(Debug, Deserialize, JsonSchema)]
struct Input { value: String }

fn build_tool(name: &str) -> tower_mcp::tool::Tool {
    ToolBuilder::new(name)
        .handler(|i: Input| async move { Ok(CallToolResult::text(&i.value)) })
        .build()
}

let guard = |_req: &ToolRequest| -> Result<(), String> { Ok(()) };

let tools: Vec<_> = vec![build_tool("a"), build_tool("b")]
    .into_iter()
    .map(|t| t.with_guard(guard.clone()))
    .collect();

pub fn with_name_prefix(&self, prefix: &str) -> Self

Create a new tool with a prefixed name.

This creates a copy of the tool with its name prefixed by the given string and a dot separator. For example, if the tool is named “query” and the prefix is “db”, the new tool will be named “db.query”.

This is used internally by McpRouter::nest() to namespace tools.

Example

use tower_mcp::{ToolBuilder, CallToolResult};
use schemars::JsonSchema;
use serde::Deserialize;

#[derive(Debug, Deserialize, JsonSchema)]
struct Input { value: String }

let tool = ToolBuilder::new("query")
    .description("Query the database")
    .handler(|i: Input| async move { Ok(CallToolResult::text(&i.value)) })
    .build();

let prefixed = tool.with_name_prefix("db");
assert_eq!(prefixed.name, "db.query");

Trait Implementations

impl Clone for Tool

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Tool

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Filterable for Tool

fn name(&self) -> &str

Returns the name of this capability.

impl Send for Tool

impl Sync for Tool