Tool Use Errors — Claude, GPT, Gemini Function Calling Errors Fix Guide | AI Error Hub
AI Error Hub/Categories/Tool Use & Function Calling Errors
Category Hub

Tool Use & Function Calling Errors

Every function calling error across Claude, GPT, and Gemini — with the fix.

24 documented errors
Tool use (function calling on OpenAI) is the pattern where the model calls your functions with structured arguments. When it works, agents feel magical. When it breaks, the failure modes are subtle: schema violations that pass provider validation but fail your code, arguments the model invented, tools the model called that don't exist, or execution timeouts that leave your agent in an inconsistent state. This hub is every documented tool-use error and its fix.

Errors in this category

Anthropic
invalid_tool_input

Model called your tool with arguments that don't match your input_schema.
unknown_tool_name

Model tried to call a tool that isn't in your tools array.
missing_tool_result

You called messages.create with tool_use in history but no matching tool_result block.
tool_use_truncated

Response cut off during tool_use generation, leaving arguments incomplete.
parallel_tool_use_limit

Requested more parallel tool calls than the model supports in one turn.
schema_size_exceeded

Combined tool schemas exceed the input token budget.
recursive_schema_depth

input_schema uses recursive $ref beyond supported depth.
invalid_tool_choice

tool_choice references a tool name not in the tools array.
OpenAI
invalid_arguments

Function call arguments failed JSON parsing or schema validation.
unknown_function_name

Model called a function not in your tools list.
strict_mode_schema_violation

Strict mode enabled but schema has non-required fields or additionalProperties true.
function_call_truncated

finish_reason='length' during function call generation.
parallel_calls_exceeded

Model attempted more than 128 parallel tool calls.
tool_choice_forced_invalid

tool_choice.function.name references a function not present.
nested_depth_exceeded

Function schema nested deeper than 5 levels in strict mode.
additional_properties_required

Strict mode requires additionalProperties: false on every object.
Google Gemini
invalid_function_declaration

functionDeclaration schema doesn't match OpenAPI 3.0 subset Gemini supports.
oneOf_unsupported

Schema uses oneOf which Gemini's OpenAPI subset doesn't support.
function_response_blocked

Safety filter blocked the function response content.
function_name_mismatch

functionResponse.name doesn't match the functionCall.name from the model.
parts_order_invalid

functionCall and functionResponse parts aren't paired in the required order.
Cross-provider
tool_execution_timeout

Your tool implementation didn't return within the caller's timeout budget.
hallucinated_arguments

Model filled required fields with plausible-sounding but invented values.
tool_loop_detected

Agent repeatedly calls the same tool with the same arguments, not converging.

Related pillar guides

G7. Function Calling Reliability Patterns

The pillar guide covering tool schema design, argument validation, retry logic, and the 10 bugs that break tool-use pipelines in production.

G8. Structured Output Reliability

Tool-as-schema is the same primitive as structured output. This guide covers schema design principles that apply to both.

Related blog posts

Bulletproof Claude API Wrapper (with code)

The wrapper pattern that turns tool-use error handling into a single decorator layer.

Frequently asked questions

Why do function calls sometimes have malformed JSON arguments?

Almost always because you're using prompt-only extraction rather than the provider's function calling API. Providers with schema-enforced generation (Anthropic tool_use, OpenAI strict mode) guarantee syntactically valid arguments. If you're seeing malformed JSON, upgrade to the structured API first before adding repair logic.

What's the difference between tool_use in Claude and function calling in OpenAI?

Underlying mechanics are equivalent — model outputs structured arguments to a defined schema. Differences: OpenAI enforces strict mode (all fields required, additionalProperties: false); Anthropic accepts more permissive schemas but recommends explicit constraints. Message shapes differ too: OpenAI uses tool_calls array in message, Anthropic uses content blocks with type='tool_use'.

How do I handle tools that the model called but don't exist?

Return a tool_result with is_error=true and a message like 'Unknown tool: X. Available tools are: Y, Z.' The model will typically pick a valid tool on the next turn. If it keeps hallucinating tools, review your system prompt — the model is inferring tools from context that don't exist in your tools array.

Can I execute multiple tool calls in parallel?

Yes on both Anthropic (via multiple tool_use blocks in one turn) and OpenAI (via multiple entries in tool_calls). Execute them in parallel in your code (Promise.all or asyncio.gather), then return all tool_results in a single follow-up message.

What's the max number of tools I can define per request?

No hard limit, but practical limits: OpenAI recommends under 20; Anthropic under 30. More tools = larger token budget spent on definitions and more model confusion. See G7 Chapter 6 for the pattern of dynamic tool selection per turn.

Why do my tool arguments come back as strings instead of the JSON types I specified?

On OpenAI, arguments come as a JSON string in tool_calls[i].function.arguments — you have to JSON.parse it. This is a common gotcha. On Anthropic, input is a parsed object in tool_use.input. Same for Gemini's functionCall.args.

How do I test tool-use flows without burning API credits?

Mock the provider client. Return synthetic tool_use responses that match your expected schemas. Test that your tool executor handles them correctly. Only run the real model in periodic golden dataset evaluations, not on every commit.