Skip to main content
Glama
Sign In
Aegis Guardrails

Aegis Guardrails

by nseney1
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

aegis_scan

Read-onlyIdempotent

Fetches and ranks the project rules that apply to the files you are about to edit, serving them within the token budget and recording the scan for governance.

Instructions

Call before editing files: returns the rules for files (default: the git diff), ranked by fitness within the token budget, and records this session's scan and rule exposure. Mandatory rules (gates, invariants) take at most two slots (the excess is in omitted_mandatory) and are served from the reviewed base, so branch-local edits to them do not bind and are listed in unreviewed_rules. Use aegis_list_rules to browse without recording and aegis_report_outcome after verifying. Fails closed if a rule file cannot be loaded.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "aegis_scan"
  }
}

Input Schema

NameRequiredDescriptionDefault
viewNo'full' (default), 'summary' (key fields, lists capped at 10 plus <list>_count) or 'ids'.
filesNoPaths you are about to edit; omitted or empty means the files changed in the git work tree and index.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv4.4.0
    • changedInput schema / properties / files / description
      Previous value: -"Workspace-relative file paths you are about to edit. When omitted or empty, defaults to modified files in the current git working tree and index."New value: +"Paths you are about to edit; omitted or empty means the files changed in the git work tree and index."
    • 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": {
-    "error": {
-      "description": "Error detail when status='FAIL'.",
-      "type": "string"
-    },
-    "guidance": {
-      "description": "Rendered markdown guidance block ready for prompt injection (omitted when view='summary' or 'ids').",
-      "type": "string"
-    },
-    "invariant_warnings": {
-      "description": "Mandatory gate and invariant rules triggered by the target files.",
-      "type": "array"
-    },
-    "invariant_warnings_count": {
-      "description": "Total count of invariant_warnings before 'summary' view truncation (present when view='summary').",
-      "type": "integer"
-    },
-    "message": {
-      "description": "Informational message when status='not_governed'.",
-      "type": "string"
-    },
-    "omitted_mandatory": {
-      "description": "Mandatory gate or invariant rules that matched but exceeded the two-slot mandatory cap.",
-      "type": "array"
-    },
-    "omitted_mandatory_count": {
-      "description": "Total count of omitted_mandatory before 'summary' view truncation (present when view='summary').",
-      "type": "integer"
-    },
-    "reason": {
-      "description": "Unbound workspace reason code when status='not_governed'.",
-      "type": [
-        "string",
-        "null"
-      ]
-    },
-    "relevant_rules": {
-      "description": "Active rules matching the target files, ranked by fitness within the JIT token budget (rule objects in 'full'/'summary' view, or rule ID strings in 'ids' view).",
-      "type": "array"
-    },
-    "relevant_rules_count": {
-      "description": "Total count of relevant_rules before 'summary' view truncation (present when view='summary').",
-      "type": "integer"
-    },
-    "rule_errors": {
-      "description": "Rule files that failed to parse when status='FAIL'.",
-      "type": "array"
-    },
-    "rules_base": {
-      "description": "Reviewed git base anchor from which binding gate and invariant rules were loaded.",
-      "type": [
-        "object",
-        "string",
-        "null"
-      ]
-    },
-    "rules_staged": {
-      "description": "Count of rules staged in relevant_rules after budget clamping (omitted when view='ids').",
-      "type": [
-        "integer",
-        "array"
-      ]
-    },
-    "rules_staged_count": {
-      "description": "Total count of rules_staged before 'summary' view truncation (present when view='summary').",
-      "type": "integer"
-    },
-    "stale_rules": {
-      "description": "Rules edited on disk since the last 'aegis sync' derived-file regeneration.",
-      "type": "array"
-    },
-    "stale_rules_count": {
-      "description": "Total count of stale_rules before 'summary' view truncation (present when view='summary').",
-      "type": "integer"
-    },
-    "stats": {
-      "description": "Scan telemetry summary including matched counts and token budget usage (omitted in 'summary'/'ids' views).",
-      "type": "object"
-    },
-    "status": {
-      "description": "Optional status indicator ('not_governed' when scanning the user layer outside an Aegis workspace, or 'FAIL' on error).",
-      "type": "string"
-    },
-    "unreviewed_rules": {
-      "description": "Gate or invariant rules added or modified since rules_base whose local changes do not bind.",
-      "type": "array"
-    },
-    "unreviewed_rules_count": {
-      "description": "Total count of unreviewed_rules before 'summary' view truncation (present when view='summary').",
-      "type": "integer"
-    },
-    "unreviewed_total": {
-      "description": "Total count of unreviewed gate or invariant rules across the workspace.",
-      "type": "integer"
-    },
-    "user_layer": {
-      "description": "Read-only user-layer metadata ({path, rules}) when scanning outside a governed Aegis workspace.",
-      "type": "object"
-    },
-    "warnings": {
-      "description": "Optional non-fatal scan warning messages.",
-      "items": {
-        "type": "string"
-      },
-      "type": "array"
-    },
-    "warnings_count": {
-      "description": "Total count of warnings before 'summary' view truncation (present when view='summary').",
-      "type": "integer"
-    }
-  },
-  "required": [
-    "relevant_rules"
-  ],
-  "type": "object"
-}New value: +null
  2. Changed3 schema fields changedv4.3.4
    • changedInput schema / properties / files / description
      Previous value: -"Workspace-relative files you are about to edit. Defaults to the git diff."New value: +"Workspace-relative file paths you are about to edit. When omitted or empty, defaults to modified files in the current git working tree and index."
    • 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": {
