Tools & Permissions

When you authorize an AI tool to connect to your org, you bind it to an org role and choose a read or read & write access level. Both gates must pass for a tool to appear.

​

What the role unlocks

No tools appear if the role holds none of these permissions. If you connect and see “no tools available”, switch to a role that has the relevant permissions — see Connect your AI tool.

​

The tool groups

​

Knowledge store

Read and search everything in your org’s knowledge store: policies, SOPs, brand guidelines, templates, and any other reference material. Read tools: list all items, get a specific item, full-text search, list revision history. Write tools (requires agent:knowledge-store:write + read & write access): create new items, update existing content, revert to a prior version. Knowledge items have their own per-folder and per-item permissions. Even with agent:knowledge-store:read on the role, the tool can only read items the role’s knowledge permissions would normally allow. Folder-inherited permissions are respected exactly as they are in the Starcat dashboard.

​

Data stores

List data stores the connected role can access, inspect their schema, and run queries. Write tools (requires agent:data-store:write + read & write access): insert, update, delete rows; modify schema. Writes target the store’s configured agent branch — if that branch is production, writes go to production.

​

Apps

List apps in the organization and discover which endpoints expose agent-callable routes. These tools require agent:projects:read on the role. Listing apps doesn’t expose code or environment variables — only app name, slug, and which endpoints have allowAgentCalls enabled.

​

Cross-app calls

Call endpoints on your org’s apps directly from your AI tool. Useful for triggering workflows, reading app state, or posting data.

• GET requests: available with agent:cross-app:call permission and read access
• Non-GET requests: additionally require read & write access

An endpoint must have allowAgentCalls enabled in the app’s cross-app settings before it’s callable. Call rate limits and logging apply the same way they do to in-product Starcat calls.

​

Roles introspection

Look up org roles, their permission sets, and the calling session’s own role and capabilities. Useful when the AI needs to understand what it’s authorized to do, or to answer questions about org permissions. whoAmI reports the bound role and a list of capability labels the connected session actually holds.

​

Skills

Discover Stardeck’s built-in skills — focused guides for using platform features. The AI tool can load these as content to apply them in context.

​

Choosing a role

Use the least privilege that covers your use case: You can change the role at any time from Settings → AI Integrations without re-authorizing.

​

Security model

The connection is double-gated: the OAuth scope (set at authorization) limits what can happen broadly, and the role’s permissions narrow it further per tool group. Both gates are enforced fresh on every request — not just at connection time. This means:

• Removing a permission from a role takes effect on the next tool call
• Removing someone’s org membership revokes their connection immediately
• Changing the role from the AI Integrations tab takes effect on the next request — no new token needed

​

Next steps