---
audience: everyone
summary: What the AI can call. The standard plugin set; how the AI picks; how to add
  your own.
title: Plugins and tools
path: concepts/plugins-and-tools
status: published
---

# Plugins and tools

When the AI in a room calls a tool, it's calling a **plugin**. Plugins
are how ScaiWave extends an AI's capabilities beyond what it can do
with just words.

## The standard set

| Plugin id | What it does |
|---|---|
| `scaiwave.web_search` | Query the live web (SearXNG-backed). Supports parallel multi-query fan-out. |
| `scaiwave.web` | Fetch a specific URL as cleaned markdown. |
| `scaiwave.notes` | Find, read, create, update notes. |
| `scaiwave.todos` | List, check, set due dates, assign todos. |
| `scaiwave.drive` | Search and fetch files from ScaiDrive (storage). |
| `scaiwave.knowledge` | Tenant-private RAG retrieval. |
| `scaiwave.calendar` | Calendar lookups (events, attendees, free/busy). |
| `scaiwave.calculator` | Exact arithmetic (no float drift). |
| `scaiwave.memory` | Long-term memory across conversations. |
| `scaiwave.skills` | Invoke skills from the ScaiSkills library. |
| `scaiwave.scailink` | Delegate to specialist tools registered by other ScaiLabs services. |
| `scaiwave.workspace_bridge` | Write into a workspace-bridged external service. |
| `scaiwave.files` | Access files attached in the current room. |
| `scaiwave.artifacts` | Create / edit canvas artifacts (collaborative documents within a chat). |

Each plugin contributes one or more **tools** the AI can call. A tool
has a name (`web_search`, `find_note`, `drive_rag_context`, …), a
parameter schema, and a callable. The AI's prompt includes the full
schema in OpenAI function-calling format.

## When the AI uses a tool

The model decides. The framework provides three things to steer that
decision:

1. **Tool descriptions** in the schema (one-paragraph "what / when to
   use" for each).
2. **Plugin-injected system context** — each plugin can prepend a
   line to the AI's system prompt summarising its surface ("You can
   search ScaiDrive with `drive_search`…").
3. **Tool-etiquette rules** in the global system prompt: how to
   format calls, how to summarise results, what to do on errors.

## Failure handling — the fallback chain

When a tool errors, plugins return a structured failure that includes
*fallback suggestions* — sibling tools the model should try instead.
For example, a ScaiDrive RAG failure suggests `web_search` (for public
info) or `find_note` (for tenant-private notes).

The AI sees the fallback list in the tool result. Tool-etiquette
rule #4 explicitly instructs:

> If a tool errors, look at the fallback suggestions and try the one
> that best fits the user's intent. When you use a fallback, tell the
> user in one sentence what failed and what you tried instead.

This is what prevents the "give up at the first 401" failure mode.
See [Planner § Failure recovery](/docs/scaiwave/concepts/planner#failure-recovery)
for the harness's contribution.

## Tenant-level toggles

Admins enable / disable each plugin per tenant under **Admin →
Plugins**. Disabled plugins don't appear in any AI's toolbox in that
tenant.

## Room-level toggles

You can disable a plugin for just one room with
`POST /v1/rooms/{room_id}/plugins/{plugin_id}/toggle`. Useful when
you want a tightly-scoped AI for a customer-facing chat that
shouldn't be able to call `drive_search`.

## Per-AI toggles

Each AI participant has a `plugins` field that lists which plugins it
can use. Set under **Admin → AI → Helpers** or with
`PUT /v1/admin/participants/{participant_id}/helper`.

## Writing your own plugin

Plugins are Python classes implementing the `BasePlugin` protocol.
See [Tutorial: Write a plugin](/docs/scaiwave/tutorials/developer/write-a-plugin)
and [Reference: Plugin protocol](/docs/scaiwave/reference/plugin-protocol).

## Permissions and side effects

Plugins declare two things in their manifest:

- **Required permissions** — `READ_MESSAGES`, `WRITE_NOTES`,
  `EXTERNAL_HTTP`, etc. The framework checks these before each
  invocation.
- **Side effect flag** — true if the call mutates anything. Side-effect
  calls in multi-user rooms can be configured to require human approval
  before executing (the approval flow is exposed in the chat as a card
  with **Approve** / **Reject** buttons).

## Where to go next

- Tutorial: [Write a plugin](/docs/scaiwave/tutorials/developer/write-a-plugin).
- Reference: [Plugin protocol](/docs/scaiwave/reference/plugin-protocol).
- API: [AI](/docs/scaiwave/reference/api/ai).