VulKill Security

Overview Schema Source Related Servers Discussions Admin

Synchronize Scan Completion or Request Verified Refund

vulkill_complete_scan

Idempotent

Syncs remote scanner state for an existing scan to finalize verified findings or issue an atomic credit refund when the job never started.

Instructions

Synchronize the remote scanner engine state for an existing scanId, finalizing verified findings or issuing an atomic credit refund when the engine confirms the job never started. Call after vulkill_start_scan to settle an active job. Do not use to start new scans (use vulkill_start_scan) or to browse workspace history (use vulkill_list_reports). The scanId must belong to the caller's workspace. Refund verification triggers when cancelRequested=true or started=false (cancelRequested takes precedence when both are passed, and omitting both runs normal completion sync), while summary is ignored when finalized findings exist and saved only as an audit note when a not_started job is refunded. Requires scan-owner VULKILL_API_KEY or OAuth 2.1 auth and returns HTTP 403 for foreign workspaces. Queries the authoritative engine rather than client claims, blocks refunds on running or completed jobs after network timeouts, and credits the originating credit_periods row at most once.

Input Schema

Name	Required	Description
`scanId`	Yes	Unique scan identifier returned by vulkill_start_scan.
`started`	No	Optional legacy boolean flag indicating whether client dispatch succeeded.
`summary`	No	Optional operator fallback note (1 to 600 characters).
`cancelRequested`	No	Boolean flag requesting job cancellation and server-verified refund evaluation (default false).

Output Schema

Name	Required	Description
`ok`	Yes	True when the engine status check succeeded and the scan record was synchronized.
`scanId`	Yes	Scan report identifier.
`status`	Yes	Updated authoritative status ('running', 'completed', 'not_started_refunded', or 'failed').
`reportUrl`	Yes	Dashboard URL for viewing the finalized report (https://app.vulkill.com/scans).
`refundIssued`	Yes	True only on the single atomic transition where reserved credits are restored.
`sitesCharged`	Yes	Net live-site credits charged after completion or refund (0 if refunded).
`creditsCharged`	Yes	Net file credits charged after completion or refund (0 if refunded).

Schema Changelog

Changes observed during successful MCP inspections.

Changed6 schema fields changedv0.1.5Nov 3, 2026

changedInput schema / properties / cancelRequested / description

Previous value: -"Set to true to request job cancellation and server-verified credit refund if the authoritative scanner engine confirms execution never started. Defaults to false."New value: +"Boolean flag requesting job cancellation and server-verified refund evaluation (default false)."

changedInput schema / properties / scanId / description

Previous value: -"Unique scan identifier returned by vulkill_start_scan (required; must belong to the authenticated user)."New value: +"Unique scan identifier returned by vulkill_start_scan."

changedInput schema / properties / started / description

Previous value: -"Legacy alias for cancelRequested (setting started=false requests server-verified non-start refund evaluation; actual refund eligibility is always determined by the authoritative scanner engine)."New value: +"Optional legacy boolean flag indicating whether client dispatch succeeded."

changedInput schema / properties / summary / description

Previous value: -"Optional human-readable note (up to 600 characters) used only if the engine does not supply its own completion summary."New value: +"Optional operator fallback note (1 to 600 characters)."

changedOutput schema / properties / ok / description

Previous value: -"True when the engine status check succeeded and the scan record was updated."New value: +"True when the engine status check succeeded and the scan record was synchronized."

changedOutput schema / properties / refundIssued / description

Previous value: -"True only on the single atomic transition where reserved credits are refunded to the billing period."New value: +"True only on the single atomic transition where reserved credits are restored."

Changed5 schema fields changedv0.1.1Nov 3, 2026

addedInput schema / properties / cancelRequested

Added value: +{
+  "default": false,
+  "description": "Set to true to request job cancellation and server-verified credit refund if the authoritative scanner engine confirms execution never started. Defaults to false.",
+  "type": "boolean"
+}

addedInput schema / properties / scanId / description

Added value: +"Unique scan identifier returned by vulkill_start_scan (required; must belong to the authenticated user)."

addedInput schema / properties / started / description

Added value: +"Legacy alias for cancelRequested (setting started=false requests server-verified non-start refund evaluation; actual refund eligibility is always determined by the authoritative scanner engine)."

addedInput schema / properties / summary / description

Added value: +"Optional human-readable note (up to 600 characters) used only if the engine does not supply its own completion summary."

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "additionalProperties": false,
+  "properties": {
+    "creditsCharged": {
+      "description": "Net file credits charged after completion or refund (0 if refunded).",
+      "type": "integer"
+    },
+    "ok": {
+      "description": "True when the engine status check succeeded and the scan record was updated.",
+      "type": "boolean"
+    },
+    "refundIssued": {
+      "description": "True only on the single atomic transition where reserved credits are refunded to the billing period.",
+      "type": "boolean"
+    },
+    "reportUrl": {
+      "description": "Dashboard URL for viewing the finalized report (https://app.vulkill.com/scans).",
+      "type": "string"
+    },
+    "scanId": {
+      "description": "Scan report identifier.",
+      "type": "string"
+    },
+    "sitesCharged": {
+      "description": "Net live-site credits charged after completion or refund (0 if refunded).",
+      "type": "integer"
+    },
+    "status": {
+      "description": "Updated authoritative status ('running', 'completed', 'not_started_refunded', or 'failed').",
+      "type": "string"
+    }
+  },
+  "required": [
+    "ok",
+    "scanId",
+    "status",
+    "refundIssued",
+    "creditsCharged",
+    "sitesCharged",
+    "reportUrl"
+  ],
+  "type": "object"
+}

First observedv0.1.0Nov 3, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Annotations only cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), and the description goes well past them: auth requirements (scan-owner VULKILL_API_KEY or OAuth 2.1), HTTP 403 for foreign workspaces, server-side verification against the authoritative engine rather than client claims, refund blocking on running/completed jobs after timeouts, and at-most-once crediting of the credit_periods row. These are exactly the mutation-safety details an agent needs.

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?

Front-loaded with the core action and zero filler, but the third sentence packs refund triggers, precedence, and summary handling into one long multi-clause statement that is harder to parse than it needs to be. Slightly dense rather than bloated.

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 an output schema present, return values need not be described, and the description still covers auth, error behavior (403), idempotency/refund guarantees, and parameter precedence for a four-parameter mutating tool. Nothing an agent needs in order to call it safely is missing.

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 coverage is already 100%, but the description adds precedence semantics the schema does not state: cancelRequested wins over started when both are passed, omitting both runs a normal completion sync, and summary is ignored when finalized findings exist yet retained as an audit note on a not_started refund. This is genuine meaning beyond the field descriptions.

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?

The description opens with a specific verb+resource ('Synchronize the remote scanner engine state for an existing scanId') and immediately enumerates the two possible outcomes: finalizing verified findings or issuing an atomic credit refund. It explicitly names the sibling tools it is not (vulkill_start_scan, vulkill_list_reports), so an agent can route correctly without opening schemas.

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?

Explicit lifecycle guidance ('Call after vulkill_start_scan to settle an active job') plus two negative cases with named alternatives: do not start new scans, do not browse history. That is the full when/when-not/alternative triad.

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

Deploy Server