Inventory Tools

Inventory tools query collected snapshots — system facts, software, services, and certificates that agents have reported back to InfraScout. They answer cross-fleet questions efficiently without dispatching live commands. For live state, use the corresponding agent execution tools.

Every inventory response carries the same freshness signal: an as_of timestamp marking the newest snapshot in the result, a staleness_seconds value (seconds since as_of), and a total count taken before pagination. A staleness_seconds of 0 means there was no matching data to age — it does not mean the data is fresh. Use staleness_seconds to decide whether the snapshot is recent enough or whether to fall back to a live agent execution.

String filters take an object

Wherever a parameter below is typed object, it is a string filter of the shape { "value": "chrome", "match_mode": "contains" }. match_mode is one of contains (the default), equals, starts_with, or ends_with, and all matching is case-insensitive. An empty value disables the filter.

Per-Host Tools

These return everything inventoried for one host. For a one-call host overview — system facts, inventory counts, and snapshot freshness, plus prior sessions and insights — use agent_get_host_summary; the former inventory_get_host_summary tool has been folded into it.

inventory_list_software_on_host

Lists every software package recorded in the last snapshot for a single host.

Parameter	Type	Required	Description
agent_id	string	✓	The agent ID.
limit	integer	—	Default 100, max 500.
skip	integer	—	Pagination offset.

Example prompt.

"Show me all installed software on AHW-ITD-10."

inventory_list_services_on_host

Lists every OS service recorded in the last snapshot for a single host.

Parameter	Type	Required	Description
agent_id	string	✓	The agent ID.
limit	integer	—	Default 100, max 500.
skip	integer	—	Pagination offset.

Example prompt.

"List all services on this host from the last inventory snapshot."

inventory_list_certificates_on_host

Lists every TLS or code-signing certificate recorded in the last snapshot for a single host.

Parameter	Type	Required	Description
agent_id	string	✓	The agent ID.
exclude_cas	boolean	—	Drop CA certificates. By default both end-entity and CA certs are returned.
limit	integer	—	Default 100, max 500.
skip	integer	—	Pagination offset.

Example prompt.

"List all end-entity certificates on this host — skip the CAs."

Fleet-Wide Tools

These pivot across many hosts. All accept either agent_ids (an explicit list) or agent_group_id (a logical pivot) to scope the fleet.

inventory_list_hosts

Queries host system facts across the fleet — OS name and version, architecture, domain, domain role, RAM, and boot time. Each row carries an inventoried flag: true means system facts have been collected, false means only the agent registration is known and only agent_id and hostname are populated. Stub rows are emitted only when no system-attribute filter is set.

Parameter	Type	Required	Description
agent_ids	array	—	Explicit agent ID list.
agent_group_id	string	—	Pivot through a group.
os_name	object	—	Match mode (contains/equals/starts_with/ends_with) plus value.
os_version	object	—	Same shape as os_name.
domain	object	—	Match mode plus value.
domain_role	string	—	Exact match (e.g. member, domain_controller).
architecture	string	—	Exact match (e.g. amd64).
ram_min_bytes	integer	—	Inclusive minimum.
ram_max_bytes	integer	—	Inclusive maximum.
booted_before	string	—	RFC3339 timestamp. Reliable on Linux/macOS; agents older than 0.8 on Windows may lack boot_time.
select	array	—	Field projection.
sort_by	string	—	hostname, os_name, boot_time, ram_total_bytes, or updated_at.
sort_order	string	—	asc (default) or desc.
limit	integer	—	Default 100, max 500.
skip	integer	—	Pagination offset.

Example prompt.

"List all Windows Server 2019 domain controllers across the fleet."

inventory_list_software

Cross-fleet software query. Use it for "which hosts have Java < 8u300" or "list every install of PuTTY". Note: install_date is populated only on Windows registry installs.

Parameter	Type	Required	Description
agent_ids	array	—	Scope to specific agents.
agent_group_id	string	—	Scope through a group.
name	object	—	Match mode plus value for software name.
publisher	object	—	Match mode plus value for publisher.
source	string	—	Exact source: registry, dpkg, rpm, snap, brew, pkgutil.
version_eq	string	—	Exact version match.
version_gt	string	—	Versions strictly greater than.
version_lt	string	—	Versions strictly less than.
select	array	—	Field projection.
sort_by	string	—	name, version, publisher, install_date, or updated_at.
sort_order	string	—	asc or desc.
limit	integer	—	Default 100, max 500.
skip	integer	—	Pagination.

Example prompt.

"Find every host with Java older than 8u300."

inventory_list_services

Cross-fleet OS service query. Use for "hosts with a stopped wuauserv service" or "services running as SYSTEM with auto startup".

Parameter	Type	Required	Description
agent_ids	array	—	Scope to specific agents.
agent_group_id	string	—	Scope through a group.
name	object	—	Match mode plus value.
display_name	object	—	Match mode plus value.
status	string	—	Exact status (e.g. running, stopped).
startup_type	string	—	Exact (Windows: automatic, automatic_delayed, manual, disabled).
run_as_account	object	—	Windows-only; match mode plus value.
select	array	—	Field projection.
sort_by	string	—	name, display_name, status, startup_type, or updated_at.
sort_order	string	—	asc or desc.
limit	integer	—	Default 100, max 500.
skip	integer	—	Pagination.

