Defining a tool

You register a tool from the Tools screen. Registering creates a draft and opens the editor, where you fill in the definition and the parameters. Saving edits that same draft in place, so there is one draft you keep refining rather than a new copy each time you save.

The definition

The definition tells the platform how to reach your endpoint and tells the model when to use it.

• Tool name. The function name the model calls, unique across your organization. Use letters, digits, and underscores, with no spaces or symbols, and don’t start with a digit. You set it once when you register the tool, and it cannot change afterward: a published project version pins a tool and serves it under this name, so renaming it would change what a frozen version calls. It is the tool’s equivalent of a catalog item’s component identifier.
• Display name. A human-readable label for your own use, like “Customer orders”. Optional, free text (any characters), and not unique, so two tools can share a label. You can change it any time. Renaming it does not change the tool name the model calls and does not affect the projects that pin the tool. If you leave it blank it defaults to the tool name.
• Description. Written for the model. It is how the model decides whether this tool answers the question in front of it, so describe what the tool returns and when it is the right one to call.
• Method and URL. The HTTP method and address the platform calls. Other transport options such as GraphQL or gRPC are not supported yet.
• Scope. Whether the tool is shared or per-user. Per-user tools carry the signed-in person’s identity (the subject) into each call, so they can return data specific to that person. Per-user tools must have a subject parameter that the portal fills in automatically from the session token. Shared tools take no subject parameter, because a shared tool’s response must not depend on who is asking. The signed assertion on every tool call still identifies the caller through its JSON Web Token sub claim, so your backend can still rate-limit or audit by caller. A shared tool just does not shape its response around them.
• When it runs. Regular tools run when the model chooses to call them. A tool marked to run at session start runs only once per conversation before the first model response; its result is given to the model as part of its initial context, so the model starts already knowing user facts that it can use to tailor the experience. Think about things such as the person’s subscription tier, recent orders, dietary restrictions, etc. You can provide the model with that context from the start, to save it a tool call later on. Session-start tools are expected to provide data that is unlikely to change over the course of the conversation.
• Required entitlement. An optional claim such as products:write that the user’s session token must carry for the tool to be available to the model. Leave blank to make it available to all users.

The parameters

Parameters are the inputs a tool receives and passes to your endpoint.

Almost every parameter is filled in by the model from the conversation: a search term, a product name, an order ID the person mentioned. Treat those values as untrusted, the same way you would treat anything a user typed. The one exception is the reserved subject, described next, which the platform fills for you.

The location tells the platform where the value goes in the request it builds to your endpoint:

• Query string — appended as ?name=value.
• URL path — substituted into a {placeholder} in your URL, so https://api.example.com/orders/{orderId} becomes /orders/12345.
• Request body — sent as a JSON field. Only methods that carry a body, POST, PUT, and PATCH, can take body parameters. An array or object rides in the body only, where it is a natural JSON value; a query string or a URL path has no single way to encode a list or an object, so those carry only scalars (a string, a number, or a boolean).

Arrays and their element type

An array parameter is a list, and it must say what its elements are: pick an element type of string, number, or boolean. The editor asks for it as soon as you set the type to array. This is not optional bookkeeping. The model needs to know it is filling a list of, say, product IDs rather than a single one, and the element type is how it is told. Elements are scalars, so an array of lists or an array of objects is not supported; if you need to send structured records, send them as separate parameters or wait for nested shapes, which are not modelled yet.

An array is sent in the request body, so an array parameter needs a method that carries one (POST, PUT, or PATCH).

The subject

The subject is a reserved parameter that names who a per-user tool is acting for. Unlike every other parameter, the platform fills the subject from the session token, and the model never sees it. Because the model can never supply the subject, a message crafted to say “fetch someone else’s orders” cannot change whose orders are fetched. Give it a location like any other parameter, often the URL path, as in /users/{subject}/orders. The subject is always a string, since it comes from the session identity, so the editor keeps its type fixed to string.

Tool editing rules

