Tool Studio
Tool Studio is where you edit an individual tool — its name, description, parameters and behaviour hints. If the Tool Catalog is the list, Studio is the editor.
This page deserves more attention than it first appears. A tool's name and description are what the AI reads to decide whether to use it, so the wording here directly determines whether the AI behaves sensibly.
Find it at Dashboard → Tool Studio.
What you can edit
| Field | What it controls |
|---|---|
| Name | What the AI sees. The primary signal for when to use this tool. |
| Description | How the AI decides whether this tool fits the task. |
| Internal Name | The identifier used internally; not shown to the AI. |
| Operation ID | The stable key from your OpenAPI spec. Survives re-imports. |
| HTTP Method / Path | The upstream call this tool makes. |
| Schema | Parameters, types, and which are required. |
| Hints | Behaviour flags — see below. |
Writing names and descriptions
This is the highest-leverage thing you can do, and generated defaults are rarely good enough — OpenAPI summaries are written for developers reading docs, not for a model choosing between forty tools.
Name it after the task, not the endpoint.
| Weak | Better |
|---|---|
getCustomerById | look_up_customer |
postInvoice | create_invoice |
patchUserV2 | update_user_details |
Say when to use it — and when not to. Descriptions that draw boundaries prevent more mistakes than descriptions that just restate the name:
Look up a single customer by their ID. Returns their contact details, account status and plan. Use
search_customersinstead if you only have a name or email.
Describe what parameters mean, not just their type. property_id is opaque; "the numeric ID of a property the user manages, from list_properties" tells the AI where to get one.
Be explicit about destructive behaviour. If a tool deletes or charges, say so plainly in the description. The AI will factor it in.
Behaviour hints
Hints tell the AI client about a tool's nature. They're advisory metadata, not enforcement:
| Hint | Meaning |
|---|---|
| Destructive | Modifies or removes data in a way that isn't easily undone |
| Idempotent | Calling it twice has the same effect as once |
| Does not modify state | Read-only |
| Open world | May access external systems beyond your API |
Marking a tool Destructive doesn't prevent it being called — it lets the client surface a confirmation. Real protection comes from role access or not publishing the tool at all.
Preview request
Preview request shows the exact HTTP call a tool would make for a given set of arguments, without sending it.
Use it whenever a tool "works but returns nothing useful" — it's usually a parameter mapped to the wrong place, which is immediately obvious in the preview and invisible otherwise. Arguments must be valid JSON.
Versions
Every change creates a new version rather than mutating the live one.
| Action | Effect |
|---|---|
| Save | Writes a new draft version |
| Make active | Promotes a version to the one being served |
| Rollback | Returns to an earlier version |
Saving alone doesn't change what AI clients call. That's deliberate — you can iterate on a tool that's live without disturbing it, then promote when ready.
A practical workflow
- Upload the spec → drafts are generated.
- Open each tool you intend to publish and rewrite the name and description properly.
- Check the schema — mark truly-required parameters as required, and describe the opaque ones.
- Set hints, especially Destructive.
- Preview request with realistic arguments.
- Save, then Make active.
- Publish in the Tool Catalog and grant role access.
- Test from a real AI client — the only way to know if your descriptions actually work.
If the AI picks the wrong tool, calls one it shouldn't, or asks the user for a parameter it could have derived — that's almost always a description problem, not a platform problem. Rewrite the description before looking anywhere else.
Enum injection
A parameter can be constrained at runtime to only the resource IDs the current user is allowed to touch — so the AI can't construct an out-of-scope call in the first place. This works on all three identity models.
Set up per tool and role from the role's inject keys. See Enum Injection.
Where to go next
- Tool Catalog — publishing
- Assigning Tool Access — who can call what
- Writing OpenAPI Specs — getting the generated drafts right up front