Aegis Guardrails

Overview Schema Source Related Servers Discussions Admin

aegis_report_outcome

Records test-backed change outcomes and the rules used so verified true positives earn CI credit; call after checks or tests to log success, failure, or neutral results.

Instructions

Call after verifying a change with tests or aegis check, naming rules from aegis_scan; use aegis_capture_insight for user corrections. With a passing aegis check --record --tests row for the current tree, the rules this session's scans exposed that match the diff are credited, counting once CI passes on the landing commit; without one, it writes at most one unwitnessed claim per session and tree, which earns no credit. Capped at 200 report rows per session and rate-limited to 5 calls per 60 seconds.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "outcome": "<outcome>",
      "rules_used": "<rules_used>",
      "idempotency_key": "<idempotency_key>"
    },
    "name": "aegis_report_outcome"
  }
}

Input Schema

Name	Required	Description
`view`	No	'full' (default), 'summary' (key fields, lists capped at 10 plus <list>_count) or 'ids'.
`files`	No	Paths edited in this change, for scan-before-edit compliance only (at most one 'edit' event per report); never affects credit.
`notes`	No	Accepted for compatibility; ignored, never stored.
`outcome`	Yes	'success', 'tp' and 'pass' claim a true positive (credited only after CI); the others read as a neutral trigger, never a false positive.
`rules_used`	Yes	Rule IDs from aegis_scan; credit comes from this session's scan exposure and the diff, not this list.
`rework_count`	No	Accepted for compatibility; ignored, never stored.
`tests_passed`	No	Accepted for compatibility; ignored, never stored.
`idempotency_key`	Yes	Unique per report (scoped by host and session): a retry is a no-op; reuse with another outcome fails.

Schema Changelog

Changes observed during successful MCP inspections.

Changed9 schema fields changedv4.4.0Oct 30, 2026

changedInput schema / properties / files / description

Previous value: -"Optional workspace-relative file paths edited in this change. Records one 'edit' activity event per idempotency_key for scan-before-edit compliance (aegis status --compliance); does not affect rule credit."New value: +"Paths edited in this change, for scan-before-edit compliance only (at most one 'edit' event per report); never affects credit."

changedInput schema / properties / idempotency_key / description

Previous value: -"Caller-supplied unique key (1-256 chars, scoped per host and session). Retrying with the same key and outcome is a no-op; reusing a key with a different outcome fails with status 'FAIL'."New value: +"Unique per report (scoped by host and session): a retry is a no-op; reuse with another outcome fails."

changedInput schema / properties / notes / description

Previous value: -"Optional free-text context describing how the rules helped or failed (max 4096 chars)."New value: +"Accepted for compatibility; ignored, never stored."

changedInput schema / properties / outcome / description

Previous value: -"Verification result for the rules in this change: 'success'/'tp'/'pass' record a true positive ('tp'), 'failure'/'fp'/'fail' record a false positive ('fp'), and 'partial' records a neutral trigger ('trigger')."New value: +"'success', 'tp' and 'pass' claim a true positive (credited only after CI); the others read as a neutral trigger, never a false positive."

changedInput schema / properties / rework_count / description

Previous value: -"Optional non-negative integer count of edit-and-retest cycles before verification succeeded (default: 0)."New value: +"Accepted for compatibility; ignored, never stored."

changedInput schema / properties / rules_used / description

Previous value: -"Non-empty list of existing rule IDs from aegis_scan. Validated against the workspace rule inventory; actual fitness credit is computed server-side from session scan exposure and git diff paths."New value: +"Rule IDs from aegis_scan; credit comes from this session's scan exposure and the diff, not this list."

changedInput schema / properties / tests_passed / description

Previous value: -"Optional boolean recording whether the project's test suite passed during verification."New value: +"Accepted for compatibility; ignored, never stored."

changedInput schema / properties / view / description

Previous value: -"Optional response projection: 'full' (default, complete payload), 'summary' (retains identity/type/status/fitness fields, caps lists at 10 items, and adds <list>_count), or 'ids' (projects each list to rule ID strings). Error responses are never projected."New value: +"'full' (default), 'summary' (key fields, lists capped at 10 plus <list>_count) or 'ids'."