+    "error": {
+      "description": "Error detail when status='FAIL'.",
+      "type": "string"
+    },
+    "guidance": {
+      "description": "Rendered markdown guidance block ready for prompt injection (omitted when view='summary' or 'ids').",
+      "type": "string"
+    },
+    "invariant_warnings": {
+      "description": "Mandatory gate and invariant rules triggered by the target files.",
+      "type": "array"
+    },
+    "invariant_warnings_count": {
+      "description": "Total count of invariant_warnings before 'summary' view truncation (present when view='summary').",
+      "type": "integer"
+    },
+    "message": {
+      "description": "Informational message when status='not_governed'.",
+      "type": "string"
+    },
+    "omitted_mandatory": {
+      "description": "Mandatory gate or invariant rules that matched but exceeded the two-slot mandatory cap.",
+      "type": "array"
+    },
+    "omitted_mandatory_count": {
+      "description": "Total count of omitted_mandatory before 'summary' view truncation (present when view='summary').",
+      "type": "integer"
+    },
+    "reason": {
+      "description": "Unbound workspace reason code when status='not_governed'.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "relevant_rules": {
+      "description": "Active rules matching the target files, ranked by fitness within the JIT token budget (rule objects in 'full'/'summary' view, or rule ID strings in 'ids' view).",
+      "type": "array"
+    },
+    "relevant_rules_count": {
+      "description": "Total count of relevant_rules before 'summary' view truncation (present when view='summary').",
+      "type": "integer"
+    },
+    "rule_errors": {
+      "description": "Rule files that failed to parse when status='FAIL'.",
+      "type": "array"
+    },
+    "rules_base": {
+      "description": "Reviewed git base anchor from which binding gate and invariant rules were loaded.",
+      "type": [
+        "object",
+        "string",
+        "null"
+      ]
+    },
+    "rules_staged": {
+      "description": "Count of rules staged in relevant_rules after budget clamping (omitted when view='ids').",
+      "type": [
+        "integer",
+        "array"
+      ]
+    },
+    "rules_staged_count": {
+      "description": "Total count of rules_staged before 'summary' view truncation (present when view='summary').",
+      "type": "integer"
+    },
+    "stale_rules": {
+      "description": "Rules edited on disk since the last 'aegis sync' derived-file regeneration.",
+      "type": "array"
+    },
+    "stale_rules_count": {
+      "description": "Total count of stale_rules before 'summary' view truncation (present when view='summary').",
+      "type": "integer"
+    },
+    "stats": {
+      "description": "Scan telemetry summary including matched counts and token budget usage (omitted in 'summary'/'ids' views).",
+      "type": "object"
+    },
+    "status": {
+      "description": "Optional status indicator ('not_governed' when scanning the user layer outside an Aegis workspace, or 'FAIL' on error).",
+      "type": "string"
+    },
+    "unreviewed_rules": {
+      "description": "Gate or invariant rules added or modified since rules_base whose local changes do not bind.",
+      "type": "array"
+    },
+    "unreviewed_rules_count": {
+      "description": "Total count of unreviewed_rules before 'summary' view truncation (present when view='summary').",
+      "type": "integer"
+    },
+    "unreviewed_total": {
+      "description": "Total count of unreviewed gate or invariant rules across the workspace.",
+      "type": "integer"
+    },
+    "user_layer": {
+      "description": "Read-only user-layer metadata ({path, rules}) when scanning outside a governed Aegis workspace.",
+      "type": "object"
+    },
+    "warnings": {
+      "description": "Optional non-fatal scan warning messages.",
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "warnings_count": {
+      "description": "Total count of warnings before 'summary' view truncation (present when view='summary').",
+      "type": "integer"
+    }
+  },
+  "required": [
+    "relevant_rules"
+  ],
+  "type": "object"
+}
  3. First observedv0.1.0

TDQS

A4.6/5.0
Behavior5/5

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

Goes well past the annotations by disclosing the two-slot cap on mandatory rules, the `omitted_mandatory` overflow field, the reviewed-base binding rule with `unreviewed_rules`, and fail-closed behavior on load errors. It also discloses the session-recording side effect, which is worth noting against readOnlyHint but reads as internal telemetry rather than a mutation of domain data.

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?

Effectively front-loaded: the trigger condition and core behavior come first, then edge cases and routing. It is a single dense paragraph with backticked field names, and every clause carries information, though the flow is slightly overpacked.

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?

With no output schema, the description still names the key return fields (`omitted_mandatory`, `unreviewed_rules`) and the failure mode. For a two-parameter read tool with full schema coverage, nothing an agent needs to call it correctly is missing.

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 coverage is 100% and both parameters are fully documented there, including the `files` default and the `view` enum. The description only restates the `files` default and adds nothing about `view` modes or path format, so baseline 3 applies.

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

Purpose5/5

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

States a specific verb and resource: returns the rules applicable to `files`, ranked by fitness within a token budget, and defaults to the git diff. It explicitly contrasts with the sibling `aegis_list_rules` ("browse without recording"), so an agent can distinguish the two without opening either schema.

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?

Opens with a directive ("Call before editing files") and names both alternatives plus their selecting conditions: `aegis_list_rules` when you want to browse without recording, `aegis_report_outcome` after verifying. When-to-use and when-not-to-use are both explicit.

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

Deploy Server

Other Tools