Claude Tool Use: मैं अपने AI एजेंटों को वास्तविक क्षमताएं कैसे देता हूं

विषय सूची

जुलाई 2026 में अपडेट किया गया।

TL;DR: Claude tool use आपके एजेंट को कार्य करने देता है — न कि केवल टेक्स्ट जनरेट करने देता है। आप टूल्स को JSON स्कीमा के रूप में परिभाषित करते हैं, Claude तय करता है कि उन्हें कब कॉल करना है, और आपका कोड वास्तविक कार्य को निष्पादित करता है। लूप तीन चरणों में है: संदेश भेजें → tool_use ब्लॉक प्राप्त करें → निष्पादित करें और परिणाम लौटाएं। मैंने यह Cloudflare Workers पर 15+ प्रोडक्शन एजेंटों में लागू किया है। विफलता बिंदु लगभग कभी AI में नहीं होता — यह टूल्स से लौटने वाले अस्पष्ट परिणामों में होता है।

[ऑपरेटर का दृष्टिकोण] मैं एक कंसल्टिंग ब्रांड और Pickleland — टेक्सास के Pflugerville में एक पिकलबॉल सुविधा — में 30+ प्रोडक्शन AI एजेंट चलाता हूं। इनमें से लगभग आधे tool use का उपयोग करते हैं — Claude API की वह सुविधा जो मॉडल को आपके कोड में परिभाषित फ़ंक्शन कॉल करने देती है। प्रोडक्शन में तैनाती और पुनरावृत्ति के बाद मैंने जिस पैटर्न पर सहमति बनाई है, वह यहां है।

Tool use एजेंट की क्षमताओं को क्यों बदलता है

टूल्स के बिना, एजेंट केवल टेक्स्ट जनरेट कर सकता है। यह सारांश, ड्राफ्टिंग और वर्गीकरण के लिए उपयोगी है — लेकिन यह वह नहीं है जो अधिकांश व्यावसायिक स्वचालन को वास्तव में चाहिए। व्यावसायिक स्वचालन को जानकारी खोजनी होती है, डेटाबेस में लिखना होता है, API कॉल करनी होती है, संदेश भेजने होते हैं।

Tool use वह तरीका है जिससे आप Claude को यह एक्सेस देते हैं। आप JSON स्कीमा के रूप में टूल्स का एक सेट परिभाषित करते हैं। Claude स्कीमा पढ़ता है, तय करता है कि किस टूल को किन तर्कों के साथ कॉल करना है, और एक संरचित tool_use कंटेंट ब्लॉक लौटाता है। आपका कोड वास्तविक फ़ंक्शन चलाता है। Claude परिणाम प्राप्त करता है और तय करता है कि आगे क्या करना है — जिसमें दूसरे टूल को कॉल करना या अंतिम टेक्स्ट रिस्पॉन्स देना शामिल है।

मुख्य बात: Claude तय करता है कि टूल कब और कैसे कॉल करना है। क्षमताएं आप परिभाषित करते हैं। मॉडल तर्क करता है कि उन्हें कब उपयोग करना है।

API फ्लो कैसे काम करता है

Tool use लूप के तीन चरण हैं। आप इस लूप को एक या कई बार चलाएंगे — यह इस पर निर्भर करता है कि मॉडल कितने टूल कॉल करता है।

चरण 1: परिभाषित टूल्स के साथ अपना संदेश भेजें

const response = await anthropic.messages.create({
  model: "claude-haiku-4-5-20251001",
  max_tokens: 1024,
  tools: [
    {
      name: "check_court_availability",
      description:
        "Check if a court is available at a given date, time, and duration",
      input_schema: {
        type: "object",
        properties: {
          date: {
            type: "string",
            description: "Date in YYYY-MM-DD format",
          },
          time: {
            type: "string",
            description: "Start time in HH:MM format (24h)",
          },
          duration_minutes: {
            type: "number",
            description: "Duration of the booking in minutes",
          },
        },
        required: ["date", "time", "duration_minutes"],
      },
    },
  ],
  messages: [
    {
      role: "user",
      content: "Is a court available tomorrow at 2pm for 90 minutes?",
    },
  ],
});

