Skip to main content
Glama
Trestle MCP

Trestle MCP

Official

Import OSCAL Model

trestle_import

Import OSCAL models from URLs or local file paths into a Trestle workspace, automatically saving each model in the directory for its OSCAL type.

Instructions

Import an existing OSCAL model into the trestle workspace.

This tool imports OSCAL models from URLs or local file paths. The imported file will be saved in the appropriate directory based on its OSCAL type (e.g., catalogs/, profiles/, component-definitions/).

Import Behavior:

  • Catalog → catalogs/{output}/catalog.json

  • Profile → profiles/{output}/profile.json

  • Component Definition → component-definitions/{output}/component-definition.json

  • SSP → system-security-plans/{output}/system-security-plan.json

Args: params (TrestleImportInput): Validated input parameters containing: - file (str): OSCAL file to import (URL or file path) - output (str): Name of output element - regenerate (bool): Force generation of new UUIDs (default: false) - trestle_root (Optional[str]): Path to trestle root directory - verbose (bool): Display verbose output (default: false)

Returns: str: Success message with import details or error

Examples: - Import NIST SP800-53 Rev5 Catalog: file="https://raw.githubusercontent.com/usnistgov/oscal-content/refs/heads/main/nist.gov/SP800-53/rev5/json/NIST_SP-800-53_rev5_catalog.json" output="nist_sp800_53_rev5"

- Import from local file:
  file="./resources/catalogs/your_catalog.json"
  output="mycatalog"

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

Input Schema

NameRequiredDescriptionDefault
paramsYes

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.2

TDQS

A3.8/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false, so the safety profile is covered. The description still adds meaningful context beyond that: the exact destination path for each OSCAL model type and the fact that 'regenerate' forces new UUIDs. The notable omission is what happens if 'output' collides with an existing element — overwrite versus error is not disclosed, which matters for a non-destructive-but-writing 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?

The description is front-loaded with the one-line purpose, then a behavior block, then Args, Returns, and Examples, which makes it scannable. Every section is relevant, though the Args list largely restates the input schema and the Returns line duplicates information an existing output schema already provides. Slight redundancy, but nothing is confusing or bloated to the point of harming selection.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a write tool with five hidden sub-parameters and an output schema, the definition covers purpose, destination paths, supported model types, parameter meanings, and worked examples — an agent could invoke it correctly. What is missing is edge-case behavior: overwriting an existing output element, handling of invalid or non-OSCAL input, and whether network access is required for URL sources. These are secondary given the output schema and annotations already supplied.

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?

Reported schema description coverage is 0% at the top level and the tool wraps five sub-fields inside a single 'params' object, so the description must carry the burden — and it does, listing each of file, output, regenerate, trestle_root, and verbose with types and defaults. It also supplies concrete example values (an NIST URL and a relative path) that the schema lacks. Much of the Args text mirrors the nested schema descriptions, so the value added is real but not extensive.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Import an existing OSCAL model into the trestle workspace,' and immediately clarifies that the source can be a URL or local file. It also enumerates which OSCAL types are supported and where each gets placed, so an agent knows exactly what the tool produces. It does not explicitly contrast itself with siblings such as trestle_validate or trestle_init, but 'import' is distinct enough that confusion is unlikely.

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?

Usage is conveyed only through two examples (importing the NIST SP800-53 catalog by URL versus a local file path). There is no explicit statement of when to choose this tool over trestle_init, trestle_validate, or the author_* generation tools, and no prerequisites such as whether the workspace must already be initialized or whether validation happens afterward. The examples help parameter selection but do not serve as real tool-selection guidance.

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