Agent Tools

Agent tools cover everything you do to and through your installed agents: discovery (counts, lists, group lookups), context (host summaries), and command dispatch (shell, PowerShell, WMI, LDAP, Windows Event Log). All execution tools are session-scoped — open a session first, then pass the session_id to whichever execution 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.
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.

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.
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'."

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.

Example prompt.

"Is agent ag_3f8a1c2d still online and ready for commands?"

agent_get_host_summary

Returns a comprehensive picture of a host in one call: agent metadata, recent sessions, and every insight ever saved against it. 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.

Example prompt.

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

Sample response.

{
  "agent": { "agent_id": "ag_3f8a1c2d", "hostname": "AHW-ITD-10", "online": true },
  "recent_sessions": [
    { "session_id": "sess_8c4d", "playbook": "security-review-agent", "status": "completed", "started_at": "2026-04-12T09:14:00Z" }
  ],
  "insights": [
    { "insight_id": "ins_1a2b", "severity": "high", "key": "smb_signing_disabled", "status": "open" },
    { "insight_id": "ins_3c4d", "severity": "medium", "key": "stale_local_admin", "status": "acknowledged" }
  ]
}

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

The five execution tools all 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.

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.

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 command argument (the same field name as agent_exec_shell — not 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.
command	string	✓	The PowerShell 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_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."

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 dial and search independently. Default 10s dial / 60s search.

Example prompt.

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

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.

Keep max_events at 50 or below; large logs produce huge responses. Use hours_ago and level to narrow before raising max_events. 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.

Parameter	Type	Required	Description
session_id	string	✓	The running session ID.
log_name	string	—	Channel name. Defaults to System.
max_events	number	—	Default 50, recommended max 100.
hours_ago	number	—	Limit to events from the last N hours.
level	string	—	Critical, Error, Warning, Information, or Verbose.
provider	string	—	Filter by event source/provider.
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.

Example prompt.

"Show me the last 20 logon events (4624) from the Security log."

See Also

For session lifecycle, see Sessions. For saving findings produced by these execution tools, see Insights. For the agent installer and capability details, see Agents Overview.