The Agent Tools Dictionary — A to Z

WWeb Search

The most-used tool in existence: give the model fresh knowledge. Hosted APIs return clean JSON — never scrape Google yourself.

Industry options: Tavily (built for agents, returns extracted content), Serper/SerpAPI (Google results), Brave Search API, Exa (semantic search), DuckDuckGo (free, rate-limited). Gotcha: result quality is query quality — let the model retry with reformulations, and cap searches per session or costs run (a lesson the memory guide covers from the token side).

def web_search(query: str, max_results: int = 5) -> dict:
    """Search the web for current information on a topic.

    Args:
        query: A specific search query. Prefer precise phrases
               over broad topics.
        max_results: Number of results (1-10).
    """
    resp = tavily.search(query, max_results=max_results)
    return {"results": [{"title": r["title"], "url": r["url"],
                         "snippet": r["content"][:500]}
                        for r in resp["results"]]}python

UURL Fetch / Reader

Search finds the page; this reads it. The modern pattern is a "reader" that returns clean markdown, not raw HTML — HTML wastes 90% of your tokens on markup.

Options: Jina Reader (prefix any URL with r.jina.ai/), Firecrawl, trafilatura (local, free), requests+BeautifulSoup (DIY). Gotcha: always truncate (pages can be 100k+ tokens) and return a truncated: true flag so the model knows it saw a partial page.

KKnowledge-Base Search (RAG)

Retrieval over your documents — policies, product docs, past tickets, wikis. This is how an agent answers company-specific questions without fine-tuning anything.

Options: ADK's VertexAiSearchTool, LlamaIndex/LangChain retrievers, pgvector + your own chunks. Gotcha: return chunks with source IDs so the agent can cite; uncited RAG answers are unauditable answers.

VVector Search

The raw primitive under RAG: nearest-neighbors over embeddings. Expose it directly when the agent needs similarity itself — "find products like this one", "find tickets similar to this bug".

Options: pgvector, Qdrant, Pinecone, FAISS/hnswlib in-process. The full mechanics are Level 6 of the search engine build-along. Gotcha: embeddings go stale when content changes — version them.

DDatabase Query (Guarded SQL)

The single highest-value tool in any data-rich company — and the most dangerous if unguarded. The pattern that works in production: read-only credentials, an allowlist of tables, a row limit, and a timeout — enforced in code, never by prompt.

import re

ALLOWED_TABLES = {"orders", "order_items", "products", "inventory"}

def run_sql(query: str) -> dict:
    """Run a read-only SQL query against the analytics warehouse.

    Args:
        query: A single SELECT statement. Available tables:
               orders, order_items, products, inventory.
    """
    q = query.strip().rstrip(";")
    if not q.lower().startswith("select"):
        return {"error": "Only SELECT queries are allowed."}
    tables = set(re.findall(r"(?:from|join)\s+([a-z_]+)", q.lower()))
    if not tables <= ALLOWED_TABLES:
        return {"error": f"Tables not allowed: {tables - ALLOWED_TABLES}"}
    rows = warehouse.query(f"{q} LIMIT 200", timeout_s=15,
                           credentials=READ_ONLY)   # enforced in code
    return {"rows": rows, "row_count": len(rows)}python

Gotcha: give the model the schema (in the instruction or a get_schema tool) or it will hallucinate column names; and log every query — the log becomes your text-to-SQL eval set.

CCode Execution

Let the model write and run Python in a sandbox. This one tool replaces a hundred specialized ones: statistics, plotting, data reshaping, date math, regex. It's the "give them a workshop, not a toolbox" move.

Options: ADK's BuiltInCodeExecutor, OpenAI Code Interpreter, E2B (hosted sandboxes), local Docker with resource caps. Gotcha: the sandbox must be a real sandbox — no network by default, CPU/memory/time capped, filesystem scoped. Model-written code is untrusted code, always.

CCalculator / Math

LLMs do arithmetic in their heads and get it wrong just often enough to burn you. If your agent quotes prices, margins, or refund amounts, arithmetic must go through a tool — even a trivial one.

Rule of thumb: if a number leaves the agent and lands in front of a customer or a P&L, it was computed by a tool, not by the model. Code execution covers this; a dedicated calculate(expression) tool is the lightweight version.

BBrowser Automation

When the target is a JavaScript app, a login wall, or a flow ("add to cart, go to checkout, read the delivery fee"), fetch-and-parse isn't enough — you need a driven browser.

