Aegis Jail MCP

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

Annotations already flag destructiveHint=true; the description adds genuinely new behavior: it refuses when files changed in the meantime (a concurrency guard) and requires prior user approval. It stops short of saying whether the copy is reversible or how partial failures are handled, so not a 5.

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

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

Two tight sentences: what it does first, then the gating condition. No filler, and the destructive operation's precondition is placed where an agent will read it before acting.

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

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

For a destructive, 2-parameter mutation with full schema coverage and no output schema, the description covers purpose, safety check, and approval gate. Minor gap: it doesn't indicate the result of a successful apply or recovery options if the conflict refusal fires.

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

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

Schema description coverage is 100%, so 'run' (with 'last' shorthand) and 'project' (absolute path defaulting to cwd) are fully documented upstream. The description references 'a run's changes' but adds no format or default detail beyond that; baseline 3 applies.

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

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

States a specific verb ('copy a run's changes') and target ('the real project'), which is unmistakable against siblings like aegis_diff (preview) and aegis_discard (throw away). An agent can route correctly without opening a sibling schema.

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

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

Gives an explicit, hard precondition: 'Only call this after the user has reviewed the diff and agreed.' It also implicitly names the alternative workflow (diff first, then apply), leaving little to inference.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description usefully scopes the result to the run's working copy rather than the committed tree, but it says nothing about diff size limits, truncation of large diffs, or whether untracked/binary files appear.

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

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

A single sentence with zero filler, front-loading the output type ('unified diff') ahead of the scoping qualifier. Nothing is repeated from the name or annotations.

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

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

For a simple read-only two-optional-parameter tool with no output schema, the description conveys enough to invoke it correctly. The only meaningful gap is behavior on very large diffs and what 'working copy' includes, which a slightly longer description could cover.

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

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

Schema description coverage is 100% – both 'run' (including the 'last' shorthand) and 'project' (with its cwd default) are fully documented in the schema. The description adds no parameter-level detail beyond that, so the baseline of 3 applies.

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

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

The description pairs a specific verb ('Show') with a specific artifact ('unified diff of the files a run changed in its working copy'), making the tool's output clearly distinct from mutating siblings like aegis_apply or aegis_discard. It doesn't explicitly name a sibling alternative, so it stops short of a 5.

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

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

Usage is implied – an agent can infer this inspects changes before applying or discarding them – but the description never states when to use it, when not to, or which sibling to prefer for related inspection (e.g. aegis_runs). No explicit routing guidance is present.

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

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

The only annotation is a title ("Discard changes"); there is no destructiveHint or readOnlyHint, so the description carries the full burden. It never states that the working copy is destroyed irreversibly, whether the run itself survives, or whether any confirmation is possible — the most important facts for a destructive tool.

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

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

A single front-loaded sentence with no filler, but the brevity comes at the cost of the behavioral detail a destructive tool needs rather than being tight and complete.

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

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

For a destructive, irreversible mutation with no safety annotations and no output schema, one sentence is insufficient. The agent cannot tell what happens to the run record afterward, whether the discard is recoverable, or how it interacts with aegis_apply.

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

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

Schema description coverage is 100%: 'run' is documented as a run id or 'last', and 'project' as an absolute path defaulting to the server's cwd. The description adds nothing beyond that, so the baseline 3 applies.

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

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

"Throw away a run's working copy" gives a concrete verb (discard) and a concrete resource (a run's working copy), which is distinguishable from siblings like aegis_apply, aegis_diff, and aegis_run. It does not explicitly contrast itself with those siblings, so it stops short of a 5.

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

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

There is no guidance on when to discard versus when to inspect with aegis_diff or aegis_runs first, and no mention of preconditions or required state. The agent must infer the workflow entirely from the sibling names.

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

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

readOnlyHint=true already tells the agent nothing persists, and the description usefully adds what is exercised (secrets, writes, network, child processes) — implying sandboxed real execution rather than static inspection. However it does not disclose runtime cost, whether a sandbox/container is required, or how failures surface, which matter for a probe that actually attempts forbidden operations.

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

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

A single well-formed sentence that front-loads the action and lists the probed surface compactly. No filler, though the terseness leaves no room for the routing/behavioral detail the tool would benefit from.

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

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

With zero required params and a fully documented schema the call mechanics are covered, but there is no output schema and the description never says what a probe returns (pass/fail per boundary? a report?) or how long it takes. For a verification tool whose value is its results, that is a meaningful gap.

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

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

Schema description coverage is 100%; both 'profile' and 'project' are documented in the schema, including the default profile semantics. The description adds no parameter-level information, so the baseline of 3 applies.

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

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

The description names a concrete action (empirically test a profile's boundary enforcement) and enumerates the boundary classes checked: secrets, writes, network, child processes. It is clearly distinct from lifecycle siblings like aegis_apply/aegis_discard, though it never explicitly contrasts itself with aegis_scan.

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

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

The phrase 'test in practice' implies this is the runtime verification counterpart to a static check, but the description never states when to prefer this over aegis_scan or aegis_run, nor any prerequisites (e.g., an existing profile). Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds that results include each profile's allowed actions, giving a hint about return content, but says nothing about ordering, scope, or behavior when no profiles exist.

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

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

One sentence, front-loaded with the action and resource, with zero wasted words. Nothing is repeated from the schema or annotations.

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

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

For a simple read-only list tool with one optional, fully documented parameter and no output schema, the description conveys enough to call it correctly. A brief note on what the output looks like or when listing is appropriate would close the remaining gap.

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

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

The single optional 'project' parameter is fully documented in the schema (100% coverage), including its cwd default. The description only gestures at scoping with 'the project's', adding no semantics beyond the schema, so baseline 3 applies.

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

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

States a specific verb (List) and resource (Aegis profiles) plus the informative detail 'what each one allows', which distinguishes it from mutating siblings like aegis_apply or aegis_run. It does not explicitly name a sibling it might be confused with, so it falls short of a 5.

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

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

There is no statement of when to use this versus aegis_probe, aegis_runs, or aegis_scan, and no mention of prerequisites such as needing an initialized Aegis project. Usage is only inferable from the verb.

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

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

Annotations only give openWorldHint=false, so the description carries the burden and does it well: no home directory or credential reads, no writes outside the copy, no network unless the profile permits, and changes are non-destructive until aegis_apply. It also discloses the return payload (exit code, output, changed files, blocked operations), which is exactly the behavioral context an agent needs before invoking.

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

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

Three tight sentences, front-loaded with the what and immediately followed by the safety constraints and the return shape. Every sentence carries distinct information with no repetition of the schema.

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

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

With no output schema and only openWorldHint in annotations, the description supplies the missing pieces: isolation guarantees, mutation staging via aegis_apply, and the structure of the result. An agent can decide to call it and interpret the response without further tools.

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

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

Schema coverage is 100%, so a baseline of 3 is guaranteed; the description adds real value by explaining that the profile governs network access and that defaults are the strictest profile, giving meaning to the profile parameter beyond its schema text. It does not add much for timeout, project, or allow_hosts, keeping it out of the top score.

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

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

States a specific verb and resource (run a shell command) plus the crucial scope modifier: inside the Aegis sandbox on a fresh *copy* of the project. That framing immediately separates it from the sibling inspection tools (aegis_probe, aegis_scan) and the mutation tools (aegis_apply).

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

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

Clearly conveys the operating context (isolated execution) and the follow-up path: changes stay in the copy until aegis_apply, which routes the agent to the right sibling after running. It does not explicitly say when to prefer aegis_probe/aegis_scan over this tool or when not to use it, so it stops short of full alternative routing.

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

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

The readOnlyHint annotation already establishes that this is a safe read operation. The description adds the scoping word 'recent' and ties results to a project, but it does not define recency, ordering, limits, pagination, or what is returned. With annotations carrying the safety profile, this is adequate but not rich.

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

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

The description is a single front-loaded sentence with no filler or redundancy. It is appropriately sized for a simple list operation.

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

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

For a simple read-only listing tool with one optional parameter and no output schema, the description covers the core action but leaves gaps around what 'recent' means, how many runs are returned, ordering, and result shape. These omissions are not severe, but the description does not fully compensate for the absence of an output schema.

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

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

The only parameter, project, is fully described in the schema, including its default behavior. The description's phrase 'of a project' reinforces the schema but adds no syntax, constraints, or additional meaning beyond it.

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

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

The description states a clear verb and resource: 'List recent Aegis runs of a project.' It implicitly contrasts with the sibling aegis_run by using 'List' rather than an execution verb, but it does not explicitly differentiate itself from aegis_run or the other siblings.

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

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

The description implies usage by saying it lists recent runs for a project, but it gives no explicit guidance on when to use this tool versus aegis_run, aegis_diff, or other siblings. There are no exclusions or alternative-routing instructions.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces this with the emphatic 'Runs nothing', while adding the material behavioral detail that the analysis is static only. It does not describe cost, runtime, or how findings are surfaced, but for a read-only scanner the safety profile is adequately conveyed and non-contradictory.

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

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

Three short sentences: verb+scope first, detection surface second, usage condition last. No filler, and the most decision-relevant content is front-loaded.

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

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

With only two optional params, no output schema, and readOnly already annotated, the description covers what an agent needs to decide to call it and what the scan does and does not do. What is missing is any hint of what the result contains (findings, severity, pass/fail) for an agent that must act on the output.

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

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

Schema description coverage is 100% and both parameters are optional with defaults documented, so the schema carries the burden. The description says nothing about the relationship or precedence between 'path' and 'project', which is the one ambiguity the schema leaves open.

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

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

A specific verb ('Statically scan') applied to a specific resource (directory/repo/skill/plugin/MCP server), followed by an enumerated list of the exact threat classes it detects. It is clearly distinguishable from siblings like aegis_run and aegis_probe, which by name imply execution and active probing rather than static inspection.

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

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

The closing sentence 'Use before working in an unfamiliar repo' gives a concrete triggering condition. It does not, however, state when to prefer a sibling (e.g., aegis_probe or aegis_run) or any exclusions, so routing is clear in one direction only.

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