चरण 2: जांचें कि क्या Claude टूल कॉल करना चाहता है

if (response.stop_reason === "tool_use") {
  const toolUseBlock = response.content.find(
    (block): block is Anthropic.ToolUseBlock => block.type === "tool_use"
  );

  if (!toolUseBlock) throw new Error("Expected tool_use block");

  // Run your actual function
  const toolResult = await checkCourtAvailability(
    toolUseBlock.input as CourtAvailabilityInput
  );

  // Step 3: Return the result to Claude
  const finalResponse = await anthropic.messages.create({
    model: "claude-haiku-4-5-20251001",
    max_tokens: 1024,
    tools: [
      /* same tools as before */
    ],
    messages: [
      {
        role: "user",
        content: "Is a court available tomorrow at 2pm for 90 minutes?",
      },
      { role: "assistant", content: response.content },
      {
        role: "user",
        content: [
          {
            type: "tool_result",
            tool_use_id: toolUseBlock.id,
            content: JSON.stringify(toolResult),
          },
        ],
      },
    ],
  });

  // finalResponse.content now has the text answer
}

यही पूरा पैटर्न है। प्रत्येक टूल कॉल के लिए तीन API इंटरैक्शन: टूल्स परिभाषित करें → tool_use ब्लॉक प्राप्त करें → परिणाम लौटाएं।

वास्तविक उदाहरण: Pickleland उपलब्धता जांचकर्ता

Pickleland एक पिकलबॉल सुविधा है। हमें Facebook Messenger, कमेंट्स और चैटबॉट के माध्यम से बुकिंग पूछताछ मिलती है। सवाल लगभग हमेशा “क्या शनिवार को दोपहर 3 बजे आप खुले हैं?” या “क्या मैं 8 लोगों के अपने समूह के लिए कोर्ट बुक कर सकता हूं?” का कोई रूपांतर होता है।

उपलब्धता जांचकर्ता एजेंट टूल use का उपयोग करके एक तैयार जवाब देने की बजाय वास्तविक समय में वास्तविक बुकिंग प्रणाली को क्वेरी करता है।

यहां पूरा एजेंट है — सरलीकृत लेकिन प्रोडक्शन के प्रति वफादार:

// workers/availability-checker.ts
import Anthropic from "@anthropic-ai/sdk";

const anthropic = new Anthropic();

const AVAILABILITY_TOOLS: Anthropic.Tool[] = [
  {
    name: "check_availability",
    description:
      "Check court availability for a date, time, and group size. Returns available courts and their prices.",
    input_schema: {
      type: "object",
      properties: {
        date: { type: "string", description: "YYYY-MM-DD" },
        start_time: { type: "string", description: "HH:MM (24h)" },
        duration_minutes: { type: "number" },
        players: { type: "number", description: "Number of players" },
      },
      required: ["date", "start_time", "duration_minutes"],
    },
  },
  {
    name: "get_pricing",
    description:
      "Get current pricing for court rentals and open play sessions",
    input_schema: {
      type: "object",
      properties: {
        session_type: {
          type: "string",
          enum: ["court_rental", "open_play", "clinics"],
        },
      },
      required: ["session_type"],
    },
  },
];

