hoot tools reference

tier system

Server-side tools (get_site_logs, get_system_presets, deploy_software, update_process, add_process, delete_process, create_talon, list_talons, set_talon_enabled, schedule_followup, cancel_followup) execute in the Next.js server process. They do not route through the agent command queue. Talons are site-level records and follow-ups are chat records, so neither is ever relayed to a machine.

execution-mode matrix

Web hoot chooses an execution path by tool name in web/lib/hoot-utils.server.ts. Server-side tools run in the Next.js server process. Legacy command tools write existing machine command types. Firestore tools create mcp_tool_call entries for the agent to execute. Local Agent SDK MCP is separate: agent/src/cortex_tools.py exposes only the tools returned by _make_tier1_tools, _make_tier2_tools, and _make_tier3_tools.

Local Agent SDK coverage is intentionally smaller than the web registry: at maximum tier it returns 21 tools, and at the default max_tier=2 it returns 15. agent/src/cortex_tools.py defines a get_gpu_processes wrapper, but the function is omitted from the returned tier-1 list, so local Agent SDK hoot does not expose it today. agent/src/mcp_tools.py also contains internal handlers that are not public web hoot tools, including get_display_layout and apply_display_topology.

tier 1: read-only tools

get_site_logs

Get activity logs across all machines in the site. Useful for finding errors, crashes, and events across the fleet. Server-side — queries Firestore directly.

get_system_info

Get comprehensive system information including hostname, OS (with correct Windows 10/11 detection), CPU model and usage, memory (used/total GB), disk (used/total GB), GPU model, driver version, VRAM (used/total GB), GPU load %, uptime, and agent version.

get_process_list

Get all owlette-configured processes with their current status, PID, launch mode, executable path, file path / command arguments, working directory, and whether they are running.

get_running_processes

Get all running OS processes with CPU and memory usage. Can filter by name.

Returns: Processes sorted by memory usage with name, PID, CPU%, memory%.

get_gpu_processes

Get per-process GPU memory (VRAM) usage via Windows Performance Counters — same data source as Task Manager. Shows dedicated and shared GPU memory per process, sorted by usage. Works cross-vendor (NVIDIA, AMD, Intel) and for all GPU APIs (DirectX, OpenGL, CUDA, Vulkan).

get_network_info

Get network interfaces with IP addresses, netmasks, and link status.

get_disk_usage

Get disk usage for all drives including total, used, free space and percentage.

get_event_logs

Get Windows event log entries from Application, System, or Security logs.

get_service_status

Get the status and start type of a Windows service. Returned start_type disambiguates "stopped" states: automatic (should be running), demand_start (stopped-is-normal idle state, e.g. wuauserv/BITS), disabled (intentionally off).

get_agent_config

Get the current owlette agent configuration (sensitive fields stripped).

get_agent_logs

Get recent owlette agent log entries.

get_agent_health

Get agent health status including connection state and health probe results.

get_system_presets

Get available software deployment presets managed by the site admin. Returns installer URLs, silent install flags, verification paths, and other deployment parameters for software like TouchDesigner, Unreal Engine, media players, etc. Use this before deploy_software to find the correct preset and parameters. Server-side — queries Firestore directly.

check_pending_reboot

Detect whether a system reboot is currently pending (from Windows Update, Component Based Servicing, pending file rename operations, or SCCM client). Read-only diagnostic — use during incident investigations, after a suspected update, or when the machine is behaving unusually. The agent also emits a site-level auto-alert the first time it detects a pending reboot (idempotent via a flag file).

Returns: pending (bool), reasons (array), last update install time, next scheduled update run time (if available).

schedule_followup

Schedule a follow-up turn on this conversation. At the scheduled time hoot is re-opened in the same chat with note injected as the instruction, acts on it, and reports back — the way a promise to "check back in ten minutes" actually happens, since a turn ends when the assistant stops typing. Server-side — the follow-up is a chat record (cortex-followups/{id}, a data-at-rest name), acted on by the cron sweep and never relayed to a machine.

