Tool Framework

Relevant source files

Purpose and Scope

The Tool Framework provides the foundational abstractions and interfaces for enabling AI agents to interact with external systems, APIs, and data sources. This page documents the core tool interfaces (BaseTool, BaseAuthenticatedTool, BaseToolset), the tool declaration mechanism, schema conversion utilities, and the execution contract that all tools must implement.

For information about specific tool types, see:

Built-in tools (Google Search, Maps, etc.): Built-in Tools
Code execution tools: Code Execution
OpenAPI/REST API tools: OpenAPI Tools
Model Context Protocol tools: MCP Tools
BigQuery data tools: BigQuery Tools
Creating custom tools: Custom Tools
Authentication and user confirmation: Tool Authentication and Confirmation

Tool Architecture Overview

Diagram: Tool Framework Core Components

Sources: src/google/adk/tools/openapi_tool/openapi_spec_parser/rest_api_tool.py68-450 src/google/adk/tools/_gemini_schema_util.py1-182 src/google/adk/tools/openapi_tool/openapi_spec_parser/operation_parser.py35-270

Core Abstractions

BaseTool

BaseTool is the abstract base class that defines the interface contract for all tools in ADK. Every tool must extend this class and implement its required methods.

Key Characteristics:

Provides tool identity through name and description attributes
Declares input parameters via _get_declaration() method returning FunctionDeclaration
Defines execution contract through run_async() method
Supports both synchronous and asynchronous execution patterns

Tool Identity:

Property	Type	Purpose
`name`	`str`	Unique identifier for the tool, used by LLMs to select tools
`description`	`str`	Human-readable explanation of tool purpose and usage
`is_long_running`	`bool`	Indicates if tool execution may take extended time

Core Methods:

Sources: src/google/adk/tools/openapi_tool/openapi_spec_parser/rest_api_tool.py68-94 src/google/adk/tools/openapi_tool/openapi_spec_parser/rest_api_tool.py185-193 src/google/adk/tools/openapi_tool/openapi_spec_parser/rest_api_tool.py358-436

BaseAuthenticatedTool

BaseAuthenticatedTool extends BaseTool to add authentication capabilities. Tools that require API keys, OAuth tokens, or other credentials should extend this class.

Authentication Properties:

Property	Type	Purpose
`auth_scheme`	`AuthScheme`	Defines authentication method (API key, OAuth2, etc.)
`auth_credential`	`AuthCredential`	Contains actual credentials or credential retrieval info
`credential_exchanger`	`AutoAuthCredentialExchanger`	Handles credential exchange and refresh

Authentication Configuration:

Authentication Flow:

Diagram: Authenticated Tool Execution Flow

Sources: src/google/adk/tools/openapi_tool/openapi_spec_parser/rest_api_tool.py82-155 src/google/adk/tools/openapi_tool/openapi_spec_parser/rest_api_tool.py195-220 src/google/adk/tools/openapi_tool/openapi_spec_parser/rest_api_tool.py364-393

BaseToolset

BaseToolset is an abstract base class for grouping multiple related tools together. Toolsets simplify tool management when dealing with families of related operations (e.g., all BigQuery operations, all operations from a single API).

Toolset Characteristics:

Aggregates multiple BaseTool instances
Provides unified configuration (e.g., shared authentication)
Enables batch tool operations
Simplifies agent configuration with logical grouping

Common Toolset Pattern:

Example: OpenAPI Toolset Structure

Diagram: Toolset Aggregation Pattern

Sources: src/google/adk/tools/openapi_tool/openapi_spec_parser/openapi_spec_parser.py51-239 tests/unittests/tools/openapi_tool/openapi_spec_parser/test_openapi_toolset.py47-61

Tool Declaration and Schema

FunctionDeclaration

Tools declare their interface to LLMs using FunctionDeclaration, a Gemini-compatible schema format that describes:

Tool name and description
Input parameters with types and constraints
Optional output schema

Declaration Structure:

