Insight Tools

An insight is a structured finding — severity, category, affected resources, evidence, and remediation steps — saved during an assessment. The six insight tools cover the full lifecycle: save, get, list, aggregate, update status, and delete.

Insight Lifecycle

Every insight starts in open and progresses through one of two terminal states:

Use dismissed for findings that are wrong, duplicates, or no longer relevant — dismissed preserves the audit trail. Avoid insight_delete for the same reason; deletion erases history.

insight_save

Saves a new finding or overwrites an existing one. Insights are upserted by the composite key (agent_id, playbook, category, key) — a second call with the same composite key replaces the prior record. Replacement is full-record overwrite, not merge: include evidence and remediation_steps on every call if you want them retained.

When session_id is provided, the insight is linked to that session and agent_id is derived from it. For agentless mscloud_* assessments where there is no session, omit session_id (and optionally agent_id).

New insights default to severity: info and status: open. Always set severity explicitly for security findings — info is almost never the right level.

Parameter	Type	Required	Description
playbook	string	✓	The playbook that produced this insight.
category	string	✓	One of security, identity, networking, compliance, performance, configuration, availability, licensing.
key	string	✓	A short stable key, e.g. smb_signing_disabled.
value	string	✓	Human-readable summary of the finding.
session_id	string	—	Link to the session that discovered it. Derives agent_id.
agent_id	string	—	Required only for agent-scoped findings without a session.
severity	string	—	critical, high, medium, low, or info (default).
evidence	string	—	Raw command output or proof.
affected_resources	array	—	E.g. ["dc01.contoso.com", "SYSVOL share"].
remediation_steps	array	—	Ordered remediation steps.
estimated_effort	string	—	low, medium, or high.

Example prompt.

"Save a high-severity finding for SMB signing disabled on this host, with the relevant policy reference as remediation."

insight_get

Returns a single insight by insight_id, with all structured fields — including remediation_steps, evidence, and affected_resources.

Example prompt.

"Show me the full details of insight ins_a1b2c3."

insight_list

Lists insights, most recently updated first. Structured filters use the explicit parameters; the search parameter is a free-text substring match across value, key, and evidence — not Lucene or OData syntax.

Parameter	Type	Required	Description
severity	string	—	critical, high, medium, low, or info.
status	string	—	open, acknowledged, in_progress, resolved, or dismissed.
category	string	—	One of the eight categories.
playbook	string	—	Filter by playbook.
agent_id	string	—	Filter by agent.
hostname	string	—	Filter by hostname.
search	string	—	Free-text substring across value, key, evidence.
limit	number	—	Default 50.
offset	number	—	Pagination.

Use cases. Pull every open critical or high finding for a remediation plan. Find every insight on a host. Search insights for a specific term across the whole tenant.

Example prompt.

"List all open high or critical security insights, most recent first."

insight_aggregate

Returns aggregated statistics — counts by severity, category, and status, plus trends over time and top affected hosts. Use this to reason about overall posture rather than individual findings.

Parameter	Type	Required	Description
agent_id	string	—	Filter by agent.
playbook	string	—	Filter by playbook.
category	string	—	Filter by category.
severity	string	—	Filter by severity.
status	string	—	Filter by status.

Example prompt.

"Give me the security posture summary across all agents — counts by severity and the top affected hosts."

Sample response.

{
  "by_severity": { "critical": 3, "high": 14, "medium": 38, "low": 71, "info": 12 },
  "by_status": { "open": 102, "acknowledged": 18, "in_progress": 7, "resolved": 9, "dismissed": 2 },
  "top_affected_hosts": [
    { "hostname": "AHW-ITD-10", "open_count": 11 }
  ]
}

insight_update_status

Updates an insight's lifecycle status, optionally reassigning it to an Entra user or group. Use whenever the user says "mark as dismissed", "acknowledged", "resolved", "close", or "reassign to someone".

The tool takes a single insight_id per call. When the user names several insights, dispatch once per insight.

Parameter	Type	Required	Description
insight_id	string	✓	The insight ID to update.
status	string	✓	open, acknowledged, in_progress, resolved, or dismissed.
assigned_to	string	—	Entra object ID of a user or group to assign.

Example prompt.

"Mark insight ins_a1b2c3 as in progress and assign it to me."

insight_delete

Permanently removes an insight. Destructive — the audit trail is lost. Prefer insight_update_status with status: dismissed whenever the insight is wrong, duplicate, or no longer relevant.

You can delete by insight_id (preferred) or by composite key (agent_id + playbook + category + key).

Parameter	Type	Required	Description
insight_id	string	—	The insight ID (preferred).
agent_id	string	—	For composite key delete.
playbook	string	—	For composite key delete.
category	string	—	For composite key delete.
key	string	—	For composite key delete.

DANGER

insight_delete cannot be undone. The audit trail of who reported the finding, when, and why is lost. Reach for insight_update_status with dismissed instead in nearly every scenario.

See Also

For the conceptual model behind insights, see Key Concepts and Insights. For the sessions that produce insights, see Sessions.