/ 
Claude-Agent-0.15
/ Claude::Agent::MCP::ToolDefinition

NAME

Claude::Agent::MCP::ToolDefinition - A tool served from this process

SYNOPSIS

my $tool = Claude::Agent::MCP::ToolDefinition->new(
    name         => 'lookup',
    description  => 'Look something up',
    input_schema => { type => 'object', properties => { id => { type => 'string' } } },
    handler      => sub {
        my ($args, $loop) = @_;
        return { content => [{ type => 'text', text => "Found $args->{id}" }] };
    },
);

The tool function exported by Claude::Agent builds one from positional arguments.

DESCRIPTION

Defines a tool Claude can call through an in-process MCP server (Claude::Agent::MCP::Server). The handler runs in your process with whatever state it closes over.

ATTRIBUTES

name

The tool's name. Claude sees it as mcp__<server>__<name>.

description

What the tool does, for the model.

input_schema

JSON Schema for the handler's arguments.

handler

sub {
    my ($args, $loop) = @_;
    return {
        content  => [{ type => 'text', text => 'Result text' }],
        is_error => 0,
    };
}

Receives the arguments and the IO::Async::Loop the query runs on (undef when there is none). Returns a result hashref, or a Future that resolves to one. content is an array of content blocks; set is_error for a tool error. A handler that dies, or whose Future fails, yields an error result naming the tool; the exception text is logged at debug level and not sent to the model.

METHODS

new

Takes a flat list of name/value pairs. Unknown names are ignored.

to_hash

my $hash = $tool->to_hash;

{ name, description, inputSchema }, the MCP tools/list shape.

execute

my $future = $tool->execute(\%args, $loop);

Runs the handler and returns a Future of the result hashref.

AUTHOR

LNATION, <email at lnation.org>

LICENSE

This software is Copyright (c) 2026 by LNATION.

This is free software, licensed under The Artistic License 2.0 (GPL Compatible).