Skip to content
Tutorials Center
My learning

Topics

Lesson 14 of 39 ยท Tools and Function Calling

Designing Good Tools for Agents

Learn how to design tools a model uses correctly: clear names and descriptions, narrow scope, compact outputs, helpful errors and a tool count that stays manageable.

A model never sees your code. It sees a name, a description, a parameter schema and, later, whatever text your tool returns. Those few lines are the entire user interface for the tool, and the "user" is a language model with no way to ask a colleague what you meant. Most tool-calling problems that look like model mistakes are really tool design problems. This lesson collects practical rules for designing tools an agent can use well.

Tools are an interface for a reader

Think of writing documentation for a smart new hire who cannot ask questions and who reads only what you wrote. They will take names literally, follow examples closely, and be confused by two tools that seem to do the same thing.

flowchart LR
  A["Name"] --> M["Model's picture of the tool"]
  B["Description"] --> M
  C["Parameter schema"] --> M
  D["Example values"] --> M
  M --> U["Choice and arguments"]

Everything the model knows about a tool comes from these four things.

Rule 1: name by intent

Prefer a verb plus noun that says what the tool does: search_orders, get_invoice, create_calendar_event. Avoid vague names (process, handle, data) and names that differ only by a tiny detail (search1, search2). Use one naming style across all tools.

Rule 2: describe when to use it, not just what it does

A good description answers three questions: what does it do, when should I choose it, and what does it not do. Compare the two versions.

Python Compare a vague and a clear tool description

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The clear version costs more tokens but removes guesswork: the model knows the identifier to pass, the allowed status values and the neighbouring tool to use for refunds. Spend tokens where they prevent mistakes.

Rule 3: keep each tool focused

Two shapes cause trouble:

  • Swiss-army tools with a mode argument that changes behavior (manage_order(action=...)) force the model to learn a mini language. Split them into get_order, cancel_order, refund_order.
  • Hair-splitting tools that return one field each (get_order_status, get_order_total, get_order_date) cost many steps. Return a compact object with the fields people usually need.

A helpful test: could a new teammate tell, from the names alone, which tool to use for a given user request? If not, merge or rename.

Rule 4: design the output for the model

The result is the next thing the model reads, so shape it deliberately.

  • Return meaningful fields (names, statuses) rather than opaque ids and internal codes, but include the ids the model needs for follow-up calls.
  • Return less: paginate, filter and truncate. A list of 5 relevant rows beats 5,000.
  • Make results self-explanatory: {"status": "shipped", "eta": "2026-11-20"} rather than [3, "2026-11-20"].
  • Say when nothing was found, and what to try. See tool errors.
Python Shape a raw record into a model-friendly result

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Notice what is gone: internal flags, numeric status codes, raw timestamps. Notice what was added: a count and a note that tells the model more exists.

Rule 5: fewer tools, chosen well

Every tool definition occupies context and competes for attention. With 5 to 10 well-separated tools, models choose accurately. With 50, mistakes rise and costs grow. Options when you have many:

  • Group them by task and give each specialist agent only its group (see multi-agent patterns).
  • Load tools on demand: first a small "discover tools" step, then expose only the relevant definitions.
  • Remove tools the agent never uses. Check your logs.

Rule 6: make dangerous tools hard to misuse

Put risk into the design: separate draft_email from send_email, make delete_* tools require a confirmation id obtained earlier, and default optional write arguments to the safest value. Safe execution is covered in Executing Tool Calls Safely.

A design checklist

Before shipping a tool, answer these:

  1. Is the name an obvious verb plus noun, unique across the set?
  2. Does the description say when to use it and what it does not do?
  3. Does every parameter have a type, a description and (where useful) an enum or example?
  4. Does the output stay small, readable and complete enough for the next step?
  5. Does failure return an actionable message?
  6. Could the tool do damage, and is that gated?

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which tool name is best?

    A verb plus noun that states the intent helps the model choose the right tool.
  2. 2. Why mention what a tool does NOT do in its description?

    Boundaries remove overlap between similar tools and cut wrong choices.
  3. 3. What is wrong with one tool that takes a free-form mode argument covering many actions?

    Focused tools with their own schemas are easier for the model to select and fill in correctly.
  4. 4. How should a tool return thousands of matching rows?

    Compact, relevant output saves context and keeps the model focused.

Summary

  • The model sees only name, description, schema and results, so design them like documentation for a reader who cannot ask questions.
  • Name by intent, describe when to use the tool and what it does not do.
  • Keep tools focused: avoid mode switches and field-by-field micro tools.
  • Shape outputs: readable fields, limits, counts and next-step notes.
  • Keep the tool set small, and separate risky actions from safe ones.

Next: Chain-of-Thought and Reasoning Models