The agent works through tools: bounded, size-capped operations against your Splunk deployment, every one of them executed with the calling user’s own session. This page lists them. Read-only tools run on their own (under the default approval mode); in Chat the authoring tools, and a search that uses more than Splunk’s commands that only read, always pause for approval; unattended runs never get those tools at all; and the MCP server, which has no approval card, offers the authoring tools only once whoever runs it switches them on, and then runs them without one.
Explore and search
| Tool | What it does |
|---|---|
profile_data | Profiles the data matching a filter in one call: total volume, breakdown by index and sourcetype, activity over time, the fields that exist with their top values, and a few sample events. The intended first step for a broad “analyze X” request. |
splunk_search | Runs a bounded search and returns up to 25 rows, so the agent writes searches that summarize (stats, timechart, top) rather than page raw events. It runs a search on its own only when every command in it only reads: splunkd’s parser expands your macros and saved searches and every subsearch, and each command is checked against Splunk’s built-in reads and the add-on commands an administrator allowed. Anything else - collect, outputlookup, delete, sendemail, script, rest, an add-on command nobody allowed - is refused with a pointer to splunk_search_with_approval. A search the parser rejects comes back with the parser’s error, for the agent to fix. Real-time time ranges are refused. A search that fails after it starts is reported as the failure it is, with the same message the search bar shows. See Security. |
verify_spl | Checks that a search parses before it is used or saved. |
list_indexes | The indexes you can search, event and metric alike, with each index’s kind - so the agent knows a metric index needs mstats - and a name filter for deployments with many indexes. |
current_time | The current time, so relative ranges are computed correctly. |
Your deployment’s vocabulary
The bundled documentation describes Splunk; these tools describe your Splunk, as the signed-in user sees it:
| Tool | What it returns |
|---|---|
list_macros | Search macros with their definitions, arguments, and the exact backticked call to paste into SPL. |
list_lookups | Lookup definitions with their type (file, KV Store, external, geospatial), the fields they expose, and a starting lookup or inputlookup line. |
list_datamodels | Data models, their dataset trees, and each dataset’s fields with the fully qualified names a data model search requires, plus ready tstats and datamodel searches and which models are accelerated and how far back. |
list_installed_commands | The SPL commands your installed apps contribute, which the bundled reference has never heard of. |
list_kvstore_collections | KV Store collections with their declared fields. |
list_users | User accounts and the roles they hold. |
splunk_server_info | The Splunk version, server roles, and platform this app runs on. |
list_savedsearches, get_savedsearch | Existing reports and alerts, to iterate on. |
list_dashboards, get_dashboard | Existing dashboards, to iterate on. |
list_alert_actions | The alert actions installed on the system - email, webhook, Slack, PagerDuty - discovered rather than guessed. |
The agent is told to survey this vocabulary before writing SPL for an environment it has not seen, and to reuse what is there rather than reinvent it. Every list tool’s filter matches each word of what the agent typed rather than the phrase as a whole, in any field, so “kubernetes audit” finds macro_kubernetes_audit_logs; a macro or lookup description that says what it selects is how you make it findable from a plain-language question.
Author, with your approval
| Tool | What it does |
|---|---|
create_dashboard, update_dashboard | Create or update a Dashboard Studio dashboard - from a compact panel list (title, search, visualization per panel) that the app expands into a full definition with a tiled layout and a global time-range picker, which also makes the approval card a reviewable list of searches; or from a raw definition for advanced layouts. Panels are checked against the visualization types the app knows, and an unrecognized type is flagged on the approval card rather than silently saved. |
create_savedsearch, update_savedsearch | Create or update a saved search, report, or alert: cron schedules and time ranges, count-based or custom trigger conditions, real-time alerts with throttling and suppression, severity, and any installed alert action. |
verify_dashboard | Validates a dashboard definition before it is written. It changes nothing, so it runs without an approval card. |
splunk_search_with_approval | Runs a search splunk_search refused - one using a command that writes or sends, rest, an add-on command nobody allowed, or one the check could not fully see into - once you approve it. The approval card shows the SPL, and the search runs with your own permissions. A search splunkd’s parser rejects is never put to you: Splunk would fail it once approved, so the agent gets the parser’s error and fixes the search instead. Not offered to unattended runs or the MCP server. |
These tools pause on an approval card in Chat, and updates are limited to your own private objects. A dashboard the agent creates carries a title and a one-line description, and the agent reports a link to it labeled with its title.
Record a decision
| Tool | What it does |
|---|---|
set_decision | Answers one of the decisions an unattended run was configured with, choosing from the answers you listed, with a short rationale. Offered only to a run that has decisions configured. It changes nothing: the answers are written as one event when the run concludes, and an alert of yours acts on them. See Decisions. |
The reference it consults
The binary embeds a cleaned copy of Splunk’s SPL Search Reference and Dashboard Studio documentation, plus curated dashboard examples, and exposes them as lookup tools (list_spl_commands, get_spl_command, list_dashboard_docs, get_dashboard_doc, and get_dashboard_examples). The agent consults them while it works, so SPL semantics and dashboard syntax come from documentation rather than model memory, and they work air-gapped. Because that reference is a snapshot of one release, the agent also asks your Splunk which version it runs and prefers long-standing syntax on an older or newer deployment.
Query templates
A template records one of your team’s conventions: a name, a description, tags, and the SPL pattern - “application logs live in index=app_prod”, “start from this accelerated tstats”, “this sourcetype needs this filter before its numbers mean anything”. The agent searches the library before writing a search of its own (search_query_templates, get_query_template), adapts the closest match, and says which template it started from.
Manage the library on the Setup page’s Query templates tab. It is shared: readable by every user of the agent, editable by app administrators. A deployment with no templates behaves as if the feature did not exist.
Situational guidance
Beyond its always-on playbook, the agent carries short notes that matter enormously when a request touches them and not at all otherwise, and it adds only the ones a request touches, selected on the words in your message: that a metric index needs mstats, that a subsearch truncates at its limits without an error, that an alert without suppression gets muted. Nine ship with the app, all about SPL and Splunk itself; what is particular to your data - which index an application logs to, which fields it carries - is what your own notes are for. You can add your own, customize a shipped one, or turn one off on the Setup page’s Guidance tab; see Configuration - guidance.
The MCP server
The app’s binary doubles as a Model Context Protocol server, so an external assistant - Claude Code, for example - can use the same size-bounded tools. Run the platform binary the app ships with the mcp subcommand; it speaks MCP over standard input and output:
$SPLUNK_HOME/etc/apps/os_ai_agent/bin/platform/<os>_<arch>/os_ai_agent mcp- With no credentials, it serves only the embedded documentation: the SPL and Dashboard Studio references, the dashboard examples,
current_time, and the Simple XML dashboard reference (list_simplexml_docs,get_simplexml_doc), which only this surface has: the agent in Splunk writes Dashboard Studio dashboards. - With a splunkd session -
OS_AI_AGENT_SPLUNKD_URI,OS_AI_AGENT_SESSION_KEY(a Splunk authentication token is best, since session keys expire) andOS_AI_AGENT_APP_DIR(the app’s directory, for its[splunk]and[splunk_search]settings) in the server’s environment - it adds the read-only Splunk tools, running as the user that token belongs to.splunk_searchfollows the same read-only check as in Chat. - The authoring tools stay off unless
OS_AI_AGENT_MCP_ALLOW_MUTATIONS=1is set. MCP has no approval card, so with that switch they run with nobody deciding, and the activity trail records them asdecision=auto.splunk_search_with_approvalis never offered, whatever the switch says.
Its tool calls land in the activity trail with surface=mcp when the server can write the trail: it takes the path from OS_AI_AGENT_AUDIT_FILE, which must name a file the target Splunk indexes (its var/log/splunk/os_ai_agent_audit.log), or, without it, derives the path from an app directory installed under that Splunk. A server with a splunkd session and no trail says so on its standard error when it starts. The MCP server does not call your model provider, so it records no usage and spends nothing.