Skip to main content
Glama

scan

Run a scan for a Saga descriptor and return the verdict with findings ranked by priority. This is expensive and has side effects: it clones repositories, executes external scanners and reaches the network.

Instructions

Run a scan for a Saga descriptor and return the verdict with findings ranked by priority. This is expensive and has side effects: it clones repositories, executes external scanners and reaches the network. Prefer summarize_report when a recent report already exists. A severity gate in the verdict judges each finding's rankedSeverity, not its severity. The scan merges draugr.config.yaml from the server's working directory, as draugr scan does.

Scope: this runs the controls the descriptor declares over the components it declares, and nothing else. It is a reproducible floor, not a substitute for reading the code. It does not reason about trust boundaries, whether a build context carries secrets into an image, how credentials are passed to subprocesses, protocol assumptions, or anything a control was not enabled for. If the question was whether a repository is safe to ship rather than whether it passes this gate, keep looking after this returns, the findings here are the part that can be checked the same way every time, not the whole answer. A scan whose scanners do more than read, such as probing a live host or sending data to a third party, or whose results are delivered off this machine, asks the user to approve it first.

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"
  }
}

Input Schema

NameRequiredDescriptionDefault
pathYespath to the Saga descriptor to scan
limitNomaximum findings to return; defaults to 20
minPriorityNoonly return findings at this priority or above: p1, p2, p3 or p4

Output Schema

NameRequiredDescriptionDefault
nextYesthe first thing to do: of the first actions at or above minPriority in fix_list's lists for this report, the one with the highest priority, the earlier list on a tie; the action's title is quoted
noteNo
feedsNoexploitability datasets the scan consulted; absent means no finding was checked against KEV or EPSS
totalYesfindings the report judged, before any priority filter; excludes suppressed
countsYesevery finding total counts, by rankedSeverity, before any priority filter
unreadNodependency files no scanner took packages from, Terraform files calling a module no scanner loaded, Helm charts Trivy could not render, files the secrets scanner skipped, and source files Semgrep skipped or did not finish; what they declare or hold was not checked
verdictYespass or fail, by the same policy the CI gate applies
acceptedNothe suppressed findings with why, until when and where each decision is written, most severe first, capped at limit; report each as a decision, never as work to fix
controlsYesthe controls this scan ran; nothing outside them was examined
findingsYes
returnedYes
deliveredNowhere this run's reports were delivered, from the descriptor's config.publishers
uncoveredNosurfaces this descriptor declares that no enabled control examined
suppressedNofindings a recorded decision took out of the ranking; not part of total
unexaminedYeswhat a Draugr scan does not examine, whatever the verdict

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.180.0
    • addedOutput schema / properties / findings / items / properties / escalation / properties / cve
      Added value: +{
      +  "description": "the CVE the dataset matched, present where the finding's rule id names none",
      +  "type": "string"
      +}
    • changedOutput schema / properties / unread / items / properties / reason / description
      Previous value: -"no lockfile, no pinned versions, a count of requirements not pinned or not read with their names where few, for a pom.xml a count of dependency versions not resolved or transitive dependencies not resolved, no packages read, 'not parsed:' and the parser's error, modules not loaded, name has an archive extension, no files read, 'over 1 MB, not scanned', or a count of rules that timed out with their ids"New value: +"no lockfile, no pinned versions, a count of requirements not pinned or not read with their names where few, for a pom.xml a count of dependency versions not resolved or transitive dependencies not resolved, no packages read, 'not parsed:' and the parser's error, modules not loaded, 'archive extension, not read' with what to do, no files read, 'over 1 MB, not scanned' with what to do, or a count of rules that timed out with their ids"
  2. Changed11 schema fields changedv0.166.3
    • addedOutput schema / properties / accepted / items / properties / rankedSeverity
      Added value: +{
      +  "description": "the severity this finding was ranked at, after the control's minimum severity and every signal; the one the report prints. A suppressed finding fails no gate",
      +  "type": "string"
      +}
    • addedOutput schema / properties / accepted / items / properties / severity / description
      Added value: +"the scanner's own rating, before the control's minimum severity or any signal moved it"
    • changedOutput schema / properties / accepted / items / required
      Previous value: -[
      -  "ruleId",
      -  "severity",
      -  "justification"
      -]New value: +[
      +  "ruleId",
      +  "severity",
      +  "rankedSeverity",
      +  "justification"
      +]
    • addedOutput schema / properties / counts / description
      Added value: +"every finding total counts, by rankedSeverity, before any priority filter"
    • changedOutput schema / properties / findings / items / properties / escalation / properties / from / description
      Previous value: -"the severity the scanner reported"New value: +"the severity before this signal raised it: the scanner's rating, held at severityFloor where that is present"
    • changedOutput schema / properties / findings / items / properties / escalation / properties / to / description
      Previous value: -"the severity the finding was ranked at"New value: +"the severity this signal raised it to"
    • addedOutput schema / properties / findings / items / properties / rankedSeverity
      Added value: +{
      +  "description": "the severity this finding was ranked at (critical, high, medium or low), after the control's minimum severity and every signal; the one the report prints and a severity gate such as --fail-on high or failOnNew judges",
      +  "type": "string"
      +}
    • changedOutput schema / properties / findings / items / properties / severity / description
      Previous value: -"critical, high, medium or low"New value: +"the scanner's own rating (critical, high, medium or low), before the control's minimum severity or any signal moved it; a severity gate reads rankedSeverity, not this"
    • addedOutput schema / properties / findings / items / properties / severityFloor
      Added value: +{
      +  "description": "the minimum severity this finding's control holds its findings at, present only where it raised the scanner's rating",
      +  "type": "string"
      +}
    • changedOutput schema / properties / findings / items / required
      Previous value: -[
      -  "severity",
      -  "ruleId",
      -  "message"
      -]New value: +[
      +  "severity",
      +  "rankedSeverity",
      +  "ruleId",
      +  "message"
      +]
    • changedOutput schema / properties / unread / description
      Previous value: -"dependency files no scanner took packages from, Terraform files calling a module no scanner loaded, files the secrets scanner skipped, and source files Semgrep skipped or did not finish; what they declare or hold was not checked"New value: +"dependency files no scanner took packages from, Terraform files calling a module no scanner loaded, Helm charts Trivy could not render, files the secrets scanner skipped, and source files Semgrep skipped or did not finish; what they declare or hold was not checked"
  3. Changed4 schema fields changedv0.166.0
    • changedOutput schema / properties / accepted / description
      Previous value: -"the suppressed findings with who decided and why, most severe first, capped at limit; report each as a decision, never as work to fix"New value: +"the suppressed findings with why, until when and where each decision is written, most severe first, capped at limit; report each as a decision, never as work to fix"
    • removedOutput schema / properties / accepted / items / properties / acceptedBy
      Removed value: -{
      -  "description": "a name the descriptor's deprecated acceptedBy states, which nothing verifies; the git history of the exclusion's line in source records who wrote it",
      -  "type": "string"
      -}
    • addedOutput schema / properties / accepted / items / properties / line
      Added value: +{
      +  "description": "for a rule in the descriptor, the line in source it starts at; report.json carries that line's git history in descriptor.exclusions[].gitHistory",
      +  "type": "integer"
      +}
    • changedOutput schema / properties / unread / items / properties / reason / description
      Previous value: -"no lockfile, no pinned versions, no packages read, modules not loaded, name has an archive extension, no files read, 'over 1 MB, not scanned', or a count of rules that timed out with their ids"New value: +"no lockfile, no pinned versions, a count of requirements not pinned or not read with their names where few, for a pom.xml a count of dependency versions not resolved or transitive dependencies not resolved, no packages read, 'not parsed:' and the parser's error, modules not loaded, name has an archive extension, no files read, 'over 1 MB, not scanned', or a count of rules that timed out with their ids"
  4. Changed1 schema field changedv0.162.1
    • changedOutput schema / properties / accepted / items / properties / acceptedBy / description
      Previous value: -"who accepted it; empty means the decision is unattributed"New value: +"a name the descriptor's deprecated acceptedBy states, which nothing verifies; the git history of the exclusion's line in source records who wrote it"
  5. Changed2 schema fields changedv0.160.0
    • changedOutput schema / properties / unread / description
      Previous value: -"dependency files no scanner took packages from, and Terraform files calling a module no scanner loaded; what they declare was not checked"New value: +"dependency files no scanner took packages from, Terraform files calling a module no scanner loaded, files the secrets scanner skipped, and source files Semgrep skipped or did not finish; what they declare or hold was not checked"
    • changedOutput schema / properties / unread / items / properties / reason / description
      Previous value: -"no lockfile, no pinned versions, no packages read, or modules not loaded"New value: +"no lockfile, no pinned versions, no packages read, modules not loaded, name has an archive extension, no files read, 'over 1 MB, not scanned', or a count of rules that timed out with their ids"
  6. Changed1 schema field changedv0.157.0
    • changedOutput schema / properties / next / description
      Previous value: -"what to do with this result"New value: +"the first thing to do: of the first actions at or above minPriority in fix_list's lists for this report, the one with the highest priority, the earlier list on a tie; the action's title is quoted"
  7. First observedv0.1.0

