Extending Sense with your own capabilities

Read the capability boundary

123456 Expand

1. 1

   Name is the stable grant string stored on agents; prefix it (acme.competitor-intel) because a collision with a platform capability is rejected.

2. 2

   When to use it is shown to the assistant's planner; write concrete triggers, because this text steers tool choice more than the description does.

3. 3

   Built-in tools come from the platform's fixed allowlist (query_data, describe_entity, ...); they are only enforced when the deployment's capability gating switch is on.

4. 4

   Script tools and MCP tools widen the callable surface; a script tool's own Required capability is the strongest per-tool check.

5. 5

   Intents it can serve adds routing vocabulary; it does not grant the capability to any agent.

6. 6

   Save creates the bundle; grant it from the saved agent's detail page and test an ungranted agent as well.

Capabilities are authored at Setup → Sense AI Studio → Configuration → Capabilities; New capability opens the dialog above, which captures the stable grant name, label, description, planner guidance ("When to use it"), built-in tools, script tools, MCP tools, optional intents and active state. A capability record participates in planning immediately when granted, but hard runtime filtering depends on the deployment switches described below.

Create a capability only after the underlying script tool or MCP server is callable and tested. Give the bundle a collision-safe tenant name, write precise planner guidance, include only necessary tools and grant it to the intended agent. Then verify the runtime's EnforceCapabilityToolGating, McpRequiresCapability and human-approval policy. A catalog design is not proof of an enforced boundary when the corresponding switches are off or the resolved allowlist is empty.

Sense agents can use tenant script tools and registered MCP servers in addition to platform tools. A tenant capability groups tool names and planning hints for an agent grant. Script tools can also name a required capability that is checked during listing and execution. Built-in and MCP exposure have separate opt-in runtime gates, so test an ungranted agent as well as a granted one before treating the bundle as an isolation control.

Capabilities in one paragraph

A capability is a named bundle used by the planner and, when enabled, the executor. With EnforceCapabilityToolGating on, built-in tools are intersected with the resolved capability tool names; however, an empty resolved allowlist deliberately fails open and several interaction/UI tools remain available. With that switch off, the catalog is planning guidance rather than a built-in-tool allowlist. MCP has its own McpRequiresCapability switch and otherwise remains exposed. Script-tool Required capability is the strongest per-tool check because the catalog filters it and execution checks it again against the effective user's capabilities or the agent's grants.

The four steps

1. Make the thing callable

Pick the surface that matches what you are integrating:

Script tools run in the platform's sandbox with a bounded timeout and no general network or file surface; a narrowly defined read accessor is supplied only for the data-read capability. MCP credentials are stored through their write-only administration path. Neither script nor MCP calls are universally approval-gated: approval appears only when human approval is enabled, the routed agent supports it and the call surface is in the effective approval-required list.

2. Bundle the tools as a capability

Create the capability with a name you'll grant on agents — prefix it clearly because a platform-capability collision is rejected. Add built-in, script and MCP names, then write When to use it as concrete planning guidance. The effective list can show generic script/MCP call surfaces in addition to named tools. That display explains what the bundle resolves to; it does not by itself prove the deployment has enabled hard built-in or MCP filtering.

3. Restrict the tool to the capability (recommended)

On the script tool, set Required capability to your capability's name. The active-tool list and execution path both enforce that requirement. Either the agent grant or the effective execution user's capability can satisfy it, so test both sources of entitlement. Without a Required capability, an active script remains available wherever the generic script-tool surface is exposed.

4. Grant it to an agent

Create the agent — or edit a saved one — and grant the capability. Write instructions that state which tool answers which question, add realistic routing examples, and test in a fresh conversation. Test a matching prompt, a non-matching prompt, an ungranted agent, an execution user that lacks the user-side capability, and both approval accept/reject paths when approval is enabled. Record the effective deployment switches with the test evidence.

A worked example

A distributor wants "how do we compare against the competitor on this account?" answered from an internal pricing API plus an in-house index calculation.

1. The pricing API is registered as an MCP server exposing a competitor-price tool.
2. The index calculation becomes a script tool, with Required capability set to ours.competitor-intel.
3. A capability ours.competitor-intel bundles the two, plus the built-in data-query tools, with when-to-use text: "Use for competitor pricing, share index, or how-do-we-compare questions."
4. A "Competitor Analyst" agent is granted ours.competitor-intel and the platform data-query capability, with routing keywords like competitor, price, compare and instructions requiring the index tool for any index figure.

The script tool is denied when neither the agent grant nor effective user capability satisfies its Required capability. The MCP conclusion depends on McpRequiresCapability; with that switch off, capability metadata alone does not remove MCP from other agents.

Current limits

Common questions

Will adding tools clutter every agent in the organization?

The new definition does not grant itself to agents, but capability metadata is not always a hard filter. Verify hard built-in gating is enabled and resolves a non-empty allowlist, verify MCP gating separately, and put Required capability on sensitive script tools. The correct production test is that an ungranted agent cannot list or execute the tool, not merely that its edit page lacks the grant name.

The assistant answers from general knowledge instead of calling my tool — why?

Usually one of two gaps. Either routing sent the message to a different agent — sharpen your agent's routing description, keywords and examples, and confirm it is active and visible to the asking user — or the agent handled it but wasn't told firmly enough to use the tool: state the requirement explicitly in its instructions, and make the capability's when-to-use text concrete. If you see a "requires the capability" authorization error instead, the script tool's required capability isn't granted to the answering agent — add the grant.

Does any of this widen what users can see or change?

It can. The routed agent's configured execution account can become the effective user for a turn, and tools can reach whatever their implementation and that identity permit. Script Required capability can be satisfied by the agent grant itself. Human approval is also configuration-dependent. Scope execution accounts and external credentials narrowly, enable and test the relevant runtime gates, and do not use the asking user's list access as an assumed ceiling. See How Sense AI is governed.

Related topics

• AI Studio
• Create an agent
• How Sense AI is governed