Settings → AI → Tools

Read-only catalog of every tool an AI agent can invoke. The catalog is defined by the platform, so this tab always reflects exactly what agents can use in your version. You cannot add or edit tools here — restricting which tools an agent may call is done from the Agents tab.

Table columns

Column	Notes
Name	Stable identifier (e.g. inspect, search, inject_session_command, list_skills).
Permission	The permission a caller’s user account must hold for the tool to run. Tools that don’t require a specific permission show None.
Actions	A View (eye) button that opens the tool’s full description — the same text the AI sees when picking a tool.

What the tools do

The tool catalog includes:

• Discovery — search (resources, locations, workers, types).
• Execution — inspect (auto-detects read/write/exec mode and enforces permissions), diagnose (worker-based diagnostics: ping, traceroute, DNS, port, HTTP, SSL, MTU, iperf3, subnet sweep, NTP, and whois tests).
• Session-bound — inject_session_command (read-only commands typed by the AI into the active SSH session, subject to AI Guardrails), get_session_commands, get_session_command_output, get_command_output.
• Read-only data — list_sessions, list_changelog, list_events, list_ids_alerts, list_syslog_messages, facts.
• Skill discovery — list_skills and load_skill, used by the platform’s own agents to find and load Skills; they are not exposed to external AI integrations.

Reading facts and retained session evidence

For facts, start with facts(op="catalog") to get a compact index of available types. Supply fact_type to retrieve one type’s full schema and example. Follow the pagination metadata when more results are available.

History describes one fact instance. If fact_key is omitted, MisterShell selects the key only when exactly one current instance exists. Otherwise, specify a key from the fact list or the error’s suggestions. To inspect a retired instance, pass its historical key explicitly; an explicit empty string selects the empty-key timeline.

The session command-list and command-output tools return success and put successful text in data. A completed command with no output is a successful empty result. Missing, expired, or unavailable recording evidence is an error, not evidence that no command ran. Check the truncation metadata before treating returned output as complete.

Common tasks

Read paginated device command results

For successful inspect commands with parsed rows, follow pagination.total_pages and request each page using the same command and parameters. Pages contain up to 50 rows, reduced when needed to fit the complete response. The full command result is cached for five minutes; subsequent pages use that cached result.

Page 1 also includes a raw-output preview of at most 2,000 characters, reduced further if necessary to preserve a large parsed row. Check raw_output_truncated and raw_output_original_chars before treating that preview as complete. Subsequent pages omit the raw text and report raw_output_included: false and raw_output_page: 1. The full raw output stays in the cached command result; this tool does not expose a separate full-raw-output download.

For commands without parsed rows, large output is split into lossless text pages. Each page contains its portion directly in raw_output; read through pagination.total_pages with the same command and parameters and concatenate the strings in page order to recover the complete output. Line endings and Unicode are preserved. Page boundaries follow line endings when possible; a line longer than the response limit spans pages.

These responses include raw_output_paginated: true, the current raw_output_page, and zero-based raw_output_start_char/raw_output_end_char offsets (the end is exclusive). raw_output_truncated: false means paging has not discarded any text. Small raw-only responses retain their original format.

For stored running configuration, an alternative is inspect('resource', resource_id, 'config_version', {'version_id': existing_version_id, 'elements': ['running_config']}). This reads a saved version, which has its own content-size limit. The elements filter belongs to config_version; it is not a parameter of the device command show_running_config.

View a tool’s full description

1. Click the View (eye) button on a row.
2. The description shown to the AI opens in a modal — including any usage notes the model sees when picking a tool.

Restrict an agent’s tool access

Tool access is configured per agent. Open Settings → AI → Agents, edit the agent, and toggle the tools it may invoke. By default an agent has access to every tool whose required permission its caller already holds; the per-agent allowlist narrows that further.

Every tool can also declare compatible agent types. This restriction always wins: selecting a tool for an incompatible agent is rejected, and a per-agent list can only narrow the compatible catalog. An empty selection means all type-compatible tools, not every tool in the system.

Interactive chat and Quick Assist also enforce the signed-in user’s permissions and location scope. Background agents are system automation: they intentionally bypass human permission and location checks, but they still cannot bypass agent-type restrictions.

Permissions

• Read / list: app.ai.read. There are no write actions on this tab.