Tools and capabilities
The agent tool surface: which capabilities an agent can request, how the tool list is assembled, and how the MCP gateway extends it.
How the tool list is built
At the start of each agent turn, the runtime builds the tool list in four steps:
- Take every capability that declares
surfaces: ['agent'](or['api', 'mcp', 'agent']). - Keep the capabilities the turn's tool policy allows.
- Keep the capabilities the current principal holds grants for.
- Add tools from enabled workspace plugins. These are external MCP servers whose tools the governed MCP tool gateway adds to the workspace toolchain. The in-app assistant skips this step: its tools are Oxagen's capability contracts only.
The result is a Vercel AI SDK tools map passed to streamText. The agent picks from this map and cannot use a tool outside it. There is no sandbox, file system, or browser tool. The only way the agent changes anything is a capability call through kernel.invoke(), and the kernel's checks answer each one. For the in-app assistant, those are your own IAM check and the capability's approval flag. Your workspace's decision rules do not apply to it.
Built-in agent tools
Fleet & agent registry
| Tool | Description |
|---|---|
list_agent_roles / get_agent_role | Inspect an agent's IAM role and effective grants. |
Runs, spend and approvals
These reads return the same record the Runs, Run, Spend and Agents pages show. Each one is low risk and runs without an approval.
| Tool | Description |
|---|---|
list_runs / get_run | List the workspace's runs, newest first, and read one run's frames. The assistant's own turns are not listed. |
list_recent_runs | Read the newest runs with the four fields the command menu shows. |
get_run_cost | Read one run's cost by model and token class. |
get_spend / get_spend_drill | Read the workspace's spend by operator, agent, model, tool, task, cost center, or MCP server, and drill into one operator, agent or tool. |
list_approvals | List the tool calls that wait on a person. |
list_agents / get_agent | List the workspace's agents, and read one agent's runtime, toolbelt, versions, credentials, roles and hosts. |
get_nav_counts | Read the sidebar's counts: pending approvals, open steering suggestions and open critical incidents. |
The assistant offers seven tools on every turn: list_runs, get_run, get_run_cost, get_spend, list_approvals, list_agents and search_graph. It finds any other tool with search_tools and loads it with load_tools.
Memory
The in-app assistant has no memory tool. The memory capabilities run on the API, MCP, and the CLI. See Agent memory for the list.
Knowledge graph
| Tool | Description |
|---|---|
query_ontology | Typed multi-hop traversal over the knowledge graph. |
get_ontology_neighbors | One-hop neighborhood of a node. |
search_graph / search_nodes | Semantic and lexical search over the graph. |
get_node / list_nodes / get_node_labels | Node lookups and browsing. |
get_graph_stats | Aggregate node and edge counts. |
These are the ontology read set. See docs/capabilities/_ontology-read-set.md in the repository for how a run opts a narrowed allowlist into it.
Approvals
An agent cannot approve or deny a parked tool call, or grant consent to an external MCP tool. resolve_approval and resolve_mcp_consent are not agent tools, because both are a person's decision. You answer them on Runs, on the Run page, or from the approvals drawer. A program answers them through the API or MCP.
Repository status (read-only)
| Tool | Description |
|---|---|
get_pr / get_pr_diff | Read pull-request metadata and diffs for a connected repository. |
get_ci_status | Read CI and check status for a branch, commit, or PR head. |
get_repo_metrics | Read repository health metrics. |
These repository-status tools read connected repositories. Separate capabilities that suggest steering changes write steering records and skills to the workspace's steering repo. Oxagen does not provide a general coding runtime.
Billing & budgets
| Tool | Description |
|---|---|
get_spend_budget / set_spend_budget | Read and set organization or workspace spend ceilings. |
get_usage_breakdown | Read metered usage for the org or workspace. |
MCP server management
| Tool | Description |
|---|---|
list_mcp_servers | List external MCP servers registered for the workspace, with each one's health and authorization state. |
list_agent_tools | List every tool available in the current turn (built-in and plugin tools). |
Plugin tools
When a workspace enables an external MCP server plugin, the governed MCP tool gateway adds that server's tools to the workspace toolchain. Plugin tools appear in the agent's tool list next to built-in tools. The same IAM and audit path governs them, so calling a plugin tool leaves the same audit record as calling a built-in tool. The server's credential stays in Oxagen, and the agent never sees it.
Plugin tool names are namespaced by the plugin's server ID to prevent collisions.
Add a tool provider
Open Tools › Providers and select Add a provider. The dialog takes you from finding a server to importing its tools without leaving the page.
- Find the server. Browse the registry searches Oxagen's verified first-party servers (Linear, Slack, GitHub, Notion, Atlassian, Sentry and others) and the official MCP Registry. Each result shows the publisher, whether the publisher proved it owns the name, the transports it offers, and how it authenticates. Custom server takes any streamable-http endpoint, including an internal one.
- Authenticate. For an OAuth server, select Authorize and sign in to the provider in the window that opens. The window closes on its own and the dialog moves on. Some servers, Slack and GitHub among them, do not register OAuth apps themselves. For those, create an OAuth app with the provider, register the redirect URL the dialog shows, and enter its client ID and secret. A server that takes a bearer token or an API key header asks for it instead.
- Review the tools the server lists, and import the ones you want. Imported tools land unclassified and on no toolbelt.
Select Add another provider to add the next one in the same dialog.
Adding and authorizing a provider needs an organization Owner or Admin, or a workspace Owner. Oxagen encrypts every token and client secret before it stores them, and never shows one again.
Provider status
Each provider row shows a status light.
| Light | Meaning |
|---|---|
| Green | The provider answered its last check and holds a live credential. |
| Yellow | The provider is connected with errors: it is degraded, has not been checked yet, or its access token lapsed and renews on the next call. |
| Red | The provider cannot be used: it is unreachable, its token expired with no way to renew, or the provider refused the token. |
A red OAuth provider offers Reconnect, which runs the sign-in again from the row. When a refresh fails at run time, Oxagen marks the provider red and emails the organization's Owners and Admins a link to the Providers tab.
The capabilities behind the dialog are search_mcp_registry, start_mcp_authorization and authorize_mcp_server.
Tool permissions and risk levels
Every tool has a riskLevel field: low, medium, or high.
- Low: allowed without a person by default.
- Medium: may be routed to a person, depending on the tool policy.
- High: routed to a person before it runs. The stream pauses, and an approval card renders.
A turn's tool policy can narrow the list further, for example with an allowlist. There is no workspace settings page for the tool policy.
A turn with no tool policy starts from the conservative default, and high-risk tools are not in the default set.