mediumAI Engineering

How do you design good tool definitions for an LLM?

Q: How do you design good tool definitions for an LLM?

**TL;DR.** The model is your API consumer: **verb-object names**, descriptions that say **when to use (and not use)** the tool, **few well-typed parameters** (enums over free strings), and results/errors the model can act on. **Fewer, higher-level tools** beat many granular ones — wrong-tool selection is the top tool-use failure. ✘ hard to use name: doStuff desc: helper for data params: input (string) <rect class='d-box-accent' x='238' y='24' width='206' height='104' rx=

382 views

Understand the problem

Tool ergonomics: names, descriptions, parameter design and error messages the model can act on.

tool-designfunction-callingschemasagents

Attempt it yourself

Sketch your approach before reading the solution — that's what interviews test.

Stuck? AI Nudge Available

Get a conceptual hint to guide your logic without spoiling the final implementation.

Study the solution

The solution is waiting

Give it an honest attempt first — then compare your thinking with the full walkthrough.

Read the code

A well-shaped tool definition

{
  name: "search_orders",
  description:
    "Search a customer's orders by status and date range. Use for questions " +
    "about order history or delivery status. NOT for refunds (create_refund) " +
    "or catalog items (search_products). Max range: 90 days.",
  input_schema: {
    type: "object",
    properties: {
      customer_id: { type: "string", description: "UUID from the session context" },
      status: { type: "string", enum: ["open", "shipped", "delivered", "returned"] },
      from_date: { type: "string", format: "date" },
      to_date:   { type: "string", format: "date" },
    },
    required: ["customer_id"],
  },
}

Join the discussion

Discussion (0)

No responses yet. Be the first to share what you think.

What is reranking and why add it after retrieval?

What is LLM-as-judge and what are its known biases?