Mipiti MCP Server

Overview Schema Source Related Servers Discussions Admin

Add Attacker

add_attacker

Add a new attacker to a threat model by specifying its capability, position, archetype, and trust boundaries; creates a new model version for security analysis.

Instructions

Add a new attacker to a threat model. Creates a new version.

Authoring contract: capability names the operations the attacker can perform from its position and what they achieve — not just the access or vantage point. Phrase it as "From [position], the attacker can [concrete operations] …" (e.g. "From the network path between the API server and the database, the attacker can read and alter requests and responses to exfiltrate data in transit or inject forged responses"). A capability that states only access is flagged with a quality_warning and the control objectives derived from it may be under-specified.

The caller supplies identity-bearing fields (capability, position, archetype, trust_boundary_ids); the backend reasons the factors. Override one later via edit_attacker with a change_reason.

Three outcomes (normal create / auto-restore / similar-rejection) mirror add_asset (entities holds the attacker). 503 on factor-reasoning or restore-candidate evaluator outage, 502 on malformed restore-candidate response.

surface_extent says how much of the reached interface this attacker's operations range over. An attacker ranging over the whole interface makes the objectives it appears in for-all obligations, which only a sound witness (typed_boundary / sink_default_deny) can credit. Declaring it here is a statement about the attacker's reach, taken with its change_reason: a person's is recorded attested; a program's only under a workspace rule delegating extent_attested, otherwise the attacker is added, the extent lands unattested and the attestation waits for a person (the answer's attestation.escalation_id). Only whole is declarable on a create: narrowing to one named entry is a statement about the objectives the attacker anchors, and a create has none yet — add the attacker, then narrow it with edit_attacker and a change_reason, where the narrowing is checked against the assets those objectives defend. There is no attacker status to set.

Input Schema

Name	Required	Description
`model_id`	Yes	ID of the threat model.
`position`	No	Position/access level.
`archetype`	No	Archetype (e.g., "insider", "external").
`capability`	Yes	Attacker capability description (required).
`change_reason`	No	Required when ``surface_extent`` is supplied — documents the declaration for the audit trail.
`server_version`	Yes
`surface_extent`	No	``"whole"`` when, from its position, the attacker's operations range over ANY entry of the interface it reaches (any endpoint, request, row, file, message or frame). Requires ``change_reason``. Omit to leave it undeclared, which is the ordinary case.
`trust_boundary_ids`	No	Comma-separated ids of the boundaries the attacker has crossed. Naming them attests the position: a person's is recorded attested; a program's only under a rule delegating ``position_attested``, otherwise the position lands suggested and the attestation waits for a person (``attestation.escalation_id``).

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv0.87.0Oct 14, 2026

changedInput schema / properties / surface_extent / description

Previous value: -"``\"whole\"`` when, from its position, the attacker's\noperations range over ANY entry of the interface it reaches\n(any endpoint, request, row, file, message or frame). Recorded\nas attested by this call and requires ``change_reason``. Omit\nto leave it undeclared, which is the ordinary case."New value: +"``\"whole\"`` when, from its position, the attacker's\noperations range over ANY entry of the interface it reaches\n(any endpoint, request, row, file, message or frame). Requires\n``change_reason``. Omit to leave it undeclared, which is the\nordinary case."

changedInput schema / properties / trust_boundary_ids / description

Previous value: -"Comma-separated trust boundary IDs."New value: +"Comma-separated ids of the boundaries the\nattacker has crossed. Naming them attests the position: a\nperson's is recorded attested; a program's only under a rule\ndelegating ``position_attested``, otherwise the position lands\nsuggested and the attestation waits for a person\n(``attestation.escalation_id``)."

Changed2 schema fields changedv0.77.0Sep 9, 2026

addedInput schema / properties / change_reason

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Required when ``surface_extent`` is supplied —\ndocuments the declaration for the audit trail."
+}

addedInput schema / properties / surface_extent

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "``\"whole\"`` when, from its position, the attacker's\noperations range over ANY entry of the interface it reaches\n(any endpoint, request, row, file, message or frame). Recorded\nas attested by this call and requires ``change_reason``. Omit\nto leave it undeclared, which is the ordinary case."
+}

Addedv0.62.2Jul 22, 2026
Removedv0.62.0Jul 17, 2026
First observedv0.57.0Jul 8, 2026

TDQS

A4.5/5.0

Behavior5/5

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

With no annotations, the description carries the full behavioral burden and does so thoroughly: it discloses version creation, auto-restore and similar-rejection outcomes, 503/502 failure modes, quality-warning behavior for capability phrasing, and attestation/escalation semantics for surface_extent and trust_boundary_ids.

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?

The response is front-loaded with the core action and version-creation effect, and its length is largely justified by the tool's complexity. It is dense and somewhat verbose in the authoring-contract and attestation sections, but the information generally earns its place.

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?

Given the 8-parameter schema, high schema coverage, and existing output schema, the description is complete enough for correct invocation. It covers creation behavior, parameter semantics, error conditions, override paths, and attestation/escalation behavior without needing to restate return values.

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

Parameters5/5

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

Schema description coverage is already 88%, but the description adds substantial meaning beyond the schema, especially for capability authoring expectations, the quality_warning consequence, change_reason being required with surface_extent, and the attestation implications of trust_boundary_ids.

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 clearly states the specific action and resource: 'Add a new attacker to a threat model. Creates a new version.' It also distinguishes the tool from edit_attacker for later overrides and mentions that outcomes mirror add_asset, but it does not explicitly distinguish this from the similar sibling add_proposed_attacker.

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

Usage Guidelines4/5

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

The description gives concrete usage guidance, including that callers supply identity-bearing fields, that the backend reasons the factors, and that overrides happen later via edit_attacker with a change_reason. It also states when surface_extent can be declared versus when narrowing must happen later, though it does not explicitly compare against add_proposed_attacker.

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

Deploy Server