Lesson 32 — Beginner

Designing Good Tools

Tool schema technically sahi hona kaafi nahi — model ko choose bhi karna padta hai. Do tools ek jaise dikhein, description dhundhli ho, ya arguments das hon toh model galat pick karega. Is lesson mein hum names, descriptions, types, ambiguity, overload aur untrusted arguments ki designing dekhenge.

Tool design kya decide karta hai

Yaad rakho: tool descriptions khud context hain. Model sirf prompt ka text hi nahi, tool schemas bhi padh kar decide karta hai — dono ek hi context window mein rehte hain.

Names, descriptions aur strong types

# GALAT — naam vague, description bekaar, sab kuch string
{"name": "process", "description": "data process karta hai",
 "parameters": {"type": "object",
                "properties": {"data": {"type": "string"}},
                "required": ["data"]}}

# SAHI — specific naam, kab-use-wali description, strong types
{"name": "refund_order",
 "description": "Order ki refund request banata hai. Sirf tab use karo jab user refund maang raha ho aur order delivered ho chuka ho.",
 "parameters": {"type": "object",
   "properties": {
     "order_id": {"type": "string", "pattern": "^ORD-[0-9]+$",
                  "description": "Format: ORD-4821"},
     "amount_rupees": {"type": "number", "description": "Positive amount"},
     "reason": {"type": "string", "description": "Ek line reason for audit"}
   },
   "required": ["order_id", "amount_rupees", "reason"]}}

• Verb + object names: refund_order, get_order_status. "process", "handle", "do_data" se model guess karega.
• Description = kab use karna hai — sirf "kya karta hai" nahi, kab NAHI use karna hai wo bhi likho.
• Strong types + patterns/enums — string ki jagah number, free text ki jagah enum. Galat value schema hi rok legi.
• Minimum parameters — jitne kam arguments, utna kam confusion. Default de sakte ho toh required mat banao.

Ambiguity aur tool overload

# AMBIGUOUS — dono "order dhoondhna", model confuse
search_orders(query)      # query mein status ya text, kya daalein?
lookup_order(order_id)
filter_orders(status)     # -> model randomly ek chunta hai

# OVERLOAD — 25 tools, sab ek jaise read_*
# selection accuracy girti hai + har request mein sab schemas jaate hain

# FIX — group karo, parameters se differentiate karo
find_order(order_id=None, status=None, text=None)   # ek tool, teeno filters

• Overlapping tools se selection errors aate hain — har description mein use-case alag se likho: "tab use karo jab...", "ye nahi...".
• Bahut saare undifferentiated tools = model ko 40 options mein choose karna — decision time aur galti dono badhte hain.
• Related read tools ko ek hi tool mein merge karo optional parameters se — ya ek router tool do jo internally dispatch kare.
• Test tareeka: 10-20 sample questions se dry-run karo aur log karo kaunsa tool chuna — selection quality ka yehi asli data hai.

Arguments = untrusted input

ALLOWED_REFUND_MAX = 5000

def execute_refund(args):
    order_id = args.get("order_id")            # missing?
    amount = float(args.get("amount_rupees", 0))

    if not isinstance(order_id, str):
        raise ValueError("order_id galat type ka hai")
    if amount <= 0 or amount > ALLOWED_REFUND_MAX:
        raise ValueError("amount limit ke bahar — human review")
    if not user_can_refund(current_user, order_id):   # permission
        raise PermissionError("is user ko ye tool chalane ka haq nahi")

    return refund_api(order_id, amount)        # destructive step aakhri mein

• Model-generated arguments ko waise hi treat karo jaise kisi stranger se aaya input — type, range, enum, business limit sab check.
• Permissions tumhare app se aate hain — model permission kabhi nahi de sakta. Har tool par apna authz check rakho.
• Destructive actions (refund, delete, send) ke liye extra gate: dry-run, confirmation, ya human approval — schema ke bina, code mein.
• Validate_args function ek hi jagah likho aur har tool execute se pehle usse guzre — scattered checks chhoot jaate hain.

Exercise

Common mistakes

• Naam rakh lena jaise process_data: — vague naam se model guess karta hai. Verb + object rakho aur description mein scope likho: kya andar, kya bahar.
• Bahut saare ek jaise tools de dena: — selection errors aur bada prompt. Group karo, parameters se differentiate karo, zaroorat na ho toh mat do.
• Arguments par bharosa kar lena: — model-generated input untrusted hai. Type, range, permission check execute se pehle; destructive ke liye approval gate.
• Description mein sirf naam dohrana: — "searches orders" kuch nahi batata. Kab use karna aur kab nahi — yeh likho, yahi model ka decision rule hai.

Board (description)                      Waiter ka decision (model)
"Refund — delivered order, 5000 tak"     -> refund tool chuno
"Refund — kabhi bhi, koi limit nahi"      -> ??? (galat pick)

Chitthi (parameter description): "amount positive, rupees mein"
-> waiter guess nahi karega ki kitne ka refund