Module 3 · Day 21

Single-Tool Prompt — Wire One Tool End to End

Day 15 বলেছিল tool use কী — loop, definition-এর তিন অংশ, brain বনাম hands। আজ (Day 21) সেটাই হাতেকলমে করবে: prompt-এর সাথে ঠিক একটা tool জুড়ে, loop-টা একবার ঘুরিয়ে, শেষ মাথা পর্যন্ত কাজ করানো।

~170 min read6 learning objectives

What you'll learn

•একটা single-tool prompt কী — prompt + ঠিক একটা tool + loop, পাঁচটা না।
•কেন একটা tool লাগে — model frozen + exact math-এ দুর্বল (tokenization, Day 2)।
•সেই একটা tool নিখুঁত লেখা — name + description (আসল lever) + input_schema।
•৪-message array নিজ চোখে বাড়তে দেখা — user → tool_use → tool_result → answer।
•Result আর error handle করা — তোমার কোড চালায়, is_error দিয়ে recover।
•Client tool (calculator — তুমি চালাও) বনাম server tool (web_search — Anthropic চালায়)।

Before this

•Day 15 — tool use intro: loop, tool definition-এর তিন অংশ, brain vs hands।
•Day 9 — structured output / JSON schema (input_schema চেনা লাগবে)।
•Day 2 — tokenization (কেন model সংখ্যায় দুর্বল, সেটা এখানে কাজে লাগবে)।

কেন একটা Tool লাগে

একটা নির্দিষ্ট গর্ত ভরাট করতে একটা নির্দিষ্ট tool।

এতদিন তুমি শুধু prompt লিখেছ। Day 15 বলেছিল tool use আসলে কী — loop, definition-এর তিন অংশ, brain বনাম hands। আজ সেটা হাতেকলমে করবে: একটা prompt-এর সাথে ঠিক একটা tool জুড়ে, loop-টা একবার ঘোরাবে। উদাহরণ — calculator, কারণ এটাই সবচেয়ে পরিষ্কারভাবে দেখায় কেন একটা tool দরকার হয়।

Single-tool promptprompt + one tool + the loop

এতদিন তুমি শুধু prompt লিখেছ। আজ একটা prompt-এর সাথে ঠিক একটা tool জুড়বে, আর loop-টা একবার ঘোরাবে। কেন একটা tool? — model-এর knowledge frozen, আর exact math-এ সে দুর্বল (সংখ্যাকে টুকরো token হিসেবে দেখে, Day 2)। একটা নির্দিষ্ট গর্ত ভরাট করতে একটা নির্দিষ্ট tool।

Why it matters

প্রতিটা বড় agent একটা single tool থেকে শুরু। আগে একটা tool নিখুঁত করতে শেখো — definition, loop, error — তারপর পরের কোনো module-এ পাঁচটা tool-এর agent সহজ লাগবে। রাফি যদি Claude-কে দিয়ে invoice-এর হিসাব করায়, তার শুধু একটা calculator tool লাগে, দশটা না।

Interactive · কেন একটা tool লাগে

Claude একা হিসাব করলে কী হয়

একটা সমস্যা বাছো, তারপর ধাপে ধাপে দেখো — Claude একা ভুল করে কেন, আর calculator tool কীভাবে ঠিক করে।

User prompt

What is 23,450 × 18%?

রাফির invoice-এ ১৮% VAT। এখানে Claude কাছাকাছি বলতে পারে, কিন্তু বড় সংখ্যায় ভরসা নেই — কখনো 4,021, কখনো 4,260 বলে ফেলে।

ধাপ 0 / 3

মনে রাখো: tool মানে Claude-কে স্মার্ট বানানো না — Claude-এর দুর্বল জায়গাটা (exact math) সঠিক একটা যন্ত্রে পাঠিয়ে দেওয়া।

Tool-টা নিখুঁত লেখা

name আর schema তো সহজ — আসল কাজ description-এ।

একটা tool define করতে তিনটা জিনিস লাগে — name, description, আর input_schema (Day 9-এ JSON schema শিখেছিলে)। আজকের আসল কাজ description-টা ভালো লেখা — দুর্বল হলে Claude ভুল সময়ে ডাকে বা miss করে।

The tool definitionname + description + input_schema

সেই একটা tool define করতে তিনটা জিনিস: `name` (calculator), `description` (কী করে, কখন ডাকবে, input কেমন, কী ফেরত), আর `input_schema` (argument-এর JSON Schema)। আজকের আসল কাজ — `description`-টা ভালো লেখা। দুর্বল হলে Claude ভুল সময়ে ডাকে বা miss করে।

Why it matters

description হলো model-এর জন্য একটা prompt (Day 6)। "Calculates math" লিখলে দুর্বল; "Use this for ANY arithmetic… returns only the number" লিখলে Claude ঠিক সময়ে ঠিক call করে। ভালো tool লেখা মানে JSON ভরাট না — prompt engineering। ৩–৪ বাক্যের কম description প্রায়ই কম পারফর্ম করে।

Interactive · সেই একটা tool লেখো

description-টাই আসল lever