Returns: followup_id, fires_at (ISO), and watch_command_id when one was passed. Keep followup_id — cancel_followup needs it.

Pass exactly one of delay_minutes and at — both, or neither, is rejected with invalid_schedule rather than silently picking a winner. Out-of-range values return invalid_delay_minutes, at_in_the_past, or at_too_far_out.

Early fire. watch_command_id is a shortcut, not a replacement for the schedule — the scheduled time stays the backstop. The sweep resolves the watched command from the machine's commands/completed document and treats only the terminal statuses (completed, failed, error, cancelled) as finished; the agent's non-terminal running marker does not fire it. A follow-up scheduled against more than one machine — a subset of a site, or a site-wide chat — has no single command whose finish means the work is done, so the id is ignored there and the follow-up waits for its scheduled time.

Firing. The follow-up pass rides the once-a-minute talons cron sweep (/api/cron/talons). Each sweep scans the 25 soonest scheduled follow-ups and starts at most 10 turns; a backlog drains over the following minutes. An early fire is therefore only found while the follow-up sits inside that scan window — past it, the follow-up still fires at its own scheduled time.

Tier 3 always waits for a person inside a fired follow-up. The turn runs with forceTier3Approval, which overrides the site's requireTier3Approval setting: a site that lets an operator auto-run tier 3 while they watch has not agreed to it running while nobody does. The model may still reach for a tier-3 tool — the turn simply parks at approval-requested until the owner comes back to the chat.

Where it fires. A follow-up fires on the machines the scheduling turn was targeting, not on whatever the chat is pointed at when it comes due — the selection may have moved since the promise was made. A site-wide follow-up stays dynamic: a machine added in the meantime is included. The target is re-validated at fire time, so machines that have left the site, gone offline, or had hoot switched off are dropped from it; if nothing is left the follow-up is marked failed with the reason on the record rather than dispatched.

Other fire-time guarantees. Site access is re-resolved on every fire and never trusted from scheduling time, so a user removed or demoted in the meantime cannot keep driving tools through a promise they left behind; the chat must still exist and still belong to the same user (chat_deleted / chat_owner_mismatch). A follow-up never supersedes a live turn — if someone is mid-conversation the doc goes back to scheduled and the next sweep retries.

Where it is not available. The tool requires a user chat: unattended hoot (autonomous dispatch, talon directives) runs as a system actor with no chat to re-open and no user whose access could be re-resolved, and gets followup_unavailable. Both follow-up tools are also withheld from the public conversations API — that surface's chatId is a chat_conversations id while the sweep resolves chats/{chatId}, so a follow-up scheduled there could never fire (it would fail closed as chat_deleted). Withholding the tools is deliberate: better no promise than one the sweep silently breaks.

cancel_followup

Cancel a scheduled follow-up before it fires. Use it when the thing the follow-up was going to check has already been settled in the conversation, or when the operator asks for it to be dropped. Server-side — reaches the same store helper as DELETE /api/hoot/followups/{followupId}, which is what the chip above the composer calls.

