Skip to main content
Glama
MCP Agent Operations

MCP Agent Operations

create_hierarchy_plan

Create a hierarchy plan from inline structured data or JSON/YAML files, saving durable HTML/JSON outputs or returning canonical inline JSON when no destination is set.

Instructions

Create a hierarchy plan as durable files or canonical inline JSON.

Source, theme, and output paths must be absolute beneath the hierarchy roots. The output folder defaults to MCP_AGENT_OPS_HIERARCHY_OUTPUT_FOLDER. When neither destination is supplied, the tool returns JSON without writing files.

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": {
      "source": "<source>",
      "output_filename": "<output_filename>"
    },
    "name": "create_hierarchy_plan"
  }
}

Input Schema

NameRequiredDescriptionDefault
themeNoPackaged or custom theme base name without `.css`.default
titleNoBrowser and page title.Hierarchy plan
sourceYesInline mapping, sequence, JSON, YAML, or an absolute JSON/YAML path.
output_folderNoOptional absolute destination beneath an authorized hierarchy root. Overrides the configured default folder.
themes_folderNoAbsolute folder for a custom theme, or null for packaged themes.
completed_itemsNoExact dotted paths or unique titles initially marked complete.
output_filenameYesBase HTML filename; the JSON plan uses the same base name.

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.15.1
    • changedInput schema / properties / output_folder / description
      Previous value: -"Optional absolute destination beneath a configured workspace."New value: +"Optional absolute destination beneath an authorized hierarchy root.\nOverrides the configured default folder."
  2. Addedv0.11.0

TDQS

A3.6/5.0
Behavior3/5

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

With no annotations, the description carries the full burden; it does disclose the key behavioral fact that the tool may write files, the path-authorization constraint (absolute paths beneath hierarchy roots), the env-var default, and the no-write fallback. It omits what happens on overwrite of an existing `output_filename`, whether writes are atomic, and any permission/validation behavior, which matter for a mutation 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?

Three sentences with the purpose front-loaded, followed by constraints and the fallback rule in descending order of importance. No filler, though the env-var sentence is somewhat specialized detail that could be collapsed.

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 7-parameter creation tool with an output schema (so return values need no explanation), the description covers path constraints, defaults, and the no-destination behavior. The remaining gap is lifecycle positioning relative to `update_hierarchy_plan`, which an agent would need before choosing this 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 is 3; the description still adds cross-parameter meaning beyond the schema by explaining the interaction between `output_folder`/`output_filename` and the JSON-only fallback, plus the env-var default for the output folder. The `source` and `theme` semantics are already fully spelled out in the schema, so no extra credit there.

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?

States a specific verb and resource ("Create a hierarchy plan") plus the two output modes (durable files vs. canonical inline JSON), which is more than a restated name. It does not explicitly contrast with `update_hierarchy_plan` or `render_hierarchy_html`, so sibling differentiation is left to inference.

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?

There is one concrete usage rule: when neither destination is supplied, the tool returns JSON without writing files. Otherwise there is no explicit when-to-use/when-not guidance and no mention of when to prefer `update_hierarchy_plan` over this creation tool, so the agent must infer lifecycle placement.

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