Recap — Designing Tools for Agent Use

# Designing Tools for Agent Use Tools are the bridge between LLMs and the outside world. The LLM decides which tool to call (and with what arguments) based on the tool's description. Good tool design = reliable agent behavior. ## The `@tool` decorator The simplest way to define a tool: ```python from langchain_core.tools import tool @tool def get_weather(city: str) -> str: '''Get the current weather for a city. Args: city: The city name, e.g., 'Mumbai' or 'New York'. Returns: A string describing current weather. ''' # Real implementation would call weather API return f"It's 28°C and sunny in {city}." @tool def search_products(query: str, category: str = None, limit: int = 5) -> list[dict]: '''Search the product catalog by keyword. Args: query: Search keyword, e.g., 'running shoes'. category: Optional category filter ('shoes', 'apparel', 'accessories'). limit: Max results to return. Returns: List of products with name, price, sku. ''' return [{"name": "...", "price": 49.99, "sku": "..."}, ...] ``` Two critical pieces: ### 1. The docstring IS the description The LLM reads it to decide WHEN to call the tool. Make it clear: - WHAT the tool does. - WHEN to use it. - WHAT arguments it needs. - WHAT it returns. A vague docstring = unreliable tool calling. ### 2. Type hints define the schema `city: str` becomes `{"city": {"type": "string"}}` in the tool schema. `limit: int = 5` becomes optional with default. Use Pydantic models for complex inputs. ## Binding tools to an LLM ```python from langchain_anthropic import ChatAnthropic llm = ChatAnthropic(model="claude-sonnet-4-6") tools = [get_weather, search_products] llm_with_tools = llm.bind_tools(tools) response = llm_with_tools.invoke("What's the weather in Mumbai?") # response.tool_calls = [{"name": "get_weather", "args": {"city": "Mumbai"}}] ``` The LLM looks at the user message, examines the bound tools, decides whether to call one. If yes, it returns a structured tool call instead of text. ## Executing the tool call ```python def call_tool(tool_call): tool_map = {t.name: t for t in tools} tool = tool_map[tool_call["name"]] return tool.invoke(tool_call["args"]) response = llm_with_tools.invoke("What's the weather in Mumbai?") if response.tool_calls: for tc in response.tool_calls: result = call_tool(tc) print(f"{tc['name']}({tc['args']}) → {result}") ``` For automated tool execution, use `ToolNode` (in LangGraph) or build a custom loop. We'll cover the production pattern in Module 2. ## Tool design principles ### Principle 1 — One tool, one job ```python # Bad — too many responsibilities @tool def manage_order(action: str, order_id: str, **kwargs) -> dict: '''Get info, refund, cancel, or update an order.''' if action == "get": ... # Good — clear, separate tools @tool def get_order_status(order_id: str) -> dict: '''Get current status of an order.''' @tool def initiate_refund(order_id: str, reason: str) -> dict: '''Initiate a refund for an eligible order.''' @tool def cancel_order(order_id: str) -> dict: '''Cancel a pending order.''' ``` The LLM picks tools by description. Specific tools with clear descriptions = reliable selection. Polymorphic tools = the LLM struggles to fill arguments correctly. ### Principle 2 — Verbose descriptions ```python # Bad @tool def get_order(order_id: str) -> dict: '''Get order.''' # Good @tool def get_order_status(order_id: str) -> dict: '''Look up the current status, tracking info, carrier, and estimated delivery of a customer's order. Use this when the customer asks about their order's location, shipping, delivery, or current state. Requires the order_id from the customer. Args: order_id: The order ID number, e.g., "12345" or "ORD-2026-00045". Returns: dict with: status (string), tracking_number, carrier, estimated_delivery_date. ''' ``` The LLM reads this. Verbose, specific descriptions improve tool selection. ### Principle 3 — Bounded and safe by default ```python # Bad — too much power @tool def run_sql(query: str) -> list: '''Execute SQL query on the database.''' return db.execute(query) # The LLM can DROP TABLE. # Good — bounded @tool def get_customer_orders(customer_id: str, limit: int = 10) -> list: '''Get the most recent orders for a specific customer.''' return db.execute( "SELECT * FROM orders WHERE customer_id = ? ORDER BY created_at DESC LIMIT ?", customer_id, limit ) ``` Don't give the LLM raw database access. Parametrize tools for specific operations. ### Principle 4 — Errors return informative messages ```python @tool def get_order_status(order_id: str) -> dict: '''Get order status.''' try: order = db.get_order(order_id) if not order: return {"error": f"No order found with ID {order_id}. Verify the customer's ord