What your agent can do

BoardHerald keys don't carry ambient "full access". Every key is minted with a persona — a named bundle of scopes that decides which tools the agent can call. The four built-in personas below cover most use cases. For a complete scope-by-scope reference (every resource, every action, what it unlocks), plus the human-role ceiling that sits above all of this, see Platform → Permissions.

Scopes in detail

Scope names follow a <resource>:<action> convention, where resource is a top-level domain (updates, resolutions, meetings, financials, kpis, users, audit, notifications, categories, search) and action is one of read, write, or a resource-specific verb (e.g. vote for resolutions, manage for users, webhook for kpis). For the full scope-by-scope table with every tool each scope unlocks, see Platform → Permissions.

A scope implies nothing beyond itself:

• updates:write does not imply updates:read. If you want an agent that posts AND reads updates, grant both.
• resolutions:vote does not imply resolutions:write (vote without authoring).
• audit:read is never implied by any other scope — it's an explicit opt-in because it exposes who-did-what across the whole tenant.
• kpis:webhook is its own narrow transport scope — it only unlocks the /api/kpis/webhook push endpoint for sync connectors, not financials:write. Issue a dedicated key for your Stripe / QuickBooks / custom HTTP forwarder and it can't rewrite KPI metadata even if compromised.

MCP-native surface

Every feature that has an admin UI also has an MCP tool. The catalogue splits cleanly:

• Read tools — updates_list, updates_get, resolutions_list, resolutions_get, meetings_list, meetings_get, financials_list, financials_get, kpis_list, kpis_get, kpis_sparkline, users_list, users_get, notifications_list, categories_list, search_query, audit_list, me_profile.
• Write tools — authoring, publishing, editing, voting. Every tool has its own scope so you can mint a key that (say) posts updates but cannot close resolutions.
• KPI-specific tools — kpis_record_period, kpis_restate, kpis_target_create, kpis_target_update, kpis_target_delete, plus the transport-only kpis_webhook_ingest. Targets are range-based time-varying goals; restatements record the previous value + a required note. See Agents → Sync KPIs for five different data-entry patterns (manual / CSV / webhook / MCP cron / Stripe connector).
• User management tools — users_invite, users_update, users_disable, users_grant_access, users_revoke_access. The grant / revoke tools take a group parameter ("FINANCE" or "INVESTOR"); users_invite accepts grantFinance + grantInvestor booleans so a member can be invited straight into the intended access state.

Principle of least authority

If an agent's job is "every morning, summarise yesterday's updates", the only scope it needs is updates:read. Don't hand it the meeting secretary persona just because it's convenient — the blast radius of a compromised key scales with the scopes it carries.

Audit trail

Every agent call lands in the tenant's audit log with the key's persona attached. An admin can see exactly which key called which tool at which timestamp — so if an agent "goes rogue", it's visible within seconds, and the key can be revoked with one click.