Tool Choice — Kiểm soát cách Claude chọn và gọi tools

Khi bạn truyền tools vào Claude API, mặc định Claude tự quyết định có cần gọi tool không. Đôi khi điều này gây ra vấn đề: Claude quá hăng hái gọi tool cho những câu hỏi đơn giản, hoặc ngược lại, bỏ qua tool khi bạn muốn nó dùng.

Parameter tool_choice cho phép bạn kiểm soát chính xác hành vi này với ba chế độ: auto, tool, và any.

Chế độ 1: auto (mặc định)

Claude tự quyết định dùng tool hay trả lời trực tiếp.

import anthropic

client = anthropic.Anthropic()

tools = [
    {
        "name": "get_weather",
        "description": "Lay thong tin thoi tiet theo thanh pho",
        "input_schema": {
            "type": "object",
            "properties": {
                "city": {"type": "string", "description": "Ten thanh pho"}
            },
            "required": ["city"]
        }
    }
]

# Che do auto - Claude tu quyet dinh
response = client.messages.create(
    model="claude-opus-4-5",
    max_tokens=512,
    tools=tools,
    tool_choice={"type": "auto"},  # Day la mac dinh, co the bo qua
    messages=[{"role": "user", "content": "Thoi tiet Ha Noi hom nay the nao?"}]
)
# Claude SE goi tool vi cau hoi lien quan den thoi tiet

response2 = client.messages.create(
    model="claude-opus-4-5",
    max_tokens=512,
    tools=tools,
    tool_choice={"type": "auto"},
    messages=[{"role": "user", "content": "Cho toi biet 2 + 2 bang may?"}]
)
# Claude KHONG goi tool vi co the tra loi truc tiep

Khi dùng auto: Trường hợp tổng quát khi bạn muốn Claude linh hoạt — đôi khi trả lời trực tiếp, đôi khi dùng tool tùy ngữ cảnh.

Vấn đề với auto: Claude có thể quá hăng hái

Với auto, chất lượng prompt ảnh hưởng trực tiếp đến quyết định của Claude. Nếu tools được mô tả quá rộng, Claude có thể gọi tool ngay cả khi không cần thiết:

# Tool mo ta qua rong - Claude co the goi bat ky luc nao
bad_tool = {
    "name": "lookup_info",
    "description": "Tim kiem bat ky thong tin gi",  # Qua chung chung!
    "input_schema": {...}
}

# Tool mo ta cu the - Claude chi goi khi thich hop
good_tool = {
    "name": "lookup_product_price",
    "description": "Tra cuu gia san pham tu catalog. Chi dung khi user hoi ve gia cu the cua mot san pham.",
    "input_schema": {...}
}

Chế độ 2: tool (Force một tool cụ thể)

Ép Claude phải gọi đúng một tool, bất kể câu hỏi là gì.

response = client.messages.create(
    model="claude-opus-4-5",
    max_tokens=512,
    tools=tools,
    tool_choice={
        "type": "tool",
        "name": "get_weather"  # Claude PHAI goi tool nay
    },
    messages=[{"role": "user", "content": "Cho toi biet 2 + 2 bang may?"}]
)

# Ket qua: Claude van goi get_weather du cau hoi khong lien quan!
# Tool input co the la: {"city": "khong xac dinh"} hoac tuong tu

Khi dùng tool:

• Bạn cần guarantee tool luôn được gọi (ví dụ: logging, analytics)
• Sử dụng tool như structured output generator (xem phần dưới)
• Testing và debugging tool cụ thể

Chế độ 3: any (Phải dùng ít nhất một tool)

Claude phải gọi ít nhất một tool trong danh sách, nhưng tự chọn tool nào.

tools = [
    get_weather_tool,
    get_time_tool,
    get_exchange_rate_tool
]

response = client.messages.create(
    model="claude-opus-4-5",
    max_tokens=512,
    tools=tools,
    tool_choice={"type": "any"},  # Claude phai dung it nhat 1 tool
    messages=[{"role": "user", "content": "Bao cao buoi sang: thoi tiet, gio, ty gia?"}]
)
# Claude se goi ca 3 tools (hoac it nhat 1 tuy theo context)

Khi dùng any:

• Bạn muốn Claude luôn kết nối với external data, không được trả lời "từ trí nhớ"
• Dashboard/report generation cần data thực
• Khi bạn có nhiều tools và muốn Claude chọn công cụ phù hợp nhất

Bảng tóm tắt

Use Case thực tế: Structured Sentiment Analysis

Kết hợp tool_choice: tool với "fake tool" là cách mạnh nhất để tạo structured output:

