ADK Tool Design Patterns

# BEFORE: opaque — the model has to guess what this is for
def proc(x: str, f: bool = False) -> dict:
    """Processes the data."""
    ...

# AFTER: the declaration teaches the model how to use it
def lookup_order(order_id: str, include_items: bool = False) -> dict:
    """Fetch the current status of a customer order by its ID.

    Use this when the user references a specific order and you need its
    status, dates, or line items. Do NOT use it to search by customer
    name or email — use `search_orders` for that.

    Args:
        order_id: The 8-digit numeric order ID from the confirmation
            email (e.g. '45810923'), NOT the shipment tracking number.
        include_items: Set True to also return the line items; leave
            False for a lightweight status-only lookup.

    Returns:
        A dict with a 'status' field ('ok' or 'error') and, on success,
        the order's state, dates, and (optionally) items.
    """
    ...

# BEFORE: stringly-typed — the model can send any string it dreams up
def create_ticket(subject: str, priority: str, payload: str) -> dict:
    """Create a support ticket. payload is a JSON string of fields."""
    ...

# AFTER: the schema itself rules out invalid calls
from enum import Enum
class Priority(str, Enum):
    low = 'low'; medium = 'medium'; high = 'high'

def create_ticket(subject: str, priority: Priority,
                  customer_id: str, notify_email: bool = True) -> dict:
    """Create a support ticket for an existing customer."""
    ...

# BEFORE: bare value — did it work? what does -1 mean?
def get_balance(account_id: str) -> float:
    return db.balance(account_id)  # or -1 on failure (!)

# AFTER: structured, self-describing, branchable
def get_balance(account_id: str) -> dict:
    row = db.balance(account_id)
    if row is None:
        return {'status': 'error', 'reason': 'not_found',
                'message': f'No account {account_id}.'}
    return {'status': 'ok', 'balance': row.amount,
            'currency': row.currency, 'as_of': row.updated_at}

# BEFORE: raises — the model sees an opaque failure, can't recover
def reserve_inventory(sku: str, qty: int) -> dict:
    resp = inventory.reserve(sku, qty)   # raises on timeout / 409
    return {'reserved': resp.id}

# AFTER: expected failures become actionable results
def reserve_inventory(sku: str, qty: int) -> dict:
    try:
        resp = inventory.reserve(sku, qty)
    except inventory.OutOfStock as e:
        return {'status': 'error', 'reason': 'out_of_stock',
                'available': e.available,
                'message': f'Only {e.available} of {sku} in stock.'}
    except inventory.Timeout:
        return {'status': 'error', 'reason': 'timeout',
                'retryable': True,
                'message': 'Inventory service is slow; safe to retry.'}
    return {'status': 'ok', 'reservation_id': resp.id}

# BEFORE: god-tool — action switch + arguments that only sometimes apply
def manage_order(action: str, order_id: str,
                 new_address: str = '', refund_amount: float = 0.0,
                 reason: str = '') -> dict:
    ...

# AFTER: one tool per capability, each schema tight and honest
def cancel_order(order_id: str, reason: str) -> dict: ...
def issue_refund(order_id: str, amount: float, reason: str) -> dict: ...
def update_shipping_address(order_id: str, address: Address) -> dict: ...

# BEFORE: a second call charges the customer twice
def charge_card(customer_id: str, amount: float) -> dict:
    return {'status': 'ok', 'charge_id': gateway.charge(customer_id, amount)}

# AFTER: a deterministic key makes a repeat a no-op
def charge_card(customer_id: str, amount: float,
               order_id: str) -> dict:
    key = f'charge:{order_id}'          # stable across retries
    res = gateway.charge(customer_id, amount, idempotency_key=key)
    return {'status': 'ok', 'charge_id': res.id,
            'was_duplicate': res.replayed}

# AFTER: ambient inputs come from context, not from the model
from google.adk.tools import ToolContext

def get_recommendations(category: str,
                        tool_context: ToolContext) -> dict:
    """Recommend products in a category for the current user."""
    user_id = tool_context.state.get('user:id')   # not a model arg
    recent  = tool_context.state.get('user:recent_views', [])
    picks = recommender.for_user(user_id, category, recent)
    tool_context.state['last_reco_category'] = category
    return {'status': 'ok', 'items': picks[:5]}

# BEFORE: floods the context with a huge document forever
def fetch_report(report_id: str) -> dict:
    return {'status': 'ok', 'report': api.get(report_id)}  # 200 KB

# AFTER: lean summary in-context, full payload offloaded
def fetch_report(report_id: str, tool_context: ToolContext) -> dict:
    doc = api.get(report_id)
    ref = tool_context.save_artifact(f'report_{report_id}.json', doc)
    return {'status': 'ok', 'summary': doc['executive_summary'],
            'row_count': len(doc['rows']), 'artifact': ref}

# BEFORE: two look-alike strings + boolean soup — easy to transpose
def transfer(a: str, b: str, x: float,
            n: bool = False, f: bool = False) -> dict: ...

# AFTER: names, types, and docs pin down every argument
def transfer_funds(source_account_id: str, dest_account_id: str,
                   amount_usd: float, notify_sender: bool = True) -> dict:
    """Move funds between two accounts owned by the current user.

    Args:
        source_account_id: Account the money leaves (the debit side).
        dest_account_id: Account the money arrives in (the credit side).
        amount_usd: Positive amount in US dollars, e.g. 49.99.
    """
    ...