3.3 MCP Toolbox for Databases & Custom Tool Integrations

1. Key Concept Definitions: The ADK & MCP Tooling Stack

1. MCP Toolbox for Databases

Google’s open-source MCP server connecting ADK agents to AlloyDB, Cloud SQL, Spanner, and BigQuery. Manages connection pooling, IAM/OAuth auth, OpenTelemetry tracing, and hot-reloadable parameterized SQL in tools.yaml.

2. Custom FunctionTool & Schemas

Wraps a Python function as a callable ADK tool. Gemini reads the function’s name, parameter type hints, and docstring to decide when and how to invoke it, expecting a structured Python dict return.

3. ToolContext (Runtime Injection)

Adding tool_context: ToolContext to a Python tool signature lets your code read/write tool_context.state, load/save artifacts, or set actions.escalate = True—injected automatically by ADK and hidden from the LLM!

4. LongRunningFunctionTool & OpenAPI

LongRunningFunctionTool returns an immediate pending ticket/job ID for slow async tasks without blocking. OpenAPIToolset parses an OpenAPI v3 spec to auto-generate callable RestApiTool operations.

5. Built-In Tool Isolation (AgentTool)

Gemini built-in tools (google_search, BuiltInCodeExecutor) cannot mix directly with custom tools on one LlmAgent. Isolate the built-in tool inside a specialist sub-agent wrapped in AgentTool!

2. Interactive Tool Architecture Switcher

Switch between the 3 Tool Integration Modes below and click the 4 stages to explore how MCP Toolbox for Databases, ADK Function Tools, and OpenAPI / AgentTool Wrappers work under the hood:

STAGE 1: ADK AGENT CONNECTION

1. Decoupling Agent Code from Database Drivers

How It Works Under the Hood

Instead of installing database drivers inside every agent container, the ADK agent connects to MCP Toolbox using ToolboxClient or MCPToolset.

Core Architecture Rule

Always select MCP Toolbox for Databases when multiple agents need governed, pooled access to Cloud SQL, AlloyDB, Spanner, or BigQuery!

3. Visual Tool Selection & Parameter Matrix

Use this comparison table to select the right ADK tool class and configuration for any enterprise requirement:

Tool Type / Class	Configuration Inputs	Runtime Output / Behavior	Primary Architectural Trigger
MCP Toolbox for Databases (`ToolboxClient` / `MCPToolset`)	`tools.yaml` (`sources`, `tools`, `toolsets`) + Server URL	Pooled, IAM-authenticated, parameterized SQL queries against AlloyDB, Cloud SQL, Spanner, or BigQuery.	Any scenario requiring secure database access, connection pooling, or updating SQL tools without redeploying agents.
Custom Function Tool (`FunctionTool`)	Python function with type hints, docstring, and optional `tool_context: ToolContext`	Executes custom Python logic and returns a JSON-serializable `dict` to the LLM.	Custom business calculations or bespoke API calls where no OpenAPI spec or MCP server exists.
OpenAPI Toolset (`OpenAPIToolset`)	OpenAPI v3 YAML/JSON specification + Auth config	Auto-generates `RestApiTool` instances for every REST endpoint in the spec.	Integrating an existing microservice or third-party REST API that already has an OpenAPI / Swagger specification.
Long-Running Tool (`LongRunningFunctionTool`)	Async/generator function that returns an initial job/ticket status	Returns a pending job ID immediately so the agent doesn’t block or time out on multi-minute tasks.	Batch data processing, slow external workflows, or asynchronous human approval tickets.
Built-In Gemini Tools (`google_search`, `BuiltInCodeExecutor`)	Pre-built ADK tool objects passed to `tools=[...]`	Runs grounded Google Search or sandboxed Python code execution inside Gemini.	Must be isolated in its own agent (and wrapped in `AgentTool`) if you also need custom tools on the root agent!

4. Real-World Deep Dive: `tools.yaml`, `ToolContext` & Built-In Tool Brain-Twisters

Architect Question	How It Works Under the Hood in Production
“What are the 3 top-level keys of `tools.yaml` in MCP Toolbox for Databases, and why does modifying a SQL query in `tools.yaml` not require redeploying our ADK agent containers?”	Decoupled Declarative SQL (`sources`, `tools`, `toolsets`): In `tools.yaml`, `sources:` defines pooled DB connections, `tools:` defines parameterized SQL statements, and `toolsets:` bundles tools by role. Because ADK agents dynamically fetch tool schemas from the MCP Toolbox server at runtime, updating `tools.yaml` on the Toolbox server hot-reloads the SQL logic with zero agent container redeployments!
“Why should we NEVER document `tool_context: ToolContext` inside our Python function’s docstring `Args:` block?”	Automatic Schema Stripping: ADK strips `tool_context: ToolContext` from the JSON schema sent to Gemini and injects the live `ToolContext` object automatically in Python. If you mention `tool_context` in the docstring text, the LLM may get confused and attempt to invent a parameter that does not exist in its schema!
“How do we combine `google_search` (or `BuiltInCodeExecutor`) with custom `FunctionTool` or `MCPToolset` tools without triggering an API conflict?”	The `AgentTool` Wrapper Pattern: Gemini models cannot mix native built-in tools and custom function declarations in the same single-agent turn. Create a dedicated specialist `LlmAgent(name='search_specialist', tools=[google_search])`, wrap it in `AgentTool(agent=search_specialist)`, and pass that `AgentTool` into your root agent’s `tools=[...]` list alongside your custom tools!