Skip to main content
Glama
Trestle MCP

Trestle MCP

Official

Generate Component Markdown

trestle_author_component_generate
Destructive

Generates editable Markdown files for each control implementation a component-definition claims, so authors can write implementation prose and YAML headers for later assembly.

Instructions

Generate component in markdown form from a component-definition in the trestle workspace.

This writes one markdown file per control implementation, per component, under ///. The markdown is where an author writes the implementation prose and the rule/parameter yaml header that trestle_author_component_assemble reads back.

Note that generate only writes what the component-definition already declares: it will not create implemented requirements for controls the component-definition does not claim.

Args: params (TrestleAuthorComponentGenerateInput): Input parameters with: - name (str): Source component-definition model name (required) - output (str): Output markdown folder (required) - force_overwrite (bool): Overwrite existing markdown content, discarding edits (default: false) - trestle_root (Optional[str]): Trestle workspace root path - verbose (bool): Display verbose output

Returns: str: Success or error message

Examples: - Use when: "Generate editable markdown for this component definition" - Use when: "Let me write implementation prose for each control a component claims" - Don't use when: There is no component-definition in the workspace yet; import one, or create one with trestle_task_csv_to_oscal_cd. - Don't use when: You only want to regenerate without losing edits — force_overwrite discards author prose.

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

Input Schema

NameRequiredDescriptionDefault
paramsYes

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv1.0.0

TDQS

A4.5/5.0
Behavior4/5

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

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true; the description goes beyond them by explaining what gets written (one file per implementation per component), the directory layout, and that force_overwrite destroys authored edits. It also clarifies a negative behavior not visible in annotations: generate will not create implemented requirements for controls the definition does not claim. Minor gap: it does not say what happens to pre-existing files when force_overwrite is 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?

Front-loaded with the core action and file layout, then scope caveat, then Args/Returns/Examples. Every section is useful, but the 'Use when' examples restate the opening paragraph and the Args list repeats schema fields, adding some redundancy.

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 destructive, file-writing tool this is nearly complete: it covers inputs, output directory structure, overwrite semantics, prerequisite absence, and the return type, and an output schema exists so return values need no elaboration. Remaining gap is the default non-overwrite behavior against existing files.

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 description coverage reads as 0% at the top level (the single 'params' object), so the description must carry the nested field meanings — and it does, enumerating name, output, force_overwrite, trestle_root and verbose with required/default markers. It adds real meaning for force_overwrite ('discarding edits') and trestle_root ('Trestle workspace root path') beyond the terse schema text, though the name/output duplications are largely restated.

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 ('Generate component in markdown form from a component-definition in the trestle workspace') and adds concrete scope: one markdown file per control implementation, per component, under <output>/<component-name>/<source>/. It also explicitly names and characterizes its counterpart, trestle_author_component_assemble, so an agent can separate generation from assembly without reading 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 two positive 'Use when' scenarios and two explicit 'Don't use when' exclusions, including the alternative action to take instead (import or create a definition with trestle_task_csv_to_oscal_cd) and the warning that force_overwrite discards author prose. This is exactly the when/when-not/alternative structure that lets an agent route correctly.

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