Tool Use & Function Calling

When to Use Tools: The Decision Tree

Not every task needs tools. If Claude can answer from training data or context, skip tools. If Claude needs live data (stock prices, real-time weather) or needs to change state (send an email, update a database), tools are essential.

Use tools when: You need real-time data that Claude's training can't provide. You need Claude to affect external systems. You're building a multi-step workflow where Claude makes decisions and calls different functions based on those decisions.

Don't use tools when: Claude can reason from context you've already provided. The task is pure generation or analysis. You're adding tools to every request "just in case" — tools add latency and complexity.

The key insight: tools are a communication channel between Claude and your system. They answer the question "What does Claude need to know or do that it can't do alone?"

Defining Tools Clearly

Tool definitions are critical. A poorly defined tool confuses Claude about when to use it, what parameters it expects, and what it returns. A clear definition makes Claude use tools reliably.

Each tool needs: a name (short, descriptive), a description (what it does and why Claude might use it), and a schema of input parameters. Each parameter needs a type, description, and whether it's required. Don't write vague descriptions — instead of "Gets user data", write "Fetches user profile information including name, email, account creation date, and subscription status for a given user ID."

Parameter specificity matters. If a parameter is a user ID, say so. If it must be an integer greater than 0, state that. If it accepts certain values, list them. Claude uses this information to validate calls before sending them.

Group related tools. If you have several tools for database queries, give them consistent naming: "query_database", "insert_record", "delete_record". This helps Claude understand the domain and make coherent choices.

Tool Responses: The Full Cycle

When Claude decides to use a tool, it sends a request with the tool name and parameters. Your system executes the tool and returns a result. Claude then sees that result and decides what to do next: use another tool, refine its approach, or answer the user based on the results.

This cycle repeats until Claude has gathered enough information to answer the user or decides no more tools are needed. You set the maximum number of tool calls to prevent infinite loops, and you validate results before passing them back to Claude.

Always include context in tool results. If a database query fails, don't just return "error". Return "error: invalid user ID format, expected numeric ID between 1 and 10000000". Claude uses this to understand what went wrong and recover.

Error Handling and Recovery Patterns

Tools will fail. Networks fail, APIs go down, parameters are invalid. Your job is to make failures recoverable and give Claude the information it needs to handle them.

When a tool fails, return the error message to Claude, not to the user. Claude can then decide whether to retry, use a different tool, or tell the user that something went wrong. If the user types "fetch my account", and the API returns "service temporarily unavailable", Claude should explain this to the user, not crash your application.

Implement retry logic carefully. If a tool call is idempotent (safe to retry, like a read), you can retry automatically a few times. If it's not (like sending money), log the attempt and ask before retrying. Be transparent to Claude: if you retried and it eventually worked, tell Claude that happened.

Rate limiting is your responsibility. If your API has rate limits, enforce them before Claude hits them. Better to reject a tool call with "rate limit: 100 calls/minute remaining 5" than to let it fail and confuse Claude.

Safety: Validating Tool Parameters

Claude generally respects parameter types and bounds you define, but you should still validate. If you defined a tool to delete records and expect an ID parameter, validate that Claude sent an ID, not a SQL injection attack or someone else's ID.

Never blindly pass Claude's tool parameters to sensitive operations. Validate inputs, check permissions, and log what's happening. If Claude asks to delete account 12345 and the user is logged in as account 67890, reject it.