Customizing tools
An agent chooses a tool from its name and description, and fills it in from its input schema. Nothing else about your API reaches it before the call. So those are what you'll want to tune, and you can change them for agents without touching your spec, your docs or your SDKs.
Select a tool in MCP Studio and open Customize for agents. Changes are drafts until you publish.
What you can change
Tool nametextWhat agents call it: letters, digits, _ and -, up to 64 characters, which fits MCP's name rules.
DescriptiontextWhat an agent reads, up to 4,000 characters. Keep it short: a tool list is read on every turn. Empty keeps your docs' text.
Inputsper fieldWhether the agent fills each field, never sees it, or has it fixed. See below.
TagslistUp to 10, comma separated, each lowercase letters, digits and -, up to 32 characters. Tool groups take everything carrying one of their tags.
The tool keeps your settings if you rename the endpoint, or rename the method in SDK Studio.
Inputs
Each input has three states.
| State | What it means | Use it for |
|---|---|---|
| Agent fills it | The agent sees the field and supplies it. You can rewrite what it reads about the field | The default |
| Hidden | Left out of the tool, so your API gets no value for it. Optional fields only | Rarely used filters that clutter the schema |
| Pinned value | Sent on every call, and the agent never sees it | Fixing an account, a region or an API version |
A pinned value can't be overridden by the agent, because the server sends it after the agent's own arguments. It's applied on the hosted server, and built into your packages.
Pins are published with your tool list and built into packages you ship. Don't pin a credential. For credentials, use sign-in or installations.
Example
Say POST /invoices takes account_id, currency and customer, and this server only serves one account.
| Field | State | Why |
|---|---|---|
account_id | Pinned to acct_123 | The agent shouldn't be able to choose an account |
currency | Agent fills it, with the description "ISO 4217 code, such as USD" | The default description didn't say which format |
customer | Agent fills it | |
internal_ref | Hidden | Agents have no use for it |
Writing a good description
Agents pick the wrong tool far more often because of a vague description than because of a missing feature.
Say what it does and when to choose it over a similar tool.
Put the most important thing first, since some clients cut descriptions short.
Name what it returns, if it isn't obvious.
Keep it to plain text. Agents don't need formatting, and each word costs context on every turn.
Bad: POST /invoices
Bad: Creates an invoice.
Good: Create a draft invoice for a customer. Use send_invoice afterwards to
email it. Returns the invoice with its ID.The quality score checks these for you, and can suggest a rewrite.
What agents see
What agents see shows the tool as an agent will receive it, with your changes applied. To see whether agents really choose and fill it correctly, add it to a test run.
Marking how a tool behaves
Two more settings on the tool tell clients what it does.
| Setting | What it does |
|---|---|
| When an agent calls it | Runs on its own, asks first, or off. See permissions and limits |
| Only adds data | Tells clients this write never deletes or overwrites anything |
Not everything needs customizing
Customizing a tool leaves your docs as they are. If a description is wrong for humans as well, fix it in API Studio instead, so everything improves at once.