Tool Calling اور Structured Outputs: وہ contract جو قائم رہتا ہے

mechanics سے پہلے، وہ جملہ جو سب سے زیادہ confusion روکتا ہے: tool call ایک request ہے، action نہیں۔

model ایک structured message نکالتا ہے جو کہتا ہے میں چاہتا ہوں کہ search_flights ان arguments کے ساتھ call ہو۔ پھر وہ رک جاتا ہے۔ آپ کا code وہ message وصول کرتا ہے، فیصلہ کرتا ہے کہ اسے honour کرنا ہے یا نہیں، جو بھی call کرنا ہو کرتا ہے، اور result کو ایک اور message کے طور پر واپس بھیجتا ہے۔ model نے کبھی آپ کے database کو نہیں چھوا، کبھی HTTP request نہیں کی، کبھی credentials نہیں رکھے۔

Chapter 30 میں agent security کی ہر بات اسی تقسیم سے نکلتی ہے، اور Chapter 23 میں agent design کی ہر بات بھی: model تجویز دیتا ہے اور آپ کا code فیصلہ کرتا ہے، اور ہر guarantee code میں رہتی ہے۔

لہٰذا vocabulary کو ہٹا دیں تو tool دو چیزیں ہے:

اس میں کچھ بھی emergent نہیں۔ جیسا کہ Chapter 11 نے establish کیا، tool calling ایک trained behaviour ہے:¹ post-training کے دوران model نے ہزاروں conversations دیکھی تھیں جو عین اسی shape میں تھیں۔ اسی لیے format model-specific ہے، اسی لیے similar size کے models کے درمیان reliability اتنی بدلتی ہے، اور اسی لیے model ایک ایسا tool call کر سکتا ہے جو اس نے پہلے کبھی نہیں دیکھا — shape train ہوئی تھی، specific tool آپ کے prompt سے آتا ہے۔

یہ tool ہے جیسے اکثر لوگ اسے پہلی بار لکھتے ہیں۔ نوٹ کریں کہ اس میں کچھ بھی غلط نہیں؛ یہ بس thin ہے:

{
  name: "search_flights",
  description: "Search for flights.",
  parameters: {
    type: "object",
    properties: {
      from: { type: "string", description: "Airport." },   
      to:   { type: "string", description: "Airport." },   
      date: { type: "string", description: "The date." },  
    },
    required: ["from", "to", "date"],
  },
}

چوبیس requests، چھ city pairs کو date express کرنے کے چار طریقوں کے ساتھ cross کیا گیا (”اگلے مہینے کی 3 تاریخ“، ”اگلا Friday“، ”15 December“، ”کل“)، greedy decoding تاکہ results reproduce ہوں:

آخری تین سے پہلے پہلی دو columns پڑھیں۔ model ہر بار درست tool call کرتا ہے اور ہر بار well-formed JSON بناتا ہے۔ failure پوری طرح values میں ہے، اور values unusable ہیں: "Madrid" بجائے MAD، "3rd October 2026" بجائے 2026-10-03۔

اس پر زور دینا ضروری ہے کیونکہ یہی طے کرتا ہے کہ کچھ break ہونے پر آپ کہاں دیکھتے ہیں۔ instinct یہ ہوتی ہے کہ retry کے ساتھ JSON parser شامل کیا جائے، یا model سے valid JSON کے لیے زیادہ سختی سے کہا جائے۔ یہاں جو ہوا، ان میں سے کوئی بھی اسے address نہیں کرتا۔

وہی endpoint۔ اس کے پیچھے وہی code۔ وہی model، وہی prompts، وہی decoding۔ صرف schema میں text بدلتا ہے:

{
  name: "search_flights",
  description: "Search scheduled flights between two airports on a given day.",
  parameters: {
    type: "object",
    properties: {
      from: {
        type: "string",
        description: "Departure airport as a three-letter IATA code, e.g. MAD for Madrid. Never a city name.",   
        pattern: "^[A-Z]{3}$",
      },
      to: { /* same */ },
      date: {
        type: "string",
        description: "Departure date as an ISO 8601 calendar date, YYYY-MM-DD. Resolve relative dates against today before calling.",   
        format: "date",
        pattern: "^\\d{4}-\\d{2}-\\d{2}$",
      },
    },
    required: ["from", "to", "date"],
  },
}