একই calculator tool — শুধু description বদলে দেখো। দুর্বল আর ভালো description-এ Claude-এর আচরণ কতটা বদলায়।

{
  "name": "calculator",
  "description": "Evaluate a single arithmetic expression and return the exact numeric result. Use this for ANY arithmetic — addition, subtraction, multiplication, division, percentages — instead of computing in your head, because the result must be precise. The expression must be a valid math string like '23450 * 0.18'. It returns only the number, nothing else.",
  "input_schema": {
  "type": "object",
  "properties": {
    "expression": {
      "type": "string",
      "description": "A valid math expression, e.g. '23450 * 0.18'"
    }
  },
  "required": ["expression"]
}
}

Claude-এর আচরণ

Claude ঠিক সময়ে ডাকে: কী করে, কখন ডাকবে, input কেমন, কী ফেরত — সব পরিষ্কার। এটাই আজকের আসল কাজ।

ভালো description-এ চারটা জিনিস থাকে:

কী করে — এক বাক্যে স্পষ্ট
কখন ডাকবে — 'Use this for ANY arithmetic…'
Input format — 'a valid math string like 23450 * 0.18'
কী ফেরত দেয় — 'returns only the number'

Tool লেখা মানে JSON ভরাট না — description হলো Claude-এর জন্য একটা prompt (Day 6)। এই বাক্যগুলোই ঠিক করে Claude কখন, কীভাবে tool ডাকবে।

৪-Message Loop চোখে দেখো

একটা tool call মানে এক উত্তর না — অন্তত দুটো API call লাগে।

একটা single-tool call মানে messages array-তে চারটা block জমা হয়: user-এর প্রশ্ন, assistant-এর tool_use request, তোমার দেওয়া tool_result, আর assistant-এর শেষ উত্তর। প্রতিটা request-এ তুমি আগের সব message আবার পাঠাও — model-এর তো memory নেই, array-ই তার স্মৃতি।

Four-message loopuser → tool_use → tool_result → answer

একটা single-tool call মানে messages array-তে চারটা block জমা হয়: (১) user-এর প্রশ্ন, (২) assistant-এর tool_use request, (৩) তোমার দেওয়া tool_result, (৪) assistant-এর শেষ উত্তর। প্রতিটা request-এ তুমি আগের সব message আবার পাঠাও — model-এর তো memory নেই, array-ই তার স্মৃতি।

Why it matters

অনেকে আটকায় এখানে: ভাবে এক call-এ উত্তর আসবে। আসে না — একটা tool ডাকলে অন্তত দুটো API call লাগে (একটা tool_use পেতে, আরেকটা result দিয়ে উত্তর পেতে)। এই array বাড়ার ছবিটা মাথায় থাকলে পুরো agent loop পরিষ্কার।

Interactive · ৪-message loop

`messages[]` array বাড়তে দেখো

একটা tool call মানে এক উত্তর না — array-তে চারটা block জমা হয়, মাঝে অন্তত দুটো API call। Next চাপো, প্রতি ধাপে একটা করে block যোগ হবে।

User— User জিজ্ঞেস করল

{ "role": "user",
  "content": "What is 23,450 × 18%?" }

তুমি API-তে user-এর প্রশ্ন আর সাথে tools=[calculator] পাঠালে।

1 / 4 message

Result ফেরত দেওয়া

Model কিছু চালায় না — তোমার কোড চালায়, আর ব্যর্থ হলে সততার সাথে জানায়।

Model কিছুই চালায় না — সে শুধু চায়। তোমার কোড calculate(expression) চালিয়ে ফল tool_result-এ ফেরত দেয়, tool_use_id দিয়ে match করে। ব্যর্থ হলে crash না — is_error: true আর পরিষ্কার বার্তা দাও; Claude পড়ে recover করে।

Run and returnyour code runs; is_error on failure

Model কিছুই চালায় না — সে শুধু চায়। তোমার কোড calculate(expression) চালিয়ে ফল `tool_result`-এ ফেরত দেয়, `tool_use_id` দিয়ে match করে। ব্যর্থ হলে crash না — `is_error: true` আর পরিষ্কার বার্তা ("Error: division by zero") দাও; Claude পড়ে recover করে।

Why it matters

এই boundary-টাই safety (Day 15)। আর একটা সততা: calculator tool প্রায়ই eval() ব্যবহার করে, তাই আগে regex দিয়ে শুধু সংখ্যা/অপারেটর রাখে — tool যা পায় সব untrusted। Production-এ eval না, safe parser। এই ছোট সতর্কতাই পরের কোনো module-এর injection defense-এর শুরু।

Interactive · result ফেরত দেওয়া

`tool_result`-এর shape

function চলার পর তুমি ফল কীভাবে ফেরত দাও? সফল আর ব্যর্থ — দুই অবস্থা টগল করে দেখো Claude কী বলে।

তুমি পাঠাও (user message)

{
  "type": "tool_result",
  "tool_use_id": "toolu_01A",
  "content": "4221.0"
}

Claude বলে

23,450 × 18% = 4,221।

function চলল, ফল string হিসেবে content-এ দিলে। Claude সেটা পড়ে পরিষ্কার উত্তর দেয়।

