Type hints

A type hint is a note on a parameter, a return value or a variable saying what type it should be. def book_ticket(train: str, seats: int) -> dict reads: train is a string, seats is an integer, and the function returns a dict. Python stores these notes but never checks them while the program runs. Tools do the checking: your editor, a type checker such as mypy or Pyright, and frameworks like ADK and Pydantic that read the hints.

The hints you need day to day are few. str, int, float, bool for single values. list[str] for a list of strings and dict[str, Any] for a dict with string keys and mixed values. Optional[str] (or the newer str | None) when a value may be None. Any when you honestly cannot say.

Press Run to trace ticket_tool.py, a booking tool written the way ADK expects tools to look. Then switch Try it to “Wrong type at runtime” to see what happens when a caller ignores the hints.

# A train booking tool with type hints, the way ADK expects tools to look.
from typing import Any, Optional

def book_ticket(train: str, seats: int, berth: Optional[str] = None) -> dict[str, Any]:
    """Books seats on a train. berth is optional."""
    fare: int = 450 * seats
    result: dict[str, Any] = {"train": train, "seats": seats, "fare": fare}
    if berth is not None:
        result["berth"] = berth
    return result

def passenger_list(names: list[str]) -> str:
    return ", ".join(names)

print(book_ticket("Shatabdi", 2))
print(book_ticket("Shatabdi", 1, berth="lower"))
print(passenger_list(["Asha", "Ravi"]))
print(book_ticket.__annotations__)

# Hints are not checked while the program runs.
print(book_ticket("Shatabdi", 2.0))

What to notice

1. Hints change nothing at runtime. The Python docs are explicit: the runtime does not enforce annotations. book_ticket("Shatabdi", 2.0) runs and returns a float fare. The hint’s job is to let tools catch that before you run.
2. Optional is about None, not about being skippable. berth: Optional[str] says the value may be a string or None. The = None default is what lets a caller leave it out. ADK applies the same rule: a parameter without a default is required even if it is Optional.
3. Container hints describe the items. list[str] is a list of strings; dict[str, Any] has string keys and any values. The square brackets are part of the hint, not a lookup.
4. Return hints are read, too. -> str and -> dict[str, Any] let an editor warn when you use the result wrongly, and tell a schema generator what the tool gives back.
5. Hints live in __annotations__. That dict is what frameworks read. If a hint is missing, the tool reads the parameter as Any, which is the least useful thing you can tell a model.

Why this matters for AI work

ADK builds a tool’s schema by inspecting the function signature: name, docstring, parameters, type hints and defaults. A parameter hinted str becomes a string field; int becomes an integer field; a parameter with no default is required. The model only ever sees that schema, so the hints are the part of your code the model reads. Function tools shows the full flow from signature to model call.