AI Agents Engineering · Tool Use & Function Calling · Lesson 2 of 3
Designing good tools & schemas
Tool quality is prompt engineering. The model chooses tools purely from their names, descriptions, and JSON schemas — vague tools cause wrong calls, missing args, and hallucinated parameters.
- Clear names + descriptions: say what the tool does, when to use it, and when NOT to. Include units and formats.
- Tight schemas: use enums, required fields, and types to constrain inputs. Fewer degrees of freedom = fewer bad calls.
- Few, orthogonal tools: too many overlapping tools confuses selection. Consolidate; hide internal complexity behind one tool.
- Return structured, model-friendly results: concise JSON or text the model can act on — not a raw 50KB dump.
- Design errors as data: return a clear error message the model can recover from, not an exception that kills the loop.
Overloaded toolsA single do_everything(action, payload) tool pushes all the decisions into a free-form string the model gets wrong. Prefer specific tools with typed args — the schema does the guiding.
◆ Lock it in
- The model selects tools from name + description + schema — treat these as prompt surface.
- Constrain inputs with enums, required, types; return concise structured results.
- Keep tools few and orthogonal; return errors as recoverable data.
Feynman drill — say it out loudYou have a tool the model keeps calling with the wrong arguments. Name three schema/description changes that would fix it.
Step 1 rate your confidence · Step 2 pick your answer
Which change most directly reduces malformed tool calls?
Step 1 — how sure are you?