AI Tool Suggestions: What a Model Can (and Can't) Change About Your MCP Tools

A model can now propose better names and descriptions for the tools on your MCP server. Here's exactly what it's allowed to change, what the server refuses, and how adopting works.

Nobody writes an OpenAPI spec for an AI agent. The operationIds come out of a code generator, so the tool is called get_v2_orders_byId. The description is whatever one line the developer typed into the annotation three years ago, if they typed anything. The required parameter has a name and a type and no hint of what a good value looks like. That's fine for a person with the reference docs open in another tab. An agent gets the tool list and nothing else.

Last time I said the fix is to write the descriptions for the model yourself. That's still true, and for a twelve-tool server it's a pleasant half hour. For a hundred and eighty tools it's a weekend you won't spend. So the platform now has a button called Suggest with AI that hands the job to a model, and this post is about the part I care about most: the fence around what that model is allowed to do.

What the model is handed

A run doesn't send the model your API. It sends a digest of your tool definitions: each tool's name, description, HTTP method and path, the names and types of its inputs (with whether each one is required, fills a path placeholder, or carries a file), and the top-level property names of the response when the shape is known. It also gets the provider's name and base URL and the full list of tool names already on the server, so anything it invents can't collide with a tool it isn't looking at.

That's the whole input. The model never calls your API, never sees a credential, and never sees a live response. Big servers go through in batches of forty tools, and a server with more than three hundred endpoint-backed tools is refused outright rather than fed through a prompt too long to be reliable. The run happens in the background, and a large API takes several minutes, so you can close the dialog and come back.

What it's allowed to propose

The instructions the model works from are specific, because "make these better" produces mush. For each tool it can propose a new name in snake_case verb-object form (search_opportunities, not getOpportunitiesUsingGET_1), with the controller prefixes, version suffixes, and _1 disambiguators stripped. It can rewrite the description for an agent deciding whether to call the tool: what the call returns, when a sibling tool is the better choice, what a good value for the key parameters looks like, and how pagination behaves. It can improve an existing input's description, flip its required flag, or add an enum of allowed values. It can drop an optional input from an over-parameterized endpoint. It can hide a tool with a one-sentence reason, mark a POST that's really a search as safe, set a sort order so the useful tools land at the top of the list, and point at the data or results envelope that wraps the useful part of a response.

Every proposal comes with a rationale, and the run also produces a summary paragraph of what it changed and why. Those are for you. Nothing in that list touches the wire.

What it can't do, no matter what it asks for

This is the part that makes the feature usable. One MCP tool is exactly one upstream HTTP call, and the wrap maps input property names by name onto path placeholders, query parameters, and body fields. So a model that "helpfully" adds a limit parameter the API doesn't have, or renames q to query because it reads better, has produced an input that maps to nothing. The call would go out with the argument silently dropped.

The server refuses those, and it refuses them regardless of what the model wrote. A suggestion can't add an input, rename one, or change a tool's method, path, request encoding, or file parameters. It can't drop an input that's required, that fills a path placeholder, or that carries a file. It can't mark a PUT, PATCH, or DELETE as safe. It can't return an entry for a tool that wasn't in its batch, and if it returns two entries for one tool, the second is ignored. A proposed name that's already taken gets a suffix instead of stealing the name. If a run would hide every tool on the server, the hides are reverted to keep, because a server with nothing to call looks broken.

A malformed suggestion doesn't sink the batch, either. That one tool falls back to "keep" with a warning, the rest of the batch goes through, and the run records every refusal so you can see what the model tried. I'd rather the model waste a suggestion than get one past the validator.

Adopting suggestions, and undoing them

Nothing is applied when the run finishes. You get a comparison: the tool as it is today next to the tool as the model would have it, changed fields highlighted, the rationale beside each row. Tools it would leave alone collapse under a summary line so you're reading the changes, not the whole server. You tick the ones you want and click Adopt selected.

An adopted tool gets marked as AI-suggested, and that marker does real work. Refresh Tools re-derives the plain discovered tools from your spec and leaves adopted ones alone, so a spec update doesn't wipe the descriptions you approved last month. The reverse guard is there too: if you refreshed or hand-edited a tool after the run so that its inputs changed, its suggestion is skipped as stale rather than applied to a tool it wasn't reasoned about. Run it again and you get a fresh proposal.

Every adopted tool also has a Revert button. Reverting puts back the spec's name, description, and schemas, drops any response extraction path the suggestion added, and returns the tool to plain discovered status. It deliberately keeps the tool's current enabled state, so a tool you hid on the model's advice stays hidden until you switch it back on yourself. The visibility decision was yours, and the revert doesn't second-guess it.

When it's worth a run

Suggestions are on Pro and above, with a monthly allowance of runs. A run is consumed when it's queued, not when you adopt, because the model spends its tokens either way. So it pays to know when the button earns its keep.

A generated spec is the obvious case: code-generated operationIds with UsingGET on the end of every one, or an API that ships v1 through v4 side by side and describes each endpoint with its method name and some spaces. That's where a model turns unreadable into usable in one pass. A hand-written spec with real summaries is the opposite case. If your API team already wrote "Returns line items, totals, and fulfillment status for a single order," the model will mostly agree with them, and you've spent a run to learn that.

Somewhere in between sits the spec that's fine for developers and merely thin for agents. Those are worth one run, followed by ten minutes of ticking boxes. Adopt the descriptions, skim the renames, be skeptical of the hides, and check the safety flag on anything that's a POST.

The model reads your tool definitions, and only your tool definitions, then proposes changes inside a fence the server enforces. Everything past that fence is your call. The MCP servers documentation has the button-by-button walkthrough and the messages you might see. If you have a server whose tool list makes an agent guess, start free, open its tools, and see what a model would rename first.