MCP Tool Reference

The MCP server provides 162 tools organized by category (139 static + 23 dynamic per-recipe-script tools).

Cross-Harness Discovery (RFC #113)

Four small tools let any MCP client — Claude Code, Cursor, Codex, vanilla Agents SDK — ground itself and reach the routing layer without depending on the initialize instructions block. Call them at session start or when the agent needs to check what Pretorin can do.

check_context

Cheap, unauthenticated probe of session grounding. Reads local CLI config only — no platform calls. Returns:

{
  "connected": true,
  "active_system": {"id": "sys-1", "name": "Primary"},
  "active_framework_id": "nist-800-53-r5",
  "suggested_next": "Ready. Call `start_task` with an `intent_verb` to route the user's request to a workflow.",
  "pending_attention": {}
}

suggested_next is deterministic and tells the agent exactly what to do given current state — call pretorin login, call list_systems, set a framework, or proceed with start_task.

Parameters: None.

When to call: Once at session start. Always safe; never makes a platform call.

list_tools

Compact catalog of every available tool. Returns one short record per tool:

{
  "total": 151,
  "tier_counts": {"default": 8, "workflow": 17, "reference": 104, "recipe": 22},
  "tools": [
    {"name": "check_context", "purpose": "Cheap, unauthenticated probe of session grounding", "tier": "default", "requires_workflow": false},
    ...
  ]
}

The full payload fits in roughly 100 lines — far smaller than fetching every tool’s inputSchema. Tier classification:

Tier	Meaning
`default`	Always advertised. Minimum surface to ground a session and route a task.
`reference`	Read-only browsing of frameworks, controls, systems, recipes. Safe without prior routing.
`workflow`	Requires prior `start_task` context. Calling without it raises `WorkflowRoutingError`.
`recipe`	Dynamic per-recipe-script tools (`recipe_<id>__<script>`).

Parameters: None.

When to call: Once at session start (or anytime “what’s available?” comes up).

search_platform_capabilities

Search the product-facing Pretorin Platform Capability Index for features that can satisfy a compliance requirement. This is a searchable product source, not a catalog dump. Agents should call it before creating local tracking documents, spreadsheets, registers, placeholder evidence, or shadow systems of record.

{
  "query": "vendor management system for third-party risk and vendor documents",
  "framework_id": "soc2",
  "control_id": "CC9.2",
  "limit": 3
}

Returns compact matches:

{
  "source_kind": "pretorin_platform_capabilities",
  "total_matches": 1,
  "matches": [
    {
      "capability_id": "vendor_management",
      "name": "Vendor Management",
      "surface": "Vendors",
      "availability": "platform_ui_and_mcp",
      "satisfies": ["track third-party providers and service providers"],
      "mcp_tools": [
        "list_vendors",
        "create_vendor",
        "upload_vendor_document",
        "list_vendor_assessment_templates",
        "launch_vendor_assessment"
      ],
      "agent_guidance": "Use Pretorin Vendor Management as the system of record before creating local vendor inventories, assessment trackers, or document folders.",
      "source_kind": "pretorin_platform_capabilities",
      "system_of_record": true,
      "confidence": "high"
    }
  ]
}

Availability values:

Availability	Meaning
`platform_ui_and_mcp`	Pretorin has a product surface and MCP tools the agent can use.
`platform_ui_with_mcp_read`	Pretorin has a product surface plus read-oriented MCP context, but the full workflow may stay in the platform UI.
`platform_ui_only`	Pretorin has a product surface, but the current MCP/CLI does not expose the workflow.

Parameters:

query (required) — Plain-English requirement or proposed local artifact.
framework_id (optional) — Framework context.
control_id (optional) — Control context.
limit (optional, 1–10, default 5) — Maximum matches to return.

When to call: Before creating local artifacts to satisfy a requirement that sounds like vendor management, risk tracking, POA&M/weakness tracking, vendor assessments, formal assessments, policy management, system scope/profile management, approval workflow, compliance report generation, eMASS synchronization, SPRS scoring, OSCAL packages, STIG/CCI tracking, or another GRC platform feature.

get_instructions

Returns the server’s routing instructions as a regular tool response. Mirrors the text the MCP initialize handshake advertises in the instructions field, for harnesses (Cursor, Codex, vanilla Agents SDK) that don’t render that text to the agent.

Parameters: None.

When to call: If the agent didn’t receive routing rules via the initialize handshake, or wants to re-read them mid-session.

Routing Errors (errors-as-instructions)

Workflow-tier tools require an active routing context — either an active system/framework set via pretorin context set, or the context that start_task resolves. Calling a workflow write without context returns a structured error payload, not just plain text:

{
  "error": "workflow_required",
  "message": "No active system/framework context. Call start_task with an intent_verb to route the request to the right workflow, or run `pretorin context set --system <id> --framework <id>` in the terminal.",
  "routing_hint": {
    "reason": "no_active_context",
    "next_action": "call_start_task",
    "missing": ["system_id", "framework_id"],
    "suggested_intent_verb": "collect_evidence"
  }
}

The response carries isError=true so agents that only check the error flag still surface the failure, but the parseable body tells them exactly which start_task call to make. This means routing rules live in the protocol, not the preamble — harnesses that ignore instructions still see the rules in the error payload they have to read anyway.

Evidence and narrative producer writes add one more guardrail: create_evidence, create_evidence_batch, and update_narrative require recipe_context_id from start_recipe. Missing recipe context returns recipe_required with a recipe_gap before scope resolution, so agents converge on start_task → source preflight → start_recipe → write.

suggested_intent_verb is set when the called tool has a registered mapping (see _TOOL_TO_INTENT_VERB in src/pretorin/mcp/server.py). Every tool in WORKFLOW_TIER has one; tools added to that set without a mapping will fail the sync test in CI.

Workflow Schema Bundling

When the agent calls get_workflow, the response includes required_tool_schemas — the full MCP Tool definitions for every tool the workflow body references:

{
  "id": "single-control",
  "manifest": { "..." },
  "body": "## Single Control Update\n\n...",
  "required_tool_schemas": [
    {"name": "create_evidence", "description": "...", "inputSchema": {...}},
    {"name": "update_narrative", "description": "...", "inputSchema": {...}},
    ...
  ]
}

Single round trip equips the agent. Schemas are response data — agents can read them as reference regardless of whether their harness supports dynamic tool registration.

Telemetry

The server emits structured telemetry events to stderr so MCP hosts can capture them through their existing log pipeline. Each event is one line:

PRETORIN_TELEMETRY_EVENT {"ts": 1747249200.12, "event_type": "workflow_routing_required", "tool": "create_evidence", "reason": "no_active_context", "missing": ["system_id", "framework_id"], "suggested_intent_verb": "collect_evidence"}
PRETORIN_TELEMETRY_EVENT {"ts": 1747249200.99, "event_type": "recipe_required", "tool": "create_evidence", "reason": "agent write attempted without recipe_context_id", "requested_evidence_type": "code_snippet", "suggested_next": "call_start_task_then_start_recipe"}

Events emitted:

event_type	When
`start_task_succeeded`	A `start_task` call completed successfully (the canonical-path signal).
`workflow_routing_required`	A write tool raised `WorkflowRoutingError` (the bypass signal).
`recipe_required`	An evidence or narrative producer write returned the structured recipe-context guardrail before scope resolution.

For the post-recipe producer path, compute the combined bypass rate as:

(workflow_routing_required + recipe_required) / start_task_succeeded

When your log pipeline can group by MCP session, count only bypass events that did not have the expected preceding canonical calls in that same session: start_task for workflow_routing_required, and start_task → source preflight → start_recipe for recipe_required. The recipe_required event carries only non-content shape data such as evidence type, item count, narrative length, and suggested_next; it must not include artifact content, narrative text, evidence ids, control ids, or source excerpts.

Per RFC #113 and issue #121, this combined bypass data gates any phase-4 default-surface cull or capability-negotiation work.

Opt-out: set PRETORIN_MCP_TELEMETRY_DISABLED=1 in the environment before starting the MCP server. Local-only — no PII or content leaves the user’s machine.

Common Write-Side Parameters

Most write-side tools (evidence, narratives, issues, control status, monitoring events) accept two shared audit-trail flags. Both default to false and should only be set when the calling agent has a deliberate reason to bypass the corresponding guardrail:

allow_scope_override — Permit a write outside the active system/framework context.
allow_unverified_sources — Permit a write when source attestation shows a mismatch.

Where listed below as “(audit-trail flags)”, a tool accepts both fields. MCP agent evidence and narrative writes require recipe_context_id returned by start_recipe; writes without one return a structured recipe_required error.

Task Routing

start_task

Route a user prompt to the right workflow. Call this FIRST whenever the user references compliance work (a control, system, framework, questionnaire, or campaign). The calling agent extracts entities from the user prompt and supplies them as structured args; pretorin applies deterministic rules to pick a workflow and bundles the platform read-state (workflow_state, compliance_status, pending items) into the response. The agent then reads the selected workflow’s body via get_workflow and follows it.

The one exception is pure reference questions (“show me AC-2”, “list frameworks”) — those go directly to the read-side tools without start_task.

Argument shape: all prompt-derived fields (intent_verb, raw_prompt, system_id, framework_id, control_ids, scope_question_ids, policy_question_ids) must be nested inside the entities object. Only active_system_id, active_framework_id, and skip_inspect live at the top level — those come from the CLI runtime, not the user prompt. Flattening prompt entities to the top level is a common caller bug: such top-level copies are ignored by the handler (not read, not rejected), so the route is decided from entities alone and the misplaced fields silently have no effect.

Parameters:

entities (required) — Structured entities extracted from the user prompt. Required sub-fields: intent_verb (one of work_on, collect_evidence, draft_narrative, answer, scope_artifacts, campaign, inspect_status) and raw_prompt (original verbatim text). Optional sub-fields: system_id, framework_id, control_ids, scope_question_ids, policy_question_ids. All prompt-derived entities live here — do not flatten them to the top level.
active_system_id (optional) — The user’s active CLI context system_id, if any. Used to detect cross-system writes.
active_framework_id (optional) — The user’s active CLI context framework_id, if any. Used by inspect_status when the user asks for current status without naming a framework.
skip_inspect (optional) — Skip the server-side platform reads when the calling agent already has fresh state. Default: false
include_source_hints (optional) — Return full source_hints in suggested_capture_plan instead of compact hint summaries. Only honored for single-control tasks; multi-control summaries never inline hints. Default: false

Returns: Selected workflow id, resolved scope (system/framework/items), platform-state bundle, and suggested_capture_plan for source/recipe preflight when the workflow produces evidence or narratives. For a single control, the plan carries compact per-expectation items: verbose source_hints are replaced with source_hint_count and preferred_source_hint; pass include_source_hints=true for full hints. For multiple controls (e.g. a control family routed to the campaign workflow), the plan is a bounded per-control summary with no items or recipe_gaps keys — counts, statuses, and a top_capture_hint per control — sized for agent context budgets. Call check_sources for the full per-expectation detail of any one control.

Framework & Control Reference

These tools are read-only and available to all authenticated users.

list_frameworks

List all available compliance frameworks.

Parameters: None

Returns: List of frameworks with ID, title, version, tier, and control counts.

get_framework

Get detailed metadata about a specific framework including AI context (purpose, target audience, regulatory context).

Parameters:

framework_id (required) — e.g., nist-800-53-r5, fedramp-moderate

Returns: Framework details including description, version, OSCAL version, and dates.

list_control_families

List control families for a framework with AI context (domain summary, risk context, implementation priority).

Parameters:

framework_id (required)

Returns: List of control families with ID, title, class, and control count.

list_controls

List controls for a framework, optionally filtered by family.

Parameters:

framework_id (required)
family_id (optional) — Family IDs are slugs like access-control, not short codes. CMMC families include a level suffix (e.g., access-control-level-2).

Returns: List of controls with ID, title, and family.

get_control

Get detailed control information including AI guidance (summary, control intent, evidence expectations, implementation considerations, common failures, complexity).

Parameters:

framework_id (required)
control_id (required) — NIST/FedRAMP: zero-padded (ac-01). CMMC: dotted (AC.L2-3.1.1).

Returns: Control details including parameters, parts, and enhancement count.

get_controls_batch

Get detailed control data for many controls in one framework-scoped request.

Parameters:

framework_id (required)
control_ids (optional) — List of canonical control IDs; omit to retrieve all controls in the framework

Returns: Full control detail records for the requested controls.

get_control_references

Get reference information including statement, guidance, objectives, and related controls.

Parameters:

framework_id (required)
control_id (required)

Returns: Statement, guidance, objectives, parameters, and related controls.

OSCAL Artifacts

Read-only access to validated OSCAL export artifacts (SSP/SAR/SAP/POA&M/ component-definition). Generation stays on the platform; these tools list and inspect what exists. Both are read-only and not active-context-enforced.

list_oscal_artifacts

List validated OSCAL artifacts for a system. Server-filtered to generation_state = succeeded AND validation_status = valid.

Parameters:

system_id (required)
artifact_type (optional) — ssp, sap, sar, poam, component_definition, bundle
framework_id (optional)
assessment_id (optional)
limit (optional, 1–100, default 50)
offset (optional, default 0)

Returns: artifacts (list of summaries with type, version, oscal_version, validation status) and total.

get_oscal_artifact

Get artifact metadata including the two-tier validation report and a presigned download URL.

Parameters:

system_id (required)
artifact_id (required)

Returns: Full metadata — oscal_version, generator_version, validation_report, checksum_sha256, file_size, and download_url.

Systems

list_systems

List systems in the current organization.

Parameters: None

Returns: System IDs, names, and summary metadata.

get_cli_status

Return the local Pretorin CLI version status, including update availability and upgrade guidance for MCP hosts and agents.

Parameters:

force (optional) — Bypass local cache and re-check PyPI for the latest version. Default: false

Returns: Current version, latest version, update available flag, and upgrade instructions.

get_source_manifest

Get the resolved source manifest for a system and evaluate it against currently detected sources. Shows which external sources (git, cloud, HRIS, etc.) are required, recommended, or optional, and whether each is currently satisfied.

Parameters:

system_id (optional) — System ID or name

Returns: Source manifest with per-source satisfaction status. Returns null manifest if none is configured.

get_system

Get system metadata including attached frameworks and security impact level.

Parameters:

system_id (required) — System ID or name

Returns: System metadata.

get_preflight

Read the local preflight verdict for the active (or given) scope: which recommended source kinds are mapped to host-local resolvers and their per-kind rollup (ready/degraded/missing/unverified/unmapped). This is the CLI-local source of truth for source availability — the platform cannot verify connections. When authenticated it also seeds the platform’s in-scope recommended source kinds into the artifact (persisted only when the profile changed something; offline it is a pure local read).

Parameters:

system_id (optional) — System ID or name; defaults to the active scope
framework_id (optional) — Framework ID; defaults to the active scope

Returns: Preflight artifact with per-kind resolver bindings and rollup. Returns exists=false with a hint when no artifact has been built yet and the platform recommends nothing.

verify_preflight

Probe every resolver bound in the preflight artifact for this scope, persist the results, and return the refreshed verdict. Probes run locally on the CLI host (e.g. gh auth status, az account show, workspace path checks).

Parameters:

system_id (optional) — System ID or name; defaults to the active scope
framework_id (optional) — Framework ID; defaults to the active scope

Returns: Refreshed preflight verdict with per-resolver probe results.

update_preflight

Bind resolver collections to recommended source kinds and persist the preflight artifact. Each kind maps to a collection of resolvers (each tells a distinct piece of the evidence story); a kind’s collection is replaced wholesale. Resolver types are open: workspace_path, cli_tool, command, manual/attested, mcp, connected_api, pretorin_feature, or any custom type with a probe.

Parameters:

bindings (required) — Array of per-kind resolver bindings to upsert. Each entry has kind (canonical source kind), optional recommended flag, and a resolvers array (each resolver has type, optional name, constraints, scope, params, and capabilities).
system_id (optional) — System ID or name; defaults to the active scope
framework_id (optional) — Framework ID; defaults to the active scope

Returns: The persisted preflight artifact with the updated bindings.

get_compliance_status

Get framework progress and implementation posture for a system.

Parameters:

system_id (required) — System ID or friendly system name

Returns: Framework status summaries and progress metrics.

set_target_scale_tier

Declare or clear the engagement’s target scale tier for a system/framework scope. The declared tier overrides the platform-derived tier used for guidance and expectation coverage.

Parameters:

system_id (optional) — Defaults to the active scope
framework_id (optional) — Defaults to the active scope
target_scale_tier (required) — baseline, moderate, or comprehensive; pass null to clear the override

Returns: target_scale_tier, derived_scale_tier, effective_scale_tier, and the platform’s reasoning.

Evidence Management

search_evidence

Search evidence within exactly one active system/framework scope. With query, performs RAG semantic search over attached evidence and scoped unattached evidence (including org policy documents) so agents can reuse existing evidence before creating new artifacts. Without query, lists evidence linked to control_id or the current framework scope.

Parameters:

system_id (optional) — System ID or friendly system name. When omitted, the active CLI scope is used if available.
control_id (optional) — Filter by control
framework_id (optional) — Filter by framework
query (optional) — Natural-language RAG query. Provide this before creating evidence to find currently attached evidence and reusable unattached evidence.
include_attached (optional) — When query is set, include evidence already attached to control_id. Default: true
include_unattached (optional) — When query is set, include scoped evidence not attached to control_id, including org policy evidence. Default: true
min_similarity (optional) — When query is set, minimum semantic similarity threshold. Default: 0.6
limit (optional) — Maximum number of results (default 20 for listing; RAG queries default to 5 and are capped at 50)
include_metadata / include_full_detail (optional) — When query is set, request full per-result metadata and control mappings. Default: false, which returns compact count markers such as metadata_key_count and control_mapping_count.
snippet_only (optional) — When query is set, replace large body fields such as artifact_content and matched_text with short snippets. Default: true
max_body_chars (optional) — When query is set and snippet_only=false, maximum characters to keep per body field. Use a positive value to opt into capped body content. Default: 0
snippet_chars (optional) — When query is set, maximum characters returned for each body-field snippet. Default: 500

Returns: Matching evidence items. RAG query responses are compact by default: full metadata and control mappings are replaced with counts, and full body fields are replaced with snippets and omitted-character counts so hot-path agent calls stay below tool-result limits. Pass include_metadata=true only when full per-result detail is needed; pass snippet_only=false with a positive max_body_chars only when body content is explicitly needed.

create_evidence

Upsert evidence on the platform (find-or-create by default). If dedupe is true, exact matching evidence in the active system/framework scope is reused; otherwise a new record is created.

Parameters:

name (required)
description (required) — Short human summary of what the evidence demonstrates
artifact_content (required) — Markdown body containing the actual evidence artifact. Use bold section labels with spacing instead of Markdown headings. Do not include gap lists, missing-information placeholders, unresolved caveats, or remediation backlog.
evidence_type (required) — Must be one of the canonical evidence types
system_id (optional) — Defaults to active scope
control_id (optional)
framework_id (optional)
dedupe (optional) — Default: true
code_file_path (optional) — Path to source file (relative to workspace root)
code_line_numbers (optional) — Line range (e.g., 10-25)
code_snippet (optional) — Relevant code excerpt
code_repository (optional) — Git repository URL
code_commit_hash (optional) — Git commit hash
source_uri, source_label, source_locator, source_excerpt, capture_method (optional at the MCP layer) — Structured provenance inputs. If omitted, the handler derives safe defaults from code context or active scope. Note: the platform’s audit-metadata contract (issue #701) requires source_locator for agent-produced evidence — the handler auto-derives lines N-M from code_line_numbers when present, but for non-code sources (policy excerpts, docs, vendor reports, dashboards) you must pass an explicit locator such as section 3.7 or page 4 paragraph 2, otherwise the platform rejects the write with Missing: source_locator.
recipe_context_id (required) — Active recipe execution context from start_recipe; evidence is stamped producer_kind='recipe' automatically.
allow_scope_override, allow_unverified_sources (optional, audit-trail flags)

Returns:

evidence_id
created — true if new, false if reused
linked — whether control/system link succeeded
match_basis — exact_name_desc_type_control_framework or none

create_evidence_batch

Create and link multiple evidence items within one system/framework scope in a single request.

Parameters:

items (required) — Array of evidence payloads. Each item: name, description, artifact_content, control_id, evidence_type (required); optional relevance_notes, code_file_path, code_line_numbers, code_snippet, code_repository, code_commit_hash, source_uri, source_label, source_locator, source_excerpt, capture_method. Artifact content uses the same no-heading, no-gap-discussion rule as create_evidence. The platform’s audit-metadata contract (issue #701) requires source_locator for agent writes — pass an explicit locator (e.g., section 3.7, lines 84-88, page 4 paragraph 2) on each item from a non-code source, or the platform will reject the corresponding item with Missing: source_locator.
system_id (optional) — Defaults to active scope
framework_id (optional) — Defaults to active scope
recipe_context_id (required) — Active recipe execution context from start_recipe; every item in the batch is stamped producer_kind='recipe'. All items share the same context — per-item context variation is not supported in v1.
allow_scope_override, allow_unverified_sources (optional, audit-trail flags)

Returns: Batch creation summary with per-item results and created evidence IDs.

link_evidence

Link an existing evidence item to a control.

Parameters:

evidence_id (required)
control_id (required)
system_id (optional) — Defaults to active scope
framework_id (optional)
expectation_key (optional) — Stable key from get_control_context.expectation_coverage
expectation_item (optional) — Raw expectation text; the platform hashes it to the stable key. Use this or expectation_key.
allow_scope_override, allow_unverified_sources (optional, audit-trail flags)

Returns: Link confirmation.

link_evidence_to_cci_implementation

Link an existing evidence item to a per-system CCI implementation row. Use when you already have the CCI implementation UUID (from get_cci_implementation or get_cci_status).

Parameters:

evidence_id (required)
cci_implementation_id (required)
system_id (optional) — Defaults to active scope
override_system_mismatch (optional, default false) — Permit cross-system attachment
override_reason (optional) — Required when override_system_mismatch is true

Returns: Link confirmation with link_summary.cci_implementation_id.

link_evidence_to_stig_rule_workflow

Link an existing evidence item to a STIG rule workflow. Lazy-creates the workflow row if none exists yet for (system, stig_rule). Use to attach remediation proof, mitigating-control documentation, or waiver-justification artifacts to a failing rule.

Parameters:

evidence_id (required)
stig_rule_id (required) — STIG catalog rule UUID
system_id (optional) — Defaults to active scope
override_system_mismatch (optional, default false)
override_reason (optional) — Required when override_system_mismatch is true

Returns: Link confirmation with link_summary.stig_rule_workflow_id.

upload_evidence

Upload a file as evidence to the platform (system-scoped, requires WRITE access).

Parameters:

file_path (required) — Absolute path to the file to upload
name (required) — Evidence name
system_id (optional) — Defaults to active scope
evidence_type (optional) — Default: other
description (optional) — Evidence description
control_id (optional)
framework_id (optional)
allow_scope_override, allow_unverified_sources (optional, audit-trail flags)

Returns: Uploaded evidence record.

delete_evidence

Delete an evidence item from the platform (system-scoped, requires WRITE access).

Parameters:

evidence_id (required) — The evidence item ID to delete
system_id (optional) — Defaults to active scope
framework_id (optional) — Defaults to active scope
allow_scope_override (optional, audit-trail flag)

Returns: Deletion confirmation.

get_evidence_attestation

Fetch the DSSE attestation envelope (ADR 0003) for an evidence record. Returns the in-toto Statement, signing key fingerprint, and provenance metadata. Read-only; no recipe context required.

Parameters:

evidence_id (required) — The evidence item ID to fetch the attestation for
include_lineage (optional, default false) — Also return the full lineage of attestations for this evidence (newest first)
include_archived (optional, default false) — When include_lineage is set, include archived attestations

Returns: DSSE envelope plus statement, signer fingerprint, and provenance fields. With include_lineage=true, also includes prior envelopes. Returns a structured attestation_unavailable error when the platform attestation surface is disabled or no envelope exists for the row.

get_narrative

Get the current narrative record for a control.

Parameters:

control_id (required)
system_id (optional) — Defaults to active scope
framework_id (optional) — Defaults to active scope
allow_scope_override, allow_unverified_sources (optional, audit-trail flags)

Returns: Narrative text, status, AI confidence metadata, and citations[]. Each citation includes grounding (claim_grounded, document_grounded, or ungrounded) plus any locator_chunk_index and matched_excerpt.

Implementation Context

get_control_context

Get rich context for a control including AI guidance, statement, objectives, scope status, current implementation details, and the full per-expectation coverage map.

Parameters:

control_id (required)
system_id (optional) — Defaults to active scope
framework_id (optional) — Defaults to active scope

Returns: Combined control metadata and implementation details. expectation_coverage maps each expectation to its expectation_key, item, tier, covered state, bound evidence, and unconfirmed suggestions.

get_scope

Get system scope and policy information including excluded controls and Q&A responses.

Parameters:

system_id (required)
framework_id (required)

Returns: Scope narrative, excluded controls, Q&A responses, and scope status.

patch_scope_qa

Apply partial scope questionnaire updates for a system/framework.

Parameters:

system_id (required)
framework_id (required)
updates (required) — Non-empty list of {question_id, answer} objects

Returns: Updated scope questionnaire state, including the saved responses.

list_org_policies

List organization policies available for questionnaire work.

Parameters: None

Returns: Policy summaries including id, name, template linkage, and questionnaire status.

get_org_policy_questionnaire

Get the canonical questionnaire state for one organization policy.

Parameters:

policy_id (required)

Returns: Policy metadata, saved answers, and the merged template/question set when available.

patch_org_policy_qa

Apply partial questionnaire updates for one organization policy.

Parameters:

policy_id (required)
updates (required) — Non-empty list of {question_id, answer} objects

Returns: Updated organization policy questionnaire state.

get_control_implementation

Get implementation details for a control in a system.

Parameters:

control_id (required)
system_id (optional) — Defaults to active scope
framework_id (optional) — Defaults to active scope
allow_scope_override, allow_unverified_sources (optional, audit-trail flags)

Returns: Current status, narrative, evidence count, operating_evidence_count (excluding the automatic scope document), compact expectation_coverage, and issue metadata.

get_control_issues

Get issues for a control implementation.

Parameters:

control_id (required)
system_id (optional) — Defaults to active scope
framework_id (optional)

Returns: Issue list with total count.

get_control_notes

Deprecated alias for get_control_issues.

Parameters:

control_id (required)
system_id (optional) — Defaults to active scope
framework_id (optional)

Returns: Issue list with total count. Compatibility responses also include notes.

update_narrative

Push a narrative text update produced by a narrative recipe.

Parameters:

control_id (required)
narrative (required) — Must be auditor-ready markdown (no headings, 2+ rich elements including inline code, 1+ structural element, no images). Do not include gap lists, missing-information placeholders, unresolved caveats, or remediation backlog; use add_control_issue.
system_id (optional) — Defaults to active scope
framework_id (optional) — Defaults to active scope
is_ai_generated (optional) — Default: false
recipe_context_id (required) — Active narrative-producing recipe context from start_recipe
evidence_ids (required) — Evidence ids cited by the narrative
evidence_citations (optional) — Full citation objects with evidence_id, optional citation_role, locator_chunk_index, and matched_excerpt. Map search_evidence’s chunk_index and matched_text to the locator fields for claim-level grounding.
allow_scope_override, allow_unverified_sources (optional, audit-trail flags)

Returns: Update confirmation.

add_control_issue

Add an issue for unresolved gaps or manual follow-up actions. Content is plain text (no markdown validation required). Issues are the durable home for gaps, missing evidence, unresolved ambiguity, and remediation work.

Parameters:

control_id (required)
content (required)
recipe_context_id (required) — Active control-note-attestation recipe context from start_recipe (legacy id for issue attestation)
system_id (optional) — Defaults to active scope
framework_id (optional) — Defaults to active scope
allow_scope_override, allow_unverified_sources (optional, audit-trail flags)

Returns: The created issue record.

add_control_note

Deprecated alias for add_control_issue.

resolve_control_issue

Resolve, unresolve, or update an existing control issue. Use this to clear blocking issues so control status can advance. Resolving an issue requires a resolution_note justification for the audit trail.

Parameters:

control_id (required)
issue_id (required)
recipe_context_id (required) — Active control-note-attestation recipe context from start_recipe (legacy id for issue attestation)
system_id (optional) — Defaults to active scope
framework_id (optional) — Defaults to active scope
is_resolved (optional) — Default: true
resolution_note (required when resolving) — Explain why the issue can be closed; stored as the resolution audit trail and cascaded to linked RFIs/findings
content (optional) — Updated issue content
is_pinned (optional)
allow_scope_override, allow_unverified_sources (optional, audit-trail flags)

Returns: The updated issue record.

resolve_control_note

Deprecated alias for resolve_control_issue. Accepts note_id instead of issue_id; otherwise the parameter set matches.

Compliance Updates

update_control_status

Start or reopen authoring for a control.

Parameters:

control_id (required)
status (required) — in_progress
system_id (optional) — Defaults to active scope
framework_id (optional)
allow_scope_override, allow_unverified_sources (optional, audit-trail flags)

CLI/MCP callers cannot set ready_to_approve, implemented, or not_applicable; those decisions happen in the Pretorin UI by a human.

Returns: Status update confirmation.

push_monitoring_event

Create a monitoring event for a system.

Parameters:

title (required)
system_id (optional) — Defaults to active scope
framework_id (optional) — Defaults to active scope
severity (optional) — critical, high, medium, low, info. Default: medium
event_type (optional) — security_scan, configuration_change, access_review, compliance_check. Default: security_scan
control_id (optional)
description (optional)
allow_scope_override, allow_unverified_sources (optional, audit-trail flags)

Returns: The created monitoring event.

generate_control_artifacts

Generate read-only AI drafts for a control narrative, evidence recommendations, and recommended issues.

Parameters:

system_id (required)
control_id (required)
framework_id (required)
working_directory (optional) — Local workspace path for code-aware drafting
model (optional) — Model override

Returns: Draft narrative text, evidence recommendations, and recommended issues. Does not write to the platform.

To persist approved evidence or narrative changes, first open the matching recipe context; create_evidence and update_narrative require recipe_context_id.

Workflow State & Analytics

get_workflow_state

Get the lifecycle state for a system+framework, showing which stage needs work next (scope, policies, controls, evidence).

Parameters:

system_id (required)
framework_id (required)

Returns: Current workflow stage, completion percentages, and next recommended action.

get_analytics_summary

Get a lightweight system progress snapshot.

Parameters:

system_id (required)
framework_id (required)

Returns: Scope completion, policy completion, control coverage, and evidence gaps.

get_family_analytics

Get per-family breakdown with narrative coverage, evidence coverage, and status distribution.

Parameters:

system_id (required)
framework_id (required)

Returns: Per-family metrics.

get_policy_analytics

Get per-policy breakdown with answer completion and review status.

Parameters:

policy_id (required)

Returns: Per-policy completion metrics.

Family Operations

get_pending_families

Identify which control families need work.

Parameters:

system_id (required)
framework_id (required)

Returns: Families with counts of pending vs total controls.

get_family_bundle

Get all controls in one family with status, narrative presence, evidence presence, and note counts.

Parameters:

system_id (required)
family_id (required)
framework_id (required)

Returns: Complete family bundle with per-control details.

trigger_family_review

Trigger AI review of all controls in a family. Takes 2-4 minutes for large families.

Parameters:

system_id (required)
family_id (required)
framework_id (required)

Returns: Review job ID for polling.

get_family_review_results

Poll family review results.

Parameters:

system_id (required)
job_id (required)

Returns: Aggregated findings with severity, affected control IDs, and recommended fixes.

Scope Workflow

get_pending_scope_questions

Get only unanswered scope questions (lightweight).

Parameters:

system_id (required)
framework_id (required)

Returns: List of unanswered questions with IDs.

get_scope_question_detail

Get guidance, tips, and example responses for a specific scope question.

Parameters:

system_id (required)
question_id (required)
framework_id (required)

Returns: Question text, guidance, tips, and example answers.

answer_scope_question

Answer one scope question.

Parameters:

system_id (required)
question_id (required)
answer (required)
framework_id (required)

Returns: Updated question state.

trigger_scope_generation

Trigger AI generation of scope document from answered questions. By default the same durable job also runs an AI review after generation.

Parameters:

system_id (required)
framework_id (required)
include_review (optional) — Run AI review after generation in the same job. Default: true

Returns: Generation job ID for polling.

trigger_scope_review

Trigger AI review of scope answers.

Parameters:

system_id (required)
framework_id (required)

Returns: Review job ID for polling.

get_scope_review_results

Poll for structured scope review findings.

Parameters:

system_id (required)
job_id (required)

Returns: Findings with severity levels and recommended fixes.

Policy Workflow

get_pending_policy_questions

Get only unanswered policy questions.

Parameters:

policy_id (required)

Returns: List of unanswered questions.

get_policy_question_detail

Get guidance, tips, and examples for a specific policy question.

Parameters:

policy_id (required)
question_id (required)

Returns: Question text, guidance, and example answers.

answer_policy_question

Answer one policy question.

Parameters:

policy_id (required)
question_id (required)
answer (required)

Returns: Updated question state.

get_policy_workflow_state

Get per-policy workflow state including completion, generation, and review status.

Parameters:

policy_id (required)

Returns: Policy workflow state.

trigger_policy_generation

Trigger AI generation of policy document from answered questions. By default the same durable job also runs an AI review after generation.

Parameters:

policy_id (required)
system_id (optional) — System ID for scope context
include_review (optional) — Run AI review after generation in the same job. Default: true

Returns: Generation job status.

trigger_policy_review

Trigger AI review of policy answers/document.

Parameters:

policy_id (required)

Returns: Review job ID for polling.

get_policy_review_results

Poll for structured policy review findings.

Parameters:

policy_id (required)
job_id (required)

Returns: Findings with severity levels and recommended fixes.

Campaign Operations

Campaigns enable bulk compliance operations with checkpoint persistence and lease-based concurrency.

prepare_campaign

Prepare a workflow-aligned campaign run with a platform state snapshot.

Parameters:

domain (required) — controls, policy, or scope
mode (required) — Campaign mode for the selected domain
system_id (optional) — Defaults to active scope
framework_id (optional) — Defaults to active scope
family_id (optional) — Target family for control campaigns
control_ids (optional) — Explicit control IDs to include
all_controls (optional) — Include all controls. Default: false
artifacts (optional) — Artifact type: narratives, evidence, or both. Default: both
review_job (optional) — Family review job ID for review-fix mode
policy_ids (optional) — Explicit policy IDs to include
all_incomplete (optional) — Include all incomplete items. Default: false
apply (optional) — Apply proposals immediately. Default: false
output (optional) — Output format: auto, live, compact, json. Default: json
checkpoint_path (optional) — Local checkpoint file path
working_directory (optional) — Working directory for executors
concurrency (optional) — Parallel execution limit. Default: 4
max_retries (optional) — Retry limit per item. Default: 2

Returns: Campaign checkpoint with item list and metadata.

claim_campaign_items

Claim items for drafting with TTL-based leases. Safe for fan-out to multiple agents.

Parameters:

checkpoint_path (required) — Local campaign checkpoint path
lease_owner (optional) — Stable identifier for the claiming agent
max_items (optional) — Number of items to claim. Default: 1
lease_ttl_seconds (optional) — Lease time-to-live. Default: 300

Returns: Claimed items with lease metadata.

get_campaign_item_context

Get full item context plus drafting instructions for a claimed item.

Parameters:

checkpoint_path (required)
item_id (required)

Returns: Control/policy/scope context, current state, and drafting guidance.

submit_campaign_proposal

Submit an external agent’s proposal without applying it to the platform.

Parameters:

checkpoint_path (required)
item_id (required)
proposal (required) — Campaign proposal payload object

Returns: Proposal acceptance confirmation.

apply_campaign

Push stored proposals to the platform.

Parameters:

checkpoint_path (required)
item_ids (optional) — Subset of item IDs to apply; omit to apply all

Returns: Apply results with per-item status.

get_campaign_status

Get structured campaign status with a stable transcript snapshot.

Parameters:

checkpoint_path (required)

Returns: Campaign progress, item states, and transcript.

Risk Management

Risks are system-scoped (except list_risk_library, which is org-level). Mitigation is recorded via update_risk — there is no separate /mitigate endpoint. Control auto-link on create/seed is opt-in: it requires framework_id plus matching ControlImplementation rows on the system.

list_risks

List risks for a system with optional filters.

Parameters:

system_id (required)
category (optional) — Filter by risk category (confidentiality, integrity, availability, etc.)
risk_level (optional) — Filter by overall risk level (critical, high, medium, low)
status (optional) — Filter by lifecycle status

Returns: Risk list with summary metadata.

get_risk

Get the full risk detail including eager-loaded artifact_links (controls, evidence, findings, vendors, monitoring events).

Parameters:

system_id (required)
risk_id (required)

Returns: Full risk record with artifact_links.

create_risk

Create a custom risk for a system. Control auto-link is opt-in: pass framework_id plus suggested_control_families and the platform will only auto-link controls that already have ControlImplementation rows for that framework.

Parameters:

system_id (required)
title (required)
category (required) — confidentiality, integrity, availability, etc.
description (optional)
cia_category (optional)
likelihood (optional)
impact (optional)
owner_id (optional)
treatment (optional) — mitigate, accept, transfer, avoid
treatment_plan (optional)
treatment_due_date (optional) — ISO date string
review_frequency_days (optional) — How often the risk should be re-reviewed
framework_id (optional) — Required for control auto-link
suggested_control_families (optional) — List of family short codes (e.g., ["AC", "IA"])

Returns: The created risk including artifact_links.

seed_risks

Bulk-instantiate library templates against a system + framework. Each template is scored against the system, and controls are auto-linked per the template’s suggested_control_families when matching ControlImplementation rows exist.

Parameters:

system_id (required)
framework_id (required)
template_ids (required) — Non-empty list of risk template IDs

Returns: Seed summary with the created risks.

update_risk

Update risk fields. This is the mitigation surface — set treatment, treatment_plan, and treatment_due_date here rather than via a separate endpoint. Set status to a terminal value (e.g., closed) to retire a risk; there is no public hard-delete because risks are part of the audit chain.

Parameters:

system_id (required)
risk_id (required)
title (optional)
description (optional)
category (optional)
cia_category (optional)
likelihood (optional)
impact (optional)
owner_id (optional)
status (optional)
review_frequency_days (optional)
treatment (optional) — mitigate, accept, transfer, avoid
treatment_plan (optional)
treatment_due_date (optional)

Returns: Updated risk record.

link_risk_artifact

Attach an artifact (control, evidence, finding, vendor, or monitoring event) to a risk. Pass exactly one artifact reference.

Parameters:

system_id (required)
risk_id (required)
link_type (required) — contributes_to_risk, mitigates_risk, evidence_of_risk
control_id (optional) — Pair with framework_id
framework_id (optional) — Required when linking a control
evidence_id (optional)
finding_id (optional)
vendor_id (optional)
monitoring_event_id (optional)

Returns: The created artifact link record.

unlink_risk_artifact

Remove a previously attached artifact link.

Parameters:

system_id (required)
risk_id (required)
link_id (required)

Returns: Removal confirmation.

refresh_risk_summary

Re-score the risk using the latest analytics and trigger a best-effort AI summary regeneration. The endpoint always returns 200 with the updated entry. The score commits regardless of AI availability; the AI summary updates only if the AI service is reachable and the org has quota — check whether ai_summary_generated_at advanced to confirm AI ran.

Parameters:

system_id (required)
risk_id (required)

Returns: Updated risk entry.

list_risk_library

Browse the org-level risk template library. Templates expose a scenario, category, cia_category, and suggested_control_families.

Parameters:

category (optional) — Filter templates by category

Returns: Library template list.

System Spec Artifacts

Auditor-required artifacts (asset inventory plus four snapshot kinds) that anchor a system’s audit chain. See System Spec Artifacts for the full schema.

list_artifact_requirements

List the 5 auditor-required system_spec artifact kinds for a system (asset inventory + 4 snapshot kinds). Returns each kind’s effective_required, optional/toggled-off state, attestation timestamp, and rationale.

Parameters:

system_id (required)

Returns: Artifact-requirement rows with required/optional state and attestation metadata.

get_asset_inventory

Return the system’s asset inventory. Active rows by default; pass as_of (ISO-8601 timestamp) to replay historical state.

Parameters:

system_id (required)
as_of (optional) — ISO-8601 timestamp for historical replay

Returns: Asset inventory rows with provenance and snapshot timestamp.

submit_asset_inventory_diff

Submit an asset-inventory diff produced by a recipe-driven scan. At least one of added / modified / decommissioned must be non-empty. recipe_id is a free-form CLI string the platform records as cli:<recipe_id> provenance per row. idempotency_key defaults to sha256(system_id, recipe_id, scan_timestamp); pass your own when replaying a scan. recipe_context_id (from start_recipe) is optional — the diff endpoint accepts it cleanly but does not require it.

Parameters:

system_id (required)
recipe_id (required) — Free-form CLI recipe id (e.g., asset-inventory-aws-baseline); stored as provenance per row
idempotency_key (optional) — Defaults to sha256(system_id, recipe_id, scan_timestamp)[:32]
recipe_context_id (optional) — UUID returned by start_recipe when the diff is produced inside an active recipe context
added (optional) — Array of new asset rows. Required per row: external_id. Recommended: name, asset_type, environment, data_classification, criticality
modified (optional) — Array of changed asset rows keyed by external_id; same shape as added
decommissioned (optional) — Array of {external_id, rationale} for assets to mark decommissioned

Returns: Diff acceptance summary with per-row outcomes.

link_spec_snapshot

Link an uploaded evidence item as the current snapshot for a system_spec kind, so it surfaces on the scope page. Use after upload_evidence returns an evidence id. kind is one of the snapshot kinds (boundary_diagram, network_dfd, ppsm, interconnection) — call list_artifact_requirements for the authoritative set. The asset inventory is not a snapshot kind (attest it with attest_spec_inventory). Requires an active workflow (call start_task first).

Parameters:

system_id (required)
kind (required) — Snapshot kind to link the evidence to
evidence_id (required) — ID of the uploaded evidence item to link as this kind’s snapshot
plan_id (optional) / step_index (optional) — B3 plan attribution

Returns: The updated snapshot-kind state.

attest_spec_snapshot

Attest a system_spec snapshot kind (boundary_diagram, network_dfd, ppsm, interconnection), setting its last_attested_at on the scope page. Typically called right after link_spec_snapshot. Requires an active workflow.

Parameters:

system_id (required)
kind (required) — Snapshot kind to attest
evidence_id (optional) — The linked evidence item being attested
sufficiency (optional) — Auditor sufficiency envelope (canonical source, coverage window, producer, verification state)
plan_id (optional) / step_index (optional) — B3 plan attribution

Returns: The updated snapshot-kind attestation state.

attest_spec_inventory

Attest the current asset inventory state, setting its last_attested_at on the scope page. Use after submit_asset_inventory_diff has the inventory in the desired state. The inventory is a living kind (rows + attestation), not a file upload — there is no evidence_id. Requires an active workflow.

Parameters:

system_id (required)
sufficiency (optional) — Auditor sufficiency envelope
attestation_name (optional) — Human-readable label for this inventory attestation
plan_id (optional) / step_index (optional) — B3 plan attribution

Returns: The inventory attestation result.

Vendor Management

list_vendors

List all vendor entities in the organization. The client fetches every matching page from the paginated public API.

Parameters:

search (optional) — Case-insensitive match on name/description
provider_type (optional) — csp, saas, managed_service, internal
risk_tier (optional) — low, moderate, high, critical
owner_user_id (optional)
assessment_status (optional) — draft, in_progress, submitted, reviewed
sort_by (optional) — name, provider_type, inherent_risk, risk_tier, residual_risk_score, next_review_at, last_assessed_at, created_at, document_count. Default: name
sort_dir (optional) — asc, desc. Default: asc

Returns: Vendor list with IDs, names, types, authorization levels, inherent risk, residual tier, reassessment dates, assessment status, and document counts when provided by the platform.

create_vendor

Create a new vendor entity.

Parameters:

name (required)
provider_type (required) — csp, saas, managed_service, internal
description (optional)
authorization_level (optional)
owner_user_id (optional)
inherent_risk (optional) — low, moderate, high, critical; medium is a deprecated alias for moderate

Returns: Created vendor record.

get_vendor

Get vendor details.

Parameters:

vendor_id (required)

Returns: Vendor metadata and linked documents.

get_vendor_history

Get vendor audit and evidence history.

Parameters:

vendor_id (required)
limit (optional) — 1..500. Default: 100

Returns: Vendor history events.

update_vendor

Update vendor fields.

Parameters:

vendor_id (required)
name (optional)
description (optional)
provider_type (optional) — csp, saas, managed_service, internal
authorization_level (optional)
owner_user_id (optional)
inherent_risk (optional) — low, moderate, high, critical; medium is a deprecated alias for moderate

Returns: Updated vendor record.

delete_vendor

Delete a vendor entity.

Parameters:

vendor_id (required)

Returns: Deletion confirmation.

upload_vendor_document

Upload vendor evidence documents (SOC 2 reports, CRMs, FedRAMP packages).

Parameters:

vendor_id (required)
file_path (required)
name (optional)
description (optional)
attestation_type (optional) — self_attested, third_party_attestation, vendor_provided. Default: vendor_provided

Returns: Uploaded document record.

list_vendor_documents

List documents linked to a vendor.

Parameters:

vendor_id (required)

Returns: Document list with metadata.

link_evidence_to_vendor

Link an evidence item to a vendor with attestation type. Set vendor_id to null to unlink.

Parameters:

evidence_id (required)
vendor_id (optional) — Vendor ID; null to unlink
attestation_type (optional) — self_attested, third_party_attestation, vendor_provided

Returns: Link confirmation.

list_vendor_assessment_templates

List vendor assessment templates available to the organization.

Parameters: None.

Returns: Template summaries including kind, source format, section count, and question count.

get_vendor_assessment_template

Get a vendor assessment template with its full section and question specs.

Parameters:

template_id (required)

Returns: Template detail, including sections, questions, and in_flight_assessment_count.

import_vendor_assessment_template

Import a SIG-Lite or CAIQ-Lite xlsx workbook as an org-scoped vendor assessment template. The default dry-run returns a preview. To persist the template, pass dry_run=false and acknowledge_license_rights=true.

Parameters:

file_path (required) — Local .xlsx workbook path
source_format (required) — sig_lite, caiq_lite
dry_run (optional) — Default: true
acknowledge_license_rights (optional) — Required when dry_run=false

Returns: Import preview on dry-run, or created template summary when persisted.

delete_vendor_assessment_template

Delete an org-scoped custom or imported vendor assessment template. Global seed templates cannot be deleted.

Parameters:

template_id (required)

Returns: Deletion confirmation.

launch_vendor_assessment

Launch an assessment against a vendor, freezing the selected template snapshot.

Parameters:

vendor_id (required)
template_id (required)

Returns: Assessment summary.

list_vendor_assessments

List assessments run against a vendor.

Parameters:

vendor_id (required)

Returns: Assessment summaries.

get_vendor_assessment

Get an assessment with its frozen template snapshot, responses, and any advisory AI summary.

Parameters:

vendor_id (required)
assessment_id (required)

Returns: Assessment detail.

save_vendor_assessment_responses

Upsert assessment answers. The first answer moves a draft assessment to in_progress.

Parameters:

vendor_id (required)
assessment_id (required)
answers (required) — List of answer objects with question_ref; optional fields are answer, comment, and evidence_item_id

Returns: Updated assessment detail.

submit_vendor_assessment

Move an in-progress vendor assessment to submitted.

Parameters:

vendor_id (required)
assessment_id (required)

Returns: Assessment summary.

score_vendor_assessment

Run advisory AI scoring over a submitted assessment. If scoring is unavailable, the platform records that state and review can still proceed through the acknowledgement gate.

Parameters:

vendor_id (required)
assessment_id (required)

Returns: Assessment detail.

review_vendor_assessment

Finalize an assessment by setting residual likelihood and impact. Values use the five-point NIST 800-30 scale: very_low, low, moderate, high, very_high.

Parameters:

vendor_id (required)
assessment_id (required)
residual_likelihood (required) — very_low, low, moderate, high, very_high
residual_impact (required) — very_low, low, moderate, high, very_high
acknowledge_no_ai_review (optional) — Required to finalize when no successful AI advisory summary exists

Returns: Reviewed assessment summary.

Inheritance & Responsibility

set_control_responsibility

Create or update an inheritance edge for a control.

Parameters:

system_id (required)
control_id (required)
framework_id (required)
responsibility_mode (required) — inherited or shared
source_type (optional) — provider, internal, or hybrid
vendor_id (optional) — Vendor providing the inherited control

Returns: Created responsibility edge.

get_control_responsibility

Check if a control is inherited and from where.

Parameters:

system_id (required)
control_id (required)
framework_id (required)

Returns: Responsibility edge details or null.

remove_control_responsibility

Convert an inherited control back to system-specific.

Parameters:

system_id (required)
control_id (required)
framework_id (required)

Returns: Removal confirmation.

generate_inheritance_narrative

AI-generate an inheritance narrative grounded in vendor documentation.

Parameters:

system_id (required)
control_id (required)
framework_id (required)

Returns: Draft inheritance narrative text.

get_stale_edges

Identify controls where the source narrative changed but the inherited control hasn’t been updated.

Parameters:

system_id (required)

Returns: List of stale inheritance edges with source change timestamps.

sync_stale_edges

Bulk update inherited controls by regenerating narratives from latest source.

Parameters:

system_id (required)

Returns: Sync results with per-control status.

STIG & CCI

list_stigs

List STIG benchmarks with optional filters.

Parameters:

technology_area (optional) — Filter by technology area
product (optional) — Filter by product name
limit (optional) — Default: 100
offset (optional) — Pagination offset. Default: 0

Returns: STIG benchmark list with IDs, titles, and rule counts.

get_stig

Get STIG benchmark detail.

Parameters:

stig_id (required)

Returns: Benchmark metadata including title, version, release info, and severity breakdown.

list_stig_rules

List rules for a STIG benchmark.

Parameters:

stig_id (required)
severity (optional) — Filter by severity (high, medium, low)
cci_id (optional) — Filter by CCI identifier
limit (optional) — Default: 100
offset (optional) — Pagination offset. Default: 0

Returns: Rule list with IDs, titles, severities, and linked CCIs.

get_stig_rule

Get full STIG rule detail.

Parameters:

stig_id (required)
rule_id (required)

Returns: Check text, fix text, discussion, and linked CCIs.

list_ccis

List CCIs with optional filters.

Parameters:

nist_control_id (optional) — Filter by NIST 800-53 control ID (e.g., AC-2)
status (optional)
limit (optional) — Default: 100
offset (optional) — Pagination offset. Default: 0

Returns: CCI list with definitions and linked controls.

get_cci

Get CCI detail with linked SRGs and STIG rules.

Parameters:

cci_id (required) — e.g., CCI-000015

Returns: CCI definition, linked SRGs, and linked STIG rules.

get_cci_chain

Get the full traceability chain: Control -> CCIs -> SRGs -> STIG rules.

Parameters:

nist_control_id (required) — NIST 800-53 control ID (e.g., AC-2)

Returns: Complete traceability from control requirements to technical checks.

get_cci_status

Get CCI-level compliance rollup for a system.

Parameters:

system_id (required)
nist_control_id (optional) — Filter by NIST control ID (e.g., AC-2)

Returns: Per-CCI pass/fail status.

get_cci_implementation

Read a single per-system CCI implementation row by (system_id, cci_uuid). Returns the live impl detail (status, status_source, narrative, ai_generated_narrative, evidence_ids, eMASS fields, has_status_conflict). 404 means the row hasn’t been initialized for this system yet.

Parameters:

system_id (required)
cci_uuid (required) — The CCI catalog UUID (the unique catalog row id, not the CCI-000XXX label)

Returns: Full CCI implementation detail.

get_stig_applicability

Get which STIGs apply to a system based on its profile.

Parameters:

system_id (required)

Returns: List of applicable STIG benchmarks.

infer_stigs

AI-infer applicable STIGs from the system’s profile.

Parameters:

system_id (required)

Returns: Recommended STIG benchmarks with reasoning.

get_test_manifest

Fetch the test manifest (applicable STIGs + rules) for a system.

Parameters:

system_id (required)
stig_id (optional) — Scope manifest to a specific STIG benchmark

Returns: Test manifest with applicable rules and scanner assignments.

submit_test_results

Upload STIG scan results to the platform.

Parameters:

system_id (required)
cli_run_id (required) — CLI scan run identifier
results (required) — Array of test result objects
cli_version (optional) — CLI version string

Returns: Submission confirmation with per-result status.

list_stig_checklists

List STIG checklists for a system (per-asset: benchmark, asset identity, title). Use to discover an existing checklist_id before export/import, or to confirm one exists for a (benchmark, asset) pair before creating a new one.

Parameters:

system_id (required)
inventory_item_id (optional) — Filter to one asset’s checklists by inventory item ID
limit (optional) — Max results per page (1–500). Default: 100
offset (optional) — Pagination offset. Default: 0

Returns: Checklist summaries (benchmark, asset identity, title, id).

create_stig_checklist

Create an asset-scoped STIG checklist bound to a benchmark + asset. Returns the new checklist summary (including its id). Fails if one already exists for that (benchmark, asset), or if the benchmark/asset is unknown. Create-or-resolve a checklist this way before importing scanner output.

Parameters:

system_id (required)
stig_benchmark_id (required) — STIG benchmark ID to bind (e.g. RHEL_9_STIG)
inventory_item_id (required) — Asset inventory item ID to bind the checklist to
title (optional) — Checklist title

Returns: The new checklist summary including its id.

export_stig_checklist

Export a checklist to a local file as DISA .ckl (XML) or .cklb (JSON). Regenerated on demand (air-gap/FIPS-safe; no eMASS connector needed). Writes to output_path and returns {path, format, size_bytes, sha256} — the raw file is written to disk, not inlined in the response. Refuses an existing output_path unless overwrite=true, and never writes through a symlink.

Parameters:

system_id (required)
checklist_id (required) — Checklist ID to export
output_path (required) — Local path to write the exported checklist file
format (optional) — ckl (XML) or cklb (JSON). Default: ckl
overwrite (optional) — Replace output_path if it already exists. Default: false

Returns: {path, format, size_bytes, sha256} for the written file.

import_stig_checklist

Import a .ckl/.cklb file into a checklist’s per-rule reviews (review axis). Full-fidelity complement to submit_test_results: ingests asset metadata, the four DISA statuses, finding details/comments, and severity override, reconciled against the benchmark. A non-reconciling import (rules dropped) returns an error result — never treat it as complete. Writes are refused outside the active context system.

Parameters:

system_id (required)
checklist_id (required) — Target checklist ID (must already exist)
file_path (required) — Local path to the .ckl (XML) or .cklb (JSON) file
format (optional) — auto, ckl, or cklb. Default: auto

Returns: Match/import counters, a reconciles flag, and capped rule-id buckets (full per-rule detail via the CLI).

import_stig_checklist_xccdf

Import an XCCDF scan document (SCAP/OpenSCAP results) into the system test axis. Separate from import_stig_checklist (the .ckl/.cklb review axis). The test axis is system-scoped, so the response reports how many checklists on the system the scan affects. Use this to push a scanner recipe’s XCCDF results so they derive DISA statuses across all checklists bound to the same benchmark.

Parameters:

system_id (required)
checklist_id (required) — A checklist ID on the target system
file_path (required) — Local path to the XCCDF results document

Returns: Import summary reporting how many checklists on the system the scan affects.

Recipes & Workflows

Recipes are markdown playbooks the calling agent reads and executes; workflows describe how to iterate items in a domain and which recipes to pick per item. See RFC 0001 for the contract spec and docs/src/recipes/ for authoring guides.

list_recipes

List loaded recipes with their summary metadata (id, name, tier, description, use_when, produces). When system_id is supplied, recipes missing required connected sources are hidden by default. Use this to discover which recipes are available, then call get_recipe(id) to read the full body.

Parameters:

tier (optional) — Filter to one tier: official, partner, or community
produces (optional) — Filter by what the recipe produces: evidence, narrative, both, or answers
system_id (optional) — Filter to recipes runnable against the system’s connected sources; also annotates each recipe with an active flag (membership in the scope’s active set)
include_unavailable (optional) — Include recipes missing required sources with unavailable reasons. Default: false
active_only (optional) — When system_id is supplied, return only the scope’s active recipe set. On an unprovisioned or missing scope this returns an empty recipe list, not the whole cookbook. Default: false

Returns: Recipe summaries with manifest metadata, required sources, per-recipe source availability, and an active flag when a system scope is supplied.

get_recipe

Return one recipe’s full manifest and body. The body is the markdown playbook the calling agent reads to understand the procedure.

Parameters:

recipe_id (required) — Recipe id to fetch

Returns: Recipe manifest plus the markdown body.

check_sources

Preflight source reachability and candidate recipes for one workflow/control. Use after start_task and before opening recipe contexts when the agent needs fresh source/recipe detail.

Parameters:

workflow_id (required) — Workflow id returned by start_task
control_id (required)
system_id (optional) — Defaults to active scope
framework_id (optional) — Defaults to active scope
include_source_hints (optional) — Return full per-expectation source_hints instead of compact hint summaries. Default: false

Returns: Compact capture-plan items with source kind, connected state, candidate recipes, selected recipe, and structured recipe_gap entries. On a provisioned scope, candidates are drawn from the active recipe set and each recipe_gap carries ready_source_kinds and ready_alternative_recipe_ids so an unmatched hint points at substitutes instead of a dead-end. Full source_hints are opt-in via include_source_hints=true.

get_active_recipes

Read the scope’s active recipe set — the curated subset of the cookbook provisioned for this (system, framework) compliance effort — plus a provisioning proposal. Call this during preflight (workflow Step 7) to seed the set, and whenever deciding what to run.

Parameters:

system_id (optional) — Defaults to active scope
framework_id (optional) — Defaults to active scope

Returns: active (the provisioned recipes), candidates (recipes runnable on this host, each with serves_kinds), coverage_gaps (ready source kinds no recipe consumes), and drift (active recipes whose pinned version/content/source has moved or left the cookbook). Returns provisioned: false / exists: false when the scope has no preflight artifact yet.

set_active_recipes

Edit the scope’s active recipe set and persist it on the preflight artifact. Seed it from get_active_recipes candidates during preflight, then adjust as the effort evolves. Establishing an active set makes it the confirmed menu: start_recipe then refuses recipes outside it (unless force=true), and the capture plan draws candidates from it.

Parameters:

recipe_ids (required) — Recipe ids to set/add/remove (may be empty only for mode='replace')
mode (optional) — replace (default, set the active set to exactly recipe_ids), add, or remove
system_id (optional) — Defaults to active scope
framework_id (optional) — Defaults to active scope

Returns: The activated/deactivated/unchanged ids, any unknown_recipe_ids skipped (not in the cookbook), and the resulting active set.

start_recipe

Open a recipe execution context. Returns a context_id the caller passes as recipe_context_id on subsequent platform-API write tool calls and to end_recipe so audit metadata is stamped with producer_kind='recipe' automatically. One recipe per session at a time (nesting forbidden in v1). Contexts auto-expire after 1 hour of inactivity. On a provisioned scope, start_recipe refuses recipes outside the active set and active recipes whose pinned version/content/source has drifted; pass force=true only for an audited ad-hoc run.

Parameters:

recipe_id (required) — Recipe id (must be loadable from the registry)
recipe_version (required) — Recipe version the caller intends to run. Read this from get_recipe(recipe_id).manifest.version (or the version field returned by list_recipes) before calling — hard-coded values will break when the recipe registry advances. Cross-checked against the loaded recipe; mismatch is an error.
params (optional) — Inputs the calling agent supplies, validated against the recipe’s params schema
selection (optional) — Structured RecipeSelection record from the engagement layer, stored on the context for the eventual RecipeResult
evidence_ids (optional) — Evidence ids supplied as inputs for narrative-producing recipes
system_id (optional) — Defaults to active scope
framework_id (optional) — Defaults to active scope
control_id (optional) — Control context for the recipe run
force (optional) — Open the context ad hoc when preflight source availability, active-set membership, or active recipe drift would otherwise refuse the run. Forced runs are recorded on the execution record.

Returns: Context id and the resolved recipe manifest snapshot.

end_recipe

Close a recipe execution context and return the RecipeResult summary (status, evidence and narrative counts, errors, elapsed time). Must be called once the recipe’s work is complete; failure to call leaves the context in place until the 1-hour expiry sweep.

Parameters:

recipe_context_id (required unless using the deprecated alias) — Context id returned by start_recipe; use this canonical name to match update_narrative, add_control_issue, and resolve_control_issue
context_id (optional, deprecated) — Legacy alias accepted for backwards compatibility. Prefer recipe_context_id.
status (optional) — Caller-supplied disposition: pass, fail, or needs_input. Default: pass

Returns: RecipeResult summary.

list_workflows

List loaded workflow playbooks (single-control, scope-question, scope-artifacts, policy-question, campaign). Each workflow describes how to iterate items in its domain and which recipes to pick per item. Use this before picking a recipe so the agent works at the right granularity.

Parameters:

iterates_over (optional) — Filter to one item-iteration shape: single_control, scope_questions, policy_questions, campaign_items, or system_spec_kinds

Returns: Workflow summaries with manifest metadata.

get_workflow

Return one workflow’s full manifest and body. The body is the markdown playbook the calling agent reads to know how to iterate items and pick recipes per item in this workflow’s domain.

Parameters:

workflow_id (required) — Workflow id to fetch

Returns: Workflow manifest plus the markdown body.

Work Plans

Agent-authored work plans are the persistence layer for the canonical agent execution contract — a declarative, resumable, auditable record of scope, intent, steps, expected outputs, and acceptance criteria. Plans are persisted locally to ~/.pretorin/plans/<id>.json; nothing in the platform contract changes when a plan is written. A future session can resume, replace, or audit the work via the returned plan id. The pretorin plan list/show/cancel CLI commands are the operator-facing view onto the same store.

create_plan

Persist an agent-authored work plan locally. Returns the full plan record including the generated plan id.

Parameters:

workflow_id (required) — Workflow id this plan executes (e.g. single-control)
intent_summary (required) — One-paragraph statement of what the agent intends to do and why; used by future sessions to decide whether to resume or replace
scope (optional) — Object with system_id, framework_id, and control_id this plan operates on
intent_inputs_snapshot (optional) — Free-form snapshot of the inputs that shaped the plan (user prompt, active scope, etc.) so the audit trail captures the why
steps (optional) — Ordered list of intended steps; each has index (contiguous from 0), summary, kind (recipe, policy_link, issue, note, or other), and optional ref_id
created_by_agent (optional) — Identifier for the agent creating the plan (e.g. claude-code-1.2.3)
acceptance_criteria (optional) — Typed conditions the platform must verify before complete_plan succeeds (max 32). Empty/omitted leaves the gate open. Each criterion has a kind (narrative_min_chars, every_claim_cites_evidence, ai_narrative_reviewed, min_evidence_count_per_control, or all_required_spec_kinds_attested) and kind-specific params

Returns: The full plan record, including the generated plan id.

get_plan

Return the full record of a previously-created plan. Use when resuming work from a prior session or auditing what was intended.

Parameters:

plan_id (required) — UUID-shaped plan id returned by create_plan

Returns: The full plan record.

list_recent_plans

List recent plans (newest first), with optional filtering by state, workflow, and scope. Returns compact summaries — call get_plan for the full record once a plan is selected. Use this at session start to find an existing plan to resume instead of creating a duplicate.

Parameters:

limit (optional) — Maximum number of plans to return (0–200, default 20)
state (optional) — Restrict results to plans in this state: active, completed, or cancelled
workflow_id (optional) — Filter by workflow id
system_id (optional) — Filter by system id
framework_id (optional) — Filter by framework id (e.g. fedramp-moderate)
control_id (optional) — Filter by control id

Returns: Compact plan summaries, newest first.

update_plan_step

Update one step’s status and/or outcome summary. Status transitions are guarded: pending → in_progress | skipped; in_progress → completed | skipped; terminal states are sticky. Refused if the plan itself is completed or cancelled.

Parameters:

plan_id (required)
step_index (required) — Index of the step to update
status (optional) — New status: pending, in_progress, completed, or skipped
outcome_summary (optional) — Short note about what the step actually produced
expected_version (optional) — Optimistic-locking guard. If supplied, the call returns a structured version_conflict error when the plan’s on-disk version no longer matches

Returns: The updated plan record.

complete_plan

Mark a plan as completed. Allowed only from active. Idempotent: completing an already-completed plan is a no-op. Cannot complete a cancelled plan. If the plan declares acceptance_criteria[], each criterion is evaluated against current platform state before the transition; any failures return a structured acceptance_failed error and the plan stays active so the agent can fix the gaps and retry.

Parameters:

plan_id (required)
outcome_summary (optional) — One-paragraph summary of what the plan ultimately produced
expected_version (optional) — Optimistic-locking guard. If supplied, the call returns a structured version_conflict error when the plan’s on-disk version no longer matches

Returns: The updated plan record.

cancel_plan

Mark a plan as cancelled. Allowed only from active. Idempotent: cancelling an already-cancelled plan is a no-op. Cannot cancel a completed plan.

Parameters:

plan_id (required)
outcome_summary (optional) — Reason for cancellation
expected_version (optional) — Optimistic-locking guard. If supplied, the call returns a structured version_conflict error when the plan’s on-disk version no longer matches

Returns: The updated plan record.

Keyboard shortcuts

Pretorin Developer & Agent Docs