mcp-secret-sentinel

Overview Schema Source Related Servers Discussions Admin

scan_file

Read-onlyIdempotent

Scan a single file to detect exposed secrets, apply project allowlists and baselines, and return redacted findings; binary and files over 5 MB are skipped.

Instructions

Scan a single file for exposed secrets.

UTF-8, UTF-16 and UTF-32 text is decoded by byte-order mark. Binary files (null-byte heuristic) and files larger than 5 MB are skipped and reported as such in the summary. The project's .secret-sentinel.toml and baseline apply.

Args: path: Absolute path to the file to scan. max_findings: List at most this many findings, most severe first (default 200, 0 = no limit).

Returns: The standard redacted findings report (see scan_text). Returns an error result if the file does not exist.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "path": "<path>"
    },
    "name": "scan_file"
  }
}

Input Schema

Name	Required	Description	Default
`path`	Yes
`max_findings`	No

Output Schema

Name	Required	Description	Default
`clean`	Yes
`summary`	Yes
`findings`	Yes
`baselined`	No
`top_files`	No
`truncated`	No
`suppressed`	No
`files_scanned`	Yes
`total_findings`	No
`counts_by_pattern`	No
`counts_by_severity`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.3.0Oct 26, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$defs": {
+    "FileCount": {
+      "properties": {
+        "file": {
+          "title": "File",
+          "type": "string"
+        },
+        "findings": {
+          "title": "Findings",
+          "type": "integer"
+        }
+      },
+      "required": [
+        "file",
+        "findings"
+      ],
+      "title": "FileCount",
+      "type": "object"
+    },
+    "Finding": {
+      "properties": {
+        "advice": {
+          "title": "Advice",
+          "type": "string"
+        },
+        "commit": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "title": "Commit"
+        },
+        "file": {
+          "title": "File",
+          "type": "string"
+        },
+        "line": {
+          "title": "Line",
+          "type": "integer"
+        },
+        "pattern": {
+          "title": "Pattern",
+          "type": "string"
+        },
+        "redacted": {
+          "title": "Redacted",
+          "type": "string"
+        },
+        "severity": {
+          "enum": [
+            "critical",
+            "high",
+            "medium"
+          ],
+          "title": "Severity",
+          "type": "string"
+        }
+      },
+      "required": [
+        "file",
+        "line",
+        "pattern",
+        "severity",
+        "redacted",
+        "advice"
+      ],
+      "title": "Finding",
+      "type": "object"
+    }
+  },
+  "properties": {
+    "baselined": {
+      "anyOf": [
+        {
+          "type": "integer"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "title": "Baselined"
+    },
+    "clean": {
+      "title": "Clean",
+      "type": "boolean"
+    },
+    "counts_by_pattern": {
+      "anyOf": [
+        {
+          "additionalProperties": {
+            "type": "integer"
+          },
+          "type": "object"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "title": "Counts By Pattern"
+    },
+    "counts_by_severity": {
+      "anyOf": [
+        {
+          "additionalProperties": {
+            "type": "integer"
+          },
+          "type": "object"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "title": "Counts By Severity"
+    },
+    "files_scanned": {
+      "title": "Files Scanned",
+      "type": "integer"
+    },
+    "findings": {
+      "items": {
+        "$ref": "#/$defs/Finding"
+      },
+      "title": "Findings",
+      "type": "array"
+    },
+    "summary": {
+      "title": "Summary",
+      "type": "string"
+    },
+    "suppressed": {
+      "anyOf": [
+        {
+          "type": "integer"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "title": "Suppressed"
+    },
+    "top_files": {
+      "anyOf": [
+        {
+          "items": {
+            "$ref": "#/$defs/FileCount"
+          },
+          "type": "array"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "title": "Top Files"
+    },
+    "total_findings": {
+      "anyOf": [
+        {
+          "type": "integer"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "title": "Total Findings"
+    },
+    "truncated": {
+      "anyOf": [
+        {
+          "type": "boolean"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "title": "Truncated"
+    }
+  },
+  "required": [
+    "clean",
+    "findings",
+    "files_scanned",
+    "summary"
+  ],
+  "title": "ScanReport",
+  "type": "object"
+}

First observedv0.2.0Sep 28, 2026

TDQS

A4.3/5.0

Behavior4/5

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

The description discloses several behaviors beyond what the annotations declare. It states that UTF-8, UTF-16 and UTF-32 text is decoded by its byte-order mark, that binary files and files larger than 5 MB are skipped and reported in the summary, that the .secret-sentinel.toml and baseline settings apply, and that the tool returns an error when the file does not exist. Because the annotations already cover the read-only and idempotent safety profile, this level of added detail is strong.

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 description is front-loaded with a one-line summary followed by clearly labelled Args and Returns sections, and every sentence carries information. The Returns section slightly duplicates what the output schema already provides, but the pointer to scan_text for the report format is still useful.

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 two-parameter read-only scanner, the description covers encoding handling, size and binary skip rules, project-config influence, error conditions, and result ordering, which is everything an agent needs in order to call it correctly. An output schema exists, so the brief note about the redacted report is sufficient.

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 0%, so the description has to carry the full burden, and it documents both parameters: path as an absolute path, and max_findings with its default of 200, its 0 = no limit semantics, and the ordering (most severe first). This adds meaning the bare schema cannot 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?

The description opens with a precise verb+resource statement, "Scan a single file for exposed secrets," which tells an agent exactly what this tool does and implicitly separates it from the sibling tools scan_directory and scan_text: it handles exactly one file. The scope of "single file" is narrow enough that the description disambiguates this tool from the directory and text siblings without opening either schema.

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

Usage Guidelines3/5

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

The phrase "single file" and the error behavior when the file does not exist show the intended usage context, but the description never explicitly says when to prefer this tool over scan_directory or scan_text, nor does it state any prerequisites. The implied scope is enough to infer the correct choice, but there is no explicit routing rule.

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

Deploy Server