Options: Playwright (the workhorse — my BSR Tracker runs on it), browser-use / Playwright-MCP (agent-native control), hosted grids (Browserbase). Gotcha: browser automation is 10–100x slower and flakier than an API. Exhaust every API/reader option first; automate browsers as the last resort, with retries and screenshots-on-failure baked in.

SScraper (Structured)

Fetch + parse into a schema, for pages you scrape repeatedly (competitor PDPs, seller listings). Unlike the generic reader, this returns typed fields — {price, availability, seller, rating} — ready for pipelines.

Modern twist: LLM-assisted extraction (fetch clean text → small model extracts the schema) survives site redesigns that break CSS selectors. That's the LLM playbook's extraction pattern pointed at the open web. Gotcha: respect robots.txt and rate limits — your agent's IP reputation is shared with your whole company.

FFile Read / Write

The agent's workspace: read inputs, write reports, build artifacts across turns. The one non-negotiable: scope it to a directory — path traversal is the oldest trick and models can be induced to try it.

from pathlib import Path
WORKSPACE = Path("/agent/workspace").resolve()

def read_file(path: str) -> dict:
    """Read a text file from the agent workspace."""
    p = (WORKSPACE / path).resolve()
    if not str(p).startswith(str(WORKSPACE)):      # jail check
        return {"error": "Path outside workspace."}
    if p.stat().st_size > 200_000:
        return {"error": "File too large — use read_file_range."}
    return {"content": p.read_text()}python

OOCR / PDF Extract

Invoices, supplier catalogs, compliance certificates — business runs on PDFs. Extract text and tables into something the model can reason over.

Options: pymupdf/pdfplumber (text-native PDFs), modern vision models (scanned docs — often better than classic OCR), unstructured.io, Azure/Google Document AI. Gotcha: tables are the hard part; extract them as structured rows, not prose, or the model will misread column alignment.

IImage / Vision

With multimodal models the "tool" is often just passing the image — but wrapping vision as an explicit tool (analyze_product_image(url) → {category, color, defects, text_in_image}) gives you a typed contract, cacheable results, and an audit trail. E-com uses: listing-photo QC, damage claims verification, counterfeit signals.

Gotcha: vision outputs need the same "null if unsure" discipline as text extraction — a confident wrong color attribute poisons your catalog.

XSpreadsheet / XLSX

The business's real lingua franca. An agent that can read the merchandiser's planning sheet and write a formatted results workbook gets adopted; one that returns JSON gets ignored.

Options: openpyxl/pandas for files; Google Sheets API for live sheets (which doubles as a human-in-the-loop surface — the agent writes, humans review in place). Gotcha: never let the agent overwrite the source sheet; write to a new tab or file, always.

AAPI Caller (Generic REST)

The universal adapter: one tool that can hit your internal services. The trade-off is real — a generic call_api(method, url, body) is maximally flexible and maximally dangerous. Production systems almost always prefer named, narrow wrappers (create_ticket, get_customer) over one open-ended caller: better model accuracy, better security, better logs.

Rule: generic caller for prototyping, named wrappers for production. If you must ship the generic one, allowlist hosts and methods in code.

EEmail Sender

Outbound email is an irreversible, outward-facing action — the exact category that needs an approval gate (see Human Approval, Shelf 7). The pattern: the tool composes a draft; a human or a hard rule releases it.

Options: SendGrid/SES APIs, Gmail API (with OAuth scopes as narrow as possible). Gotcha: never give a prototype agent your personal mailbox scope; the prompt-injection section explains why.

NNotification (Slack / Push / WhatsApp)

The cheapest, safest action tool — telling a human something happened. Every monitoring agent ends here: inventory alerts to the buying channel, price-drop alerts, RTO spikes.

def notify_slack(channel: str, message: str) -> dict:
    """Post a message to a Slack channel. Allowed channels:
    #inventory-alerts, #pricing-watch, #agent-reports."""
    if channel not in ALLOWED_CHANNELS:
        return {"error": f"Channel not allowed: {channel}"}
    slack.chat_postMessage(channel=channel, text=message[:4000])
    return {"status": "sent"}python

CCalendar & Time

Models don't reliably know what "now" is, and they're bad at timezone and business-day math. A tiny get_current_time(tz) / add_business_days(date, n) pair prevents a whole genre of bugs — wrong delivery promises being the expensive e-com one.

WWebhook Trigger

Fire an event into systems you already run — a Zapier/n8n flow, an Airflow DAG, an internal job queue. This is how agents plug into existing automation instead of replacing it: the agent decides when and with what payload; the battle-tested pipeline does the work.