export async function handleInquiry(
  userMessage: string,
  env: Env
): Promise<string> {
  const messages: Anthropic.MessageParam[] = [
    { role: "user", content: userMessage },
  ];

  // Agentic loop — keep going until stop_reason is "end_turn"
  while (true) {
    const response = await anthropic.messages.create({
      model: "claude-haiku-4-5-20251001",
      max_tokens: 512,
      system:
        "You are the booking assistant for Pickleland, a pickleball facility in Pflugerville, TX. " +
        "Use the tools to look up real availability and pricing. Never make up availability or prices. " +
        "If the customer wants to book, direct them to pickleland.com/book.",
      tools: AVAILABILITY_TOOLS,
      messages,
    });

    // Push the assistant's response into message history
    messages.push({ role: "assistant", content: response.content });

    if (response.stop_reason === "end_turn") {
      const textBlock = response.content.find(
        (b): b is Anthropic.TextBlock => b.type === "text"
      );
      return (
        textBlock?.text ??
        "I wasn't able to answer that — please call us directly."
      );
    }

    if (response.stop_reason === "tool_use") {
      // Process ALL tool calls in this response (Claude can request multiple at once)
      const toolResults: Anthropic.ToolResultBlockParam[] = [];

      for (const block of response.content) {
        if (block.type !== "tool_use") continue;

        let result: unknown;

        switch (block.name) {
          case "check_availability":
            result = await checkAvailability(
              block.input as AvailabilityInput,
              env
            );
            break;
          case "get_pricing":
            result = await getPricing(block.input as PricingInput, env);
            break;
          default:
            result = { error: `Unknown tool: ${block.name}` };
        }

        toolResults.push({
          type: "tool_result",
          tool_use_id: block.id,
          content: JSON.stringify(result),
        });
      }

      // Return all tool results in a single user message
      messages.push({ role: "user", content: toolResults });
    }
  }
}

यहां दो बातें ध्यान देने योग्य हैं।

एजेंटिक लूप। मैं तब तक जारी रहता हूं जब तक stop_reason === "end_turn" नहीं हो जाता। Claude check_availability कॉल कर सकता है, तय कर सकता है कि उसे प्राइसिंग भी चाहिए, get_pricing कॉल कर सकता है, और फिर अंतिम उत्तर दे सकता है — यह एक उपयोगकर्ता संदेश के लिए तीन API कॉल हैं। लूप इसे बिना किसी विशेष तर्क के संभालता है।

प्रति टर्न कई टूल कॉल। Claude एक ही रिस्पॉन्स में कई tool_use ब्लॉक लौटा सकता है। मैं उन सभी को प्रोसेस करता हूं और सभी परिणामों को एक ही user संदेश में लौटाता हूं। यदि आप उन्हें एक-एक करके प्रोसेस करते हैं और अलग-अलग लौटाते हैं, तो आप बातचीत का प्रवाह तोड़ देते हैं और टोकन बर्बाद करते हैं।

वास्तविक उदाहरण: लीड रिसर्च एजेंट

मेरा कंसल्टिंग ब्रांड एक रिसर्च एजेंट का उपयोग करता है जो इनबाउंड लीड को उनसे बात करने से पहले समृद्ध करता है। जब कोई संपर्क फ़ॉर्म भरता है, तो एजेंट उनकी कंपनी पर रिसर्च करता है और कॉल से पहले मुझे जो जानने की ज़रूरत है वह निकालता है।

इसके टूल परिभाषाओं में एक राइट टूल शामिल है — और यहां पैटर्न दिलचस्प हो जाता है:

const RESEARCH_TOOLS: Anthropic.Tool[] = [
  {
    name: "search_company",
    description: "Search for information about a company",
    input_schema: {
      type: "object",
      properties: {
        company_name: { type: "string" },
        website: { type: "string", description: "Company website if known" },
      },
      required: ["company_name"],
    },
  },
  {
    name: "save_research",
    description:
      "Save the completed research summary to Airtable. Call this when all research is complete.",
    input_schema: {
      type: "object",
      properties: {
        company_summary: { type: "string" },
        estimated_size: {
          type: "string",
          enum: ["1-10", "11-50", "51-200", "200+"],
        },
        likely_use_case: { type: "string" },
        priority: { type: "string", enum: ["high", "medium", "low"] },
        notes: { type: "string" },
      },
      required: [
        "company_summary",
        "estimated_size",
        "likely_use_case",
        "priority",
      ],
    },
  },
];

