What Are Tools in ADK: Function Calling and Registration

If the Gemini model is the "Brain" of your agent, then Tools are its "Hands." Without tools, an agent is just a chatbot—it can talk about the world, but it cannot change it. With tools, an agent becomes an effector, capable of searching the web, querying databases, sending emails, and executing complex calculations.

In the Gemini ADK, tools are built on the foundation of Function Calling. In this lesson, we will explore the technical mechanics of how Gemini converts your Python code into a machine-readable schema, how it "decides" which tool to use, and why native function calling is superior to traditional string-parsing approaches.

1. The Anatomy of a Tool

In the ADK ecosystem, a "Tool" is simply a standard Python function that has been wrapped in a way that Gemini can understand. However, for a function to be a good tool, it must provide three things to the model:

Identity: A clear, concise name (e.g., get_user_by_id).
Intent: A descriptive docstring that tells Gemini when and why to use this tool.
Interface: A strongly-typed signature that defines the required and optional arguments.

The Conversion Process:

When you pass a list of functions to the tools parameter of a Gemini model, the ADK performs an automated conversion: Python Function -> JSON Schema -> System Library for Gemini.

2. Function Calling: How it Works

Function Calling is a native capability of the Gemini 1.5 family. It is not "prompt engineering." Instead, it is a specialized training phase where the model learns to output a structured Tool Request instead of standard conversational text.

sequenceDiagram
    participant U as User
    participant G as Gemini
    participant R as ADK Runtime
    participant T as Python Function
    
    U->>G: "What is the weather in NY?"
    Note over G: Reasoning: I need the 'get_weather' tool.
    G->>R: ToolRequest(name='get_weather', args={'city': 'New York'})
    R->>T: Executes get_weather('New York')
    T-->>R: Returns "22°C, Sunny"
    R->>G: Observation: "22°C, Sunny"
    G-->>U: "The current weather in New York is 22°C and sunny."

The "Structured Output" Guarantee

Because this is a native feature, Gemini is highly reliable at producing valid JSON that matches your schema. You don't have to write complex regex parsers to find the arguments inside a block of text.

3. Tool Registration and Binding

The Gemini ADK makes registration almost invisible. You don't need to write complex JSON schemas by hand; you just write clean Python.

Best Practices for Binding:

Type Hints: Always use them (e.g., location: str instead of just location). They are used to generate the JSON types (string, integer, number).
Docstrings: Be descriptive. Gemini uses the docstring as its primary "instruction manual" for the tool.

import google.generativeai as genai

# 1. Define the functions
def add_numbers(a: float, b: float):
    """Adds two numbers and returns the result."""
    return a + b

def multiply_numbers(a: float, b: float):
    """Multiplies two numbers and returns the result."""
    return a * b

# 2. Bind them to the model
# The tools can be a single list
model = genai.GenerativeModel(
    model_name='gemini-1.5-flash',
    tools=[add_numbers, multiply_numbers]
)

4. Parallel Function Calling

One of the standout features of Gemini 1.5 is Parallel Function Calling. If a user asks a question that requires multiple tool calls (e.g., "What is the weather in New York, London, and Tokyo?"), Gemini can emit all three tool requests in a single turn.

The Workflow:

Request: Gemini returns a list of 3 tool calls.
Execution: Your code runs the 3 functions (concurrently if you use asyncio).
Synthesis: You send the results of all 3 back to Gemini at once.
Final Response: "The weather in NY is X, in London is Y, and in Tokyo is Z."

5. Built-in vs. Custom Tools

While you will mostly build Custom Tools (your own code), the Gemini ecosystem also provides Built-in Tools.

A. Google Search (Search Tool)

Provides the model with a "grounded" connection to the real-time internet.

Why use it?: To prevent hallucinations on current events and get specific citations.

B. Code Interpreter (Code Tool)

Allows the model to write and execute its own Python code in a sandboxed environment.

Why use it?: For complex math, data visualization, and file manipulation where a pre-written tool is too restrictive.

6. Security: The Principle of Least Privilege

When registering tools, remember that you are giving an LLM access to your infrastructure.

Tool Sandboxing

Never give an agent a generic execute_sql(query) tool. This is a recipe for SQL injection and data loss.
Instead, give it specific tools like get_inventory_levels(item_id) and update_reorder_point(item_id, quantity).

Input Validation

Always validate the arguments Gemini passes to your tool inside the function. Gemini might decide to pass a string where you expect an integer, or pass a filename like ../../etc/passwd.

7. Implementation: A Multi-Tool Agentic Workflow

Let's build a small "Utility Agent" that can handle both math and internet searches.

import google.generativeai as genai

# 1. A Custom Tool
def calculate_growth_rate(initial_value: float, final_value: float, periods: int):
    """
    Calculates the Compound Annual Growth Rate (CAGR).
    Args:
        initial_value: Starting value.
        final_value: Ending value.
        periods: Number of years/periods.
    """
    if periods == 0: return 0
    return ((final_value / initial_value)**(1/periods)) - 1

# 2. Setup the Agent with Custom and Built-in tools
# Note: google_search is currently a 'builtin' in the Vertex AI / AI Studio API
# For the Python SDK, we often provide it as a specific tool object.
model = genai.GenerativeModel(
    model_name='gemini-1.5-pro',
    tools=[calculate_growth_rate] # Add search if supported in your environment
)

# 3. Execution
chat = model.start_chat(enable_automatic_function_calling=True)
response = chat.send_message(
    "If our sales were 10M in 2020 and 15M in 2024, what was our yearly growth rate?"
)

print(response.text)

8. Summary and Exercises

Tools are what make agents Actionable.

Function Calling is the native communication layer.
Registration is automated by the Gemini ADK via docstrings and type hints.
Parallel Calling optimizes efficiency for multi-part queries.
Security requires specific, narrow tool definitions over generic ones.

Exercises

Tool Transformation: Take a Python function that connects to an external API (like a weather API or a Cat Facts API). Transform it into a "Gemini Tool" by adding the necessary docstrings and type hints.
Schema Inspection: Most frameworks allow you to "print" the JSON schema generated from your function. Use a library like pydantic or the Gemini SDK internals to see what the JSON looks like for a function with 5 different arguments.
Parallel Challenge: Write a user prompt that forces the model to use two different tools at the same time. (e.g., "Find the population of France AND calculate what 10% of that is.")

In the next lesson, we will look at Tool Design Principles, moving from "how it works" to "how to make it robust and production-ready."