# Designing tools a model can use

By @omar · Published Nov 2, 2026 · From the roadmap [Building AI Agents: tools, memory and evals](https://ornix.io/u/omar/building-ai-agents)

A tool is a contract between a deterministic program and a model that reads English. Most agent failures I see are tool failures wearing a model's face: the schema was vague, the output was enormous, or the error said "failed". Design tools the way you would design an API for a smart colleague who cannot ask you questions.

## Fewer, bigger, clearer

The model has to pick the right tool from its description alone, so every tool you add makes the choice harder and the prompt longer. Two habits fix most of it.

**Match the task, not the database.** An agent that schedules meetings needs `schedule_meeting(attendees, duration, window)`, not `list_users`, `list_events` and `create_event` for the model to stitch together across six turns. Wrap the chain inside one tool and let deterministic code do the joining. Fewer steps means less cost, less latency and fewer chances to go wrong.

**Name the intent and namespace the family.** `search_docs` and `search_tickets` beat two tools both called `search`. Prefixes keep related tools grouped when a model sees forty of them.

```mermaid
%% ornix:id=tool0001
flowchart LR
    subgraph Bad["Low-level tools: 6 turns"]
        direction LR
        A1["list_users"] --> A2["list_events"] --> A3["find_gap (model does it)"] --> A4["create_event"]
    end
    subgraph Good["Task-level tool: 1 turn"]
        direction LR
        B1["schedule_meeting(attendees, duration, window)"]
    end
    Bad -.->|"compose in code"| Good
```

## What to put in the definition

- **A description written like onboarding.** What it does, when to use it, when not to, and what it returns. Two or three plain sentences beat a keyword list.
- **Unambiguous parameter names.** `user_email` beats `user`. Use enums for closed sets. Mark required fields. Add one example value in the parameter description.
- **Strict schemas.** Reject unknown fields and wrong types before you run anything. Some APIs can enforce your schema at generation time; validate again anyway.
- **Responses made for a reader.** Return names and short descriptions, not opaque UUIDs. Offer a `response_format` of `concise` or `detailed` so the model can ask for more.
- **Output limits with guidance.** If you truncate, say so and say how to get the rest: "Showing 20 of 340 results. Narrow with the `query` parameter or pass `cursor=20`."
- **Errors that teach.** "Invalid date" teaches nothing. "date must be YYYY-MM-DD, for example 2026-03-14; you sent 'next Friday'" fixes itself on the next turn.

## The hidden tax of schemas

Tool definitions ride along on every request. If one schema costs about 200 tokens and you expose 40 tools:

$$\text{overhead} = 40 \times 200 \times 20 \text{ steps} = 160{,}000 \text{ input tokens per run}$$

That is before the agent has read a single file. Cache the tool block, keep the order deterministic so the cache survives, and delete tools the task does not need. Some platforms can also load tool definitions on demand; a retrieval step over tool descriptions is the same idea as week 4 applied to your own tool list.

## In code

```python
SEARCH_TICKETS = {
    "name": "tickets_search",
    "description": (
        "Search support tickets by text and optional status. Use this to find prior "
        "reports before filing a new one. Returns up to 20 tickets, newest first. "
        "Do not use it to read a single ticket; use tickets_get for that."
    ),
    "input_schema": {
        "type": "object",
        "properties": {
            "query": {"type": "string", "description": "Keywords, for example 'login timeout'"},
            "status": {"type": "string", "enum": ["open", "closed", "any"]},
            "response_format": {"type": "string", "enum": ["concise", "detailed"]},
            "cursor": {"type": "integer", "description": "Offset from a previous truncated result"},
        },
        "required": ["query"],
        "additionalProperties": False,
    },
}


def tickets_search(query, status="any", response_format="concise", cursor=0):
    if status not in {"open", "closed", "any"}:
        raise ValueError("status must be one of open, closed, any")
    rows = db.search(query, status)
    page = rows[cursor : cursor + 20]
    lines = [f"#{r.id} [{r.status}] {r.title}" for r in page]
    if response_format == "detailed":
        lines = [f"{line} | {r.owner} | {r.summary[:200]}" for line, r in zip(lines, page)]
    footer = ""
    if len(rows) > cursor + 20:
        footer = f"Showing {cursor + 1}-{cursor + 20} of {len(rows)}. Pass cursor={cursor + 20} for more."
    return "\n".join(lines + [footer]) if page else "No tickets match. Try fewer or broader keywords."
```

Notice the empty-result message. "No tickets match" with a suggestion keeps the model moving; an empty string makes it guess.

## Evaluate tools like code

Write ten realistic tasks that need your tools. Run them. Read the transcripts, not just the scores: look for repeated calls with the same arguments, calls to the wrong tool, retries after a vague error. Each pattern is a fix in a description, a schema or a message. Change one thing, rerun, keep what helped. This is the loop from week 8 applied at the smallest scale.

## Common mistakes

- Wrapping every REST endpoint as its own tool. Your API is not the model's task.
- Returning raw JSON blobs with 40 fields when the model needs three.
- Overlapping tools whose descriptions do not say when to prefer each.
- Side effects hidden inside a tool called `get_something`. Name writes as writes.
- Letting a tool return unbounded text. One 200,000-character page can wipe out the context window.

## Check yourself

- Rewrite three chained low-level tools into one task-level tool. What logic moves into code?
- Give an error message for a bad date that lets the model fix its own call.
- Why does tool order matter for caching?
- What would you log to find out a tool description is misleading the model?

---

Roadmap: https://ornix.io/u/omar/building-ai-agents (Markdown: https://ornix.io/u/omar/building-ai-agents.md)

Canonical page: https://ornix.io/u/omar/building-ai-agents/designing-tools-a-model-can-use
