Tool Use & Function Calling for LLM Agents: Best Practices Guide

Tool use is where most LLM agent reliability problems actually live — not in the model's reasoning, but in ambiguous tool schemas, unhelpful error messages, and tools that compound mistakes when retried. Here's how to design tools that hold up under real agent loops.

Step 1: Write Tool Descriptions as Decision-Time Prompts

The model reads a tool's name and description every time it decides whether to call it — a vague description causes wrong-tool selection even when the implementation behind it is correct.

json

Explicitly stating when not to use a tool (for open-ended exploration... use explore_codebase instead) resolves ambiguity at decision time instead of leaving the model to guess between two similar-sounding tools.

Step 2: Keep the Toolset Small and Non-Overlapping

python

Every additional tool with a similar purpose to an existing one increases the chance of the model picking the wrong one. Consolidating overlapping capabilities into a single, well-parameterized tool is usually better than adding a new tool for every variation.

Step 3: Use Constrained Types Over Free-Text Strings

json

An enum is validated before the tool implementation ever runs, catching an invalid value immediately with a clear schema error — a free-text status field invites typos and casing inconsistencies ("Closed" vs "closed") that only surface as a bug deep inside the tool's logic.

Step 4: Return Actionable Errors, Not Just "Error"

python

A specific error message that names what's wrong and hints at the correct path forward lets the model self-correct on the very next turn. A bare "error": true response tends to produce either an identical retry of the same failing call or the model giving up on the task entirely.

Step 5: Design Tools to Be Idempotent Where Possible

python

Agent loops sometimes retry a tool call after a timeout or an ambiguous response. If the underlying action isn't idempotent, that retry can silently duplicate a side effect — sending a duplicate email, double-charging a payment, or incrementing a counter twice for one logical action.

Step 6: Scope Tool Availability to the Current Task Phase

python

Rather than exposing the full tool catalog on every single turn, restricting it to what's relevant for the current phase of a task reduces the chance of an irrelevant tool being selected simply because it was available.

Key Takeaways

Tool descriptions function as decision-time prompts and need to be specific enough to disambiguate from similar tools, constrained parameter types catch invalid input before it reaches the implementation, actionable error messages let a model self-correct instead of retrying blindly, and idempotent tool design prevents a retried call from silently compounding a side effect.

Frequently Asked Questions

Why does an LLM agent sometimes call the wrong tool even when the right one exists?

Usually because the tool descriptions are vague or overlap with each other — the model chooses based on the tool's name and description at decision time, so two tools that sound similar (e.g. "search_docs" and "find_documentation") measurably increase wrong-tool selection versus one clearly-scoped tool that does the job.

Should tool error messages just say "Error" or include detail?

Include specific, actionable detail — what went wrong and, where possible, what a valid retry would look like. A model that receives "Error: invalid date format, expected YYYY-MM-DD" can self-correct on the next turn; a model that receives just "Error" tends to retry the exact same failing call or give up entirely.

Why use enums instead of free-text strings in tool parameters?

An enum is validated before the tool ever executes, so an invalid value is caught immediately with a clear error rather than reaching the tool implementation with malformed input. Free-text strings for something like a status field ("active", "pending", "closed") invite typos and inconsistent casing that a constrained enum eliminates entirely.

What does it mean for a tool to be "idempotent" and why does it matter for agents?

An idempotent tool produces the same end state no matter how many times it's called with the same input — for example, "set status to active" rather than "increment counter by one." Agent loops sometimes retry a tool call after an ambiguous or timed-out response; if the tool isn't idempotent, that retry can silently duplicate a side effect like sending a second email or charging a payment twice.