changedOutput schema / (root)

Previous value: -{
-  "additionalProperties": false,
-  "properties": {
-    "aegis_version": {
-      "description": "Running Aegis package version string.",
-      "type": "string"
-    },
-    "check": {
-      "description": "Check record ID that witnessed the report (present when status='recorded').",
-      "type": "string"
-    },
-    "checked_at": {
-      "description": "UTC ISO-8601 timestamp when the report was processed.",
-      "type": "string"
-    },
-    "credited": {
-      "description": "Rule IDs credited in the outcome ledger (empty for unwitnessed 'claimed' or 'rate_limited' reports).",
-      "items": {
-        "type": "string"
-      },
-      "type": "array"
-    },
-    "credited_count": {
-      "description": "Total count of credited rules before 'summary' view truncation (present when view='summary').",
-      "type": "integer"
-    },
-    "error": {
-      "description": "Error message when status='FAIL'.",
-      "type": "string"
-    },
-    "limit": {
-      "description": "Per-session report cap (200) returned when status='rate_limited'.",
-      "type": "integer"
-    },
-    "recorded": {
-      "description": "False when status='rate_limited' or when an unwitnessed claim for the same session and tree was already recorded.",
-      "type": "boolean"
-    },
-    "scope": {
-      "description": "Workspace scope metadata envelope ({tree}).",
-      "type": "object"
-    },
-    "source": {
-      "description": "Command or tool name that produced the response ('aegis_report_outcome').",
-      "type": "string"
-    },
-    "status": {
-      "description": "Report disposition: 'recorded' (witnessed by a matching check record), 'claimed' (unwitnessed self-report), 'rate_limited' (session cap reached), or 'FAIL'.",
-      "enum": [
-        "recorded",
-        "claimed",
-        "rate_limited",
-        "FAIL"
-      ],
-      "type": "string"
-    },
-    "tree": {
-      "description": "Git tree hash computed for the workspace at report time.",
-      "type": [
-        "string",
-        "null"
-      ]
-    },
-    "witness": {
-      "description": "Attestation tier: 'aegis' when backed by a passing 'aegis check --record --tests' row for the current tree, or 'self' for unwitnessed claims.",
-      "enum": [
-        "aegis",
-        "self"
-      ],
-      "type": "string"
-    }
-  },
-  "required": [
-    "credited"
-  ],
-  "type": "object"
-}New value: +null

Changed9 schema fields changedv4.3.4Oct 22, 2026

changedInput schema / properties / files / description

Previous value: -"Optional: the files this change edited (workspace-relative). They measure scan-before-edit compliance (aegis status --compliance); they credit no rule."New value: +"Optional workspace-relative file paths edited in this change. Records one 'edit' activity event per idempotency_key for scan-before-edit compliance (aegis status --compliance); does not affect rule credit."

changedInput schema / properties / idempotency_key / description

Previous value: -"Unique key for this report. Retrying with the same key never records twice."New value: +"Caller-supplied unique key (1-256 chars, scoped per host and session). Retrying with the same key and outcome is a no-op; reusing a key with a different outcome fails with status 'FAIL'."

addedInput schema / properties / notes / description

Added value: +"Optional free-text context describing how the rules helped or failed (max 4096 chars)."

changedInput schema / properties / outcome / description

Previous value: -"Verification outcome."New value: +"Verification result for the rules in this change: 'success'/'tp'/'pass' record a true positive ('tp'), 'failure'/'fp'/'fail' record a false positive ('fp'), and 'partial' records a neutral trigger ('trigger')."

addedInput schema / properties / rework_count / description

Added value: +"Optional non-negative integer count of edit-and-retest cycles before verification succeeded (default: 0)."

changedInput schema / properties / rules_used / description

Previous value: -"Names of the rules this outcome is about, as aegis_scan returned them."New value: +"Non-empty list of existing rule IDs from aegis_scan. Validated against the workspace rule inventory; actual fitness credit is computed server-side from session scan exposure and git diff paths."

addedInput schema / properties / tests_passed / description

Added value: +"Optional boolean recording whether the project's test suite passed during verification."

