Tools and scopes

Which agents appear as tools, how they are named, how the input schema is built, and the 25-tool cap.

A key decides which agents your assistant can see. Pick deliberately — a short, sharp tool list works far better than a long one.

The three scopes

Set this per key in Settings → API Keys. Each key row has an MCP tools control.

Scope	What appears	When to use it
My agents	Every live agent you published, newest first	The default. Best for testing your own work
Chosen agents	Only the agents you tick, in any combination	Best for real use: a small, curated toolbox
REST only	No tools at all. The key still works for the HTTP API	For server keys that should never appear in an assistant

Fewer tools, better results

Assistants degrade when a tool list gets long — they pick worse, and every listed tool eats context on every turn. Five to ten sharp tools beats twenty-five. Twenty-five is the hard cap; extra agents are dropped, not paged.

Tool names

An agent alice/product-description becomes the tool alice__product-description — the slash becomes a double underscore, because MCP tool names must be plain identifiers. The mapping is reversed on call, so the agent that runs is always the one named.

What the assistant reads

One entry from tools/list

{
  "name": "alice__product-description",
  "description": "Turns a product name into shop copy. (costs 3 credits)",
  "inputSchema": {
    "type": "object",
    "properties": {
      "prompt": {
        "type": "string",
        "description": "What is the product?. Example: a walnut desk lamp",
        "default": "a walnut desk lamp",
        "maxLength": 120
      },
      "tone": { "type": "string", "enum": ["warm", "technical", "playful"] }
    },
    "required": ["prompt"]
  }
}

The description is the creator's own, with the price appended — so the assistant knows what a call costs before it makes one.
The schema is built from the same published fields the detail endpoint returns. One contract, two renderings.
A free agent is labelled (free) rather than a credit count.

How field types map

amnt field	JSON Schema	Notes
`text`, `longtext`	`string`	`maxLength` carried through when the creator set one
`integer`	`integer`	`minimum` and `maximum` carried through
`boolean`	`boolean`
`enum`	`string` + `enum`	The allowed values are listed, so the assistant cannot invent one
`image`	`string`	An `https://` URL. There is no file upload over MCP
`ratio`	`string`	An aspect ratio such as `1:1` or `16:9`

What comes back from a call

Text and markdown arrive as one text block.
Images arrive as their URLs, one per block — assistants can open them, and they stay valid.
Structured results (JSON, chain receipts, verdicts) arrive as formatted JSON text.
Failures come back as an MCP error result with a readable message — and your credits already refunded. An empty balance says so, with a top-up link.

Changing what is exposed

Editing a key's scope takes effect on the next tools/list. Most clients only ask on connect, so restart the client (or toggle the server off and on) after a change.

Every tool call spends real money

An assistant can call a tool without asking you first, depending on your client settings. Keep the balance you are willing to lose in the account, give an assistant a REST-only key when in doubt, and prefer Chosen agents over exposing everything.