date format 24 میں سے 2 سے 24 میں سے 24 ہو جاتا ہے۔ perfect، صرف text change سے، code کو چھوئے بغیر اور retry logic کے بغیر۔ اگر آپ اس chapter سے ایک operational habit لیں تو وہ یہ ہے: جب tool غلط call ہو، fix تقریباً ہمیشہ description میں ہوتی ہے، اور یہ system کی سب سے سستی fix ہے۔

اب دوسری column پڑھیں، جو زیادہ اہم نصف ہے۔

date 24 میں سے 24 بار ISO format میں ہے۔ وہ درست دن 24 میں سے 12 بار ہے۔

تو اب آدھی calls میں perfectly formatted date ہے جو غلط date ہے۔ description نے model کو بتایا کہ کون سی shape produce کرنی ہے، اور model نے اسے flawless produce کیا — مگر ”اگلا Friday“ کو 2026-09-11 میں بدلنے کے لیے آج کی date جاننا اور calendar arithmetic کرنا ضروری ہے، اور description کی کوئی مقدار یہ supply نہیں کرتی۔ airports کے ساتھ بھی یہی ہے: format 4 سے 16 ہوا، مگر value صرف 4 سے 8، کیونکہ MAD لکھنے کے لیے جاننا پڑتا ہے کہ Madrid کا airport MAD ہے۔

یہ فرق اس chapter کا load-bearing idea ہے:

schema form کے بارے میں contract ہے۔ یہ model کے output کو parseable، typed اور consistent بنا سکتا ہے۔ یہ اسے true نہیں بنا سکتا، اور ہر failure mode جو اچھے schema کے بعد بھی بچتا ہے knowledge failure ہے، format failure نہیں۔

دونوں کو مختلف fixes چاہیے، اور انہیں confuse کرنا weeks ضائع کرتا ہے۔ Format failures description میں یا constrained decoding کے ذریعے fix ہوتے ہیں، نیچے۔ Knowledge failures knowledge کو prompt میں ڈال کر fix ہوتے ہیں — system message میں current date، ایک airport lookup بطور second tool جسے model پہلے call کرے، schema میں enum جب set اتنا چھوٹا ہو کہ enumerate کیا جا سکے۔ نوٹ کریں کہ تینوں میں common کیا ہے: یہ problem کو model کی memory سے نکال کر اس کے input میں منتقل کرتے ہیں، جو Chapter 24 کا پورا موضوع ہے۔

اوپر کی ہر چیز اب بھی اس پر rely کرتی ہے کہ model درست shape produce کرنے کا انتخاب کرے۔ ایک stronger guarantee دستیاب ہے، اور یہ Chapter 17 کا بہترین payoff ہے۔

یاد کریں generation کیسے کام کرتی ہے: ہر step پر model vocabulary کے ہر token کے لیے logit produce کرتا ہے، اور sampler ایک چنتا ہے۔ Constrained decoding بیچ میں ایک step insert کرتی ہے۔ ایک grammar — جو آپ کے JSON Schema سے derived ہے — کے given، یہ compute کرتی ہے کہ اگلے legal tokens کون سے ہو سکتے ہیں، باقی سب کے logits کو negative infinity پر set کرتی ہے، اور sampler کو باقی میں سے choose کرنے دیتی ہے۔

