How to create a custom tool in ADK?

[hyr0ky]

I have a question about creating custom tools in ADK. How do I define a custom tool function and register it with an agent?

---

1

[agrovr]

For a normal Python tool, you do not need to subclass BaseTool. Define a typed function and put the function itself in the agent's tools list; ADK automatically wraps it as a FunctionTool.

from google.adk.agents import Agent


def calculate_total(
    unit_price: float,
    quantity: int,
    discount_percent: float = 0,
) -> dict:
    """Calculate an order total after a percentage discount.

    Args:
        unit_price: Price of one item.
        quantity: Number of items.
        discount_percent: Optional discount from 0 to 100.
    """
    if unit_price < 0 or quantity < 1:
        return {
            "status": "error",
            "error_message": (
                "unit_price must be non-negative and quantity must be at least 1"
            ),
        }

    if not 0 <= discount_percent <= 100:
        return {
            "status": "error",
            "error_message": "discount_percent must be between 0 and 100",
        }

    subtotal = unit_price * quantity
    total = subtotal * (1 - discount_percent / 100)
    return {
        "status": "success",
        "subtotal": round(subtotal, 2),
        "total": round(total, 2),
    }


root_agent = Agent(
    name="order_agent",
    model="gemini-2.5-flash",
    instruction=(
        "Help with order totals. Use calculate_total when calculation is needed."
    ),
    tools=[calculate_total],
)

ADK inspects the function name, docstring, type hints, parameters, and default values to build the tool schema. A parameter without a default is required; a parameter with a default is optional. The function name and docstring help the model decide when to call it.

A dictionary is the preferred return type because it gives the model structured context. Include a clear status and a human-readable error_message instead of raising expected business-validation errors. If the function needs session state or authentication, add a parameter typed as ToolContext; ADK injects it and does not expose that parameter to the model.

Official guide: ADK function tools