# Tools and scopes Devii's capabilities are a declarative **catalog** of actions. Each action declares a `handler` that routes it, and an auth scope. See also [Devii internals](/docs/devii-internals.html) and [Data and persistence](/docs/devii-data.html). ## How tools are declared `actions/spec.py` defines `Action` (name, method, path, params, `requires_auth`, `requires_admin`, `handler`) and `Catalog`. `registry.py` unions the per-category tuples into `CATALOG`. `tool_schema()` projects each action into the JSON tool schema sent to the model; `tool_schemas_for(authenticated, is_admin)` is the **scope filter** - guests only receive actions where `requires_auth` is false, and `requires_admin` actions are offered only to administrators, so account-operating and admin-only tools are not even presented to a guest or member. ## Handler categories (scopes) | Handler | Scope | What it does | |---|---|---| | `http` | platform API | The bulk of the catalog (`actions/catalog.py`): posts, comments, votes, follows, messages, projects, gists, bookmarks, polls, notifications, admin endpoints, and the admin-only `site_analytics` (GET `/admin/analytics`). Sent over the `PlatformClient` with the user's auth. | | `login` / `logout` / `status` | session | Authenticate or report auth state. | | `agentic` | reasoning | `plan`, `reflect`, `recall`, `forget_lessons`, `verify`, `delegate`. | | `task` | scheduling | Create/list/update/delete autonomous tasks (once / interval / cron). | | `docs` | knowledge | `search_docs` over this documentation. | | `fetch` | web | `fetch_url` with an SSRF guard and size caps. | | `rsearch` | external web | `rsearch` (web/image search), `rsearch_answer` (web-grounded AI answer), `rsearch_chat` (direct AI chat), `rsearch_describe_image` (vision). They call an external public service, not this platform, and are gated by the `devii_rsearch_enabled` config (URL configurable via `devii_rsearch_url`). | | `cost` | accounting | `usage_quota` reports the owner's 24h quota usage as a percentage (no money, available to everyone); `cost_stats` reports the full USD cost breakdown and is `requires_admin` - administrators only. | | `chunks` | large results | `read_more` paginates any oversized tool result. | | `avatar` | on-screen | The `avatar_*` tools (md-clippy character) - web only. | | `client` | the browser | `get_page_context`, `run_js`, `highlight_element`, `clear_highlights`, `show_toast`, `scroll_to_element`, `navigate_to`, `reload_page` - run in the user's own browser; `run_js` is gated by the `devii_allow_eval` config. | ## Auth scope `requires_auth` defaults to true. The dispatcher refuses an auth-required action when the platform client is not authenticated. `requires_admin` actions are gated twice: the model never receives their schema unless the session owner is an administrator, and the dispatcher independently rejects any `requires_admin` action for a non-admin owner. The owner's admin status is resolved server-side from the session/API-key user role (`is_admin(user)`), never from client input. Beyond this, **role** enforcement for platform data is also done by the platform endpoints themselves (for example the admin endpoints return 403 to non-admins). The local handlers (`avatar`, `client`, `agentic`, `task`, `docs`, `cost`, `chunks`) act only on the owner's own session, browser, or memory; financial cost figures are never disclosed to non-admins. ## The ReAct protocol The system prompt enforces an operating protocol: `plan()` must be the first tool call; authentication and permissions gate account actions; `recall()` consults lessons; mutating actions require a `verify()`; tool errors trigger a `reflect()`. For counts and "how many" questions the model is told to use `site_analytics` (the admin-only [analytics endpoint](/docs/admin.html)) rather than paging lists, and to `search_docs` before guessing a route. The external `rsearch_*` web tools are not platform-specific: the prompt makes Devii prefer platform tools always and call them only when the user explicitly asks to search the web or an outside source. See [Security and limits](/docs/devii-security.html) for the confidentiality and memory rules.