Tool Design

Tool Design

Overview

A tool is a contract between a deterministic system and a non-deterministic caller. A normal API assumes a rational developer who reads the docs, handles error codes, and knows which endpoint to call. An agent breaks all of those assumptions: it may pick the wrong tool because two names look alike, pass malformed parameters despite a clear schema, pull back a dataset that blows its own context window, or misread a cryptic error and retry the same failing call.

So tools for agents are designed defensively: clear enough that the agent can't easily misuse them, informative enough to steer the agent toward a better next move, and lean enough to spend the context window carefully.

The payoff: agent and human ergonomics align. A tool that an agent uses well is almost always a tool a human finds intuitive too. Designing for a non-deterministic caller just produces a better API.

None of this is framework- or language-specific. The same five principles apply whether the tool is an MCP server tool, a LangChain/LangGraph tool, an OpenAI/Anthropic function-calling definition, or a plain function exposed to a model — and whether it's written in TypeScript, Python, or anything else. What varies is the syntax of name / description / parameters / returns; the design thinking does not. See references/examples.md for the same tool proven across languages and surfaces.

The Five Principles

Apply these when writing or reviewing any tool. The deep dive with worked schema shapes is in references/principles.md.

1. Strategic selection

Build tools around user workflows, not database schemas or API endpoints. Don't wrap every endpoint as its own tool — the agent then struggles to choose among near-duplicates and you spend prompt budget documenting all of them. Consolidate related operations into one well-parameterized tool when it maps to how a user thinks about the task.

Prefer one get_expenses(start_date, end_date, category?, ...) over get_expense_by_id + list_all_expenses + filter_by_category + search_expenses.

Ask: does this map to how users think about the task? Would merging it with a sibling reduce the number of decisions the agent has to make?

But don't consolidate on data alone. Two tools touching the same table can still be two workflows. A bounded row listing ("show me my Dining transactions in June") and an aggregate query ("how much did I spend on Dining last quarter") look like prime merge candidates — same data, adjacent phrasing. Merging them into one tool with a mode flag satisfies the principle's letter and makes selection harder: the agent now reasons about which mode on every call, and the two have genuinely different return shapes and safety properties. Consolidate operations that share a workflow, not operations that merely share data.

2. Clear naming and namespacing

Names and descriptions decide whether the agent picks the right tool. Use descriptive, action-oriented names — never bare search, fetch, process. When an agent has tools from several sources, collisions cause mis-selection, so namespace with a consistent prefix — by service (slack_search, notion_search) or resource (expenses_get, expenses_summarize).

Check whether your surface prefixes for you: many MCP clients auto-prepend the server name, so hardcoding the prefix too yields agentailor_agentailor_search. Let the surface prefix, or prefix yourself — not both. See references/principles.md.

A description should answer three questions:

• What does it do? (1–2 sentences)
• When should the agent reach for it? (a few example queries)
• How is it used? (key parameters, constraints, what it returns)

Every parameter gets a description with its format, an example, and constraints — "Start date in ISO format (YYYY-MM-DD). Example: '2025-01-01'", not start_date: string.

3. Meaningful context return

Return information the agent can reason about directly, not identifiers it must resolve with another call. Include the expense's description and category, not just a UUID. Attach lightweight metadata (totals, the date range, which filters were applied) so the agent knows what it's looking at.

Make verbosity configurable: a response_format of concise (essential fields) vs detailed (full metadata) lets the agent trade detail against tokens per task. When a result feeds the next tool call, return the exact value that next call needs (e.g. the canonical URL/id to pass along), so the agent can chain without a lookup.

4. Token efficiency

Every token in a tool response is a token unavailable for reasoning. Give collection-returning tools sensible default limits (e.g. 50) plus pagination and filter parameters. When you truncate, say so and say how to continue — "Found 847, returning 50; narrow the date range or add a category filter" beats silently dropping rows. Validate inputs that would produce huge responses (e.g. reject a >1-year range) before running the query.

5. Descriptions are prompts

The tool's name, description, and parameter docs are prompt engineering — every word shapes how the agent uses the tool. Be explicit about when to use it, required vs optional parameters, and the shape of the output. Refine this text iteratively against real agent behavior: unclear wording is the most common reason an agent mis-selects or mis-calls a tool.

Validation Checklist

When writing or reviewing a tool, confirm:

• Strategic — consolidates a real workflow; not one-tool-per-endpoint, not overlapping near-duplicates.
• Named — descriptive, action-oriented, namespaced to avoid collisions; not a bare verb.
• Described — the description says what / when / how, with example queries.
• Parameterized — every parameter documents format + example + constraints; required vs optional is intentional; optionals have sensible defaults.
• Contextual — returns human-readable info and metadata, not just IDs; verbosity is configurable when responses can be large.
• Efficient — default limits, pagination/filters, truncation messages that guide the next query; guards against responses that would blow the context window.
• Helpful on failure — errors explain what went wrong and what to do next, with an example; no cryptic codes.
• Tested — the checklist items above that are mechanically checkable have deterministic tests (unit at minimum, integration where real I/O decides correctness); the behaviors only a model can exercise have evals (or are knowingly deferred).