VulKill Security

Overview Schema Source Related Servers Discussions Admin

List Live & Completed VulKill Scan Reports

vulkill_list_reports

Read-onlyIdempotent

Retrieve and filter past workspace security scan reports by status or mode to inspect severity counts, CVSS/CWE findings, and credit usage.

Instructions

Retrieve the workspace's security scan reports, including severity counts, CVSS/CWE findings, and credit usage. Call after vulkill_start_scan or vulkill_complete_scan to inspect past results. Do not use to settle an in-flight job (use vulkill_complete_scan) or to check wallet quota (use vulkill_check_credits). Filters status ('running', 'completed', 'not_started_refunded' with creditsCharged=0, or 'failed') and mode ('auto', repository 'source'/'semantic'/'infrastructure', or live 'web') combine with logical AND and sort by createdAt DESC before limit truncates the slice. Because cursor pagination is not used, narrow status or mode to inspect older runs beyond the 25-report cap. Requires VULKILL_API_KEY or OAuth 2.1 auth and isolates records to the caller's workspace. Charges zero credits and enforces 60 requests/minute per workspace.

Input Schema

Name	Required	Description
`mode`	No	Optional scan execution profile filter.
`limit`	No	Maximum number of scan reports to return (1 to 25, default 25).
`status`	No	Optional scan lifecycle status filter.

Output Schema

Name	Required	Description	Default
`reports`	Yes	List of matching scan reports belonging to the authenticated workspace, ordered newest-first.
`reportUrl`	Yes	Direct link to the VulKill web reports dashboard (https://app.vulkill.com/scans).

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedv0.1.5Nov 3, 2026

addedInput schema / properties / limit

Added value: +{
+  "default": 25,
+  "description": "Maximum number of scan reports to return (1 to 25, default 25).",
+  "maximum": 25,
+  "minimum": 1,
+  "type": "integer"
+}

addedInput schema / properties / mode

Added value: +{
+  "description": "Optional scan execution profile filter.",
+  "enum": [
+    "auto",
+    "source",
+    "semantic",
+    "infrastructure",
+    "web"
+  ],
+  "type": "string"
+}

addedInput schema / properties / status

Added value: +{
+  "description": "Optional scan lifecycle status filter.",
+  "enum": [
+    "running",
+    "completed",
+    "not_started_refunded",
+    "failed"
+  ],
+  "type": "string"
+}

changedOutput schema / properties / reports / description

Previous value: -"List of up to 25 recent scan reports belonging to the authenticated workspace, ordered newest-first."New value: +"List of matching scan reports belonging to the authenticated workspace, ordered newest-first."

Changed1 schema field changedv0.1.1Nov 3, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "additionalProperties": false,
+  "properties": {
+    "reportUrl": {
+      "description": "Direct link to the VulKill web reports dashboard (https://app.vulkill.com/scans).",
+      "type": "string"
+    },
+    "reports": {
+      "description": "List of up to 25 recent scan reports belonging to the authenticated workspace, ordered newest-first.",
+      "items": {
+        "properties": {
+          "critical_count": {
+            "description": "Count of critical-severity findings.",
+            "type": "integer"
+          },
+          "high_count": {
+            "description": "Count of high-severity findings.",
+            "type": "integer"
+          },
+          "id": {
+            "description": "Unique scan report ID.",
+            "type": "string"
+          },
+          "info_count": {
+            "description": "Count of informational findings.",
+            "type": "integer"
+          },
+          "low_count": {
+            "description": "Count of low-severity findings.",
+            "type": "integer"
+          },
+          "medium_count": {
+            "description": "Count of medium-severity findings.",
+            "type": "integer"
+          },
+          "mode": {
+            "description": "Scan mode used ('auto', 'source', 'semantic', 'infrastructure', 'web').",
+            "type": "string"
+          },
+          "status": {
+            "description": "Current scan status ('running', 'completed', 'not_started_refunded', 'failed').",
+            "type": "string"
+          },
+          "target_name": {
+            "description": "Scanned target or repository label.",
+            "type": "string"
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "reports",
+    "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 already declare readOnly/idempotent/non-destructive, and the description still adds substantive context beyond them: required auth (VULKILL_API_KEY or OAuth 2.1), workspace record isolation, zero credit charge, and a 60 requests/minute per-workspace limit. It also discloses the pagination constraint and the 25-report cap, which materially affects how a caller must query older runs.

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

Conciseness5/5

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

Four tightly packed sentences with no filler: purpose first, routing second, filter mechanics third, operational constraints last. Every clause conveys distinct, actionable information.

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?

For a filtered list tool with an output schema already documenting returns, the description covers everything an agent needs: what it returns at a high level, when to call it, how filters interact, the result cap, auth needs, cost, and rate limit. No material gap remains.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains that the 'not_started_refunded' status implies creditsCharged=0, that 'source'/'semantic'/'infrastructure' are repository modes while 'web' is live, and that filters combine with AND and sort by createdAt DESC before limit truncates. It stops short of describing limit's interaction with offset-less paging in parameter-level terms, keeping it at 4.

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 (retrieve the workspace's security scan reports) and immediately scopes the payload (severity counts, CVSS/CWE findings, credit usage). It is clearly separable from siblings like vulkill_complete_scan and vulkill_check_credits, which are named directly.

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 explicit positive guidance ('Call after vulkill_start_scan or vulkill_complete_scan to inspect past results') and two explicit negative cases with the correct alternative named for each (in-flight settlement vs. wallet quota). Nothing about tool selection is left to inference.

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

Deploy Server