Designing tools agents can actually use
Marek Vlasak · 27 August 2026 · 7 min read
When an agent misbehaves the instinct is to rewrite the system prompt. More often the tools themselves are the problem: vague names, overloaded parameters, and errors the model cannot act on.
One tool, one job
A tool with a mode parameter that switches between search, create and delete asks the model to make three decisions at once. Split it. Three narrow tools are far easier to select between than one wide one.
The docstring is the specification
python
@tool
def search_invoices(customer_id: str, since: str) -> list[dict]:
"""Find invoices for one customer issued on or after a date.
Args:
customer_id: Internal customer identifier, e.g. "C-4417".
since: ISO date, e.g. "2026-01-01".
"""Spell out the format of every argument with an example. Models copy examples far more reliably than they infer conventions.
Make errors recoverable
Returning a raw stack trace ends the loop. Returning a sentence that names the problem and the valid alternatives lets the agent correct itself on the next step.