Configure the service for the admin. Pick one `action`; only the fields relevant to that action are needed (supplying extras is harmless, but a required field must be present).
- `setup_telegram_bot` — persist a Telegram bot token so the service can receive messages through the bot and send back replies. Pass the `token` from BotFather (the `NNN:AAA...` string). The token is validated live via getMe and saved, and the Telegram listener hot-reloads it immediately — no restart is required. Next step: use `bind_telegram` to bind the admin's Telegram account — their `@username` or their numeric id — then ask the admin to send `/start` to the bot.
- `bind_telegram` — bind the admin's own Telegram account so incoming bot messages are routed to them. Pass `handle` as the account's `@username` (with or without the leading `@`) or its numeric Telegram id — the admin supplies the value by hand, and nothing is looked up. A number is the binding's address from the start; a nickname gains its address when its owner writes (Telegram itself forbids the bot to open the conversation until then).
- Refused: a value already bound to another account; Telegram's own service identities (the anonymous group administrator, a channel-attributed message, an auto-forwarded channel post) under either spelling; the reserved handle "unknown"; and an account that already holds a Telegram binding. A bot's handle is stored like any other nickname, but it never authorizes its bot — a bot is never a person.
- An account holds at most one Telegram binding: remove the existing one on the desktop Settings → Users page, then attach the new one. Switching kinds is remove-then-attach — there is no replace action here, and this tool offers no removal.
- `add_workspace` — register a workspace (a software project directory) and switch the admin's active workspace to it. Pass a short unique `name` (used in ticket ids and the GUI) and the absolute `path` to the software project directory. Workspaces are for software projects only; material that is not a software project — documents, notes, research files — goes in your personal workspace, not in a workspace.
- `add_user` — create a guest account and bind them to Telegram. Pass the user's display `name` and their Telegram account as `telegram`, under the same rules as `bind_telegram` above.
- The `name` is also the name of the account's personal workspace folder, so it must be one every platform the service runs on can create: no path separators, no characters a folder name may not hold, nothing ending in a dot or a space, no reserved device name, and not too long — the `name` parameter carries the exact rule. The name is used verbatim, never adjusted, so a refused name is a question back to the admin rather than a name to reshape yourself.
- Refused: the admin's own name (the name is the admin marker, so only guest accounts can be created); a name that cannot be the folder of a new account (the refusal names the exact reason); a name that already exists with a Telegram binding, saying what to remove first; the reserved "unknown"; and the service identities. A name holding no binding is completed instead — a half-finished earlier run.
- `setup_web_search` — register a web-search backend so agents can use `web_search`. Pass the `provider` — `firecrawl` or `exa` — and its API `key`. The provider and its matching key are persisted. Once registered, agents that support web search (e.g. the Assistant) can call `web_search` immediately.
Custom tools are authored as script files in the `shared` folder of the admin's personal workspace; a tool is referenced everywhere by its file name without the extension, and it becomes available to another user only by being granted to them.
- `grant_tool` — grant one custom tool to a user. Pass the user's name as `user` and the tool's name as `tool` (the file name without its extension of a script in the `shared` folder of the admin's personal workspace). Granting a tool the user already has is a no-op.
- `revoke_tool` — revoke one custom tool from a user. Pass `user` and `tool` as for `grant_tool`. Revoking a grant the user does not have is a no-op.
- `list_grants` — show the custom-tool grants as recorded. Pass `user` to list that user's grants, or omit it to list every user that has any. Grants are listed even when the granted tool's file no longer exists in `shared`, so the list reflects what was recorded, not what currently works.