اگر schema کہتا ہے کہ اگلی چیز { ہونی چاہیے، تو ہر token جو { نہیں ہے اس کی probability zero ہے۔ ”unlikely“ نہیں: zero۔ model invalid JSON emit نہیں کر سکتا کیونکہ invalid tokens sampling سے پہلے distribution سے remove کر دیے گئے تھے۔

یہی ”structured outputs“، ”JSON mode“ اور ”guided generation“ کے نیچے ہوتا ہے، اور یہی ان کی دو properties explain کرتا ہے۔ guarantee ہر اس چیز کے لیے total ہے جسے grammar express کر سکتی ہے — types، required fields، enums، nesting — کیونکہ یہ politely request کرنے کے بجائے mechanically enforce ہوتی ہے۔ اور یہ content کے بارے میں کچھ نہیں کہتی: grammar "date" کو date pattern match کرنے والی string ہونے پر force کر سکتی ہے، مگر اسے درست دن ہونے پر force نہیں کر سکتی۔ یہ پچھلے section والی ہی wall ہے، بس دوسری طرف سے آ کر۔

دو practical notes۔ یہ free نہیں: mask ہر step پر compute کرنا پڑتا ہے، اور complex grammars measurable latency cost کرتی ہیں۔ اور یہ بدل دیتی ہے کہ model کیا کر رہا ہے — preferred token سے ہٹایا گیا model perfect structure produce کرتے ہوئے worse content produce کر سکتا ہے، اسی لیے simple shapes کے لیے ”اچھے سے پوچھو اور validate کرو“ اب بھی reasonable default ہے، اور constrained decoding اپنی cost تب earn کرتی ہے جب shape complex ہو یا consumer strict ہو۔

Chapter 14 نے ایک timeout کے بعد retry کو measure کیا تھا جو ایک answer کے لیے دو generations bill کر رہا تھا۔ tools کے ساتھ یہی failure worse ہو جاتا ہے، کیونکہ tool کچھ کر سکتا ہے۔

اگر آپ کا code charge_card call کرتا ہے، timeout ہوتا ہے، اور retry کرتا ہے، تو آپ کے پاس دو charges ہیں۔ model کو اس میں سے کسی چیز کا پتا نہیں؛ اسے ایک tool result دکھتا ہے۔ fix وہی ہے جو کسی بھی distributed system میں ہے اور یہ model کا مسئلہ نہیں: call کو ایک key دے کر operation کو idempotent بنائیں، تاکہ second execution پہلے کو recognise کرے اور کام دوبارہ کرنے کے بجائے اس کا result return کرے۔

اس سے نکلنے والا design rule صاف لفظوں میں کہنے کے قابل ہے۔ اپنے tool catalogue میں reads کو writes سے الگ رکھیں۔ read کو freely retry کیا جا سکتا ہے، parallel چلایا جا سکتا ہے، اور cache کیا جا سکتا ہے۔ write ایسا نہیں کر سکتا، اور اسے key، permission check، اور — ہر اس چیز کے لیے جس کے ہونے سے پہلے user جاننا چاہے — approval step لے کر چلنا چاہیے جو request اور action کے درمیان human رکھتا ہے۔ یہ approval step courtesy نہیں: یہ ان چند چیزوں میں سے ایک ہے جو prompt injection اور real consequence کے درمیان کھڑی ہیں — اور، Chapter 30 measure کرتا ہے، انہی میں سب سے کمزور بھی۔

folklore کہتا ہے کہ بہت سے tools load کرنے سے model غلط choose کرتا ہے۔ اسے repeat کرنے کے بجائے measure کرنا بہتر ہے، اس لیے: وہی چوبیس requests، flight tool کے ساتھ بڑھتا ہوا دوسرے tools کا set — جن میں تین جان بوجھ کر confusable ones شامل ہیں (train timetables، ferry crossings، bus routes)۔

Selection degrade نہیں ہوئی۔ بیس tools کے ساتھ، جن میں تین plausibly confusable تھے، half-billion-parameter model نے چوبیس میں سے چوبیس بار right one pick کیا۔ دس پر dip وہ تین calls ہیں جنہوں نے different tool name کیا، اور یہ بیس تک جانے پر باقی نہیں رہتا۔

یہ negative result ہے اور اسے اسی طرح report ہونا چاہیے: اس task پر، ان tools کے ساتھ، ”too many tools“ مسئلہ نہیں تھا۔ جو چیز monotonically اور six factor سے بڑھی وہ prompt ہے: 353 tokens سے 2,119، conversation کی ہر request پر paid، ہمیشہ، چاہے کوئی tool use ہو یا نہ ہو۔

لہٰذا folklore کا honest version cost اور context، accuracy نہیں کے بارے میں ہے۔ بیس tools ہر message پر permanent tax ہیں، اور Chapter 16 پہلے ہی دکھا چکا ہے کہ چالیس turns میں permanent prefix bill کے ساتھ کیا کرتا ہے۔ جب لوگ report کرتے ہیں کہ بہت سے tools quality کو hurt کرتے ہیں، mechanism عموماً یہ ہوتا ہے کہ definitions نے وہ context باہر دھکیل دیا جو matter کرتا تھا — یہ Chapter 24 کا problem ہے جو Chapter 18 کا costume پہنے ہوئے ہے۔ وہ tools جو واقعی ایک دوسرے کے near-duplicates ہیں real problem بھی ہیں، اور ان کی fix fewer tools نہیں بلکہ better descriptions and namespaces ہے: انہیں system کے لحاظ سے prefix کریں (crm.search_customer، billing.search_customer) تاکہ دو teams سے merge ہونے والے دو catalogues collide نہ کریں، اور model کے پاس discriminate کرنے کے لیے کچھ ہو۔

tools کو اس کے لحاظ سے sort کرنا مدد دیتا ہے کہ وہ world کے ساتھ کیا کرتے ہیں، کیونکہ ہر ایک کی engineering مختلف ہے۔

Data tools read کرتے ہیں: search، fetch، query۔ Retryable، parallelisable، cacheable۔ یہ nothing useful return کر کے fail ہوتے ہیں، اور ان کا main risk یہ ہے کہ یہ untrusted text کو context میں لے آتے ہیں — جو Chapter 30 کا entire attack surface ہے۔

Action tools write کرتے ہیں: send، create، charge، delete۔ key کے بغیر retryable نہیں، safely parallelisable نہیں، اور یہی وجہ ہے کہ approval flows exist کرتے ہیں۔

Orchestration tools دوسرے models call کرتے ہیں۔ ایک ایسا tool جس کی implementation ایک اور agent ہے، اپنے prompt، اپنے tools اور اپنے loop کے ساتھ — اور calling model کے لیے یہ بالکل باقی دو جیسا دکھتا ہے، کیونکہ schema اور endpoint ہی وہ سب ہیں جو وہ کبھی دیکھتا ہے۔

یہ third kind curiosity نہیں۔ یہ Chapter 25 کے agent-as-a-tool نصف کے پیچھے mechanism ہے — دوسری topology، handoff، conversation دے دیتی ہے اور اسے کبھی واپس نہیں لیتی — اور یہ عین اس لیے کام کرتا ہے کہ اس chapter کا interface اتنا narrow ہے کہ پورا agent اس کے پیچھے fit ہو جاتا ہے۔

اب آپ کے پاس ایک model ہے جو چیزیں ask کر سکتا ہے، اور ایک contract ہے جو asking کو parseable بناتا ہے۔ آپ کے پاس جو نہیں ہے وہ یہ ہے کہ وہ prompt میں fit ہونے والی چیزوں سے آگے کس چیز کے بارے میں ask کرے۔

production میں سب سے common tool، بہت بڑے margin سے، اس text body پر search ہے جو model نے training کے دوران کبھی نہیں دیکھا: آپ کی documentation، آپ کے tickets، آپ کے contracts۔ یہ solved problem لگتا ہے — اسے embed کریں، nearest neighbours تلاش کریں، انہیں paste کریں — اور جو parts solved نہیں ہیں وہی decide کرتے ہیں کہ answer trustworthy ہے یا نہیں: text کو embedding سے پہلے کیسے cut up کیا جاتا ہے، کون سا similarity threshold اتنا low ہے کہ مجھے نہیں معلوم معنی دے، اور citation کو claim کے ساتھ کیسے attach کیا جاتا ہے تاکہ reader اسے check کر سکے۔

Chapter 19 retrieval ہے، اور یہ وہ chapter ہے جہاں wrong answer curiosity رہنا چھوڑ کر liability بننا شروع کرتا ہے۔

اس chapter کی measurements Qwen/Qwen2.5-0.5B-Instruct سے آتی ہیں، greedy decoding کے ساتھ، 24 generated requests پر جو six city pairs کو four date phrasings کے ساتھ cross کرتی ہیں، tool definitions کے لیے model کے own chat template کو use کرتے ہوئے۔ یہ exactly reproduce ہوتی ہیں، اور یہ small model ہیں: format/value split کو mechanism کی demonstration کے طور پر پڑھیں، current models کیا کرتے ہیں اس کے benchmark کے طور پر نہیں۔ frontier model ”اگلا Friday“ کو کہیں زیادہ often درست resolve کرتا ہے — اور پھر بھی schema سے اسے ایسا کرنے پر مجبور نہیں کیا جا سکتا، یہی وہ part ہے جو generalise کرتا ہے۔

اوپر use ہونے والی JSON Schema vocabulary (type، properties، required، pattern، format، enum) اس JSON Schema draft میں specified ہے جس کا نام آپ کے provider کی documentation دیتی ہے؛ useful subset چھوٹا ہے اور providers کے across same ہے، اور جو differences موجود ہیں — کون سے keywords constrained decoding کے ذریعے enforce ہوتے ہیں بجائے اس کے کہ صرف model کو pass کیے جائیں — انہیں assume کرنے کے بجائے provider کی structured-output guide میں پڑھنا چاہیے۔

constrained decoding بطور technique کے لیے، guidance-style libraries اور outlines project grammar-to-logit-mask construction کو اس طرح document کرتے ہیں جو directly Chapter 17 کے sampler پر map ہوتا ہے۔ اور round trip itself کے لیے، سب سے clear specification tutorial نہیں بلکہ protocol ہے: Chapter 26 اسے line by line پڑھتا ہے۔