save_research वह है जिसे मैं राइट टूल कहता हूं — इसका उद्देश्य जानकारी प्राप्त करना नहीं है, बल्कि Claude के आउटपुट को संरचित रूप में डेटाबेस में कमिट करना है। मैं टेक्स्ट रिस्पॉन्स से JSON पार्स करने की कोशिश करने के बजाय इस पैटर्न का उपयोग करता हूं। Claude जानता है कि रिसर्च कब पूरी होती है और सही टाइप वाले फील्ड के साथ save_research कॉल करता है। मुझे कभी पार्सर नहीं लिखना पड़ता।

यह tool use का सबसे स्वच्छ अनुप्रयोग है: जो स्कीमा आप चाहते हैं उसके साथ एक “फाइनल एक्शन” टूल परिभाषित करें, और Claude टूल कॉल के माध्यम से संरचित आउटपुट देता है। कोई टेक्स्ट पार्सिंग नहीं, कोई regex नहीं, फ्रीफॉर्म टेक्स्ट आउटपुट का कोई JSONSchema वैलिडेशन नहीं।

एक टूल बनाम कई

Tool use शुरू करते समय स्वाभाविक प्रवृत्ति एक विशाल टूल बनाने की होती है जो सब कुछ करे। इस प्रवृत्ति का विरोध करें। छोटे, केंद्रित टूल्स तीन कारणों से बेहतर हैं:

1. Claude छोटे टूल्स के बारे में बेहतर तर्क करता है। get_court_status नाम का टूल जो उपलब्धता लौटाता है, मॉडल के लिए manage_facility टूल की तुलना में प्रसंस्करण करना आसान है जो mode पैरामीटर लेता है और आंतरिक रूप से शाखाएं करता है।

2. छोटे टूल्स परीक्षण करना आसान है। प्रत्येक टूल एक TypeScript फ़ंक्शन है जिसे आप LLM से स्वतंत्र रूप से यूनिट टेस्ट कर सकते हैं। आपको करना चाहिए — एक सक्रिय बातचीत के अंदर टूल बग्स को डीबग करना कठिन है।

3. Claude छोटे टूल्स को समानांतर कर सकता है। यदि दो टूल एक-दूसरे पर निर्भर नहीं हैं, तो Claude उन्हें एक ही रिस्पॉन्स में कॉल कर सकता है और आप उन्हें समानांतर में प्रोसेस करते हैं। यह तभी काम करता है जब टूल वास्तव में स्वतंत्र हों।

अपवाद: टूल्स जिन्हें बहुत अधिक साझा आंतरिक स्थिति तक पहुंच की आवश्यकता होती है। यदि फ़ंक्शन को एक ही डेटा स्रोत से 10 वेरिएबल चाहिए, तो एक समृद्ध स्कीमा वाला एक टूल 10 टूल्स से बेहतर है जो प्रत्येक अलग से डेटाबेस तक पहुंचते हैं।

मेरा व्यावहारिक नियम: प्रत्येक अलग क्षमता के लिए एक टूल से शुरू करें। केवल तब टूल्स को मर्ज करें जब आप देखें कि Claude उन्हें हर अनुरोध में एक साथ कॉल कर रहा है।

लागत निहितार्थ

Tool use टोकन जोड़ता है। प्रत्येक टूल परिभाषा सिस्टम प्रॉम्प्ट संदर्भ में जाती है। प्रत्येक tool_use और tool_result ब्लॉक बातचीत इतिहास में टोकन खपत करता है। मल्टी-टर्न एजेंटिक लूप के लिए, यह तेज़ी से बढ़ता है।

Pickleland उपलब्धता जांचकर्ता के लिए, एक सामान्य बातचीत कुल 3-4 API कॉल चलाती है (प्रारंभिक संदेश + 1-2 टूल कॉल + अंतिम उत्तर), प्रत्येक 600-900 टोकन प्रोसेस करता है। Haiku मूल्य निर्धारण पर, यह प्रति पूछताछ $0.001 से कम चलता है। जैसा कि मैं AI एजेंट लागत गणित पोस्ट में समझाता हूं, Haiku अच्छी तरह से परिभाषित टूल-कॉलिंग कार्यों को विश्वसनीय रूप से संभालता है और एक ही टोकन वॉल्यूम के लिए Sonnet से 10 गुना सस्ता है।