TDQS

A4.3/5.0
Behavior3/5

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

No annotations are supplied, so the description carries the full behavioral burden and does so well: it declares cost, side effects (cloning, external scanners, network), config merging from the server working directory, and a non-obvious gate rule (judges rankedSeverity, not severity). The gap is that it never describes what the verdict or findings look like, permissions, or failure modes beyond a new output schema the agent must open.

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?

Dense but front-loaded: cost and side effects are stated before scope, and scope before the caveat. Every sentence carries new information, and the terse 'Scope:' label structures the long caveat block readably.

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 a 3-param tool with full schema coverage, an output schema for return values, and no annotations, the description supplies everything an agent needs: what it does, when to avoid it, its cost and side effects, what it deliberately does not cover, and when to ask for approval.

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

Parameters3/5

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

Schema coverage is 100%, so path, limit and minPriority are already documented inline; that sets the baseline at 3. The description adds only indirect meaning by noting findings are 'ranked by priority' and that the gate uses rankedSeverity, without clarifying how minPriority interacts with that ranking.

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?

Specific verb+resource: 'Run a scan for a Saga descriptor and return the verdict with findings ranked by priority.' It immediately distinguishes itself from summarize_report and describes the output shape (verdict + prioritized findings) without needing the 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?

Explicitly routes agents: 'Prefer summarize_report when a recent report already exists', and adds a when-not clause ('If the question was whether a repository is safe to ship... keep looking after this returns'). It also states a precondition for user approval when scanners probe live hosts or results leave the machine.

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