Ownership is enforced inside the store transaction (the Admin SDK bypasses firestore.rules, so that is the only gate every caller passes through): only the user who scheduled a follow-up can cancel it, and only while it is still scheduled. Failure results are followup_not_found (404), followup_forbidden (403, it belongs to another user), and followup_not_scheduled (409, it already fired or was cancelled — a cancel that loses the race with the sweep's claim lands here). Like schedule_followup, it is unavailable to unattended hoot and withheld from the public conversations API.

tier 2: process & machine management tools

These execute immediately without user confirmation. Owlette-configured process control tools (restart_process, kill_process, start_process, set_launch_mode) wrap existing commands. Process config tools (update_process, add_process, delete_process) run server-side through the same validated action functions as the dashboard, and the talon tools (create_talon, list_talons, set_talon_enabled) run server-side through the same talon store as the talon editor. The rest are purpose-built with validated parameters and narrower blast radius than raw shell scripts.

restart_process

Restart an owlette-configured process by name.

kill_process

Kill/stop a running owlette-configured process.

start_process

Start a stopped owlette-configured process.

set_launch_mode

Set the launch mode for a process.

Schedule block format:

{
  "days": ["mon", "tue", "wed", "thu", "fri"],
  "ranges": [
    { "start": "09:00", "stop": "18:00" }
  ]
}

update_process

Update an owlette-configured process by name. Only fields provided in the tool call are changed. Runs server-side through updateProcess; the agent picks up the config change through the existing config listener and launch-mode diff.

add_process

Create a new owlette-managed process on the target machine. Runs server-side through createProcess; the new process defaults to launch_mode: "off" unless a launch mode is supplied.

delete_process

Delete an owlette-configured process by name. Runs server-side through deleteProcess. Deleting a process removes it from the machine config; it does not terminate an already-running OS process. Use kill_process first when the running process should also be stopped.

capture_screenshot

Capture a screenshot of the remote machine's desktop. Returns the image for visual analysis — use to diagnose display issues, verify process state, or see what's currently on screen.

manage_process

Kill, suspend, or resume OS processes by name pattern. Works on any process, not just Owlette-managed ones. Safer than run_command + taskkill: validated params, no shell, refuses to touch critical system processes (lsass, winlogon, csrss, etc.) via an internal blocklist.

manage_windows_service

Full services.msc parity — start, stop, restart, pause/continue, set startup type, configure failure recovery, or get full service details in one call. Use set_recovery to configure auto-restart on crash (critical for unattended media installations). Use get_details to query status, startup type, binary path, dependencies, and recovery config at once.

configure_gpu_tdr

Configure Windows GPU Timeout Detection and Recovery. Writes TdrDelay (and optionally TdrDdiDelay) to the registry. Critical for TouchDesigner / Unreal / Unity installations with heavy shader work — the default 2-second timeout causes silent crashes on complex GPU operations. A reboot is required for changes to take effect.

manage_windows_update

Pause, resume, or schedule Windows Update. Pause before live events; use set_active_hours to block auto-reboot during quiet hours; set_scheduled_install for exact install timing; set_feature_deferral / set_quality_deferral to delay rollouts. Windows Update is the #1 threat to unattended 24/7 installations.

suppress_setup_screens

Suppress the full-screen Windows setup screens that hijack the display at sign-in after updates: the "Choose privacy settings" experience, the Windows Welcome Experience, "Let's finish setting up your device" (SCOOBE), and the Edge first-run tour. Writes the machine-wide policies plus the per-user keys for every existing profile (mounting signed-out profiles' hives) and the Default profile, so future accounts inherit the suppression. apply is idempotent — feature updates are known to reset these keys, so re-assert on a schedule (the update guard talon preset does exactly this).

manage_notifications

Control Windows toast notifications and Focus Assist. Essential for kiosks and video walls where a surprise "Updates are ready" toast would interrupt an exhibit. Use disable_all_toasts to fully silence the system, enable_focus_assist with alarms_only for total silence, or disable_for_app to silence a specific app.

configure_power_plan

Set Windows power plan and disable sleep/hibernate/screen blanking. Required for any 24/7 unattended installation — default power settings will sleep the machine, blank the screen, or hibernate, all of which break live deployments.

manage_scheduled_task

Full Task Scheduler parity — list, enable, disable, delete, run_now, stop, create new tasks, get details, and get run history. Use create for weekly memory-flush reboots, boot-time media app launches, or event-triggered restarts.

network_reset

Flush DNS, renew IP lease, restart a network adapter, or reset the winsock stack. Common fix for NDI dropouts, Firebase connectivity loss, DNS resolution issues at venue networks. reset_winsock requires a reboot to fully take effect.

registry_operation

Read, write, or delete Windows registry values. Restricted to an allowlist of safe registry paths (Winlogon, GraphicsDrivers, WindowsUpdate, Notifications, Power, Services, etc.) — system hives like SAM, SECURITY, and Cryptography are blocked.

clean_disk_space

Clean temp files, Windows temp, prefetch cache, recycle bin, or Owlette logs with an age filter. Use dry_run=true to preview what would be deleted.

get_event_logs_filtered

Fast filtered event log query via Get-WinEvent -FilterHashtable. Orders of magnitude faster than get_event_logs when searching for specific crashes, process sources, or event IDs.

manage_windows_feature

Add, remove, or list Windows Optional Features (DISM, e.g. NetFx3, OpenSSH-Server), Windows Capabilities (FoD, e.g. OpenSSH.Client), or AppX Packages (Store apps like OneDrive, Xbox Game Bar, Cortana, Teams). Critical features for Owlette itself are blocklisted and cannot be disabled. AppX install is not supported.

show_notification

Display an on-screen message on the remote machine — useful when a technician is physically nearby. Toast style is a subtle corner notification; modal style uses msg.exe to block the screen briefly. Opposite of manage_notifications, which suppresses notifications.

create_talon

Create a talon on this site — a saved automation of trigger → optional condition → outputs. See talons for the product-level picture. Server-side — talons are site-level records written through the same store as the dashboard editor, never relayed to a machine.

Confirm before calling. A talon runs unattended against real machines, so hoot is instructed never to call this from a vague request: it states back the exact talon it intends to create — trigger, condition, every output, the machines in scope, the cooldown — and waits for the operator to confirm.

Trigger shapes (exactly one form):

{"type": "schedule", "entries": [{"id": "e1", "days": ["mon", "wed"], "time": "09:00"}]}
{"type": "schedule", "intervalMinutes": 30}
{"type": "threshold", "metric": "cpu_percent", "operator": ">", "value": 90}
{"type": "event", "eventTypes": ["process_crash", "machine_offline"], "delayMinutes": 2}

• schedule / entries — 24-hour HH:MM in the site's timezone, up to 50 entries. entries and intervalMinutes are mutually exclusive.
• schedule / intervalMinutes — 5 to 1440 minutes, but 15 minutes minimum when the condition is a visual_check.
• threshold — metrics cpu_percent, memory_percent, disk_percent, gpu_percent, cpu_temp, gpu_temp, network_latency, network_packet_loss; operators >, <, >=, <=. Threshold talons ride the existing alert pipeline: one fires when an alert rule fires and the breach matches the talon's own metric, operator, and bound — so a threshold talon does nothing until a matching alert rule exists.
• event — process_crash, machine_offline, process_start_failed, process_restarted, exe_missing, and the display_* events. Event triggers only: delayMinutes (0-1440) waits that long after the event before running, e.g. letting a restarted app finish booting before a visual_check looks at it.

Condition — {"type":"none"} (default), or {"type":"visual_check","expectation":"the lobby wall is playing the loop, not showing a desktop","monitor":0}, which captures a fresh screenshot and asks a vision model whether the expectation holds. expectation is 500 characters or fewer; monitor is 0 for all displays combined, 1 for primary.

Output entries — each entry is an object keyed by type:

type: "cortex" is the hoot output — the wire literal is a deliberate survivor of the cortex → hoot rename (it is persisted on every talon and every talon-run summary, and the MCP tool schema is itself a published contract). Every label a human reads says hoot. See web/lib/hoot/WIRE_NAMES.md class B.

Refusals. A command output takes the same privilege as issuing the command by hand — site admins only, refused with command_output_forbidden (403) both in the tool and again in the store. A visual_check condition or a cortex output spends the talon author's own LLM key, so authoring one without a saved key returns llm_key_required (400). Exceeding 20 talons on the site returns talon_limit_reached (409). Validation rejects unknown top-level fields outright, so the model can never stamp a server-owned field onto the document; field-level failures come back as invalid_talon with field_errors rather than throwing and taking the turn down.

Returns: talon_id, name, enabled, next_run_at.

Unattended hoot cannot call this tool: authoring a talon is standing fleet policy that outlives the incident, so create_talon is excluded from the autonomous investigator's tool list regardless of tier.

list_talons

List the talons on this site, ordered by name. Call it before set_talon_enabled to get a talon id, and before create_talon so an existing talon is not duplicated.

Returns: count, plus per talon talon_id, name, enabled, trigger (the normalized object, not a prose summary, so the exact metric / interval / event values are available for follow-up calls), outputs (types only), last_run_status, last_run_at, next_run_at.

Read-only, so unlike the two writing talon tools this one stays available to unattended hoot.

set_talon_enabled

Arm or disarm an existing talon. Disabling leaves the talon in place — it does not delete it.

Enabling recomputes nextRunAt from now in the site's timezone, so a talon that sat disabled for a while does not fire the moment it comes back, and re-checks the author's LLM key when the talon has a visual_check condition or a hoot output (llm_key_required if it is gone). Either edge clears a system-set disable reason, so a re-armed talon does not still claim it was switched off. Like create_talon, this tool is excluded from unattended hoot.

Returns: talon_id, name, enabled, next_run_at.

tier 3: privileged tools

These require explicit user confirmation before execution.

run_command

Execute a shell command on the remote machine.

Returns: stdout, stderr, exit code.

Allowed commands (first word must be one of):

ipconfig, systeminfo, hostname, whoami, tasklist, netstat, ping, tracert, nslookup, dir, type, echo, set, ver, wmic, sc, net, reg, nvidia-smi, dxdiag

This is the default set (DEFAULT_ALLOWED_COMMANDS); it is overridable via config.mcp.allowed_commands. A running command can be cancelled from its tool card, which kills the process tree on the machine.

run_powershell

Execute a PowerShell command on the remote machine.

Returns: stdout, stderr, exit code.

No command restrictions — every invocation is audit-logged to the site events feed and the local [MCP-AUDIT] log. Fixed 25-second timeout; for long-running work use execute_script. A running command can be cancelled from its tool card, which kills the process tree on the machine.

run_python

Execute Python code on the remote machine in the user's desktop session.

Sandboxed execution (since v2.6.5). When invoked via this tool, code runs with:

• Restricted __builtins__ — eval, exec, compile, globals, locals, breakpoint, input, exit, quit are all removed. open, print, getattr/setattr, and common types/exceptions remain available.
• Gated imports — only a curated subset of the standard library is importable: math, json, re, datetime, time, random, collections, itertools, functools, operator, string, textwrap, decimal, fractions, statistics, copy, pprint, base64, hashlib, hmac, struct, io, csv, pathlib, typing, dataclasses, enum, abc. Dangerous modules — os, subprocess, shutil, ctypes, socket, and third-party packages like psutil or mss — raise ImportError with guidance to use execute_script or run_command instead.
• No filesystem access beyond output_dir — the code can open() files it writes into the provided output_dir variable, but cannot reach the rest of the filesystem without going through a gated import.

The LLM cannot escape this sandbox. Internal first-party callers (e.g. the agent's own screenshot capture path in agent/src/session_exec.py) pass trusted=True, which restores full builtins and unrestricted imports; that flag is not reachable from the LLM-exposed tool schema.

Returns: stdout from print(), plus any files written to output_dir.

read_file

Read the contents of a file on the remote machine.

write_file

Write content to a file on the remote machine.

list_directory

List the contents of a directory with file sizes and modification dates.

execute_script

Execute a PowerShell script on the remote machine with no command restrictions. Use for software installs, diagnostics, stress tests, service management, registry edits, or any other admin task. For most routine sysadmin scenarios, prefer a purpose-built Tier 2 tool (e.g. manage_windows_service, registry_operation, clean_disk_space) — execute_script is the escape hatch when no purpose-built tool fits.

Returns: stdout, stderr, exit code.

Timeouts are capped at 3300 seconds (55 minutes) so a result stays retrievable; for jobs that run longer than that, launch the work detached (e.g. a background job or scheduled task) and check back in a follow-up turn rather than blocking the tool call. A running execute_script can be cancelled from its tool card — the process tree is killed within a few seconds and the card resolves to "cancelled by user".

deploy_software

Deploy and install software on the remote machine using the full deployment pipeline: download installer, run silent install, verify installation, and track progress. Creates a tracked deployment visible on the Deployments page. Server-side — orchestrated by the server, not the agent directly.

Requires user confirmation before execution. hoot will summarize the deployment plan (software, version, install path, parallel install status, processes to close) and wait for explicit approval before proceeding.

TouchDesigner specifics: Download URL is auto-constructed from version number. parallel_install is automatically enabled to prevent the installer from removing existing builds. Use the full installer, not the WebInstaller.

Silent flag formats by installer type:

• Inno Setup: /VERYSILENT /SUPPRESSMSGBOXES /NORESTART /DIR="path"
• NSIS: /S /D=path
• MSI: /quiet /norestart INSTALLDIR="path"

reboot_machine

Reboot the remote machine with a 30-second countdown delay. Can be cancelled from the dashboard or via cancel_reboot within the countdown window.

shutdown_machine

Shut down the remote machine with a 30-second countdown delay. The machine will NOT automatically restart.

cancel_reboot

Cancel a pending reboot or shutdown. Must be called within the 30-second countdown window.

security model

tool execution flow

LLM decides to call a tool
  |
  +-- Tier 3: pause for in-chat approval (when the per-site approval gate is on)
  |     +-- User approves: continue to the tool-name execution path
  |     +-- User denies: return "denied by user"
  |
  +-- Server-side tools
  |     +-- get_site_logs / get_system_presets query Firestore on the web server
  |     +-- deploy_software creates deployment records and install commands server-side
  |     +-- update_process / add_process / delete_process call process action functions server-side
  |     +-- create_talon / list_talons / set_talon_enabled call the talon store server-side
  |     +-- schedule_followup / cancel_followup write the chat's follow-up records;
  |         the once-a-minute cron sweep fires them, with tier 3 forced to wait
  |         for approval and site access re-resolved at fire time
  |
  +-- Legacy command-mapped tools
  |     +-- Write existing command types such as restart_process or reboot_machine
  |     +-- Agent handles the legacy command and writes completion state
  |
  +-- Firestore mcp_tool_call tools
        +-- Create an mcp_tool_call command in Firestore
        +-- Agent receives and executes the MCP tool
        +-- Agent writes result to completed queue
        +-- Turn runner polls for the result (bounded by the tool's own timeout)

The turn runs server-side, detached from the browser connection — it keeps executing and its results still land in the chat even if the connection drops or the page reloads, and the client reattaches to stream it. Long-running shell tools (run_command, run_powershell, execute_script) can be cancelled from their tool card mid-flight: the agent kills the process tree and the card resolves to "cancelled by user". The whole turn can be stopped server-side from the chat.

command allowlists

run_command enforces an allowlist on the agent side. Even if a command is sent via Firestore, the agent rejects it if the first command isn't in the allowlist. run_powershell has no allow-list — it accepts arbitrary PowerShell, with accountability provided by mandatory audit logging (site events feed + local [MCP-AUDIT] log). run_python enforces its sandbox on the agent side — the LLM cannot override the import gate or restore blocked builtins.

tier 2 blocklists

Tier 2 tools enforce per-tool blocklists to prevent self-inflicted outages:

• manage_process — critical system processes (lsass, winlogon, csrss, etc.) cannot be killed
• registry_operation — SAM, SECURITY, and Cryptography hives are unreachable; only an allowlist of safe key prefixes is permitted
• manage_windows_feature — core Windows features Owlette depends on (NetFx4, WMI-*, PowerShell*) cannot be removed
• create_talon — command outputs are site-admin only, and webhook URLs that resolve to private, loopback, or link-local addresses are rejected

Agent-executed Tier 2 tools emit structured [MCP-AUDIT] log entries for each invocation. Server-side process config tools use the process mutation audit path with actor cortex:user_<userId>. Talon tools emit talon_mutated rows with the same actor, via: "cortex", and the originating chat id. The follow-up tools emit no mutation row of their own — the follow-up document is the record, and the DELETE /api/hoot/followups/{followupId} route behind the composer chip audits its own cancels as chat_mutated / verb cancel_followup.

agent-side limits

• Subprocess timeout: 25 seconds (default; overridable per-tool where applicable)
• Max output size: 50KB
• Screenshot max size: 10MB