How to Define Tools for LLMs

Tools Are the Bridge Between LLM and Action

A tool is a function the LLM can call. The LLM needs to understand what each tool does to use it correctly.

The Anatomy of a Good Tool Definition

A tool needs three things:

1. Name: Short, clear, verb-based.

   • Good: web_search, fetch_page, calculate_total
   • Bad: search, get, do_thing

2. Description: Tells the LLM when to use this tool.

   • This is the most important part.
   • One or two sentences.
   • Say what it does and when to use it.

3. Parameters: What inputs the tool accepts.

   • Keep it to 3-5 key parameters.
   • Mark required vs. optional.
   • Include examples.

Write a Clear Description

Bad description:

"Search the web."

The LLM doesn't know when to use this. Is it for news? Stock prices? Definitions?

Good description:

"Search the internet for current information. Use this when the user asks about recent events, news, prices, or any topic that changes over time. The search returns a list of web pages with titles and snippets."

Now the LLM knows:

• What it does (search the internet)
• When to use it (recent information, news, prices)
• What it returns (list of pages)

Define Parameters

Bad parameter list:

{
  "query": "The search term"
}

The LLM doesn't know if query is required. Doesn't know if it's one word or a sentence.

Good parameter list:

{
  "query": {
    "type": "string",
    "description": "The search term. Example: 'latest AI breakthroughs 2026'. Can be multiple words.",
    "required": true
  },
  "num_results": {
    "type": "integer",
    "description": "How many results to return. Default: 5. Range: 1-10.",
    "required": false,
    "default": 5
  }
}

Now the LLM knows:

• query is required
• num_results is optional with a default
• What each parameter does
• What values are valid

Examples in Descriptions

Include examples. The LLM learns from examples.

With examples:

"Calculate the total price of items in a shopping cart. 
Example: cart = [{item: 'apple', price: 1.5}, {item: 'banana', price: 0.5}]
This tool returns {total: 2.0}"

Without examples:

"Calculate total price."

The first tells the LLM the exact format. The second leaves the LLM guessing.

Use JSON Schema

If you're using an API (OpenAI, Anthropic, etc.), use JSON schema to define tools.

{
  "name": "web_search",
  "description": "Search the internet for current information about any topic.",
  "parameters": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "The search query. Example: 'latest AI news 2026'"
      },
      "num_results": {
        "type": "integer",
        "description": "Number of results to return (1-10). Default: 5."
      }
    },
    "required": ["query"]
  }
}

Make Error Messages Helpful

When a tool fails, the error message should help the LLM recover.

Bad error:

"Error: Invalid format"

The LLM doesn't know what's wrong. It will guess and probably guess wrong.

Good error:

"Error: Parameter 'date' must be in YYYY-MM-DD format. You provided: '03-29-2026'. Please retry with format 2026-03-29."

The LLM sees the exact problem and how to fix it. It can retry immediately.

Test Your Tool Definition

Before using a tool in production:

1. Manual test: Call the tool yourself. Does it work?
2. Edge case test: What if the parameter is empty? Very long? Special characters?
3. LLM test: Give the LLM a task that should use the tool. Does the LLM call it correctly? If not, the description needs work.

Common Tool Mistakes

Mistake 1: Too many parameters Each parameter is a chance for the LLM to mess up. Keep it to 3-5.

Mistake 2: Vague names Names like get or run don't tell the LLM what the tool does. Use specific verbs: fetch, search, validate.

Mistake 3: No examples Examples are the fastest way to teach the LLM. Always include them in descriptions.

Mistake 4: No error handling If the tool fails, the error message should help the LLM recover. Otherwise, the LLM will loop or give up.

Tool Design Checklist

• Name is specific and verb-based
• Description says when to use this tool
• Description includes an example
• Parameters are minimal (3-5 max)
• Required parameters are marked
• Error messages are helpful and specific
• Tool is tested manually
• LLM can call the tool correctly on first try