VulKill Security

Overview Schema Source Related Servers Discussions Admin

Plan Credit-Bounded Scan Scope & Shard Estimate

vulkill_scan_guided_interactive

Read-onlyIdempotent

Preview scan scope by calculating a zero-credit dry-run plan of covered files, live sites, shard count, and over-quota overflow before launching a real scan.

Instructions

Calculate a dry-run scan execution plan for covered files, live sites, shard count, and uncovered overflow. Call after vulkill_check_credits and before vulkill_start_scan to preview scope. Use vulkill_start_scan to launch a real scan, or vulkill_check_credits when only raw balances are needed. Parameters files and sites specify requested counts, while coveredFiles and coveredSites return accepted quota-bounded counts at 1 file credit per file across ceil(coveredFiles / 5000) shards and 1 site credit per site, placing any over-quota excess into missingFiles and missingSites without failing. Code modes ('source', 'semantic', 'infrastructure') force coveredSites=0, 'web' forces coveredFiles=0 and shards=0, and 'auto' evaluates both. Requires VULKILL_API_KEY or OAuth 2.1 auth, charges zero credits, and launches no workers.

Input Schema

Name	Required	Description	Default
`mode`	No	Analysis profile ('auto', 'source', 'semantic', 'infrastructure', or 'web'; default 'auto').	auto
`files`	No	Requested repository file count for the dry-run plan (0 to 100,000,000, default 0).
`sites`	No	Requested live web/API origin count for the dry-run plan (0 to 10,000, default 0).

Output Schema

Name	Required	Description
`mode`	Yes	Selected scan execution mode ('auto', 'source', 'semantic', 'infrastructure', or 'web').
`shards`	Yes	Number of parallel 5,000-file container shards required for coveredFiles.
`shardSize`	Yes	Maximum files per container shard (5000).
`coveredFiles`	Yes	Number of requested files covered by the caller's available file credits.
`coveredSites`	Yes	Number of requested live sites covered by the caller's available site credits.
`missingFiles`	Yes	Uncovered file count when requestedFiles exceeds remainingFiles (0 if fully covered).
`missingSites`	Yes	Uncovered site count when requestedSites exceeds remainingSites (0 if fully covered).
`creditsCharged`	Yes	Credits deducted by this planning call (always 0).
`requestedFiles`	Yes	Number of files requested by the caller.
`requestedSites`	Yes	Number of live sites requested by the caller.

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv0.1.9Nov 3, 2026

changedInput schema / properties / files / description

Previous value: -"Requested repository file count to include in the dry-run plan (0 to 100,000,000, default 0)."New value: +"Requested repository file count for the dry-run plan (0 to 100,000,000, default 0)."

changedInput schema / properties / mode / description

Previous value: -"Selected analysis profile ('auto', 'source', 'semantic', 'infrastructure', or 'web'; default 'auto')."New value: +"Analysis profile ('auto', 'source', 'semantic', 'infrastructure', or 'web'; default 'auto')."

changedInput schema / properties / sites / description

Previous value: -"Requested live web/API origin count to include in the dry-run plan (0 to 10,000, default 0)."New value: +"Requested live web/API origin count for the dry-run plan (0 to 10,000, default 0)."

Changed3 schema fields changedv0.1.5Nov 3, 2026

changedInput schema / properties / files / description

Previous value: -"Total number of source/repository files to include in the dry-run capacity plan (0 to 100,000,000; partitioned into 5,000-file shards). Defaults to 0."New value: +"Requested repository file count to include in the dry-run plan (0 to 100,000,000, default 0)."

changedInput schema / properties / mode / description

Previous value: -"Scan profile: 'auto' (full multi-engine scan, 35m watchdog), 'source' (SAST/SCA/secrets, 25m watchdog), 'semantic' (deep taint/symbolic solver, 30m watchdog), 'infrastructure' (containers/IaC/binaries, 25m watchdog), or 'web' (live DAST on verified domains, 35m watchdog). Defaults to 'auto'."New value: +"Selected analysis profile ('auto', 'source', 'semantic', 'infrastructure', or 'web'; default 'auto')."

changedInput schema / properties / sites / description

Previous value: -"Total number of verified live web/API origins to include in the dry-run capacity plan (0 to 10,000). Defaults to 0."New value: +"Requested live web/API origin count to include in the dry-run plan (0 to 10,000, default 0)."

Changed7 schema fields changedv0.1.1Nov 3, 2026