Component	Type	Purpose
`name`	`str`	Function identifier (max 60 characters)
`description`	`str`	Usage instructions and purpose
`parameters`	`Schema`	Input parameter schema in Gemini format

Schema Example:

Declaration Method in RestApiTool:

src/google/adk/tools/openapi_tool/openapi_spec_parser/rest_api_tool.py185-193

Sources: src/google/adk/tools/openapi_tool/openapi_spec_parser/rest_api_tool.py185-193 src/google/adk/tools/openapi_tool/openapi_spec_parser/operation_parser.py241-253

Schema Conversion

The tool framework provides utilities to convert between different schema formats, primarily in _gemini_schema_util.py.

Key Conversion Functions:

Function	Purpose
`_to_gemini_schema()`	Converts OpenAPI v3.1 schema to Gemini `Schema`
`_sanitize_schema_formats_for_gemini()`	Filters unsupported fields and formats
`_dereference_schema()`	Resolves `$ref` pointers in JSON schemas
`_to_snake_case()`	Converts naming conventions (camelCase → snake_case)

Schema Conversion Pipeline:

Diagram: Schema Conversion Pipeline

Supported Type Mappings:

OpenAPI Type	Gemini Type	Notes
`string`	`STRING`	Supports `enum`, `date-time` formats
`integer`	`INTEGER`	Supports `int32`, `int64` formats
`number`	`NUMBER`	Float/double values
`boolean`	`BOOLEAN`	-
`array`	`ARRAY`	With `items` schema
`object`	`OBJECT`	With `properties` map
`["string", "null"]`	`STRING` (nullable=true)	Nullable types

Format Sanitization:

src/google/adk/tools/_gemini_schema_util.py115-165

Name Conversion:

src/google/adk/tools/_gemini_schema_util.py35-74

Sources: src/google/adk/tools/_gemini_schema_util.py35-182 tests/unittests/tools/test_gemini_schema_util.py23-461

Tool Parameter Processing

ApiParameter

The ApiParameter class represents a single function parameter, handling type conversion and validation.

Parameter Properties:

Property	Type	Purpose
`original_name`	`str`	Name from source (OpenAPI, etc.)
`py_name`	`str`	Python-compatible identifier (snake_case)
`param_location`	`str`	Where parameter appears (query, body, header, path, cookie)
`param_schema`	`Schema`	Type and validation rules
`description`	`str`	Human-readable explanation
`type_value`	`type`	Python type for runtime (str, int, List[str], etc.)
`type_hint`	`str`	Type hint string for documentation
`required`	`bool`	Whether parameter is mandatory

Parameter Location Types:

Location	Description	Example Use Case
`query`	URL query parameters	`?location=SF&units=C`
`body`	Request body (JSON)	POST/PUT payload
`header`	HTTP headers	Authentication, content-type
`path`	URL path segments	`/users/{userId}`
`cookie`	Cookie values	Session tokens

Type Inference:

src/google/adk/tools/openapi_tool/common/common.py106-176

Parameter Name Sanitization:

src/google/adk/tools/openapi_tool/common/common.py33-51

Sources: src/google/adk/tools/openapi_tool/common/common.py54-104 tests/unittests/tools/openapi_tool/common/test_common.py49-157

OperationParser

For OpenAPI-based tools, OperationParser extracts parameters from OpenAPI Operation objects and converts them to ApiParameter instances.

Parsing Pipeline:

Diagram: OperationParser Processing Flow

Parameter Extraction Methods:

Method	Source	Output
`_process_operation_parameters()`	`operation.parameters`	Query, path, header, cookie params
`_process_request_body()`	`operation.requestBody`	Body parameters
`_process_return_value()`	`operation.responses['2xx']`	Return type schema
`_dedupe_param_names()`	All parameters	Unique parameter names

Request Body Handling:

src/google/adk/tools/openapi_tool/openapi_spec_parser/operation_parser.py105-152

Parameter Deduplication:

src/google/adk/tools/openapi_tool/openapi_spec_parser/operation_parser.py153-163

