Skip to main content
Glama

Update blueprint

update_blueprint
DestructiveIdempotent

Update blueprint fields, replacing content only if the supplied checksum matches so concurrent edits fail instead of being overwritten. Read the blueprint first to get its checksum.

Instructions

Change one of your blueprints. Only the fields you pass change; content replaces the whole text and the old text is not kept. Read the blueprint with get_blueprint first and pass its content_checksum as expected_checksum: if someone edited it since (web UI, CLI, another agent) the call fails with 409 instead of overwriting their change. Setting visibility PUBLIC publishes it to the marketplace.

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": {
      "id": "<id>"
    },
    "name": "update_blueprint"
  }
}

Input Schema

NameRequiredDescriptionDefault
idYesBlueprint id, e.g. bp_clx1abc.
nameNoNew name, at least 3 characters.
tagsNoUp to 10 tags of at most 30 characters, e.g. ["react", "typescript"].
typeNoFile format the blueprint is for. AGENTS_MD is AGENTS.md, CLAUDE_MD is CLAUDE.md, CURSOR_MDC a .cursor/rules/*.mdc file, *_COMMAND a slash command, AGENT_SKILL a skill's SKILL.md, AGENT_DEFINITION a subagent such as .claude/agents/<name>.md, MCP_CONFIG an .mcp.json, CUSTOM anything else.
contentNoNew full text; replaces the current content.
team_idNoTeam to share a TEAM blueprint with; send it together with visibility TEAM. Needed only when you belong to more than one team; with one team, that team is used.
categoryNoCategory slug, e.g. web, devops, saas, mobile, data or other.
visibilityNoPRIVATE (only you), TEAM (your team) or PUBLIC. PUBLIC publishes the content to the public marketplace where anyone can read it.
descriptionNoOne or two sentences on what the blueprint is for.
expected_checksumNocontent_checksum from get_blueprint. Strongly recommended whenever content changes.

Output Schema

NameRequiredDescriptionDefault
successNo
blueprintNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed19 schema fields changedv0.3.0
    • addedInput schema / additionalProperties
      Added value: +false
    • addedInput schema / properties / category
      Added value: +{
      +  "description": "Category slug, e.g. web, devops, saas, mobile, data or other.",
      +  "maxLength": 50,
      +  "type": "string"
      +}
    • changedInput schema / properties / content / description
      Previous value: -"New content for the blueprint (optional)"New value: +"New full text; replaces the current content."
    • addedInput schema / properties / content / minLength
      Added value: +10
    • changedInput schema / properties / description / description
      Previous value: -"New description for the blueprint (optional)"New value: +"One or two sentences on what the blueprint is for."
    • addedInput schema / properties / description / maxLength
      Added value: +1000
    • addedInput schema / properties / expected_checksum
      Added value: +{
      +  "description": "content_checksum from get_blueprint. Strongly recommended whenever content changes.",
      +  "maxLength": 128,
      +  "type": "string"
      +}
    • changedInput schema / properties / id / description
      Previous value: -"ID of the blueprint to update"New value: +"Blueprint id, e.g. bp_clx1abc."
    • addedInput schema / properties / id / maxLength
      Added value: +128
    • addedInput schema / properties / id / pattern
      Added value: +"^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$"
    • changedInput schema / properties / name / description
      Previous value: -"New name for the blueprint (optional)"New value: +"New name, at least 3 characters."
    • addedInput schema / properties / name / maxLength
      Added value: +200
    • addedInput schema / properties / name / minLength
      Added value: +3
    • addedInput schema / properties / tags
      Added value: +{
      +  "description": "Up to 10 tags of at most 30 characters, e.g. [\"react\", \"typescript\"].",
      +  "items": {
      +    "maxLength": 30,
      +    "minLength": 1,
      +    "type": "string"
      +  },
      +  "maxItems": 10,
      +  "type": "array"
      +}
    • addedInput schema / properties / team_id
      Added value: +{
      +  "description": "Team to share a TEAM blueprint with; send it together with visibility TEAM. Needed only when you belong to more than one team; with one team, that team is used.",
      +  "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$",
      +  "type": "string"
      +}
    • addedInput schema / properties / type
      Added value: +{
      +  "description": "File format the blueprint is for. AGENTS_MD is AGENTS.md, CLAUDE_MD is CLAUDE.md, CURSOR_MDC a .cursor/rules/*.mdc file, *_COMMAND a slash command, AGENT_SKILL a skill's SKILL.md, AGENT_DEFINITION a subagent such as .claude/agents/<name>.md, MCP_CONFIG an .mcp.json, CUSTOM anything else.",
      +  "enum": [
      +    "AGENTS_MD",
      +    "CLAUDE_MD",
      +    "COPILOT_INSTRUCTIONS",
      +    "WINDSURF_RULES",
      +    "CLINE_RULES",
      +    "CODEX_MD",
      +    "CURSOR_RULES",
      +    "CURSOR_MDC",
      +    "GEMINI_MD",
      +    "ZED_INSTRUCTIONS",
      +    "VOID_CONFIG",
      +    "TRAE_RULES",
      +    "IDX_CONFIG",
      +    "ROO_RULES",
      +    "CONTINUE_CONFIG",
      +    "CODY_CONFIG",
      +    "TABNINE_CONFIG",
      +    "AMAZONQ_RULES",
      +    "AUGMENT_RULES",
      +    "KILOCODE_RULES",
      +    "JUNIE_GUIDELINES",
      +    "KIRO_STEERING",
      +    "AIDER_MD",
      +    "GOOSEHINTS",
      +    "WARP_MD",
      +    "OPENCODE_JSON",
      +    "OPENHANDS_MD",
      +    "CURSOR_COMMAND",
      +    "CLAUDE_COMMAND",
      +    "WINDSURF_WORKFLOW",
      +    "COPILOT_PROMPT",
      +    "CONTINUE_PROMPT",
      +    "OPENCODE_COMMAND",
      +    "AGENT_SKILL",
      +    "MCP_CONFIG",
      +    "AGENT_DEFINITION",
      +    "CUSTOM"
      +  ],
      +  "type": "string"
      +}
    • changedInput schema / properties / visibility / description
      Previous value: -"New visibility: PRIVATE, TEAM, or PUBLIC (optional)"New value: +"PRIVATE (only you), TEAM (your team) or PUBLIC. PUBLIC publishes the content to the public marketplace where anyone can read it."
    • addedInput schema / properties / visibility / enum
      Added value: +[
      +  "PRIVATE",
      +  "TEAM",
      +  "PUBLIC"
      +]
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "properties": {
      +    "blueprint": {
      +      "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"
      +    },
      +    "success": {
      +      "type": "boolean"
      +    }
      +  },
      +  "type": "object"
      +}
  2. First observedv0.1.0

TDQS

A4.7/5.0
Behavior5/5

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description goes well beyond them: it discloses that unspecified fields are left untouched, that content replaces the entire text and the old text is not kept (irreversible data loss), that a 409 is returned rather than silently overwriting a concurrent edit, and that visibility PUBLIC publishes to the public marketplace. This is exactly the kind of consequence detail annotations cannot convey.

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?

Four short sentences, front-loaded with the core action, then data-loss semantics, then the concurrency protocol, then the publishing side effect. No filler or restatement of the title.

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?

For a 10-parameter mutation tool with a rich output schema, the description covers the riskiest aspects: partial-update semantics, destructive content replacement, optimistic concurrency via checksum, and the public-publishing side effect. Return values are covered by the output schema, so nothing essential is missing.

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, and the description still adds real semantics: content is a full replacement rather than a merge, and expected_checksum is the checksum from get_blueprint whose mismatch triggers a 409. It does not explain the interplay of team_id and visibility TEAM beyond what the schema already says, keeping it at 4.

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?

"Change one of your blueprints" names a specific verb and resource, and the surrounding sentences scope it as a partial-update operation distinct from create_blueprint or delete_blueprint. An agent can distinguish it from every listed sibling without opening a schema.

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?

It gives an explicit prerequisite workflow: call get_blueprint first and pass its content_checksum as expected_checksum, and it warns of the 409 conflict if the resource changed meanwhile. It also covers the PUBLIC/visibility consequence. It stops short of naming alternatives (e.g. when to use create_blueprint instead), so not a 5.

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