MMemory Save / Recall

The save_finding / get_findings pair: distill noisy tool output into structured facts the agent can retrieve later — within a session (state) or across sessions (memory service). This shelf has its own complete guide: The Complete Guide to Agent Memory — 8 levels from scratchpads to knowledge graphs, including why these tools exist and the pruning trick that makes them pay.

The one-line rule: any tool whose output is bulky (search, fetch, SQL) should have a companion save-tool that keeps the conclusion and lets you drop the payload.

AAgent-as-Tool

Wrap a whole specialist agent as a callable tool: the parent calls research_agent(question) and gets back its final answer, exactly like a function. This is how you compose narrow experts — each with a small, focused toolset — instead of building one agent with 40 tools it can't choose between.

from google.adk.tools.agent_tool import AgentTool

sql_analyst = Agent(name="sql_analyst", tools=[run_sql],
                    instruction="Answer questions using the warehouse...")

coordinator = Agent(
    name="coordinator",
    tools=[AgentTool(agent=sql_analyst), web_search, notify_slack],
)python · adk

WWorkflow Handoff

Different from agent-as-tool: instead of asking a specialist and continuing, transfer the whole conversation — support triage handing a billing thread to the billing agent. Agent-as-tool = a phone call; handoff = a department transfer. Most frameworks support both (ADK sub-agents, OpenAI handoffs); choosing wrong causes either lost context or ping-pong loops.

HHuman Approval

The most important tool in this dictionary that nobody demos: a tool that pauses and asks a person. Every irreversible or outward-facing action — refunds over a threshold, emails to customers, price changes — routes through it.

def request_approval(action: str, details: str,
                     tool_context: ToolContext) -> dict:
    """Request human approval before an irreversible action.
    Use for: refunds > AED 200, any customer-facing message,
    any price or inventory change."""
    ticket = approvals.create(action=action, details=details,
                              session=tool_context.session_id)
    # long-running: agent pauses; human approves in a queue UI;
    # the workflow resumes with the decision
    return {"status": "pending", "ticket_id": ticket.id}python

Design note: the approval threshold lives in the tool and the instruction both — the instruction teaches the model when to ask; the tool enforces it when the model forgets.

LLong-Running Task

Some work outlives a conversational turn — a 20-minute scrape, a batch job, a report build. The tool starts the job and returns a handle; a companion check_task(task_id) polls it. ADK models this natively (LongRunningFunctionTool); elsewhere it's the start/poll pair by convention.

OOrder Status

The WISMO tool — the single highest-volume use case in e-com support (see the LLM playbook). Returns status from the system of record; the model phrases, never invents.

def get_order_status(order_id: str, tool_context: ToolContext) -> dict:
    """Get current status and delivery estimate for an order.

    Args:
        order_id: The order ID, format 'N' + digits (e.g. N123456).
    """
    customer = tool_context.state["customer_id"]      # from auth, NOT the model
    order = oms.get(order_id)
    if order is None or order.customer_id != customer:
        return {"error": "Order not found for this account."}
    return {"status": order.status,
            "eta": str(order.promised_date),
            "last_scan": order.last_tracking_event,
            "items": [i.title for i in order.items]}python

The critical line: customer identity comes from the session, never from a model argument — or any user can ask about any order. This one pattern is the difference between a support agent and a data breach.

CCatalog Lookup

Product details by SKU or query — the grounding tool for any shopping or content agent. Wraps your search service (which, after the build-along, you understand end to end).

Gotcha: include availability and price as of now in the response — an agent quoting yesterday's cached price is a complaint generator.

IInventory Check

Stock, weeks-of-cover, and age bracket by SKU — the tool version of the inventory playbook's health matrix, powering replenishment and liquidation agents (use case 4 below).

PPrice Scraper / Index

Competitor price by matched product, availability-adjusted, with a scraped-at timestamp — the pricing playbook's CPI machinery exposed as a tool.

Gotcha: return the match confidence with the price; acting on a bad product match is worse than no data.

PPromo Eligibility

Whether this customer + this cart qualifies for a voucher — as deterministic code. The model must never compute discounts: eligibility rules, stacking limits, and amounts come from the tool; the model only explains the result (the promo playbook's rules, executable).

RRTO Risk Score

COD refusal risk before dispatch — the returns playbook's model behind a tool interface: score_rto(order_id) → {risk: 0.72, tier: "high", recommended_action: "whatsapp_confirm"}. The agent orchestrates the confirmation flow; the score stays a model artifact with an owner.