Sources: src/google/adk/tools/openapi_tool/openapi_spec_parser/operation_parser.py35-270 tests/unittests/tools/openapi_tool/openapi_spec_parser/test_operation_parser.py26-401

Tool Execution

ToolContext

ToolContext provides execution environment information to tools, including access to session state, authentication, and agent context.

Context Properties:

Property	Type	Purpose
`state`	`State`	Session and app-level state
`get_auth_response()`	method	Retrieve authentication responses
`request_credential()`	method	Request user credentials

Context Usage in Tools:

Sources: src/google/adk/tools/openapi_tool/openapi_spec_parser/rest_api_tool.py358-436 tests/unittests/tools/openapi_tool/openapi_spec_parser/test_rest_api_tool.py42-49

Execution Contract

All tools must implement the run_async() method, which defines the execution contract.

Method Signature:

Return Value Conventions:

Pattern	Purpose	Example
Success result	Normal execution	`{"result": "success", "data": {...}}`
Error result	Execution failure	`{"error": "Error message with details"}`
Pending result	Awaiting user input	`{"pending": True, "message": "Need auth"}`
Text fallback	Non-JSON response	`{"text": "Plain text response"}`

Execution Error Handling:

RestApiTool Execution Example:

src/google/adk/tools/openapi_tool/openapi_spec_parser/rest_api_tool.py364-436

Sources: src/google/adk/tools/openapi_tool/openapi_spec_parser/rest_api_tool.py358-436 tests/unittests/tools/openapi_tool/openapi_spec_parser/test_rest_api_tool.py199-269

Tool Integration with Agents

Agent Tool Assignment

Tools are assigned to agents via the tools parameter during agent initialization.

Assignment Patterns:

Tool Execution Flow in Agents

Diagram: Tool Execution in Agent Context

Tool Declaration Injection:

During agent execution, the flow preprocesses the LLM request to include tool declarations:

Tool Result Handling:

After tool execution, results are formatted and sent back to the LLM:

Sources: src/google/adk/tools/openapi_tool/openapi_spec_parser/rest_api_tool.py68-193 tests/unittests/tools/openapi_tool/openapi_spec_parser/test_rest_api_tool.py42-140

Tool Name Constraints

Tool names in ADK are subject to LLM provider constraints:

Constraint	Value	Reason
Max length	60-64 characters	Gemini function name limit
Format	snake_case	Python convention
Characters	`[a-z0-9_]`	Function identifier rules
Uniqueness	Required	Disambiguation

Name Truncation:

src/google/adk/tools/openapi_tool/openapi_spec_parser/rest_api_tool.py117-119

Name Conversion:

Tool names are automatically converted to snake_case using _to_snake_case():

src/google/adk/tools/openapi_tool/openapi_spec_parser/operation_parser.py189-194

Sources: src/google/adk/tools/_gemini_schema_util.py35-74 src/google/adk/tools/openapi_tool/openapi_spec_parser/rest_api_tool.py117-119 src/google/adk/tools/openapi_tool/openapi_spec_parser/operation_parser.py189-194

Tool Framework Class Hierarchy

Diagram: Tool Framework Class Hierarchy

Sources: src/google/adk/tools/openapi_tool/openapi_spec_parser/rest_api_tool.py68-450 src/google/adk/tools/openapi_tool/openapi_spec_parser/operation_parser.py35-270 src/google/adk/tools/openapi_tool/common/common.py54-263

Summary

The Tool Framework provides:

Core Abstractions: BaseTool, BaseAuthenticatedTool, BaseToolset define the tool interface contract
Schema Conversion: Utilities to convert OpenAPI schemas to Gemini-compatible FunctionDeclaration format
Parameter Processing: ApiParameter and OperationParser handle type inference and parameter extraction
Execution Contract: Standardized run_async() method with ToolContext for state and authentication
Agent Integration: Seamless tool declaration and execution within agent workflows

This framework enables ADK to support diverse tool types (REST APIs, MCP, BigQuery, custom Python functions) through a unified interface, while handling authentication, schema conversion, and error handling consistently.

For specific tool implementations, see the related pages listed at the beginning of this document.