Agent Tools

Agent tools cover everything you do to and through your installed agents: discovery (counts, lists, group lookups), context (host summaries), command dispatch (shell, PowerShell, WMI, LDAP, Windows Event Log), reading log files on any platform and the systemd journal on Linux, and performance observation — system metrics on Linux, counters and live ETW traces on Windows. All execution, log-reading, performance, and tracing tools are session-scoped — open a session first, then pass the session_id to whichever tool the task needs.

Discovery

These tools answer "what agents are out there" without running anything on a host.

agent_count

Returns total matches plus a faceted breakdown by os_family, status, and group_id for the same filter as agent_list. Call this first in tenants of unknown size to decide whether to narrow before pulling full agent records. Counting is cheap and avoids the context cost of a full list.

Use cases. Sanity-check fleet size before planning an assessment. Decide whether to filter a query (by status, OS, or group) before listing. Get a quick OS distribution overview.

Parameter	Type	Required	Description
status	string	—	One of online, offline, stale, command_ready.
os_family	string	—	One of windows, linux, darwin.
capability	string	—	Exact match on an advertised capability, such as ldap, wmi, etw, journald, or mcp_proxy.
search	string	—	Case-insensitive substring on hostname or display name.
group_id	string	—	Restrict to members of a specific agent group.

Example prompt.

"How many online Windows agents do we have right now?"

The response carries total plus a facets map keyed by os_family, status, and group_id so you can read the breakdown without a second call.

This is also the right way to answer "does this fleet have a host that can do X". Because a count is never truncated the way a page is, capability="mcp_proxy" returns the exact number of proxy-capable hosts in one call — more reliable than listing agents and inspecting their capability arrays, which only ever sees one page.

agent_list

Lists agents with paginated, filtered results. Returns an envelope { agents, total, limit, offset, has_more } and a lean record per agent (agent_id, hostname, display_name, os, os_family, arch, version, capabilities, online, command_ready, status, group_ids). Default page size is 50, maximum 200.

Use cases. Find a host by hostname substring. Pull every member of a specific agent group. List all online Linux agents to plan a Linux-only assessment.

Parameter	Type	Required	Description
status	string	—	online, offline, stale, or command_ready.
os_family	string	—	windows, linux, or darwin.
capability	string	—	Exact match on an advertised capability, such as ldap, wmi, etw, journald, or mcp_proxy.
search	string	—	Case-insensitive substring on hostname or display name.
group_id	string	—	Restrict to a specific group.
limit	integer	—	Default 50, max 200.
offset	integer	—	Pagination offset.

Example prompt.

"Find online Windows hosts whose hostname starts with 'AHW-ITD'."

Capability matching is exact rather than partial, because capability names are a closed set — a partial match for etw would also select hosts that only advertise etw_autologger.

A page is not the fleet

total is always the exact match count, but a page is capped at 200. A result carrying has_more: true means you have seen one page, not the whole fleet, and it can never prove that nothing matches. To answer "does any host have X", pass the filter that expresses X and read total — or call agent_count. Tenants are expected to reach 100–1,000 agents, so an unfiltered listing is never a fleet-wide answer.

agent_get

Fetch a single agent by agent_id. Returns the same lean record as agent_list entries. Use when you already have the ID — for example, when an ID was returned by agent_get_host_summary or recalled from a prior conversation — and you need to confirm current state before dispatching commands. The agent_id is always a UUID; passing a hostname is rejected, so if you only have a hostname, call agent_list(search="<hostname>") first and use the agent_id it returns.

Example prompt.

"Is agent 7b1c4d2e-3f8a-4c2d-9e6f-1a2b3c4d5e6f still online and ready for commands?"

agent_get_host_summary

Returns a comprehensive picture of a host in one call: agent metadata, recent sessions, every insight ever saved against it, and the current-state inventory snapshot — system facts plus counts of inventoried software, services, and certificates with snapshot freshness. Use this whenever you need prior context — when a user says "resume work on this host", "what did we find last time", or "pick up where we left off". This is the right call for continuity, not a manual loop over session_list plus insight_list.

The inventory section is omitted for hosts that have never been inventoried. Drill into the details with the per-host inventory tools. This tool absorbed the former inventory_get_host_summary, which no longer exists.

Example prompt.

"Resume work on AHW-ITD-10 — what did we find last time?"

Sample response.

