Skip to main content
Glama
Trestle MCP

Trestle MCP

Official

Convert CSV to OSCAL Mapping Collection

trestle_task_csv_to_oscal_mc
Destructive

Generate an OSCAL mapping-collection JSON from a formatted CSV of control-to-control correspondences, with relationship types, mapped IDs, and optional confidence and coverage scores.

Instructions

Convert a CSV file to an OSCAL mapping-collection JSON file.

This tool runs the trestle task csv-to-oscal-mc command, which reads a specially formatted CSV of control-to-control correspondences and produces mapping-collection.json — the OSCAL model for "control X over here means the same thing as controls Y and Z over there".

The CSV must have:

  • Row 1: column headings

  • Row 2: column descriptions

  • Row 3+: data rows

Required CSV columns:

  • $$Source_Resource, $$Target_Resource: for each side, a path to a catalog JSON file or an href to a profile. Both sides are loaded and every id in the ref lists is looked up in them. An id that is not found is dropped without a warning, and the row is still written with whatever ids did resolve: ac-1 ac-99-typo on one side produces a map naming ac-1 only, and the run reports success. It fails only when nothing in a row's list resolves at all. So a successful run does not mean every id in the CSV made it into the output -- check the id-refs in mapping-collection.json against the CSV if the mapping has to be complete.

  • $$Map_Source_Id_Ref_List, $$Map_Target_Id_Ref_List: whitespace-separated control ids, or statement ids such as ac-1_smt.a. Several ids on one side are what makes a mapping many-to-many.

  • $$Map_Relationship: the relationship type, as an NCName token. The conventional values are the NIST IR 8477 section 4.3 set-theory relationships — equivalent, subset-of, superset-of, intersects-with, no-relationship — but trestle does not restrict the vocabulary. Leave the cell empty to declare a control unmapped: it is then recorded in the gap summary instead of producing a map entry.

Optional CSV columns:

  • $$Map_Confidence_Score, $$Map_Coverage: percentages expressed in the range 0 to 1, not 0 to 100. A value of 80 is silently dropped with a "Percentage value out of range" warning and the map entry is written without it; write 0.8.

Resource paths in the CSV are resolved relative to the trestle process's working directory, which is trestle_root when you pass one and wherever the server was started when you do not. Pass trestle_root, or use absolute paths, so the CSV does not depend on how the server was launched.

Args: params (TrestleTaskCsvToOscalMcInput): Input parameters with: - title (str): Mapping collection title (required) - version (str): Mapping collection version (required) - csv_file (str): Path to the input CSV file (required) - output_dir (str): Output directory for mapping-collection.json (required) - output_overwrite (bool): Overwrite existing output (default: true) - trestle_root (Optional[str]): Trestle workspace root path (optional) - verbose (bool): Display verbose output (optional)

Returns: str: Success or error message with the output file location

Examples: - Use when: "Map our internal control set onto NIST SP 800-53" - Use when: "Produce an OSCAL mapping collection from this crosswalk spreadsheet" - Don't use when: You want a component definition out of a CSV; use trestle_task_csv_to_oscal_cd. - Don't use when: The CSV is missing a required column, or names control ids that are not in the source or target resource.

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": {
      "params": "<params>"
    },
    "name": "trestle_task_csv_to_oscal_mc"
  }
}

Input Schema

NameRequiredDescriptionDefault
paramsYes

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv1.0.0

TDQS

A4.9/5.0
Behavior5/5

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

Annotations already declare destructiveHint=true and idempotentHint=false, and the description remains consistent with that while adding behavior the annotations cannot express: unresolvable ids are silently dropped and the run still succeeds, an all-unresolved row is the only hard failure, out-of-range percentages are discarded with a warning, and relative paths resolve against the process cwd. These are the exact failure modes an agent needs before invoking a write tool.

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 and well partitioned, with the highest-risk caveats (silent id dropping, percentage range) placed before the mechanical details. The closing "Args:" block largely restates the input schema's own property descriptions, which is redundant bulk, though the rest of the length is earned by genuinely non-obvious edge cases.

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 mutation tool with an output schema, no annotations gap, and a nested params object, it covers everything needed to call it correctly: CSV contract, path resolution, overwrite default, and the success-vs-correctness distinction. Return behavior is summarized briefly, which is sufficient given an output schema exists.

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?

Substantially exceeds the schema: it defines the three-row CSV layout, enumerates required vs optional column tokens, specifies whitespace-separated id-ref syntax including statement ids, and pins the non-obvious 0-to-1 scale for confidence and coverage. It also explains that trestle_root governs how csv_file and resource paths are resolved — meaning the schema alone 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?

States a specific verb+resource pair ("Convert a CSV file to an OSCAL mapping-collection JSON file") and immediately explains what the output means semantically ("control X over here means the same thing as controls Y and Z over there"). It also distinguishes itself from the sibling cd tool by name, so an agent can route 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?

Provides explicit "Use when" and "Don't use when" pairs, including a named alternative (trestle_task_csv_to_oscal_cd) for the adjacent component-definition case and a precondition about missing columns or unresolvable ids. There is a mild internal tension between the don't-use rule about unknown ids and the earlier statement that unknown ids are silently dropped, but the routing intent is unambiguous.

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