একটা নিয়ম মনে রাখো: tool_result যায় user message-এ, আর content array-তে সবার আগে। text দিতে চাইলে tool_result-এর পরে। উল্টো হলে API 400 error দেয়।

❌ ভুল order → 400 error

"content": [
  { "type": "text", "text": "ফল:" },     // ❌ text আগে
  { "type": "tool_result", ... }
]

✅ ঠিক order

"content": [
  { "type": "tool_result", ... },         // ✅ আগে
  { "type": "text", "text": "এরপর?" }
]

Error মানে loop crash না — is_error: true আর একটা কাজে-লাগা বার্তা দিলে Claude নিজেই সামলে নেয়। আর tool_result সবসময় content array-তে আগে।

Client বনাম Server Tool

কে চালায় — তার ওপর নির্ভর করে কোনটা বাছবে।

Calculator একটা client tool — তুমি function লেখো, তুমি চালাও, তুমি tool_result পাঠাও। web_search একটা server tool — শুধু type: "web_search_20250305" দিয়ে enable করো; Anthropic নিজে চালায়, result auto context-এ আসে, তোমাকে tool_result পাঠাতে হয় না।

Client vs serveryou run it / Anthropic runs it

Calculator একটা client tool — তুমি function লেখো, তুমি চালাও, তুমি tool_result পাঠাও। web_search একটা server tool — শুধু `type: "web_search_20250305"` দিয়ে enable করো; Anthropic নিজে চালায়, result auto context-এ আসে, তোমাকে tool_result পাঠাতে হয় না।

Why it matters

কোনটা বাছবে নির্ভর করে "কে চালাবে"-র উপর। তোমার private logic/data (calculator, database) → client। বাইরের সাধারণ ক্ষমতা (web search) → server, কম কোড কিন্তু খরচ ($10/1000) আর control কম। এই পার্থক্য বুঝলে tool বাছাই সহজ।

Interactive · client বনাম server tool

কে চালায়?

সব tool তোমার কোড চালায় না। calculator (client) বনাম web_search (server) — পাশাপাশি দেখো পার্থক্যটা কোথায়।

Client tool

calculator (আজকেরটা)

কে চালায়: তোমার কোড চালায়
tool_result পাঠাও?: হ্যাঁ — তুমি tool_result পাঠাও
খরচ: Free (তোমার নিজের কোড)

tools=[{
  "name": "calculator",
  "description": "...",
  "input_schema": { ... }
}]

1Model tool_use request দেয়

2তোমার কোড calculate() চালায়

3তুমি tool_result ফেরত পাঠাও

4Model উত্তর দেয়

তুমিই function লেখো, তুমিই চালাও, control পুরো তোমার হাতে। তোমার private data বা logic হলে এটাই লাগবে।

Server tool

web_search

কে চালায়: Anthropic-এর server চালায়
tool_result পাঠাও?: না — result auto context-এ আসে
খরচ: $10 / 1000 search + token

tools=[{
  "type": "web_search_20250305",
  "name": "web_search",
  "max_uses": 5
}]

1Model search করতে চায়

2Anthropic নিজে search চালায়

3Result সরাসরি Claude-এর context-এ ঢোকে

4Model citation-সহ উত্তর দেয়

তুমি শুধু type দিয়ে enable করো — কোনো function লিখতে/চালাতে হয় না, tool_result পাঠাতে হয় না। সুবিধা বেশি, কিন্তু খরচ আছে আর control কম।

নিয়ম: তোমার নিজের logic/data হলে client tool (তুমি চালাও); বাইরের সাধারণ ক্ষমতা হলে server tool (কম কোড, কিন্তু খরচ + কম control)।

Nail one before fivetool-triggering control

একটা single-tool prompt পুরোপুরি কাজ করানো = prompt + একটা tool + loop + error handling। Claude tool কম ডাকলে description শক্ত করো বা system-এ nudge দাও ("Always use the calculator for arithmetic"); বেশি ডাকলে উল্টোটা। জোর করতে চাইলে tool_choice: any/tool।

Why it matters

একটা tool ঠিকঠাক না করে দশটা যোগ করলে debug করা অসম্ভব। পরের কোনো module-এ multi-tool agent বানাবে — কিন্তু সেটার ভিত্তি আজকের এই একটা নিখুঁত tool। reps matter more than count।

Check Your Understanding

ভুল হলে সমস্যা নেই — প্রতিটার ব্যাখ্যা আছে।

Misconception check

ভালো tool integration মানে একসাথে অনেকগুলো tool দেওয়া

Misconception check

Calculator tool দিলেই Claude আর নিজে হিসাব করে ভুল করবে না

Misconception check

tool_result-টা assistant message-এ পাঠাতে হয়

Misconception check

Tool চালাতে গিয়ে error হলে পুরো loop ভেঙে যায়

Misconception check

web_search-এর জন্যও তোমাকে function চালিয়ে tool_result পাঠাতে হয়

Misconception check

একটা tool ডাকলে এক API call-এই উত্তর পেয়ে যাবে

Quick check