tool.go

Overview

This file implements an adapter that integrates Model Context Protocol (MCP) tools into the agent tooling system. It defines a wrapper type that converts MCP tools into native tools conforming to the tool.Tool interface used by agents and large language models (LLMs). This allows agents to discover and invoke external MCP tools seamlessly as part of their toolsets.

The main responsibilities of this file include:

This integration extends the Tooling System with MCP tools, enabling dynamic extension of agent capabilities through the MCP ecosystem.

Types and Functions

getSessionFunc

type getSessionFunc func(ctx context.Context) (*mcp.ClientSession, error)

This function type is used internally to lazily initialize and retrieve the MCP session required to call MCP tools.

convertTool

func convertTool(t *mcp.Tool, getSessionFunc getSessionFunc) (tool.Tool, error)

This function creates an instance of mcpTool that holds the MCP tool's name, description, and JSON schema for input/output validation, along with the session getter function.

mcpTool

type mcpTool struct {
	name            string
	description     string
	funcDeclaration *genai.FunctionDeclaration

	getSessionFunc getSessionFunc
}

This struct acts as the adapter between MCP tools and the ADK tooling system.

Name() string

func (t *mcpTool) Name() string

Implements the tool.Tool interface method.

Description() string

func (t *mcpTool) Description() string

Implements the tool.Tool interface method.

IsLongRunning() bool

func (t *mcpTool) IsLongRunning() bool

Implements the tool.Tool interface method. MCP tools are treated as short-lived calls.

ProcessRequest

func (t *mcpTool) ProcessRequest(ctx tool.Context, req *model.LLMRequest) error

This method calls a utility to pack the tool declaration into the LLM request, enabling the LLM to discover and invoke the tool.

Declaration() *genai.FunctionDeclaration

func (t *mcpTool) Declaration() *genai.FunctionDeclaration

Used by the LLM tooling integration to register the MCP tool's callable interface.

Run

func (t *mcpTool) Run(ctx tool.Context, args any) (map[string]any, error)

Implementation Details:

  1. Obtains the MCP client session via getSessionFunc.

  2. Calls session.CallTool with the tool name and arguments.

  3. Checks for errors returned by the MCP tool call:

    • If IsError is true, aggregates textual error details from the response content.

    • Returns an error with detailed messages if present.

  4. If structured content is available in the response, returns it under "output".

  5. Otherwise, concatenates all text content from the response and returns it as a string under "output".

  6. If no text content is found, returns an error indicating empty response content.

This method encapsulates the MCP protocol call lifecycle and adapts the response to the agent tooling conventions.

Important Implementation Details

Interactions with Other System Components

This file is a crucial bridge between the MCP protocol toolset and the ADK agent tooling system, enabling agents to transparently invoke external MCP tools.

Usage Example

// Assume getSession is a function that returns a cached MCP client session.
mcpTool, err := convertTool(mcpToolMetadata, getSession)
if err != nil {
    // Handle error
}

// Use the tool in an agent context.
ctx := toolContext // implementor of tool.Context
args := map[string]any{
    "query": "example input",
}

result, err := mcpTool.Run(ctx, args)
if err != nil {
    // Handle tool execution error
}

// Access output result
output := result["output"]

Structure Diagram

classDiagram
class mcpTool {
-name: string
-description: string
-funcDeclaration: genai.FunctionDeclaration
-getSessionFunc: getSessionFunc
+Name(): string
+Description(): string
+IsLongRunning(): bool
+ProcessRequest(tool.Context, *model.LLMRequest): error
+Declaration(): *genai.FunctionDeclaration
+Run(tool.Context, any): map[string]any, error
}
mcpTool ..|> toolinternal.FunctionTool
mcpTool ..|> toolinternal.RequestProcessor

References to Related Topics