Everything so far has been about what the model says. A tool is what lets it do something: check whether a name is taken, send an email, create a record. The moment you add one, the model stops being a text generator attached to your product and becomes a caller inside it.
Which means a tool is an API endpoint whose consumer cannot read your documentation, will never see your error page, and decides entirely on its own whether to call you at all. Everything peculiar about designing tools follows from that.
The Description Is the API
Your integration guide, your parameter docs, your "when to use this" note — all of it collapses into one string.
#[Description('Check if a site URL is available before creating a site.
Always call this before CreateSiteTool to avoid using taken URLs.')]
class CheckUrlAvailabilityTool extends Tool
Short, because the tool is simple, and it still does two jobs: says what the tool does, and says when to call it relative to another tool.
For a subtler tool the description carries much more, including things you would never put in documentation for a human:
#[Description('Offer the user a short list of ready-made answers to pick from
instead of making them compose one. The client renders these as tappable cards,
so this is how you ask for services, opening hours, or any other detail with a
small set of likely answers. YOU generate the options from what you already know
about the business — "Japanese restaurant" should yield Dine-in, Takeout,
Delivery, Catering, not a generic list. Use multi=true when several answers can
be true at once (services), multi=false when only one can (hours). The user\'s
pick comes back as their next message, so wait for it before moving on. Do not
also list the options in your own text; the cards already show them.')]
Four distinct jobs in one paragraph:
- What it does — offers ready-made answers.
- What the user will see — tappable cards, which the model cannot know and which changes how it should write.
- How to use it well — generate options specific to this business, with a worked example. Without that, you get Option A / Option B / Other.
- What not to do afterwards — don't repeat the options as text, and wait for the reply.
That last category is the one people miss. A tool description is not only a contract, it is behavioural guidance for the turn after the call. If your interface renders something, tell the model not to duplicate it in prose, or it will.