# Tools & scopes

> What a connected assistant can actually do - the tool catalog, how scopes gate it, and the conventions that keep tool use reliable.

Source: https://app.assetlab.ca/docs/ai/tools-and-scopes

When an assistant connects, it sees a catalog of AssetLab tools - over 200 of them, covering every major resource. What it can *call* is decided by your API key's scopes.

## The tool naming convention

Tools follow a strict verb-resource pattern, so the catalog is predictable:

| Pattern | Example | Does |
|---|---|---|
| `list_*` | `list_work_orders` | Query records, with filters and pagination |
| `get_*` | `get_asset` | Fetch one record by ID |
| `create_*` | `create_work_order` | Create a record; returns the created row |
| `update_*` | `update_pm_schedule` | Modify fields on a record |
| `delete_*` | `delete_part` | Remove a record |
| `bulk_create` / `bulk_update` | - | Batch operations for supported resources |

## What's covered

Essentially the whole platform:

- **Registry** - assets, sites, buildings, locations, systems, classifications, asset types, manufacturers, custom fields
- **CMMS** - work orders (+comments), work requests, PM schedules and templates, form templates/items/responses, parts, vendors, contracts, compliance
- **Financials** - asset costs, expenses, invoices, purchase orders, budgets, change orders, cost categories
- **Projects** - projects and their tasks, milestones, phases, budget items, time entries, risks, updates, team
- **Infrastructure** - networks, feature classes, features, inspections, zones
- **Analytics** - dashboard summaries and snapshots, FCI history, risk history, replacement plans
- **Level of service** - service areas, measures, measurements

The authoritative per-resource table ships with the [npm package](https://www.npmjs.com/package/@assetlab/mcp-server); the [REST API resources](/docs/reference/resources) page mirrors it.

## Scopes gate everything

Each API key carries scopes of the form `resource:read` / `resource:write` (or `*:*` for full access):

- `assets:read` → `list_assets`, `get_asset` work; `create_asset` is refused
- `work_orders:write` → create/update/delete work orders
- No scope → the tools for that resource fail with a permission error the assistant can read and explain

Scopes are chosen at key creation in **Settings → API Keys**, grouped by category with bulk toggles. The full scope list is in the [reference](/docs/reference/scopes).

### Practical scope sets

| Use case | Scopes |
|---|---|
| "Ask questions about my data" | All `:read`, no writes |
| Maintenance copilot | Reads + `work_orders:write`, `work_requests:write`, `pm_schedules:write`, `form_templates:write` |
| Data migration assistant | The specific `:write` scopes for what's being loaded, temporary key |
| Full trust | `*:*` - appropriate once habits are established |

## Conventions the server enforces

Two behaviors make tool use reliable, and they're built in:

1. **Lookup before create.** The server instructs assistants to resolve real IDs via `list_*` tools instead of guessing - creating an asset means first finding the actual site, building, and system IDs. Malformed IDs are rejected with instructions to look up first.
2. **Your organization only.** The key is bound to one organization at creation. Nothing an assistant sends can widen that - tenant identity comes from the key, never from tool input.

## Rate limits

Keys carry a per-minute rate limit (default 60 requests/min). Assistants doing large sweeps pace themselves against it; bulk tools exist precisely so a 200-record load is a handful of calls, not 200.