Xử lý lỗi thường gặp khi sử dụng Tool trong Claude API
Trust: ★★★☆☆ (0.90) · 0 validations · factual
Published: 2026-05-09 · Source: crawler_authoritative
Tình huống
Nhà phát triển tích hợp Claude API tool use feature gặp các lỗi phổ biến: gọi sai tool, tạo tham số không tồn tại, tool gọi tuần tự thay vì song song, cache bị mất hiệu lực, và lỗi khi thực hiện request.
Insight
Bảng chẩn đoán triệu chứng và cách khắc phục cho các lỗi phổ biến khi sử dụng tool trong Claude API. Lỗi gọi sai tool: nguyên nhân thường là mô tả tool mơ hồ - cần làm rõ mô tả, phân biệt tool bằng KHI nào dùng không chỉ dựa trên tool đó làm gì; Claude không gọi tool có thể do trùng tên tool hoặc schema quá chung chung - cần kiểm tra tên trùng lặp và thêm input_examples; gọi sai loại tham số là do schema mơ hồ - thêm strict: true hoặc input_examples. Lỗi tạo tham số không tồn tại: model tạo thừa khi không có strict mode - cần thêm strict: true nếu schema nằm trong subset được hỗ trợ; giá trị tham số ngoài enum: thu hẹp enum hoặc thêm input_examples. Tool gọi tuần tự thay vì song song: do định dạng message history - cần gửi nhiều tool_result blocks trong MỘT user message thay vì một message mỗi lượt; disable_parallel_tool_use bị bỏ qua: phải đặt trên request trả về tool_use, không phải request sau đó. Cache liên tục mất hiệu lực: mỗi request đều miss do tool_choice thay đổi - cần giữ tool_choice ổn định hoặc đặt cache_control breakpoint trước điểm thay đổi; thêm tool giữa cuộc hội thoại làm hỏng cache do tool được thêm vào đầu mảng - cần dùng defer_loading: true để append inline. Lỗi request-time: thiếu tool_result cho tool_use id hoặc tool_result không phải block nội dung đầu tiên - cần trả về một tool_result cho mỗi tool_use block, đặt trước mọi text; schema không tương thích strict mode: dùng pattern với strict: true không được hỗ trợ - cần loại bỏ pattern hoặc bỏ strict: true; tất cả tools có defer_loading: true - ít nhất một tool phải được load ngay lập tức, tool search itself không được có defer_loading: true. Khác biệt escape JSON (Opus 4.6+): so sánh string trên tool inputs thất bại với model mới do khác biệt Unicode và forward-slash escaping - cần parse bằng json.loads() hoặc JSON.parse(), không so sánh string thô trên input đã serialize.
Hành động
- Khi Claude gọi sai tool: làm rõ mô tả tool, tập trung vào KHI nào nên dùng thay vì chỉ WHAT; kiểm tra tên trùng lặp trong danh sách tool; thêm input_examples để minh họa cách dùng. 2. Khi Claude tạo tham số không tồn tại: thêm strict: true nếu schema nằm trong JSON Schema subset được hỗ trợ; thu hẹp enum hoặc thêm input_examples cho các lựa chọn hợp lệ. 3. Khi tool gọi tuần tự: gửi nhiều tool_result blocks trong một user message duy nhất thay vì một message mỗi lượt; đặt disable_parallel_tool_use trên request trả về tool_use. 4. Khi cache mất hiệu lực: giữ tool_choice ổn định giữa các request; đặt cache_control breakpoint trước điểm thay đổi biến; dùng defer_loading: true với tool search để append inline thay vì thêm vào đầu mảng. 5. Khi có lỗi request-time: luôn trả về một tool_result cho mỗi tool_use block; đặt tool_result blocks trước mọi text trong user message; không dùng pattern với strict: true; đảm bảo ít nhất một tool không có defer_loading: true. 6. Khi so sánh string thất bại với model mới: luôn parse JSON bằng json.loads() hoặc JSON.parse(), không so sánh string thô.
Điều kiện áp dụng
Nội dung dành cho nhà phát triển tích hợp Claude API, không liên quan đến nền tảng thương mại điện tử hoặc chiến lược bán hàng online
Nội dung gốc (Original)
Troubleshooting tool use
Fix the most common tool-use errors with symptom-to-fix diagnostic tables.
Symptom-to-fix tables for the most common tool-use errors. Each fix cross-references the page that owns the feature.
Claude calls the wrong tool
| Symptom | Likely cause | Fix |
|---|---|---|
| Claude calls tool A when you wanted tool B | Description ambiguity | Sharpen descriptions. Differentiate tools by WHEN to use them, not only WHAT they do. See Define tools. |
| Claude never calls your tool | Tool name collision or overly-generic schema | Check for duplicate names across your tool list. Add input_examples to make the intended use concrete. |
| Claude calls with wrong parameter types | Model guessing at ambiguous schema | Add strict: true (if your schema is in the supported subset) or add input_examples. |
Claude invents tool parameters
| Symptom | Likely cause | Fix |
|---|---|---|
| Parameter that doesn’t exist in your schema | Model over-generation without strict mode | Add strict: true if your schema is in the supported subset. |
| Parameter values outside your enum | Missing strict mode or too-large enum | Shrink the enum or add input_examples showing valid choices. |
Parallel tool calls don’t work
| Symptom | Likely cause | Fix |
|---|---|---|
| Claude calls tools sequentially when parallel would be better | Message history formatting | Send multiple tool_result blocks in ONE user message, not one per turn. See Parallel tool use. |
disable_parallel_tool_use seems ignored | Set too late in the conversation | Must be set on the request that returns tool_use. Setting it on a later request has no effect on earlier tool calls. |
Cache keeps invalidating
| Symptom | Likely cause | Fix |
|---|---|---|
| Every request is a cache miss | tool_choice varying between requests | Keep tool_choice stable or place the cache_control breakpoint before the variation point. See Tool use with prompt caching. |
| Adding a tool mid-conversation breaks cache | Tool prepended to the tools array | Use defer_loading: true with tool search to append the tool inline instead of modifying the array head. |
Errors at request time
| Error | Cause | Fix |
|---|---|---|
tool_use ids were found without tool_result blocks immediately after | Missing tool_result for some tool_use ids, or tool_result is not the first content block in the user message | Return one tool_result for every tool_use block in the assistant response. Put tool_result blocks before any text. See Handle tool calls and Parallel tool use. |
Input schema is not compatible with strict mode: string patterns are not supported | Using pattern with strict: true | Remove the pattern or drop strict: true. The pattern keyword is not in the supported JSON Schema subset yet. |
All tools have defer_loading: true | No tools visible to the model | At least one tool must be immediately loaded. The tool search tool itself must never have defer_loading: true. |
JSON escaping differences (Opus 4.6+)
| Symptom | Cause | Fix |
|---|---|---|
| String comparison on tool inputs fails with newer models | Unicode and forward-slash escaping differs between model versions | Parse with json.loads() or JSON.parse(). Never do raw string matching on serialized input. |
Next steps
Liên kết
- Nền tảng: Claude · Anthropic
- Nguồn: https://platform.claude.com/docs/en/agents-and-tools/tool-use/troubleshooting-tool-use.md
Xem thêm: