Lesson 65 — Beginner

Tools for Agents

Level 2 mein tumne tool calling seekhi — ek call, ek jawab. Agent mein wahi skill baar baar chalti hai: model available tools mein se chunta hai, arguments banata hai, aur outcome dekh kar agla kadam decide karta hai. Is lesson mein tool schema design, selection sudhaarna, failure recovery, result size limiting aur read-only vs consequential tools cover honge.

Tool ka anatomy — naam, description, schema

TOOLS = [
  {
    "name": "search_orders",
    "description": "Customer ya order id se orders dhoondho. Sirf padhta hai — kuch badalta nahi. Use tab jab email ya order id diya ho.",
    "parameters": {
      "type": "object",
      "properties": {
        "query": {"type": "string", "description": "email ya order id ka fragment"},
        "limit": {"type": "integer", "minimum": 1, "maximum": 20, "default": 5}
      },
      "required": ["query"]
    }
  }
]

Tool selection aur arguments sudhaarna

• Description mein rule likho: kab use karna hai, kab nahi, kya input chahiye — teeno line mein.
• Duplicate tools hatao: search_orders aur find_orders jaise do naam = model confuse. Merge karo ya responsibilities alag karo.
• Typed arguments: enum, min/max, default — galat value ki gunjaish kam. Required sirf wo jo bina kaam na ho.
• Logs rakho: kaunsa tool kis argument ke saath kyun chuna — selection quality ka data yahin se aata hai, guess se nahi.
• Chhote tools: ek tool ek kaam. 20 parameter wala tool model ke liye mushkil hai — usko tod do.

Sequential, dependent, parallel aur repeated calls

Agent ek turn mein ek se zyada tool calls bhi de sakta hai. Rule simple hai: dependent calls sequential, independent calls parallel, aur har repeat budget ke andar.

import asyncio

async def run_turn(calls, deps):
    # dependent: pehle order id chahiye tabhi refund status milega — seq
    order = await run_tool(calls[0])          # lookup_order(email=...)
    status = await run_tool(calls[1], order)  # refund_status(order_id=...)

    # independent: do alag API — saath chalao, waqt aadha
    a, b = await asyncio.gather(
        run_tool("inventory", sku="X1"),
        run_tool("tracking", ship_id="S9"),
        return_exceptions=True,               # ek fail ho toh doosra na gire
    )
    return {"status": status, "inventory": a, "tracking": b}

• Repeated calls: pagination loop ya search → refine — par har repeat budget mein count hota hai, yaad rakho.
• Gather mein exceptions: return_exceptions=True se ek tool ka crash baaki ko nahi dubota.
• Order of writes: jo calls side effect rakhte hain, unhe parallel mat chalao — pehle read, phir single write.

Failure se recovery aur result size

def safe_tool(call):
    try:
        raw = run_tool(call.name, call.args)
        return truncate(str(raw), limit=2000)   # context ko anjaan chhota na karo
    except UnknownTool:
        return "yeh tool exist nahi karta — available tools list dekho"
    except Timeout:
        return "tool ka waqt khatam — dobara try ya alag tool chuno"
    except Exception as exc:
        return f"tool nakaam raha: {type(exc).__name__}. Koi aur raasta try karo."

• Errors ko model tak pahunchao: chhupao mat — informative message do, tabhi wo recover ya alternate tool choose karega.
• Error message actionable ho: "internal error" bekaar hai; "30 din se purana order nahi dhoondha ja sakta" ka matlab hai model ko.
• Result truncate karo: bada API JSON poora mat daalo — pehle relevant fields, phir limit. (Offloading detail L6 mein.)
• Format stable rakho: model ko predictable shape chahiye — kabhi dict, kabhi HTML mat do.

Read-only vs consequential tools

Tools ko do tiers mein baanto: read-only (search, list, get — rukne ki zarurat nahi) aur consequential (refund, delete, send — duniya badal dete hain). Consequential tools par hamesha confirmation/permission layer chahiye.

GATED = {"send_email", "issue_refund", "delete_record"}

def execute_refund(order_id, amount, approved=False):
    if not approved:
        return {"status": "needs_approval",
                "detail": "user confirmation chahiye — phir approved=True se call karo"}
    payments.refund(order_id, amount)
    return {"status": "refunded", "order_id": order_id}   # idempotent: ek hi baar

Exercise

Common mistakes

• Vague tool descriptions: Description hi selection ka base hai. Kab use karna hai, kab nahi, kya input chahiye — teeno likho, warna model guess karega.
• Raw output seedha context mein daalna: Bada API JSON poora context kha jaata hai, aur model beech wale facts kho deta hai. Relevant fields chuno, phir truncate karo.
• Consequential tools bina gate ke: Refund/delete send direct mat do — approval layer pehle se rakho. Pehla galat refund hi kaafi hai production ke liye.
• Tool errors ko chhupana: Exception ko loop mein rehne do nahi — informative message banao taki model recover kar sake. Silent failure = same call dobara-dobara.

# bekaar — model confuse
{"name": "do_something", "description": "data nikalta hai"}

# accha — kab, kya, kitna sab clear
{"name": "search_orders",
 "description": "Customer ke orders dhoondho. Use jab email ya order id diya ho. Sirf padhta hai, kuch badalta nahi."}