Example prompt.

"Across all production servers, which have services running as LocalSystem with auto startup?"

Service collection is not systemd-specific. Each Linux agent detects the service manager its host actually runs — systemd, procd on OpenWrt, OpenRC on Alpine and Gentoo, or SysV and BusyBox init — and reads it natively, so an embedded appliance contributes real rows rather than an error. What varies across managers is how much detail there is to report: startup_type is a Windows concept, and a SysV host can enumerate its services and their enabled state without being able to report a reliable running status, which comes back as unknown rather than being guessed at.

inventory_list_certificates

Cross-fleet TLS and code-signing certificate query. Use for "certs expiring in 30 days", "any SHA1-signed certs", or "self-signed certs in the Personal store".

Parameter	Type	Required	Description
agent_ids	array	—	Scope to specific agents.
agent_group_id	string	—	Scope through a group.
subject_cn	object	—	Match mode plus value.
issuer_cn	object	—	Match mode plus value.
store	object	—	Match mode plus value for cert store name.
expired_only	boolean	—	Only already-expired certs.
expires_within_days	integer	—	Mutually exclusive with expired_only.
is_self_signed	boolean	—	Filter on self-signed status.
exclude_cas	boolean	—	Drop CA certificates.
signature_algorithms	array	—	Exact match list (e.g. ["SHA1-RSA","MD5-RSA"] for weak crypto).
min_key_size	integer	—	Returns certs whose key size is less than this. RSA: 1024/2048/3072/4096; ECDSA curves: 256/384/521.
select	array	—	Field projection.
sort_by	string	—	subject_cn, issuer_cn, not_after, not_before, public_key_size, or updated_at.
sort_order	string	—	asc or desc.
limit	integer	—	Default 100, max 500.
skip	integer	—	Pagination.

Example prompt.

"Find every certificate expiring in the next 30 days, sorted by expiry."

inventory_list_changes

Lists inventory changes detected on one or more hosts since a given timestamp. Use this for change tracking — "what changed in the last 24 hours" or "any new services added this week".

Unlike the other fleet-wide tools, this one does not fan out across the whole fleet: you must scope it with agent_ids or agent_group_id. After visibility filtering, a single call covers at most 50 hosts — split larger groups into batches. Both since and a scope are required. Filter by category (software, services, system, certificates) and change type (added, removed, modified).

Parameter	Type	Required	Description
since	string	✓	RFC3339 timestamp — return changes detected at or after this time.
agent_ids	array	—	Scope to specific agents. Provide this or agent_group_id.
agent_group_id	string	—	Scope through a group. Provide this or agent_ids.
categories	array	—	One or more of software, services, system, certificates.
change_types	array	—	One or more of added, removed, modified.
limit	integer	—	Default 100, max 500.
skip	integer	—	Pagination.

Example prompt.

"What software changes were detected across our fleet in the last 24 hours?"

Distribution Tools

These return bucketed counts rather than individual rows. Because a bucketed count is an aggregation and not a page of results, neither tool paginates: they take no limit and no skip, and the parameters below are the complete set. Scope the fleet with agent_ids or agent_group_id, and bound the output with top_n where the tool offers it.

inventory_get_software_distribution

Returns the top-N most common software packages across the fleet, grouped by (name, version) and sorted by host count descending. Use it for "what are the most common applications" or "how many hosts have each version of Chrome installed".

top_n is the only thing that bounds the result — it caps how many buckets come back, and total reflects the number actually returned (≤ top_n). Raise top_n if you need more.

Parameter	Type	Required	Description
agent_ids	array	—	Scope to specific agents.
agent_group_id	string	—	Scope through a group.
name	object	—	Limit to packages matching this name. Omit for top-N across the fleet.
top_n	integer	—	Default 50, max 500.

Example prompt.

"What are the top 20 most common applications installed across the fleet?"

The response carries a buckets array. Each bucket is a key object holding the grouped fields — here name and version — alongside a count (the number of hosts with that package). There is no top-level name, version, or host_count. The envelope's total reflects the number of buckets returned (≤ top_n).

{ "buckets": [ { "key": { "name": "Google Chrome", "version": "126.0.6478.127" }, "count": 42 } ], "total": 1 }

inventory_get_system_distribution

Returns a bucketed count of hosts grouped by one or more system attributes. Use for fleet composition questions like "how many hosts run each OS version" or "distribution by domain role".

The number of buckets follows from group_by — you get one bucket per distinct combination of the attributes you group on, across the hosts in scope. Group on fewer attributes to get a coarser result.

Parameter	Type	Required	Description
group_by	array	✓	One or more of os_name, os_version, architecture, domain, domain_role.
agent_ids	array	—	Scope to specific agents.
agent_group_id	string	—	Scope through a group.

Example prompt.

"Show me the OS version distribution across our Windows fleet."

The response carries a buckets array. Each bucket is a key object holding the requested group_by fields, alongside a count (the number of hosts in that bucket). There is no top-level host_count.

{ "buckets": [ { "key": { "os_name": "Windows Server 2019", "domain_role": "domain_controller" }, "count": 6 } ], "total": 1 }

See Also

For live host state when inventory data is too stale, dispatch agent execution tools inside a session. For agent installation and what each platform inventories, see Agents Overview.