Tool calling is an API design problem in disguise

#A client that never reads the guide

When a model calls your tools, it is a client integrating against your API using only the description you supplied. It will not ask a colleague, read the source, or notice a convention that is obvious to you.

Every ambiguity therefore becomes a wrong call, at some rate, forever. Models can learn to use tools effectively when the interface is clear [1], and clarity is entirely on the interface designer.

#Four failures I have caused

Unstated units. A parameter named duration with no unit. The model guessed seconds. The API meant milliseconds. Rename it to durationMs and the problem disappears, which is advice that applies equally to human clients.

Overlapping tools. A search tool and a find tool with similar descriptions. The model picked between them inconsistently, and no prompt change fixed it because the descriptions genuinely did not distinguish them. Merging them fixed it.

Optional parameters that are not optional. A filter documented as optional that returned an unusable result when omitted. The model omitted it, reasonably. Either it is required or the default is sensible.

Errors with no remedy. Returning "invalid request" gives the model nothing to act on, so it retries identically. Returning which field was invalid and what was expected lets it correct itself, which is the loop that reasoning and acting approaches depend on [2].

#Granularity

Too fine and the model needs many calls to do anything, with a chance of going wrong at each step. Too coarse and the parameters become a configuration object the model fills in badly.

The heuristic that has worked: a tool should correspond to something a person would describe as one action. Not "set field" and not "run the entire workflow", but the unit somebody would name in a sentence.

#Security is different here

Tool calls have effects, and the arguments are influenced by content the model has read. If the model retrieves a document, that document can attempt to steer a subsequent call [3].

That means the ordinary rules apply with more force. Authorise the call against the user's permissions rather than the agent's. Validate arguments at the boundary as you would for any untrusted input. Require confirmation for anything irreversible. Complete mediation and least privilege are exactly the right framing [4].

An agent with broad credentials and tools that act on them is a confused deputy waiting to happen.

#Observability

Log every call with its arguments, its result and the step that produced it. When a run goes wrong, the question is always which call started it, and reconstructing that from output text alone is guesswork.

Tracking runs, steps and tool calls as first-class records rather than log lines was the single change that most improved my ability to debug agent behaviour.