Skip to main content
Glama

export_cbom

Read-onlyIdempotent

Export a CycloneDX 1.6 CBOM for one directory, carrying verifiable coverage and unmasked-by-default evidence for auditors, customers, or pipeline artefacts.

Instructions

Scan one directory and return a CycloneDX 1.6 CBOM that carries its own coverage.

Same reading as scan_repo; a different document. Use this when the result has to leave the machine -- an auditor, a customer, a pipeline artefact -- and scan_repo when a person or an agent is going to read it here.

What the document carries beyond the components: compositions.aggregate states how complete the list is in the schema's own vocabulary, complete only when every file present was examined; properties carries the whole coverage block flattened, including every file not examined with its reason; and each asset carries evidence.occurrences with file, line and matched text.

The coverage block travels as properties because the CycloneDX root object is additionalProperties: false and the format has no field for it. That is the point of emitting it this way rather than a limitation to work around.

The serial number is derived from the two pins and a digest of the findings, not from where the tree sits, so two runs of the same code over the same corpus that find the same things share it and a different result does not. The timestamp is the tree's commit time (or SOURCE_DATE_EPOCH), so two runs over one unchanged tree give the same bytes; the read window stays in the scan result.

The matched text in evidence.occurrences is masked by default, for the reason given on scan_repo and one more: this document is the one built to be sent. An auditor needs the algorithm, the file and the line; the contents of the line are not part of the claim being made.

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

Input Schema

NameRequiredDescriptionDefault
pathYesDirectory to scan and export, same argument as `scan_repo`.
levelNoHow much of each matched line to carry in `evidence.occurrences`. Same three levels and the same default as `scan_repo`.masked

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.17.0
    • addedInput schema / properties / level
      Added value: +{
      +  "default": "masked",
      +  "description": "How much of each matched line to carry in `evidence.occurrences`. Same three levels and the same default as `scan_repo`.",
      +  "enum": [
      +    "full",
      +    "masked",
      +    "trimmed"
      +  ],
      +  "title": "Level",
      +  "type": "string"
      +}
  2. Addedv0.7.0

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already declare readOnly, idempotent and closed-world, but the description adds genuinely non-obvious behavior: the serial number is derived from pins plus a findings digest rather than tree location, and the timestamp is commit time or SOURCE_DATE_EPOCH, so identical inputs yield byte-identical output. It also discloses the default masking of matched text and why, and how coverage is embedded via `properties` given the schema's `additionalProperties: false`.

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?

Purpose and the sibling distinction are front-loaded in the first two paragraphs, and most sentences carry real information. A few lines are rhetorical rather than informative — e.g. "That is the point of emitting it this way rather than a limitation to work around" — and the total length is heavy for a two-parameter tool.

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?

Despite an output schema existing, the description still explains the document's salient structure (aggregate completeness vocabulary, flattened coverage properties, evidence occurrences) and determinism guarantees, which are exactly what an agent needs to reason about the artifact. Nothing material is missing for a read-only export tool.

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 baseline would be 3, but the description adds meaning: `path` is the same argument as `scan_repo`, and `level` controls how much of each matched line is carried in `evidence.occurrences`, with the default tied to the fact that this document is the one built to be sent. It stops short of enumerating the three levels' semantics, deferring to `scan_repo`.

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 — scan one directory and return a CycloneDX 1.6 CBOM — and explicitly positions it against the sibling `scan_repo` ("Same reading as `scan_repo`; a different document"). An agent can distinguish the two 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 Guidelines5/5

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

Gives an explicit selection rule: use this when the artifact must leave the machine (auditor, customer, pipeline artifact), and `scan_repo` when a human or agent will read it in place. That is a concrete when-to-use / when-to-use-the-alternative pair, not an implied one.

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