addedInput schema / properties / files / default
```
Added value: +0
```

addedInput schema / properties / files / description

Added value: +"Total number of source/repository files to include in the dry-run capacity plan (0 to 100,000,000; partitioned into 5,000-file shards). Defaults to 0."

addedInput schema / properties / mode / default
```
Added value: +"auto"
```

addedInput schema / properties / mode / description

Added value: +"Scan profile: 'auto' (full multi-engine scan, 35m watchdog), 'source' (SAST/SCA/secrets, 25m watchdog), 'semantic' (deep taint/symbolic solver, 30m watchdog), 'infrastructure' (containers/IaC/binaries, 25m watchdog), or 'web' (live DAST on verified domains, 35m watchdog). Defaults to 'auto'."

addedInput schema / properties / sites / default
```
Added value: +0
```

addedInput schema / properties / sites / description

Added value: +"Total number of verified live web/API origins to include in the dry-run capacity plan (0 to 10,000). Defaults to 0."

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "additionalProperties": false,
+  "properties": {
+    "coveredFiles": {
+      "description": "Number of requested files covered by the caller's available file credits.",
+      "type": "integer"
+    },
+    "coveredSites": {
+      "description": "Number of requested live sites covered by the caller's available site credits.",
+      "type": "integer"
+    },
+    "creditsCharged": {
+      "description": "Credits deducted by this planning call (always 0).",
+      "type": "integer"
+    },
+    "missingFiles": {
+      "description": "Uncovered file count when requestedFiles exceeds remainingFiles (0 if fully covered).",
+      "type": "integer"
+    },
+    "missingSites": {
+      "description": "Uncovered site count when requestedSites exceeds remainingSites (0 if fully covered).",
+      "type": "integer"
+    },
+    "mode": {
+      "description": "Selected scan execution mode ('auto', 'source', 'semantic', 'infrastructure', or 'web').",
+      "type": "string"
+    },
+    "requestedFiles": {
+      "description": "Number of files requested by the caller.",
+      "type": "integer"
+    },
+    "requestedSites": {
+      "description": "Number of live sites requested by the caller.",
+      "type": "integer"
+    },
+    "shardSize": {
+      "description": "Maximum files per container shard (5000).",
+      "type": "integer"
+    },
+    "shards": {
+      "description": "Number of parallel 5,000-file container shards required for coveredFiles.",
+      "type": "integer"
+    }
+  },
+  "required": [
+    "mode",
+    "requestedFiles",
+    "requestedSites",
+    "coveredFiles",
+    "coveredSites",
+    "missingFiles",
+    "missingSites",
+    "shardSize",
+    "shards",
+    "creditsCharged"
+  ],
+  "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?

Goes well past the annotations: it discloses zero credit charge, no worker launch, non-failing over-quota behavior, and the auth requirement (VULKILL_API_KEY or OAuth 2.1). These are exactly the operational facts an agent needs before invoking a planning tool, and none are derivable from readOnlyHint/idempotentHint alone.

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 purpose, then sequencing, then semantics, then mode/auth notes — a logical progression with no filler sentences. The middle paragraph is dense (credit model plus shard formula in one clause), which slightly raises reading effort, but every sentence carries information an agent would otherwise have to guess.

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?

Covers the full picture for a three-param planning tool: when to call, cost, side effects, auth, quota math, mode-specific zeroing, and overflow handling. An output schema exists, so return-value structure needn't be documented, yet the description still explains the key output fields semantically.

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?

Even though schema coverage is 100%, the description adds substantial meaning the schema cannot: files/sites are requested counts while coveredFiles/coveredSites are quota-accepted counts, the 1-credit-per-file cost model, the ceil(coveredFiles/5000) shard formula, and overflow routing into missingFiles/missingSites. The mode enumeration is also given behavioral consequences (source/semantic/infrastructure force coveredSites=0; web forces coveredFiles=0 and shards=0), which the enum values alone do not convey.

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: "Calculate a dry-run scan execution plan" with the exact outputs it previews (covered files, live sites, shard count, uncovered overflow). The name of the sibling used for the real launch (vulkill_start_scan) makes the boundary unmistakable without opening any 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?

Gives an explicit ordering rule ("Call after vulkill_check_credits and before vulkill_start_scan") plus two named alternatives with the condition that selects each: start_scan to actually launch, check_credits when only raw balances are needed. Both when-to-use and when-not-to-use are covered.

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

Deploy Server