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. Each response carries an as_of timestamp so you know how fresh the data is; for live state, use the corresponding agent execution tools.

Per-Host Tools

These return everything inventoried for one host.

inventory_get_host_summary

Returns system facts, plus a counts object with software, services, and certificates counts, and an as_of timestamp marking the last snapshot. Pass agent_id. Use it before starting an inventory assessment to gauge coverage and freshness.

This is distinct from agent_get_host_summary, which returns prior insights and sessions instead of inventory counts.

Example prompt.

"Give me an inventory snapshot summary for AHW-ITD-10."

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?"

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

since is 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.
agent_group_id	string	—	Scope through a group.
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.

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

total reflects the number of buckets 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.
limit	integer	—	Default 100, max 500.
skip	integer	—	Pagination.

Example prompt.

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

The response carries a buckets array — each bucket has name, version, and host_count — plus a total reflecting the number of buckets returned (≤ top_n).

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

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.
limit	integer	—	Default 100, max 500.
skip	integer	—	Pagination.

Example prompt.

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

Each bucket carries the requested group_by fields plus a host_count.

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.