{
  "agent": { "agent_id": "7b1c4d2e-3f8a-4c2d-9e6f-1a2b3c4d5e6f", "hostname": "AHW-ITD-10", "online": true },
  "recent_sessions": [
    { "session_id": "9c4d8e1f-2a3b-4c5d-8e6f-7a8b9c0d1e2f", "playbook": "security-review-agent", "status": "completed", "started_at": "2026-04-12T09:14:00Z" }
  ],
  "insights": [
    { "insight_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "severity": "high", "key": "smb_signing_disabled", "status": "open" },
    { "insight_id": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f", "severity": "medium", "key": "stale_local_admin", "status": "acknowledged" }
  ],
  "inventory": {
    "system": { "os_name": "Windows Server 2022", "domain_role": "member" },
    "counts": { "software": 214, "services": 187, "certificates": 32 },
    "as_of": "2026-06-10T22:00:00Z"
  }
}

Grouping

agent_group_list

Lists agent groups with filters and pagination. Returns full group metadata per record — group_id, name, description, environment, role, domain, site, criticality, type, member_count, agent_ids, and tags. Use this to find pivot groups by attribute (such as role=domain_controller or environment=prod), then call agent_list(group_id=…) to hydrate the actual member agents.

Parameter	Type	Required	Description
search	string	—	Substring on name, description, role, or domain.
environment	string	—	Exact match on environment (e.g. prod, staging).
criticality	string	—	Exact match on criticality (e.g. low, medium, high).
type	string	—	static or dynamic.
agent_id	string	—	Only return groups containing this agent.
limit	integer	—	Default 50, max 200.
offset	integer	—	Pagination offset.

Example prompt.

"List all groups with role 'domain_controller' in the production environment."

agent_group_get

Get a specific group by group_id. Returns full metadata plus the list of member agent_ids. Use when you need the deep state of one group; for the more common case of "given an agent, what groups does it belong to and who are the siblings", call agent_groups_for_agent instead.

Example prompt.

"Show me everything about group grp_dc_prod."

agent_groups_for_agent

Resolves the curated context around a single agent in one round trip. Pass agent_id; the response carries groups (up to 200 groups the agent belongs to, with full metadata), siblings (up to 200 visible sibling agents that share at least one of those groups), and a siblings_has_more flag. When siblings_has_more is true, refine with agent_list(group_id=…) against the relevant pivot group.

This replaces the older pattern of calling agent_group_list(agent_id=…) and then looping agent_get/agent_list(group_id=…). Use it whenever you have a chosen agent and need its purpose-context — what roles or environments it serves, who else plays the same role — before commanding the host or recording insights.

Example prompt.

"What groups is AHW-ITD-10 in, and which other hosts share those groups?"

Remote Execution

These session-scoped tools take a session_id (not agent_id — the target is derived from the session). Output is returned as stdout, stderr, and an exit_code with timing metadata. Each tool requires a specific agent capability; calls to agents missing that capability fail fast.

timeout_seconds is capped at one hour; larger values are silently clamped to that ceiling.

WARNING

Execution tools can run any command the target supports — including destructive ones (Remove-*, rm, shutdown, Stop-Service, format-volume). Prefer read-only verbs (Get-*, Test-*, Measure-*, cat, journalctl) for assessments. Reserve writes for explicit remediation tasks the user has approved.

TIP

For purely investigative PowerShell, reach for agent_exec_powershell_readonly instead — it validates each script against an admin-managed command policy and blocks anything that looks like it changes host state before the script ever reaches the host.

agent_exec_shell

Executes a bash/sh command on a Linux or macOS agent. Requires the shell capability. Pipe large outputs through head, tail, or grep to keep responses small.

Parameter	Type	Required	Description
session_id	string	✓	The running session ID.
command	string	✓	The shell command to execute.
timeout_seconds	number	—	Default 30. Increase for slow operations like package scans.

Example prompt.

"On the running session, show me the last 50 lines of /var/log/auth.log."

The response carries stdout, stderr, exit_code, and duration_ms — the same envelope returned by every agent_exec_* tool.

agent_exec_powershell

Runs a PowerShell command or script on a Windows agent. Requires the powershell capability. The script goes in the script argument — note that agent_exec_shell uses command for POSIX shell input, but this tool uses script.

To keep responses small, pipe through Select-Object -First N, project only the properties you need, and convert with ConvertTo-Json -Depth 3 -Compress.

Parameter	Type	Required	Description
session_id	string	✓	The running session ID.
script	string	✓	The PowerShell command or script.
timeout_seconds	number	—	Default 30. Increase for slow AD or certificate operations.

Example prompt.

"List the running services on this host as JSON, including name and display name."

agent_exec_powershell_readonly

Runs read-only PowerShell for assessment work, with a safeguard the write-capable agent_exec_powershell does not have: before anything is dispatched, InfraScout validates the script against a command policy. If the script appears to change host state, the call is blocked and never reaches the host — you get structured feedback explaining what tripped the check instead of command output. Only scripts that read state actually run. Requires the powershell capability, takes the script in script, and returns the same stdout/stderr/exit_code/duration_ms envelope as agent_exec_powershell when a script passes.

The command policy is managed by your administrators: a curated baseline that blocks host-mutating cmdlets, plus any allow or deny rules they add. When a target agent belongs to more than one group, the most restrictive combination applies. Every blocked attempt is recorded in the session's audit trail alongside successful executions, so a denied call is visible in review rather than silently dropped.

Because it cannot change the host, this tool is also available to read-only Task Agents, which are denied the write-capable execution tools by design. Reach for it whenever the task is purely investigative and you want the guarantee that nothing you run can modify the target.

Parameter	Type	Required	Description
session_id	string	✓	The running session ID.
script	string	✓	The read-only PowerShell command or script.
timeout_seconds	number	—	Default 30. Increase for slow AD or certificate operations.

Example prompt.

"Read-only: show me the local administrators group membership on this host as JSON."

agent_exec_wmi

Runs a WQL (WMI Query Language) query on a Windows agent. Requires the wmi capability. This call is query-only — for WMI method invocation use agent_exec_powershell with Invoke-CimMethod.

Always select specific properties; avoid SELECT * because it returns large objects. Common namespaces: root\cimv2 (OS, hardware, processes, services), root\SecurityCenter2 (AV/firewall), root\MicrosoftDNS (DNS zones), root\CIMV2\Security\MicrosoftVolumeEncryption (BitLocker).

Parameter	Type	Required	Description
session_id	string	✓	The running session ID.
query	string	✓	A WQL query — SELECT specific properties, not *.
namespace	string	—	Defaults to root\cimv2.
timeout_seconds	number	—	Default 30.

Example prompt.

"Query WMI for installed antivirus products on this host."

WMI responses do not use the generic stdout/stderr/exit_code/duration_ms envelope. Each call returns the matched objects alongside a meta block (execution_ms, rows_returned, rows_examined, truncated) and a from_cache flag. from_cache is true when the call reused an existing connection to the namespace; the first query against a namespace opens that connection and runs slower, and subsequent queries to the same namespace are served from it.

agent_exec_ldap

Performs an LDAP search via an agent with the ldap capability. The call is search-only (base_dn, filter, attributes); for LDAP add/modify/delete, use agent_exec_powershell with the ActiveDirectory module.

Always specify attributes — omitting it returns every attribute and produces very large responses.

Parameter	Type	Required	Description
session_id	string	✓	Running session whose target agent has the ldap capability.
base_dn	string	✓	LDAP base DN, e.g. DC=corp,DC=example,DC=com.
filter	string	✓	LDAP search filter, e.g. (objectClass=user).
attributes	array	—	Attributes to return, e.g. ["sAMAccountName","mail"].
timeout_seconds	number	—	Applied to the dial and the search independently, so the worst-case wait is up to twice this value. Default 10s dial / 60s search.

Example prompt.

"List members of Domain Admins — sAMAccountName and mail only."

agent_exec_daemon_start

Spawns a long-lived daemon on a Linux agent that must survive both the originating call's timeout and a restart of the agent itself — for example splunk start, custom service-start scripts, or anything that forks a service meant to outlive the call. Use this instead of agent_exec_shell for commands that intentionally daemonize: a daemon started through the shell tool dies when the call times out or the agent restarts.

The call is argv-only — pass the binary in program and its arguments in args; there is no shell layer, so pipes and redirects do not work. Where a proper service unit already exists, prefer routing through systemctl (program: "/usr/bin/systemctl", args: ["restart", "splunk"]). The response includes the name of the transient unit the daemon runs in, which operators can inspect with systemctl status.

Requires the daemon_start capability, which only systemd-managed Linux agents advertise — macOS, Windows, and non-systemd Linux hosts reject the call.

Parameter	Type	Required	Description
session_id	string	✓	Running session whose target agent has the daemon_start capability.
program	string	✓	The binary to spawn — absolute path or PATH-resolvable name.
args	array	—	Arguments passed verbatim to the program.

Example prompt.

"Restart the Splunk forwarder on this host — it has to keep running after we're done."

agent_list_event_logs

Lists available Windows Event Log channels on an agent. Requires the eventlog capability. Returns name, record_count, is_enabled, and last_write_time per channel — last_write_time is useful for spotting which channels are still actively receiving events.

Always pass a filter if you know what you are looking for. Unfiltered enumeration walks roughly 1000 channels and takes about a second; filtered enumeration (e.g. Microsoft-Windows-PowerShell*, *Defender*) finishes in tens of milliseconds.

Parameter	Type	Required	Description
session_id	string	✓	The running session ID.
filter	string	—	Wildcard pattern. Defaults to *.
enabled_only	boolean	—	Defaults to true.

Example prompt.

"Which PowerShell event log channels are enabled on this host?"

agent_query_event_log

Queries Windows Event Log entries on an agent. Requires the eventlog capability. Each entry returns structured fields (time_created, provider_name, event_id, level, message, channel, computer) plus an event_data map of the event's parameter values — prefer event_data["FieldName"] over regex-parsing the message, and prefer this tool over Get-WinEvent via agent_exec_powershell.

Filtering happens in two layers. Event IDs, level, provider, time bounds, and computer name are applied through the channel's index and keep queries fast — make these as selective as you can. The event_data_match* predicates (exact, prefix, and substring matches on named event_data fields, such as {"TargetUserName": "svc_sssd"}) and case-insensitive matching are applied on the agent after rendering, scanning every event the indexed filter lets through. That scan is bounded by max_examined; when the cap fires before max_events is satisfied, the response sets meta.examined_limit_hit — narrow the indexed filters or raise the cap. Predicates handled in the post-filter layer are reported in meta.post_filtered, and predicates whose values could not be expressed safely (quotes or angle brackets) are dropped and reported in meta.dropped_predicates, so you can detect an under-filtered query.

When the structured filters cannot express a query, pass raw_xpath — a complete XPath 1.0 filter applied verbatim, the same language Event Viewer and Get-WinEvent -FilterXPath use. It cannot be combined with the structured filters (event_ids, event_data_match*, level, and so on); the tool rejects the combination before anything runs, and a malformed filter returns an error. When you only need volume — "how many 4771 failures this week" — pass count_only to get the match count plus a per-event-ID breakdown instead of the entries themselves. The count is bounded by the max_examined ceiling, and the result flags when the ceiling was reached, so a floored count is identifiable.

INFO

raw_xpath and count_only require an up-to-date agent version. An older agent ignores them — a raw_xpath sent to an old agent returns unfiltered results — so keep the fleet current via agent updates.

Events come back newest-first (descending time_created), so max_events keeps the most recent N — "the last 50" means the 50 most recent entries. Keep max_events at 50 or below; large logs produce huge responses. For chatty channels (Sysmon, PowerShell/Operational, AppLocker) where event_data dominates response size, set truncate_event_data_chars (and optionally truncate_message_chars) to cap each field — the response's meta.truncated flag indicates when content was elided. Selective event_data_match* predicates over wide time windows on chatty channels often need a raised timeout_seconds.

Parameter	Type	Required	Description
session_id	string	✓	The running session ID.
log_name	string	—	Channel name. Defaults to System.
event_ids	array	—	One or more event IDs, e.g. [4624, 4625]. Indexed — prefer this as the primary narrowing filter.
event_data_match	object	—	Exact-equality predicates on named event_data fields, AND-composed.
event_data_match_prefix	object	—	Prefix predicates, e.g. {"TargetUserName": "svc_"}.
event_data_match_contains	object	—	Substring predicates, e.g. {"ScriptBlockText": "Invoke-Mimikatz"}.
match_case_insensitive	boolean	—	Case-insensitive matching for all value predicates (ASCII only). Default false.
raw_xpath	string	—	Complete XPath 1.0 filter applied verbatim. Cannot be combined with the structured filters.
count_only	boolean	—	Return the match count plus a per-event-ID breakdown instead of the entries. Default false.
computer	string	—	Originating computer — useful on ForwardedEvents and other collector channels.
hours_ago	number	—	Last N hours. Mutually exclusive with time_after/time_before.
time_after / time_before	string	—	RFC3339 bounds for forensic queries with absolute windows.
level	string	—	Critical, Error, Warning, Information, or Verbose.
provider	string	—	Filter by event source/provider.
max_events	number	—	Default 50, recommended max 100.
max_examined	number	—	Scan cap for event_data predicates. Default max_events × 20 (min 1000), ceiling 10000.
truncate_event_data_chars	number	—	Cap each event_data value. 256–512 recommended for chatty channels.
truncate_message_chars	number	—	Cap the message field.
timeout_seconds	number	—	Default 30. Raise for event_data predicates over wide windows.

Example prompt.

"Show me failed logons (4625) for accounts starting with svc_ in the last 24 hours."

Log Files & Journals

Reading a log is its own kind of question, and it is the one place where a shell command is the wrong instrument: tail, grep, cat, and journalctl return whatever they find as a raw dump, and the three lines that answer the question arrive buried in four thousand that do not. Two tools cover this case instead — one for text log files, one for the systemd journal. Both narrow on the host and return a capped, structured result, so a multi-gigabyte log can answer a question without flooding the conversation.

File reading works on Windows, Linux, and macOS alike. The journal tool is Linux-only. For Windows Event Log channels, use agent_query_event_log — those are structured events, not text lines.

agent_read_log_file

Reads a text log file at an absolute path on the target host. By default you get the last 200 lines; head_lines reads from the start of the file instead. Narrow the read with grep (a regular expression applied during the scan, so the filter runs before the line cap rather than after it), invert it with grep_invert to drop noise you already know about, and match case-insensitively with case_insensitive. dedupe_consecutive collapses runs of identical consecutive lines into one with a repeat count — a service that logged the same retry two thousand times contributes a single line. truncate_line_chars caps over-long lines so one thousand-column blob cannot blow the token budget, and since/until restrict the read to a time window based on each line's leading timestamp.

Two guards keep pathological files from ruining the call. max_scan_bytes bounds how much of a runaway log the agent walks, and the response flags when older bytes were skipped. And a single line past the internal scan cap does not discard the read: you get the lines scanned up to that point plus a scan_error note that the scan stopped early — treat that response as partial rather than complete.

Prefer this tool over agent_exec_shell whenever the target is a log file. On a Linux host running systemd, prefer agent_query_journald for anything the journal already holds.

Credential files are refused, not read

The agent runs with full system privileges, so an unrestricted file reader would be a credential-disclosure tool rather than a log reader. A hard denylist now refuses the well-known credential locations outright — the Windows SAM and SECURITY hives and their shadow copies, /etc/shadow, SSH and TLS private keys, cloud-provider token caches, and the agent's own certificate material among them. A refused path returns an explanation and never reaches the file system, and the rule applies to every caller regardless of role. Matching is done on the resolved path, so a UNC share, a shadow-copy path, a .. traversal, or a symlink pointing at a denied file is refused the same way.

Parameter	Type	Required	Description
session_id	string	✓	Running session ID; the target agent must advertise the log-file capability.
path	string	✓	Absolute path to the text log file on the host, e.g. /var/log/syslog.
tail_lines	number	—	Last N lines, newest last. Default 200, max 5000. The primary mode — logs are append-ordered.
head_lines	number	—	First N lines instead of the tail. Max 5000. Mutually exclusive with tail_lines.
grep	string	—	Regular expression; only matching lines are returned. Applied during the scan, before the line cap.
grep_invert	boolean	—	Return only the lines that do not match grep.
case_insensitive	boolean	—	Case-insensitive grep matching.
dedupe_consecutive	boolean	—	Collapse runs of identical consecutive lines into one, marked with a repeat count.
truncate_line_chars	number	—	Per-line character cap. Default 2000, max 100000. Raise it to keep longer lines.
include_line_numbers	boolean	—	Prefix each line with its line number within the scanned window.
since / until	string	—	RFC3339 bounds matched against each line's leading timestamp. Lines with no parseable timestamp are dropped while a time filter is active.
max_scan_bytes	number	—	Runaway guard — scan at most this many bytes. Default 100 MiB, max 1 GiB.
timeout_seconds	number	—	Dispatch timeout. Default 30.

Example prompt.

"This update failed around 14:30 — read the servicing log for that window and tell me why."

Timestamp Handling

Time windows are matched against the timestamp each line carries, and how that timestamp is read depends on whether the log states a timezone.

Logs that write a local wall-clock time with no timezone — syslog, dpkg, Python, MySQL, Postgres, and the Windows CBS and DISM servicing logs among them — are interpreted in the host's local time, which is what they actually mean. The since and until bounds you pass are matched against that, so ask for the window in the host's local time rather than converting it to a UTC instant first. Logs that carry an explicit timezone (RFC 3339, Apache) are interpreted absolutely, as written.

Syslog lines carry no year at all. InfraScout infers the year the line belongs to, so a December line read in January is dated correctly instead of landing eleven months in the future and falling out of a "last 24 hours" window.

This needs an up-to-date agent

Log reading runs on the host, so it ships in the agent binary. Hosts still on an older build reject the command with an error until they update — keep the fleet current via agent updates.

Because this is a structured tool rather than a shell command, it is also available to read-only Task Agents, which are denied the shell execution tools by design. A delegated read-only investigation can open the log file it needs without ever holding a tool that could change the host. For the full story, see A Log File Reader That Doesn't Flood the Conversation.

agent_query_journald

Queries the systemd journal on a Linux agent — the Linux counterpart of agent_query_event_log. Every filter is pushed down into journalctl rather than applied after the fact, and entries come back as fixed-key objects, newest first, with priority names spelled out instead of numbered. Reach for it over agent_exec_shell plus journalctl for anything the journal holds: authentication and sudo activity, sshd, kernel messages, or a single unit's history.

Filters compose. unit narrows to one systemd unit, identifier catches programs that log without one, priority names a severity and returns that level and everything more severe (journald's own semantics — err also returns crit, alert, and emerg), grep applies a regular expression to the message text, and kernel gives you the dmesg equivalent. Bound the window with hours_ago or an absolute since/until pair, or restrict to the current boot.

For "how many" questions, count_only skips paging entries entirely and returns a match count with per-priority and per-unit breakdowns. That is the right shape for questions like "how many failed SSH logins overnight" — you get the number and where it concentrated without carrying thousands of entries through the conversation.

Parameter	Type	Required	Description
session_id	string	✓	Running session whose target agent advertises the journald capability.
unit	string	—	One systemd unit, e.g. sshd.service. Omit for all units.
identifier	string	—	Syslog identifier, e.g. sudo, CRON — for programs that log without a unit.
priority	string	—	Severity name (emerg through debug) or 0–7. Returns that level and everything more severe.
grep	string	—	Regular expression applied to the message text. An all-lowercase pattern matches case-insensitively.
current_boot	boolean	—	Restrict to the current boot.
kernel	boolean	—	Kernel messages only — the dmesg equivalent. Implies the current boot.
hours_ago	number	—	Relative window in hours, fractions allowed. Mutually exclusive with since/until.
since / until	string	—	Absolute RFC3339 bounds. Mutually exclusive with hours_ago.
max_events	number	—	Entries returned, newest first. Default 100, max 1000.
truncate_message_chars	number	—	Per-message cap. Default 2000, max 100000.
count_only	boolean	—	Return match_count plus per-priority and per-unit breakdowns instead of entries.

Example prompt.

"How many failed SSH logins did this host see in the last 12 hours, and from which units?"

Reading the system journal requires privilege the agent normally has, so the journald capability appears only on Linux hosts where the agent can actually read it. Where the host's journalctl is too old to push a regex down, the agent falls back to scanning the newest entries itself and flags the response, so a partial answer is never presented as a complete one.

Performance & Tracing

These tools watch a host over time rather than running a single command: read performance counters or system metrics as a snapshot or a short series, and start background ETW (Event Tracing for Windows) sessions that keep recording on the host — across the conversation ending and even agent restarts — until you stop them. All seven are session-scoped and require an up-to-date agent that advertises the matching capability.

Platform support splits cleanly. Counter reads and ETW tracing are Windows-only; agent_perf_read_metrics is the Linux equivalent for system vitals and returns the same output shape, so a fleet-wide performance question reads the same either way.

INFO

These tools require a current agent version. An older agent does not advertise the performance-counter, metrics, or ETW capability and rejects the call, so keep the fleet current via agent updates.

The curated capture profiles in Data Collection Sets build on the same tracing engine — reach for those first when your investigation matches a common scenario, and use agent_trace_start directly when you need to choose providers yourself.

agent_perf_list_counters

Discovers which Windows performance counter objects, counters, and instances exist on a host. The available set is host-specific — the directory-service (NTDS) objects appear only on domain controllers, SQLServer:* only where SQL Server is installed, Web Service only on IIS — so call this first to learn what the target exposes before reading values with agent_perf_read_counters. Always pass object_filter when you know roughly what you are after; an unfiltered listing returns hundreds of objects. Set include_detail=true (combined with a filter) to get each matched object's counter and instance names — exactly what you need to build \Object(Instance)\Counter paths. Counter names come back in English regardless of the host's display language.

Parameter	Type	Required	Description
session_id	string	✓	Running session ID from session_start; the target agent must advertise the performance-counter capability.
object_filter	string	—	Case-insensitive substring on object names, e.g. NTDS, processor, logicaldisk. Always pass one when you can.
include_detail	boolean	—	Also return each matched object's counter and instance names. Combine with object_filter — detail for every object is very large.
timeout_seconds	number	—	Discovery timeout. Default 30.

Example prompt.

"What performance counters does this domain controller expose for the directory service?"

agent_perf_read_counters

Reads Windows performance counter values — a point-in-time snapshot, or a short sampled window with a per-instance time series plus min/max/avg/last aggregates. counter_paths take English names in the form \Object(Instance)\Counter — for example \Processor(_Total)\% Processor Time, \LogicalDisk(*)\Avg. Disk sec/Read, or \NTDS\LDAP Searches/sec — with * in the instance slot expanding to all instances; at most 20 paths per call, local counters only. Because counters are host-specific, discover exact names with agent_perf_list_counters (include_detail=true) first. duration_seconds=0 (the default) returns a single snapshot (roughly one to two seconds, since rate counters need two internal samples); a value above 0 samples every interval_seconds over the window and is capped at 300 seconds — this is a short-window read, so take repeated reads for longer observation. Output is bounded at 200 expanded instances and 2000 total series points; when the point cap trips, the series are trimmed but the aggregates still come back.

Parameter	Type	Required	Description
session_id	string	✓	Running session ID; target agent must advertise the performance-counter capability.
counter_paths	array	✓	English \Object(Instance)\Counter paths. Max 20 per call; local counters only.
duration_seconds	number	—	Sampling window. 0 or omitted returns a snapshot; values above 300 are clamped to 300.
interval_seconds	number	—	Seconds between samples in a windowed read. Default 1. Raise it on longer windows to stay under the point cap.
timeout_seconds	number	—	Optional; derived as duration_seconds + 30s grace when omitted, so the window is never truncated.

Example prompt.

"Sample CPU, disk queue length, and available memory on this host for a minute and give me the peaks."

agent_perf_read_metrics

Reads Linux performance metrics — the counterpart to agent_perf_read_counters, in the same snapshot-or-window shape with the same min/max/avg/last aggregates, so the two read identically when you compare a Windows host to a Linux one.

The difference is what you ask for. Windows counters are named paths you have to discover first; here you name categories and InfraScout knows where the numbers live. Omit metrics and you get the system-vitals default — CPU (total and per core, including I/O wait), memory (used, available, cached, swap), disk throughput and IOPS per real device, network throughput and error rates per interface, and load averages. Add process when you want the heaviest processes as well; top_n sets how many to return by CPU and by memory.

Results use dotted metric paths with an instance, so a value identifies itself: cpu.usage_pct on instance cpu0, disk.read_bytes_sec on sda, network.rx_bytes_sec on eth0. Windowing works exactly as it does for counters — duration_seconds of 0 is a snapshot, anything higher samples every interval_seconds and is capped at 300 seconds, and the dispatch timeout is derived from the window so sampling is never cut short.

Parameter	Type	Required	Description
session_id	string	✓	Running session ID; target agent must advertise the Linux metrics capability.
metrics	array	—	Categories to sample: cpu, memory, disk, network, load, process. Omit for the system-vitals default (everything but process).
duration_seconds	number	—	Sampling window. 0 or omitted returns a snapshot; values above 300 are clamped to 300.
interval_seconds	number	—	Seconds between samples in a windowed read. Default 1.
top_n	number	—	With process, how many processes to return by CPU and by memory. Default 10, max 50.
timeout_seconds	number	—	Optional; derived as duration_seconds + 30s grace when omitted.

Example prompt.

"This Linux box feels slow — sample CPU, memory, and disk for thirty seconds and show me the top processes."

Prefer this over agent_exec_shell with top, vmstat, or cat /proc/...: those return text you then have to parse, while this returns numbers already keyed and aggregated. The capability is probe-backed, so a non-Linux agent — or a Linux host where the agent cannot read the kernel's metrics interface — rejects the call with a clear not-supported error rather than returning something wrong.

agent_trace_start

Starts a persistent ETW trace on a Windows agent — background capture of DNS lookups, TCP/network activity, process and image events, and more, recorded on the host while you do other work. The kernel session persists past this call: it keeps recording after the tool returns, after the conversation ends, and across agent restarts, until agent_trace_stop is called or max_duration_seconds elapses (default 24 hours, maximum 7 days). Events are written as a ring of size-capped .etl segments — the agent keeps at most four segments per trace (the active one plus the newest sealed ones; older ones are deleted oldest-first), so on-host disk use is bounded by max_file_mb × 4. providers accepts well-known aliases (dns, kernel-process, kernel-network, tcpip, smb-client, smb-server) or a registry-format {GUID}. A host allows at most four concurrent InfraScout trace sessions, shared with collection_start — call agent_trace_list to see what is already running. Returns trace_id (the handle for reading and stopping), the kernel session name, the segment file pattern, and the expiry timestamp.

Parameter	Type	Required	Description
session_id	string	✓	Running session ID; target agent must advertise the ETW capability.
providers	array	✓	ETW providers to enable — well-known aliases or registry-format {GUID} strings. At least one required.
max_duration_seconds	number	—	Trace lifetime before the agent's reaper stops it. Default 86400 (24h), max 604800 (7d); larger values are clamped.
max_file_mb	number	—	Size at which the current segment rolls to a new file. Default 256, max 1024.
timeout_seconds	number	—	Dispatch timeout for the start call only. Default 15. It does not bound the trace, which outlives the call.

Example prompt.

"Start a DNS and network trace on this host — something resolves intermittently and I'll check back later."

agent_trace_read

Reads recorded events from a trace — a bounded decode, newest segments first: up to max_events (default 100, hard cap 1000). If the trace is still running, reading never stops or alters it, so call again for fresher events. Narrow with provider_filter (an alias like dns or a {GUID}), event_ids, since/before (RFC3339 bounds), min_severity (returns that level or more severe), and a property_key/property_contains pair that substring-matches a named decoded property. Events come back decoded and legible — friendly provider, event, and operation names instead of raw numeric codes, and for DNS and Kerberos results a plain-language meaning alongside the status code. meta reports examined and whether the cap truncated the read. The authoritative events_lost figure comes from agent_trace_list/agent_trace_stop, not this call's meta.

Parameter	Type	Required	Description
session_id	string	✓	Running session ID; target agent must advertise the ETW capability.
trace_id	string	✓	The trace handle from agent_trace_start or agent_trace_list.
provider_filter	string	—	Restrict to one provider — an alias or a {GUID}.
event_ids	array	—	Only events with these IDs (0–65535).
since / before	string	—	RFC3339 lower/upper bounds; before must be after since.
max_events	number	—	Maximum decoded events. Default 100, hard cap 1000 (larger values clamped).
min_severity	string	—	critical, error, warning, informational, or verbose — returns that level or more severe.
property_key / property_contains	string	—	Keep events whose decoded property_key value contains property_contains (case-insensitive). Supply both.
timeout_seconds	number	—	Dispatch timeout. Default 30.

Example prompt.

"Read the Kerberos warnings and errors from that trace around 09:40 this morning."

agent_trace_stop

Stops a trace and returns its final statistics (events_lost, buffers_written, total_file_bytes, deleted). Data is destroyed only with delete_file=true, which irreversibly deletes the recorded .etl segments from the host. With delete_file=false (the default) the stopped trace is retained — its files stay on disk, it remains listed by agent_trace_list (with running=false), and its events stay readable via agent_trace_read until the trace's original expiry, when the agent's reaper reclaims them. Stopping frees one of the four concurrent trace slots. Only InfraScout's own sessions can be stopped; foreign ETW sessions are never touched.

Parameter	Type	Required	Description
session_id	string	✓	Running session ID; target agent must advertise the ETW capability.
trace_id	string	✓	The trace handle from agent_trace_start or agent_trace_list.
delete_file	boolean	—	Also delete the recorded .etl segments immediately. Default false keeps them readable until expiry.
timeout_seconds	number	—	Dispatch timeout. Default 30.

Example prompt.

"Stop that trace but keep the recording so I can read it again later."

agent_trace_list

Lists the InfraScout ETW trace sessions on a host — running and recorded — with each trace's providers, running state, start and expiry timestamps, recorded segment bytes, and events_lost. Use it to recover a trace_id handle, check how much a trace has captured so far, or see how many of the four concurrent slots are in use before starting another. Only sessions InfraScout created are listed; foreign ETW sessions (Defender, AutoLogger, and the like) are never visible or touched. A trace stopped with delete_file=false stays listed with running=false until its expiry.

Parameter	Type	Required	Description
session_id	string	✓	Running session ID; target agent must advertise the ETW capability.
timeout_seconds	number	—	Dispatch timeout. Default 30.

Example prompt.

"What traces are running on this host, and how many trace slots are free?"

See Also

For session lifecycle, see Sessions. For saving findings produced by these execution tools, see Insights. For the curated capture profiles built on these tracing primitives, see Data Collection Sets. For the agent installer and capability details, see Agents Overview.