लीड रिसर्च एजेंट Sonnet पर चलता है क्योंकि निर्णय — लीड को प्राथमिकता देना, फिट का अनुमान लगाना — के लिए Haiku की तुलना में अधिक तर्क क्षमता की आवश्यकता होती है जो ओपन इनपुट पर विश्वसनीय रूप से प्रदान करता है। गणना फिर भी काम करती है क्योंकि यह कम बार चलती है (प्रति दिन हजारों बार नहीं, सप्ताह में कुछ बार)। मॉडल चुनाव कार्य जटिलता का अनुसरण करता है, व्यक्तिगत प्राथमिकता का नहीं।

विफलता बिंदु जिसके बारे में कोई बात नहीं करता

प्रोडक्शन tool use में मैं जो सबसे आम विफलता बिंदु देखता हूं वह Claude का गलत टूल कॉल करना नहीं है। यह टूल का कुछ ऐसा लौटाना है जिसके बारे में Claude स्पष्ट रूप से तर्क नहीं कर सकता।

यदि आपका टूल 40 फील्ड वाला रॉ डेटाबेस ऑब्जेक्ट लौटाता है, तो Claude को यह समझने में भ्रम होता है कि कौन से फील्ड महत्वपूर्ण हैं। यदि आपका टूल अपवाद फेंकता है (जो टूल परिणाम के बजाय Worker क्रैश के रूप में प्रकट होता है), तो लूप चुपचाप टूट जाता है। यदि आपका टूल null लौटाता है जब उसका मतलब “कोई परिणाम नहीं” है, तो Claude को नहीं पता कि पुनः प्रयास करना है या छोड़ देना है।

टूल परिणामों के लिए तीन नियम:

संक्षिप्त, स्पष्ट परिणाम लौटाएं। { available: true, courts: ["Court 3", "Court 5"], price_per_hour: 20 } — पूरी डेटाबेस पंक्ति नहीं।

टूल फ़ंक्शन के अंदर त्रुटियों को पकड़ें और उन्हें संरचित परिणामों के रूप में लौटाएं। { error: "booking system timeout", retry: true } — फेंका गया अपवाद नहीं जो Worker को क्रैश करता है।

“कोई परिणाम नहीं” को स्पष्ट बनाएं। { available: false, next_available: "2026-07-23T14:00:00Z" } — बिना संदर्भ के null या खाली array नहीं।

Claude अस्पष्ट रिटर्न वैल्यू की तुलना में स्पष्ट संकेतों के बारे में बहुत बेहतर तर्क करता है। प्रोडक्शन में tool use डिबग करने में मैंने जो भी समय बिताया है, वह मॉडल के तर्क के बारे में नहीं, अस्पष्ट परिणामों के बारे में था।

ऑपरेटर का निष्कर्ष

Tool use वह सुविधा है जो Claude को टेक्स्ट जनरेटर से ऑपरेटर में बदलती है। स्पष्ट इनपुट स्कीमा के साथ केंद्रित टूल्स परिभाषित करें। मॉडल को एकल रिस्पॉन्स में सभी tool_use ब्लॉक संभालें। stop_reason === "end_turn" होने तक एजेंटिक लूप चलाएं। अपने टूल फ़ंक्शन से स्वच्छ, संक्षिप्त परिणाम लौटाएं — रॉ डेटा ऑब्जेक्ट नहीं, फेंके गए अपवाद नहीं, अस्पष्ट null नहीं।

मॉडल तर्क संभालता है। आपका कोड वास्तविक दुनिया की क्रियाएं संभालता है। इन दो कार्यों को स्पष्ट रूप से अलग रखें और आर्किटेक्चर बनाए रखने योग्य रहेगा, भले ही आप टूल्स जोड़ते रहें।

