Skip to main content
Glama

Create hierarchy

create_hierarchy
Idempotent

Creates a hierarchy that groups the blueprints of one repository, such as every AGENTS.md in a monorepo. Identifies repositories by repository_root and returns the existing hierarchy instead of a duplicate.

Instructions

Create a hierarchy: a group that ties the blueprints of one repository together, for example every AGENTS.md of a monorepo. repository_root identifies the repository; if you already have a hierarchy with that repository_root, it is returned unchanged instead of a duplicate. Add blueprints to it with create_blueprint (hierarchy_id plus repository_path). Returns the hierarchy with its ha_ id.

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": {
      "name": "<name>",
      "repository_root": "<repository_root>"
    },
    "name": "create_hierarchy"
  }
}

Input Schema

NameRequiredDescriptionDefault
nameYesDisplay name, e.g. "acme monorepo".
descriptionNoShort description of the hierarchy.
repository_rootYesUnique identifier of the repository, e.g. github.com/acme/monorepo.

Output Schema

NameRequiredDescriptionDefault
treeNoThe same blueprints nested by parent_id
messageNo
successNo
hierarchyNo
blueprintsNoEvery blueprint in the hierarchy, flat
total_blueprintsNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed10 schema fields changedv0.3.0
    • addedInput schema / additionalProperties
      Added value: +false
    • changedInput schema / properties / description / description
      Previous value: -"Short description of the hierarchy (optional)"New value: +"Short description of the hierarchy."
    • addedInput schema / properties / description / maxLength
      Added value: +1000
    • changedInput schema / properties / name / description
      Previous value: -"Name of the hierarchy"New value: +"Display name, e.g. \"acme monorepo\"."
    • addedInput schema / properties / name / maxLength
      Added value: +200
    • addedInput schema / properties / name / minLength
      Added value: +1
    • changedInput schema / properties / repository_root / description
      Previous value: -"Root path of the repository this hierarchy maps to"New value: +"Unique identifier of the repository, e.g. github.com/acme/monorepo."
    • addedInput schema / properties / repository_root / maxLength
      Added value: +500
    • addedInput schema / properties / repository_root / minLength
      Added value: +1
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "properties": {
      +    "blueprints": {
      +      "description": "Every blueprint in the hierarchy, flat",
      +      "items": {
      +        "properties": {
      +          "category": {
      +            "type": [
      +              "string",
      +              "null"
      +            ]
      +          },
      +          "content": {
      +            "description": "The blueprint text (only on single-blueprint reads and updates)",
      +            "type": "string"
      +          },
      +          "content_checksum": {
      +            "description": "Pass as expected_checksum to update_blueprint",
      +            "type": [
      +              "string",
      +              "null"
      +            ]
      +          },
      +          "created_at": {
      +            "type": "string"
      +          },
      +          "description": {
      +            "type": [
      +              "string",
      +              "null"
      +            ]
      +          },
      +          "hierarchy_id": {
      +            "type": [
      +              "string",
      +              "null"
      +            ]
      +          },
      +          "id": {
      +            "description": "Blueprint id, e.g. bp_clx1abc",
      +            "type": "string"
      +          },
      +          "name": {
      +            "type": "string"
      +          },
      +          "parent_id": {
      +            "type": [
      +              "string",
      +              "null"
      +            ]
      +          },
      +          "repository_path": {
      +            "description": "Path in the repository; only the file name for a public blueprint of someone outside your team",
      +            "type": [
      +              "string",
      +              "null"
      +            ]
      +          },
      +          "tags": {
      +            "items": {
      +              "type": "string"
      +            },
      +            "type": "array"
      +          },
      +          "tier": {
      +            "type": [
      +              "string",
      +              "null"
      +            ]
      +          },
      +          "type": {
      +            "description": "File format, e.g. AGENTS_MD or CLAUDE_MD",
      +            "type": "string"
      +          },
      +          "updated_at": {
      +            "type": "string"
      +          },
      +          "visibility": {
      +            "description": "PRIVATE, TEAM or PUBLIC",
      +            "type": "string"
      +          }
      +        },
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "hierarchy": {
      +      "properties": {
      +        "blueprint_count": {
      +          "type": "integer"
      +        },
      +        "created_at": {
      +          "type": "string"
      +        },
      +        "description": {
      +          "type": [
      +            "string",
      +            "null"
      +          ]
      +        },
      +        "id": {
      +          "description": "Hierarchy id, e.g. ha_clx1abc",
      +          "type": "string"
      +        },
      +        "name": {
      +          "type": "string"
      +        },
      +        "repository_root": {
      +          "type": "string"
      +        },
      +        "updated_at": {
      +          "type": "string"
      +        }
      +      },
      +      "type": "object"
      +    },
      +    "message": {
      +      "type": "string"
      +    },
      +    "success": {
      +      "type": "boolean"
      +    },
      +    "total_blueprints": {
      +      "type": "integer"
      +    },
      +    "tree": {
      +      "description": "The same blueprints nested by parent_id",
      +      "items": {
      +        "type": "object"
      +      },
      +      "type": "array"
      +    }
      +  },
      +  "type": "object"
      +}
  2. First observedv0.1.0

TDQS

A4.3/5.0
Behavior4/5

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

Annotations already declare idempotentHint=true, destructiveHint=false and openWorldHint=true. The description still adds real value by naming the idempotency key (repository_root) and specifying that the existing object is returned unchanged rather than erroring or duplicating — behavior the annotations alone can't express. Return-value detail is covered by the output schema, so no penalty there.

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?

Four short sentences, front-loaded with the concept definition before the mechanics. Every sentence carries a distinct fact (definition, identity key, dedupe outcome, next step) with no filler; slightly dense with parenthetical asides but not wasteful.

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?

The tool has an output schema, so return shape needs no elaboration, and the description handles the two things an agent would otherwise get wrong: what a hierarchy is for and what happens on a repeated repository_root. What's missing is minor — whether a hierarchy can be renamed or cleaned up (delete_hierarchy exists among siblings) and any auth/scope prerequisites.

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 is 100%, so the baseline is 3. The description lifts `repository_root` from a mere string field into a uniqueness/identity constraint and thereby implies the practical consequence of reusing a root, which the schema's one-line field description does not convey. Minor uplift is earned; `name` and `description` add nothing beyond their schema descriptions.

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 plus a concrete gloss of what a hierarchy is ("a group that ties the blueprints of one repository together, for example every AGENTS.md of a monorepo"). A reader can distinguish it from create_blueprint, which the description explicitly positions as the follow-up for adding members.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear context: create the container first, then use create_blueprint with hierarchy_id plus repository_path. It also states the dedupe condition (an existing hierarchy with that repository_root is returned unchanged) rather than letting the agent assume a duplicate is created. It stops short of stating when *not* to use it in favor of get_hierarchy/list_hierarchies, so not a full 5.

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