Trestle MCP

Official

by oscal-compass

Overview Schema Source Related Servers Discussions Admin

Python

Local

Validate OSCAL Document

trestle_validate

Read-onlyIdempotent

Validate a standalone OSCAL file against the OSCAL schema, enforcing required fields and types, with optional semantic checks for duplicate UUIDs and broken references.

Instructions

Validate a standalone OSCAL file against the OSCAL schema.

This tool loads the OSCAL document through the trestle model classes, which enforces the OSCAL schema (required fields, field types, enums, UUID formats, and nesting). Optionally it also runs trestle's semantic validators (duplicate UUIDs, broken internal references, links, and rule parameters).

It detects the model type from the file's single top-level wrapper key, so it validates any top-level OSCAL model: catalog, profile, component-definition, system-security-plan, assessment-plan, assessment-results, or plan-of-action-and-milestones.

Unlike trestle validate on the CLI, this works on a standalone file that is not part of a trestle workspace — for example a POA&M JSON produced by an authoring flow.

Args: params (TrestleValidateInput): Input parameters with: - file (str): Path to the OSCAL .json/.yaml/.yml file (required) - expected_model_type (Optional[str]): Enforce the file is this model type (e.g. 'plan-of-action-and-milestones') - semantic (bool): Run semantic validators too (default: true)

Returns: str: A pass/fail message; on failure, the concrete reasons.

Examples: - Use when: "Validate this POA&M JSON is valid OSCAL" file="./poam.json", expected_model_type="plan-of-action-and-milestones" - Use when: "Check that catalog.json conforms to the OSCAL schema" - Don't use when: The file is inside a trestle workspace and you want the full trestle validate workspace checks.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`params`	Yes

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.2.1Aug 26, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Read-only, idempotent, non-destructive annotations already establish safety. Beyond that, the description explains model-type auto-detection, optional semantic validators, and what happens on failure, which the annotations do not cover. It provides meaningful behavioral context without contradicting hints.

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?

The description is structured with a clear summary, an Args section, Returns, and Examples. The essential scope and primary usage are front-loaded, and the 'Don't use when' note appears at the end without bloating the start. Every sentence contributes distinct information.

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 the rich input schema, output schema, and read-only annotations, the description covers the required inputs, an optional parameter, semantic validation behavior, accepted file formats, supported models, and non-workspace scope. Little is left for the agent to infer.

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?

Even though the schema's parameter descriptions are detailed and cover all three fields, the tool description adds value by restating the file path requirement, the default for semantic validation, expected_model_type example values, and the POA&M use case. The description does not fully duplicate the schema, and its examples clarify parameter selection.

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 begins with a specific verb and resource: 'Validate a standalone OSCAL file against the OSCAL schema.' It enumerates supported model types and explicitly contrasts itself with the CLI `trestle validate` on workspaces, giving it distinct identity among siblings.

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?

The description gives explicit use cases and a 'Don't use when' condition, routing the agent away from the CLI workspace-based validation. Examples map concrete natural-language requests to parameter values, so when-to-use is unambiguous.

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

Deploy Server