sentiment_schema = {
    "name": "record_sentiment",
    "description": "Luu tru ket qua phan tich cam xuc",
    "input_schema": {
        "type": "object",
        "properties": {
            "sentiment": {
                "type": "string",
                "enum": ["positive", "negative", "neutral", "mixed"]
            },
            "score": {
                "type": "number",
                "description": "Tu -1.0 den 1.0"
            },
            "confidence": {
                "type": "number",
                "description": "Do tin cay 0.0 den 1.0"
            },
            "dominant_emotion": {
                "type": "string",
                "enum": ["joy", "anger", "sadness", "fear", "surprise", "disgust", "neutral"]
            },
            "brief_reason": {
                "type": "string",
                "description": "Ly giai ngan trong 1 cau"
            }
        },
        "required": ["sentiment", "score", "confidence", "dominant_emotion", "brief_reason"]
    }
}

def analyze_sentiment_batch(texts):
    results = []
    for text in texts:
        response = client.messages.create(
            model="claude-opus-4-5",
            max_tokens=256,
            tools=[sentiment_schema],
            tool_choice={"type": "tool", "name": "record_sentiment"},
            messages=[{
                "role": "user",
                "content": f"Phan tich cam xuc doan van sau:

{text}"
            }]
        )

        # Ket qua la JSON truc tiep - khong can parse text
        sentiment_data = response.content[0].input
        results.append({
            "text": text[:50] + "...",
            **sentiment_data
        })

    return results

# Test
reviews = [
    "San pham rat tot, giao hang nhanh, toi rat hai long!",
    "That vong qua, hang bi hong khi nhan duoc, chat luong kem.",
    "Binh thuong, khong co gi dac biet nhung cung dung duoc.",
    "Gia kha dat nhung chat luong tuong xung, se mua lai."
]

results = analyze_sentiment_batch(reviews)
for r in results:
    print(f"Text: {r['text']}")
    print(f"  Sentiment: {r['sentiment']} (score: {r['score']:.2f}, confidence: {r['confidence']:.0%})")
    print(f"  Emotion: {r['dominant_emotion']}")
    print(f"  Reason: {r['brief_reason']}")
    print()

Output đảm bảo 100% là JSON hợp lệ với đúng types và enum values — không cần try/except cho JSON parsing.

Xử lý Parallel Tool Calls với tool_choice

Khi dùng any hoặc auto, Claude có thể gọi nhiều tools cùng một lúc. Đây là cách xử lý đúng:

def process_response_with_multiple_tools(response, messages):
    """Xu ly response co the co nhieu tool calls"""

    if response.stop_reason != "tool_use":
        # Claude tra loi truc tiep
        return response.content[0].text

    # Thu thap tat ca tool results
    tool_results = []
    for block in response.content:
        if block.type == "tool_use":
            result = execute_tool(block.name, block.input)
            tool_results.append({
                "type": "tool_result",
                "tool_use_id": block.id,
                "content": str(result)
            })

    # Them assistant response va tool results vao history
    messages.append({"role": "assistant", "content": response.content})
    messages.append({"role": "user", "content": tool_results})

    # Tiep tuc vong lap
    next_response = client.messages.create(
        model="claude-opus-4-5",
        max_tokens=1024,
        tools=ALL_TOOLS,
        messages=messages
    )

    return process_response_with_multiple_tools(next_response, messages)

Disable Tool Use hoàn toàn

Đôi khi bạn muốn không dùng tool gì cả trong một lượt cụ thể:

# Truyen tools=[] hoac khong truyen tools parameter
response = client.messages.create(
    model="claude-opus-4-5",
    max_tokens=512,
    # Khong truyen tools - Claude chi tra loi bang text
    messages=[{"role": "user", "content": "Xin chao!"}]
)

# Hoac neu ban da khai bao tools truoc do trong conversation
# va muon disable trong mot luot cu the:
# Su dung tool_choice={"type": "auto"} voi tools=[]
# Hoac don gian la khong truyen tools parameter

Tips và Anti-patterns

Nên làm:

• Dùng tool choice khi build data extraction pipeline — guaranteed JSON output
• Dùng any cho agents cần real-time data — tránh hallucination từ outdated training data
• Dùng auto cho conversational interfaces — Claude linh hoạt hơn cho UX tốt hơn
• Viết description tools thật cụ thể để auto hoạt động đúng

Không nên:

• Force tool any trong chatbot tổng quát — sẽ gây ra tool calls không cần thiết, tốn token
• Dùng tool choice với tool mà input không related — Claude sẽ điền input mơ hồ
• Bỏ qua stop_reason check — luôn kiểm tra trước khi đọc content

Bài tiếp theo: giải quyết vấn đề parallel tool calls — khi bạn cần Claude gọi nhiều tools đồng thời để giảm latency, và cách dùng "batch tool" meta-pattern khi Claude không tự làm.