changedInput schema / properties / view / description

Previous value: -"Optional response projection: full (default), summary or ids."New value: +"Optional response projection: 'full' (default, complete payload), 'summary' (retains identity/type/status/fitness fields, caps lists at 10 items, and adds <list>_count), or 'ids' (projects each list to rule ID strings). Error responses are never projected."

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "additionalProperties": false,
+  "properties": {
+    "aegis_version": {
+      "description": "Running Aegis package version string.",
+      "type": "string"
+    },
+    "check": {
+      "description": "Check record ID that witnessed the report (present when status='recorded').",
+      "type": "string"
+    },
+    "checked_at": {
+      "description": "UTC ISO-8601 timestamp when the report was processed.",
+      "type": "string"
+    },
+    "credited": {
+      "description": "Rule IDs credited in the outcome ledger (empty for unwitnessed 'claimed' or 'rate_limited' reports).",
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "credited_count": {
+      "description": "Total count of credited rules before 'summary' view truncation (present when view='summary').",
+      "type": "integer"
+    },
+    "error": {
+      "description": "Error message when status='FAIL'.",
+      "type": "string"
+    },
+    "limit": {
+      "description": "Per-session report cap (200) returned when status='rate_limited'.",
+      "type": "integer"
+    },
+    "recorded": {
+      "description": "False when status='rate_limited' or when an unwitnessed claim for the same session and tree was already recorded.",
+      "type": "boolean"
+    },
+    "scope": {
+      "description": "Workspace scope metadata envelope ({tree}).",
+      "type": "object"
+    },
+    "source": {
+      "description": "Command or tool name that produced the response ('aegis_report_outcome').",
+      "type": "string"
+    },
+    "status": {
+      "description": "Report disposition: 'recorded' (witnessed by a matching check record), 'claimed' (unwitnessed self-report), 'rate_limited' (session cap reached), or 'FAIL'.",
+      "enum": [
+        "recorded",
+        "claimed",
+        "rate_limited",
+        "FAIL"
+      ],
+      "type": "string"
+    },
+    "tree": {
+      "description": "Git tree hash computed for the workspace at report time.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "witness": {
+      "description": "Attestation tier: 'aegis' when backed by a passing 'aegis check --record --tests' row for the current tree, or 'self' for unwitnessed claims.",
+      "enum": [
+        "aegis",
+        "self"
+      ],
+      "type": "string"
+    }
+  },
+  "required": [
+    "credited"
+  ],
+  "type": "object"
+}

First observedv0.1.0Oct 17, 2026

TDQS

A4.4/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations provide only readOnlyHint=false, so the description carries the burden and does it well: it discloses credit vs. no-credit mechanics, the one-unwitnessed-claim-per-session/tree limit, the 200-row session cap, the 5-per-60-second rate limit, and the CI-passing condition for credit. These are exactly the operational constraints an agent needs before invoking a stateful reporting tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the calling condition and the sibling routing, followed by the credit and cap mechanics. The second sentence is dense but every clause (credit condition, no-credit fallback, row cap, rate limit) carries required information, so there is little waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 8-parameter, stateful reporting tool with no output schema and minimal annotations, the description covers invocation timing, credit rules, fallback behavior, idempotency implications via retry semantics in schema, caps, and rate limits. Nothing material is missing for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents every parameter including the outcome enum's credit semantics, files' non-effect on credit, and the ignored compatibility fields. The description reinforces that credit derives from session scan exposure and the diff rather than the `rules_used` list, but adds little per-parameter guidance (e.g. `view`) beyond what the schema states; baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description makes clear this records a change outcome for credit (calling it after tests or `aegis check`, naming rules from `aegis_scan`) and explicitly contrasts it with `aegis_capture_insight` for user corrections. The core verb 'report the outcome of verified work' is implied through the calling conditions rather than stated outright, so it falls short of a perfect 5 but is easily distinguishable from siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit preconditions ('call after verifying a change with tests or `aegis check`'), names the alternative for the adjacent case (`aegis_capture_insight` for user corrections), and spells out the two branches — credited with a passing recorded check row, or a single unwitnessed no-credit claim per session and tree.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server