यदि आप अपना पहला tool use एजेंट बना रहे हैं, तो ऊपर के उपलब्धता जांचकर्ता पैटर्न से शुरू करें — एक टूल, एक उद्देश्य, एक एजेंटिक लूप। उसे तैनात करें। फिर दूसरा टूल जोड़ें।

संबंधित: वह एजेंट स्टैक जो मैं 30+ प्रोडक्शन एजेंट चलाने के लिए उपयोग करता हूं · Haiku बनाम Sonnet: एजेंट कार्यों के लिए लागत गणित · इवेंट-ट्रिगर बनाम शेड्यूल्ड एजेंट: किस काम के लिए कौन सा पैटर्न

Tool use एजेंट बना रहे हैं और अटक गए हैं? संपर्क करें — मैं ऑपरेटर टीमों के लिए प्रोडक्शन एजेंट आर्किटेक्चर डिज़ाइन और बनाता हूं।

अक्सर पूछे जाने वाले प्रश्न

क्या Claude tool use सभी मॉडलों के साथ काम करता है?

हां — tool use सभी वर्तमान Claude मॉडलों पर समर्थित है। Claude Haiku स्पष्ट स्कीमा वाले अच्छी तरह से परिभाषित टूल्स को विश्वसनीय रूप से संभालता है और उच्च-वॉल्यूम कार्य प्रकारों के लिए सबसे सस्ता विकल्प है। Sonnet अधिक अस्पष्ट या खुले टूल-कॉलिंग निर्णयों को बेहतर ढंग से संभालता है। Haiku से शुरू करें; यदि आउटपुट गुणवत्ता अपर्याप्त है तो ऊपर जाएं।

Claude tool use और OpenAI फ़ंक्शन कॉलिंग में क्या अंतर है?

यांत्रिक रूप से समान। OpenAI ने “function calling” बनाया; Anthropic इसे “tool use” कहता है। दोनों मामलों में: आप JSON स्कीमा परिभाषित करते हैं, मॉडल संरचित कॉल लौटाता है, आपका कोड फ़ंक्शन निष्पादित करता है। API का आकार अलग है लेकिन अवधारणा एक ही है।

क्या Claude एकल रिस्पॉन्स में कई टूल्स कॉल कर सकता है?

हां। Claude एकल assistant रिस्पॉन्स में कई tool_use ब्लॉक लौटा सकता है। उन सभी को प्रोसेस करें और एकल user संदेश में सभी परिणाम लौटाएं। ऊपर Pickleland उदाहरण में एजेंटिक लूप पैटर्न देखें — response.content पर for लूप इसे सही तरीके से संभालता है।

मुझे प्रति एजेंट कितने टूल्स परिभाषित करने चाहिए?

मैं प्रति एजेंट 8-10 टूल्स से कम रखता हूं। इससे परे, मैंने देखा है कि Claude कभी-कभी पहले प्रयास में गलत टूल चुनता है, जो सुधार लूप में टोकन बर्बाद करता है। यदि आपको 10 से अधिक क्षमताओं की आवश्यकता है, तो एजेंट को विशेष टूल सेट के साथ कई एजेंटों में विभाजित करें बजाय एक ऐसा एजेंट बनाने के जो सब कुछ जानता हो।

क्या मुझे संरचित आउटपुट के लिए tool use का उपयोग करना चाहिए?

हां — save_research राइट-टूल पैटर्न Claude से टेक्स्ट ब्लॉक में JSON लौटाने के लिए कहने और फिर उसे पार्स करने से अधिक स्वच्छ है। जो स्कीमा आप चाहते हैं उसके साथ एक “फाइनल एक्शन” टूल परिभाषित करें। Claude समाप्त होने पर सही टाइप वाले फील्ड के साथ उसे कॉल करेगा। कोई पार्सर आवश्यक नहीं।