LLM tool calling: how an agent calls a real API

A language model cannot look anything up. It writes text. LLM tool calling is the trick that lets it act anyway: the model writes a structured request that says "call this function with these arguments", your code runs the function, and the result goes back to the model as new text.

The pattern is simple on paper. It gets harder once the functions are real APIs with keys, prices and failures. This post explains the loop, lists what breaks first, and shows a way to keep the tool list short so the model keeps choosing well.

What is LLM tool calling?

LLM tool calling, also called function calling, is a feature of model APIs. You send the model a list of tools, each with a name, a description and a schema for its inputs. When the model decides a tool is needed, it replies with the tool name and a set of arguments instead of plain text.

The model does not run anything. Your application, or a client such as Claude Code, receives the request, runs the function, and sends the result back. The model reads it and either answers or asks for another call. That back-and-forth is the agent loop.

How does the loop work step by step?

Two details matter. The model only knows a tool through its description, so a vague description gives wrong calls. And the loop can run many times in one question, so cost and delay add up per call.

What breaks when the tool is a real API?

Five things, in the order most people meet them.

Bad arguments. The model sends a domain with "https://" when the API wants a bare host. Validate inputs in your code and return a clear error, so the model can fix the call.

Keys. Each API needs a credential. Keep it in your code or a gateway, never in the prompt, because the model's context can leak.

Failures. APIs time out, return empty results or return errors. Return the failure as a result the model can read, and say what to do next, such as trying a different provider.

Cost. Each call may cost money, and a loop can call many times. Report the price in the tool result, or cap the number of calls.

Retries. A retry after a timeout can charge twice if the API is not idempotent. Use an idempotency key when the provider supports one.

None of these is hard alone. Together they are why a quick demo takes a day to make safe.

Why do too many tools hurt?

Every tool definition goes into the model's context, and the model has to pick among them. With a dozen tools it chooses well. With hundreds it chooses worse, and it spends tokens reading descriptions it will never use.

One fix is a tool that searches other tools. Instead of listing every endpoint, you give the model a "find a tool for this job" function and a "run this tool" function. The list stays at a handful while the reach stays wide. This is the shape of an MCP gateway, described in MCP gateway for agents.

How does looot handle tool calling?

looot gives an agent a small fixed set of tools: discover, inspect, run, runs, balance and top_up. The model calls discover with a plain description, such as "work email for a person at a company". It gets a short list of endpoints, calls inspect on one to read the input fields and the price, then calls run with the arguments.

That moves the five problems to one place. The gateway holds the provider keys. The price is in the inspect result, before the call. A run is idempotent on a key, so a retry after a timeout does not charge twice. The result of each run, with its cost, can be read afterwards through the runs tool.

You can use this from any client that speaks MCP, or call the REST API from your own code. MCP vs API for agents explains which fits your case, and how to build an MCP server covers the case where you write your own tools.

The live table shows the price of two typical tool calls today.

What should the tool descriptions say?

If you write your own tools, write the description for the model, not for a person. Say what the tool does, what it needs, what it returns and when not to use it. Name the input format with an example. State what an empty result means.

A short, specific description is clearer to the model than a long one. "Returns the top ten Google results for a query as title, URL and position. Needs a query and a country code" tells the model all it needs.

How do I test a tool-calling setup?

Test the tool before you test the model. Call each function by hand with a normal input, a bad input and an empty input. Check that the bad input gives a clear error and the empty input gives a clear empty result.

Then test the model with a small set of questions where you know which tool should be called. Record which tool it picked and with what arguments. If it picks wrong, the fix is nearly always in the tool description, so reword it and run the same questions again.

Keep this set. When you add a tool or change a description, run it again. It takes a minute and catches the case where a new tool steals calls from an old one.

What does a failed call look like to the model?

Return failures as plain results, not as crashes. A good failure message says what went wrong and what to try. "No results for this query. Try a broader query or a different country code" gives the model a next step. A bare stack trace does not.

The same goes for a call that was refused for cost. If the balance cannot cover a run, looot refuses it with a link to top up, and the agent can pass that on to you. A refusal the agent can read is more useful than a silent failure, because the agent can stop, tell you why and ask what to do.

Try it: a prompt for your agent

This prompt makes the agent show the tool loop on one real call and print each step.

Steps 3 and 4 are free, and step 5 costs the price you read in step 4.

What it cannot do

• It does not teach the model to choose well. A vague instruction still gives a vague call.
• It does not replace validation in your own tools. Check arguments before you act on them.
• It covers the endpoints in the catalog. A function that is not there needs your own tool.
• It does not run calls on a timer. A job that repeats needs scheduled runs, not available yet.

Last checked 2026-10-03 against the live catalog and the looot skill file. Author: the looot team.