Designing tools an LLM can use correctly
When you give a model a tool, you are publishing an API. The consumer is an unusual one, though. It never reads your source, never opens the documentation site, and never asks a colleague what a parameter means. All it gets is a name, a paragraph of description and a JSON Schema, and from those it has to decide whether to call the tool, when, and with what.
Everything I believe about API design still applies. The difference is that the margin for ambiguity is gone: a developer who misreads a parameter finds out in code review, a model finds out in production, if at all.
The description is the whole contract
With a human consumer, the signature is the start of the contract, and documentation, examples and the type system fill in the rest. With a model, the tool definition is everything. Whatever you know about the tool but did not write down, the model does not know.
That changes what "good enough" means. search(query) is fine in a codebase where you can jump to the
implementation. For a model it leaves every question open: search what, in which scope, how many results,
in what order, and what to do when there are too many.
A useful test: read the tool list exactly as the model receives it, with nothing else open. If you would not know which tool to pick or what to pass, the model won't either. It will just guess with more confidence.
One job per tool
A tool that does several things depending on a mode or action parameter is hard to use well.
manage_issue(action, ...) with create, close, comment and delete hides four contracts behind one
name, and the parameters that make sense for one action are noise, or traps, for the others. A schema can
say "body is required when action is comment", but not in a way every model reliably follows.
Split it: create_issue, close_issue, add_comment. Each gets a description that covers one behaviour,
parameters that are all relevant, and its own permissions. That last part matters more than it looks.
Once delete_issue is its own tool, you can leave it out, or put it behind an approval, without touching
the others.
Names and descriptions are for the model
Names should say what happens: get_invoice, list_invoices, void_invoice. Not internal jargon, not
abbreviations, not the name of the service class behind it. If two tools sound alike, the model will mix
them up; rename one or merge them.
The description should answer what a careful caller would ask:
- What does it do, and what does it not do?
- When should it be used instead of a similar tool?
- What does it return, and how much of it?
- Does it change anything?
Keep it short and factual. A description is not the place for every edge case; it is the place for the
two or three facts that decide whether this is the right call. If a parameter has a format, say so with an
example: "ISO 8601 date, e.g. 2026-10-11" is worth more than "the date".
Constrain the parameters
Every free-form string is an invitation to guess. If a parameter has five valid values, make it an enum.
If a number has a range, state the range and enforce it. If a string is an identifier, say where it comes
from ("the id returned by list_invoices"), so the model fetches one instead of inventing one.
In .NET, Microsoft.Extensions.AI derives the schema from the method signature, so the constraints live
in ordinary C#:
using System.ComponentModel;
using Microsoft.Extensions.AI;
public enum IssueState { Open, Closed, All }
public sealed record IssueSummary(int Number, string Title, IssueState State);
public sealed record IssuePage(IReadOnlyList<IssueSummary> Items, string? NextCursor);
public sealed class IssueTools(IIssueStore store)
{
[Description("Searches issues in the current repository by text in the title or body. " +
"Returns summaries only, newest first. Use get_issue to read one in full.")]
public Task<IssuePage> SearchIssuesAsync(
[Description("Words to look for, e.g. \"login timeout\".")] string query,
[Description("Which issues to include.")] IssueState state = IssueState.Open,
[Description("How many results to return, 1 to 50.")] int limit = 20,
[Description("The nextCursor of a previous result. Omit for the first page.")] string? cursor = null,
CancellationToken cancellationToken = default)
=> store.SearchAsync(query, state, Math.Clamp(limit, 1, 50), cursor, cancellationToken);
}
var tools = new IssueTools(store);
var options = new ChatOptions
{
Tools = [AIFunctionFactory.Create(tools.SearchIssuesAsync, name: "search_issues")],
};
The [Description] on the method becomes the tool's description, and the ones on the parameters describe
the parameters. The enum reaches the model as a list of allowed strings, because the library's default
serializer options write enums as strings. Parameters with defaults are optional, and the
CancellationToken is bound by the library and left out of the schema. To see exactly what the model
will see, print the function's JsonSchema.
Note the Math.Clamp. A description is a request, not a guarantee. The schema narrows what the model is
likely to send; your code still has to check what it actually sent. That is input validation, and it
belongs in the tool, the same as at any other API boundary.
Errors that say what to do next
When a tool fails, the error is all the model has to decide its next step. "Error: 404" leads to a retry with the same arguments, or an apology to the user. "No issue #4121 in this repository. Use search_issues to find the right number." leads to a correct second call.
Write errors the way you would want them if you could not see the code: what was wrong, which value caused it, and what would work instead. Keep "your arguments were wrong" apart from "something on our side failed" and "you are not allowed to do this", because the right reactions differ: fix and retry, wait or give up, stop.
There is a detail in Microsoft.Extensions.AI worth knowing. When a function throws,
FunctionInvokingChatClient sends the model a generic error by default; the exception message only
reaches it if you set IncludeDetailedErrors, and the documentation warns that this can expose internal
details. For expected failures I would rather return a result that carries the guidance, and keep
exceptions for what is really exceptional.
Side effects: idempotency and dry runs
Models repeat calls. A response gets cut off, a timeout fires, a loop runs one step too many, and the same call arrives twice. For a read, that costs tokens. For "send the invoice", it costs a second invoice.
Tools with side effects should be safe to call twice. The ways to get there are the same as for HTTP: accept an idempotency key, or make the operation naturally idempotent. Set a state rather than toggle it; "make sure the label exists" rather than "add a label".
For operations that are expensive or hard to undo, a dryRun parameter that returns what would happen
is cheap to build and very useful. The model can show the plan, a person can read it, and the real call
comes after. Irreversible actions need more than a parameter, though: they need an approval step the
model can't skip, which I wrote about in
Prompt injection is an input problem.
Protect the context window
Everything a tool returns lands in the model's context, which is finite and shared with everything else the model needs to keep in view. A tool that returns ten thousand rows is not helpful. It pushes the actual task out of sight.
So results should be bounded by default:
- Paginate. Return a page and a cursor, as in the example above, and default to a small page.
- Summary first, detail on demand. A list tool returns ids and titles; a get tool returns the full record.
- Truncate honestly. If you cut a long text, say so in the result: how much was left out and how to get the rest. A silently truncated result is worse than an error, because the model treats it as complete.
- Leave out what the model can't use. Internal keys, audit columns and nested objects nobody asked for are just tokens.
Few tools beat many
Tool definitions are sent with every request, and every extra tool is one more option to choose wrongly. Twenty tools with overlapping descriptions are harder to use than six that are clearly different.
This is the hardest rule to keep, because each tool on its own looks reasonable. The question is not "could this be useful?" but "would the model pick the right one of these, every time?". If two tools are nearly always called together, merge them. If a tool is rarely needed, leave it out of the default set and add it only where it is used. And if a tool is dangerous, not offering it is the strongest guarantee you have that it won't be called.
None of this is new. It is ordinary API design without the safety net of a human reader: clear names, narrow contracts, validated input, useful errors, bounded output. The model reads every word you give it and nothing else, so it is worth choosing those words carefully.
