Insight Tools

An insight is a structured, actionable finding — severity, category, affected resources, evidence, and remediation steps — saved during an assessment. Every insight carries a severity that ranks how urgently a human should act on it. Non-actionable observations ("this control is fine", host facts, inventory) are not insights; record them as facts elsewhere. 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 and keeps the disposition visible. Prefer it over insight_delete, which hides the finding from the backlog instead.

insight_save

Saves a new finding or updates an existing one. Insights are upserted by the composite key (agent_id, playbook, category, key) — a second call with the same composite key merges into the prior record. value and severity are always overwritten on every save. The optional fields — evidence, remediation_steps, estimated_effort, and affected_resources — are preserved from the prior save unless you resend them; resending an optional field is how you replace or clear it.

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 status: open. severity is required — set it deliberately on every save.

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.
severity	string	✓	One of critical, high, medium, or low.
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.
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, or low.
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.
workflow_id	string	—	Filter to a specific workflow's insights.
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.

{
  "total": 138,
  "by_severity": { "critical": 3, "high": 14, "medium": 38, "low": 83 },
  "by_category": { "security": 61, "identity": 24, "configuration": 33, "compliance": 20 },
  "by_status": { "open": 102, "acknowledged": 18, "in_progress": 7, "resolved": 9, "dismissed": 2 },
  "trends": [
    { "date": "2026-06-27", "count": 12 },
    { "date": "2026-06-28", "count": 18 }
  ],
  "trends_resolved": [
    { "date": "2026-06-28", "count": 4 }
  ],
  "top_affected_hosts": [
    { "hostname": "AHW-ITD-10", "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

Removes an insight from every list, view, and the active backlog. This is a soft delete: a later insight_save on the same composite key revives the finding. Prefer insight_update_status with status: dismissed whenever the insight is wrong, duplicate, or no longer relevant, since dismissal keeps the finding visible with an audit trail rather than hiding it.

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.

WARNING

insight_delete hides a finding rather than retiring it on the record. Reach for insight_update_status with dismissed instead in nearly every scenario — it keeps who reported the finding, when, and why, and signals the disposition to anyone reviewing the backlog.

See Also

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