/ 
Claude-Agent-0.12
/ Claude::Agent::MCP::ToolDefinition

NAME

Claude::Agent::MCP::ToolDefinition - MCP tool definition

DESCRIPTION

Defines a custom MCP tool.

ATTRIBUTES

  • name - Tool name (will be prefixed with mcp__server__)

  • description - Description of what the tool does

  • input_schema - JSON Schema defining the tool's input parameters

  • handler - Coderef that executes the tool

HANDLER SIGNATURE

Handlers receive the input arguments and an optional IO::Async::Loop. They can return either a hashref (synchronous) or a Future (asynchronous).

# Synchronous handler (backward compatible)
sub handler {
    my ($args, $loop) = @_;

    # $args is a hashref of input parameters
    # $loop is the IO::Async::Loop (optional, may be undef)

    # Return a result hashref:
    return {
        content => [
            { type => 'text', text => 'Result text' },
        ],
        is_error => 0,  # Optional, default false
    };
}

# Asynchronous handler (returns Future)
sub async_handler {
    my ($args, $loop) = @_;

    # Use loop for async operations
    my $future = $loop->delay_future(after => 1)->then(sub {
        return Future->done({
            content => [{ type => 'text', text => 'Async result' }],
        });
    });

    return $future;  # Return Future that resolves to result hashref
}

METHODS

to_hash

my $hash = $tool->to_hash();

Convert the tool definition to a hash for JSON serialization.

execute

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

Execute the tool handler with the given arguments. Returns a Future that resolves to the result hashref.

The handler may return either a hashref (synchronous) or a Future (asynchronous). Synchronous results are automatically wrapped in Future->done().

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).