Agent Tool Design
Overview
A tool has two consumers with opposite needs: the model, which needs a compact, trustworthy, decision-shaped result, and the UI/caller, which needs the full payload. A tool that returns one blob to both serves neither. Design the tool as a contract with both consumers, and treat everything the tool fetches as untrusted input.
Quick reference — every tool has these parts
| Part |
Contract |
| Name + description |
Description says when to call it and when not to ("Use for award/points searches. Not for cash fares — use search_flights."). The model reads this to decide; the docstring is the decision surface, not documentation. |
| Args |
Typed, validated at the boundary (pydantic args_schema). Enums/Literal for closed sets. No verbose: bool, include_x: bool flag piles — split into tools or a single mode enum. Hard caps on range/size args (le=, max span). |
| Result to the model |
Short text: counts, top-N, IDs the model can reference back, and one line telling it where the rest went. Ferdinand measured ~70% token savings vs. full JSON with no reasoning loss. |
| Result to the UI |
Full structured payload over a side channel the transport actually forwards — see "Two channels" below. Never routed through the model's context. |
| Errors |
Returned as data, not raised: {error: <code>, retryable: bool, user_message: str} plus an empty/partial results. Distinguish no_results from error. Internal detail goes to the server log only. |
| External calls |
Timeout set. Idempotent by construction: a cache key from the normalized args so retries and duplicate model calls don't double-hit the API. Result count capped (Google Places maxResultCount is 20 — know your provider's ceiling). |
| Long-running |
Emit progress on the side channel (started / N of M / done) so the UI isn't blank for 10s. |
| Fetched content |
Untrusted. Wrap upstream free text in delimiters, cap its length, never let it become an instruction. Only your summary text addresses the model. |
| Tests |
HTTP client injectable; a record/replay fixture per provider so tool tests run offline and deterministically. |
What happens on exception by default (langchain 1.4.2 / langgraph 1.2.11)
create_agent builds ToolNode without handle_tool_errors, so the default _default_handle_tool_errors applies (langgraph/prebuilt/tool_node.py:383):
- Argument validation failure (
ToolInvocationError) → returned to the model as a ToolMessage ("Error: … Please fix your mistakes.") — the loop continues.
- Any other exception in the tool body →
raise e. The run aborts. Your HTTP 500 becomes the user's blank screen.
So: catch inside the tool, return data. Don't rely on the harness.
Two channels — the worked example
from datetime import date
from typing import Literal
from langchain_core.callbacks import adispatch_custom_event
from langchain_core.tools import tool
from pydantic import BaseModel, Field
class AwardSearchArgs(BaseModel):
origin: str = Field(pattern=r"^[A-Z]{3}$")
destination: str = Field(pattern=r"^[A-Z]{3}$")
date_from: date
date_to: date
cabin: Literal["economy", "premium", "business", "first"] = "economy"
limit: int = Field(default=25, le=50)
@tool("search_awards", args_schema=AwardSearchArgs)
async def search_awards(origin, destination, date_from, date_to, cabin, limit) -> str:
"""Search award (points/miles) seat availability. Use when the traveler wants to
redeem points. Not for cash fares — use search_flights for those."""
key = cache_key("awards", origin, destination, date_from, date_to, cabin)
try:
rows = await awards_client.search(key=key, ..., limit=limit, timeout=12)
except UpstreamError as e:
payload = {"error": e.code, "retryable": e.retryable, "results": []}
await adispatch_custom_event("awards_panel", payload)
return f"Award search failed ({e.code}). {e.user_message}"
await adispatch_custom_event("awards_panel", {"query": key, "results": rows})
top = sorted(rows, key=lambda r: r.miles)[:5]
lines = [f"- {r.date} {r.program} {r.miles:,} mi [row={r.id}]" for r in top]
return (f"{len(rows)} award option(s) {origin}→{destination}. Top by miles:\n"
+ "\n".join(lines) + "\nFull list is in the panel; cite rows by [row=…].")
The model gets ~10 lines. The panel gets everything. The side channel here is adispatch_custom_event because that is what ag_ui_langgraph forwards (CUSTOM frame, payload untouched) — the ag-ui-protocol skill owns that mechanism. response_format="content_and_artifact" is not a side channel in this stack: ag_ui_langgraph forwards ToolMessage.content only and never reads .artifact — the payload stays in graph state and the browser never sees it.
Common mistakes
- Raising for control flow. A raised
httpx.HTTPStatusError ends the run; a returned {error, retryable} lets the model apologize and offer the cash search.
- Interpolating upstream text straight into the model-facing summary. A hotel description containing "ignore previous instructions" now addresses your agent.
- Assuming the transport forwards your side-channel. Check the adapter source for the field you're populating —
artifact is the one that bites.
1---2name: agent-tool-design3description: Use when writing or reviewing a tool that an LLM agent will call — a langchain/langgraph @tool, an Anthropic tool definition, an MCP tool — especially one that wraps an external API, returns data a UI will render, or can fail. Also use when a tool "works in tests but the model calls it wrong", "returns too much and blows the context", or "crashes the whole run on a 500".4---56# Agent Tool Design78## Overview910A tool has two consumers with opposite needs: the **model**, which needs a compact, trustworthy, decision-shaped result, and the **UI/caller**, which needs the full payload. A tool that returns one blob to both serves neither. Design the tool as a contract with both consumers, and treat everything the tool fetches as untrusted input.1112## Quick reference — every tool has these parts1314| Part | Contract |15|---|---|16| **Name + description** | Description says *when to call it* and *when not to* ("Use for award/points searches. Not for cash fares — use `search_flights`."). The model reads this to decide; the docstring is the decision surface, not documentation. |17| **Args** | Typed, validated at the boundary (pydantic `args_schema`). Enums/`Literal` for closed sets. No `verbose: bool`, `include_x: bool` flag piles — split into tools or a single `mode` enum. Hard caps on range/size args (`le=`, max span). |18| **Result to the model** | Short text: counts, top-N, IDs the model can reference back, and one line telling it where the rest went. Ferdinand measured ~70% token savings vs. full JSON with no reasoning loss. |19| **Result to the UI** | Full structured payload over a **side channel the transport actually forwards** — see "Two channels" below. Never routed through the model's context. |20| **Errors** | Returned as data, not raised: `{error: <code>, retryable: bool, user_message: str}` plus an empty/partial `results`. Distinguish `no_results` from `error`. Internal detail goes to the server log only. |21| **External calls** | Timeout set. Idempotent by construction: a cache key from the normalized args so retries and duplicate model calls don't double-hit the API. Result count capped (Google Places `maxResultCount` is 20 — know your provider's ceiling). |22| **Long-running** | Emit progress on the side channel (started / N of M / done) so the UI isn't blank for 10s. |23| **Fetched content** | Untrusted. Wrap upstream free text in delimiters, cap its length, never let it become an instruction. Only *your* summary text addresses the model. |24| **Tests** | HTTP client injectable; a record/replay fixture per provider so tool tests run offline and deterministically. |2526## What happens on exception by default (langchain 1.4.2 / langgraph 1.2.11)2728`create_agent` builds `ToolNode` **without** `handle_tool_errors`, so the default `_default_handle_tool_errors` applies (`langgraph/prebuilt/tool_node.py:383`):2930- **Argument validation failure** (`ToolInvocationError`) → returned to the model as a `ToolMessage` ("Error: … Please fix your mistakes.") — the loop continues.31- **Any other exception in the tool body** → `raise e`. The run aborts. Your HTTP 500 becomes the user's blank screen.3233So: catch inside the tool, return data. Don't rely on the harness.3435## Two channels — the worked example3637```python38from datetime import date39from typing import Literal40from langchain_core.callbacks import adispatch_custom_event41from langchain_core.tools import tool42from pydantic import BaseModel, Field4344class AwardSearchArgs(BaseModel):45 origin: str = Field(pattern=r"^[A-Z]{3}$")46 destination: str = Field(pattern=r"^[A-Z]{3}$")47 date_from: date48 date_to: date49 cabin: Literal["economy", "premium", "business", "first"] = "economy"50 limit: int = Field(default=25, le=50)5152@tool("search_awards", args_schema=AwardSearchArgs)53async def search_awards(origin, destination, date_from, date_to, cabin, limit) -> str:54 """Search award (points/miles) seat availability. Use when the traveler wants to55 redeem points. Not for cash fares — use search_flights for those."""56 key = cache_key("awards", origin, destination, date_from, date_to, cabin)57 try:58 rows = await awards_client.search(key=key, ..., limit=limit, timeout=12)59 except UpstreamError as e:60 payload = {"error": e.code, "retryable": e.retryable, "results": []}61 await adispatch_custom_event("awards_panel", payload)62 return f"Award search failed ({e.code}). {e.user_message}"6364 await adispatch_custom_event("awards_panel", {"query": key, "results": rows})65 top = sorted(rows, key=lambda r: r.miles)[:5]66 lines = [f"- {r.date} {r.program} {r.miles:,} mi [row={r.id}]" for r in top]67 return (f"{len(rows)} award option(s) {origin}→{destination}. Top by miles:\n"68 + "\n".join(lines) + "\nFull list is in the panel; cite rows by [row=…].")69```7071The model gets ~10 lines. The panel gets everything. The side channel here is `adispatch_custom_event` because that is what `ag_ui_langgraph` forwards (`CUSTOM` frame, payload untouched) — the **ag-ui-protocol** skill owns that mechanism. `response_format="content_and_artifact"` is *not* a side channel in this stack: `ag_ui_langgraph` forwards `ToolMessage.content` only and never reads `.artifact` — the payload stays in graph state and the browser never sees it.7273## Common mistakes7475- **Raising for control flow.** A raised `httpx.HTTPStatusError` ends the run; a returned `{error, retryable}` lets the model apologize and offer the cash search.76- **Interpolating upstream text straight into the model-facing summary.** A hotel description containing "ignore previous instructions" now addresses your agent.77- **Assuming the transport forwards your side-channel.** Check the adapter source for the field you're populating — `artifact` is the one that bites.
andreasbloomquist