A few configurations are unsafe or malformed, and the dashboard refuses them.

• A per-user tool must have a subject. A per-user tool acts on someone’s private data, so it must always know, safely, who that someone is. You cannot save a per-user tool without a subject parameter, and because the subject can only come from the session, a prompt injection can never change it.
• The subject must be a string. The platform fills the subject from the session’s string identity, so a subject parameter is always typed as a string. The editor fixes this for you; a tool registered over MCP with a non-string subject is refused.
• A session-start tool may declare only the subject. A tool that runs at session start runs before the model responds, so it cannot fill any other parameters. The only parameter it may carry is the platform-filled subject.
• A body parameter needs a method that carries a body. GET and DELETE requests have no body, so a body parameter on one is refused. Use POST, PUT, or PATCH, or move the parameter to the query string.
• A path parameter needs its placeholder. A parameter placed in the URL path needs a matching {placeholder} in the URL, or its value would have nowhere to go. Add the {placeholder} to the URL and set the parameter’s location to the path in the same edit; Save validates them together.
• Each parameter needs a distinct name. Two parameters on the same tool cannot share a name. Rename one, or remove the duplicate.
• A type must fit its location. A path or query value must be a scalar (a string, a number, or a boolean). An array or object rides in the body only. The editor pins an array or object to the body for you.
• An array must have an element type. An array parameter says what its elements are, one of the scalar types. The editor asks for it when you choose the array type; a tool registered over MCP without one is refused. Only an array has an element type; setting one on any other type is refused.

Failure modes

• “A tool with this name already exists.” Names are unique across your organization, spanning both org-wide and project-specific tools. Pick another name, or edit the existing tool instead of registering a second one.
• “A parameter with this name already exists on this tool.” Two of the tool’s parameters share a name. Rename one, or remove the duplicate.
• “A per-user tool needs a subject parameter.” You set the tool’s scope to per-user without a subject parameter. Add one, or change the scope to shared if the tool does not actually depend on who is asking.
• “The subject parameter must be a string.” A subject parameter was typed as something other than a string, usually from a tool registered over MCP. Set its type to string; the portal fills its value from the session for you.
• “A tool that runs at session start may declare only the subject parameter.” You marked the tool to run at session start while it still has another parameter. Remove the others, or turn off “runs at session start” if the tool really does need model input.
• “A GET or DELETE request cannot carry a body parameter.” Move the parameter to the query string, or change the method to POST, PUT, or PATCH.
• “A path parameter needs a matching placeholder in the URL.” Add {name} to the URL for a path parameter named name, then save.
• “This type cannot ride in that location.” An array or object can only go in the request body, and the query string and URL path take only a scalar. Move the parameter to the body, or change the type.
• “An array parameter must say what its elements are.” You set a parameter’s type to array without an element type. Choose one of string, number, or boolean.
• “Only an array parameter has an element type.” A non-array parameter carries an element type, usually from a tool registered over MCP. Remove it, or change the type to array.

Versions and drafts

Tools are versioned, the same way catalog items are. While you are building a tool you are editing its draft, and saving refines that one draft in place. When you are happy with it, you publish the tool to freeze the draft into an immutable version that can never change again. To keep working after that, start a new draft: it begins as a copy of the published version, so you carry on from where you left off rather than from scratch, and publishing that draft mints the next version.

A published tool version is what a project version pins and freezes into what your project serves. A project version that is still a draft can pin a draft of a tool, so you can exercise an unreleased tool in your test environment before publishing. Publishing the project version publishes any draft tool it pins first, so a published project version only ever pins published tools. A tool can be shared across your whole organization, so publishing it, whether on its own or as part of publishing a project version, freezes it for every project that pins it.

Opening a published tool shows it read-only, every field and parameter fixed. To change anything, start a new draft.

Editing with an agent

You can manage tools using an agent. See the MCP server help for more information. An agent only ever writes to a draft. Publishing a tool freezes what your projects rely on, so it stays a person’s deliberate step and is never something an agent does.