Skip to main content
Glama
Sign In
Kiln

Kiln

by codeofaxel
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python

retire_design_branch

Destructive

Mark a design branch as retired to preserve its records and free the branch name for reuse. Use it when a branch is no longer active but must remain auditable.

Instructions

Mark a branch retired — preserves records, frees the name.

Free door, tiered answer — Free: Branch · merge · cherry-pick · undo, on the designs you keep · Pro: Branch · merge · cherry-pick · undo, on every design · Business: ✓ · Enterprise: ✓.

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": {
      "branch_id": "<branch_id>"
    },
    "name": "retire_design_branch"
  }
}

Input Schema

NameRequiredDescriptionDefault
branch_idYesId of the design branch to retire. On a design owned by a team the caller must hold that team's admin role, or the retire is refused.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv1.5.1
    • addedInput schema / properties / branch_id / description
      Added value: +"Id of the design branch to retire.  On a design owned by a team the caller must hold that team's admin role, or the retire is refused."
  2. Addedv1.5.0

TDQS

B3.2/5.0
Behavior4/5

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

Annotations already flag destructiveHint=true and readOnlyHint=false, and the description genuinely adds to that by clarifying this is a soft retirement — records survive, only the name is released — which is exactly the distinction an agent needs before calling a 'destructive' tool. It stops short of stating reversibility/undo, whether unmerged work blocks retirement, or what happens to dependent branches or PRs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The opening sentence is tight and front-loaded, but the second sentence is a pricing/marketing tier listing that is irrelevant to whether or how an agent invokes this tool and dilutes an otherwise clean definition. Half the description does no work.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter state-changing operation with no output schema, the core effect is covered and the schema handles the authorization caveat. Gaps remain around prerequisites and consequences — whether the branch must be merged first, whether retirement is undoable, and what happens to open pull requests or children — which matter for a destructive-hinted mutation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the single branch_id property already documents the team-admin prerequisite, so the schema carries the parameter burden. The description adds no syntax, format, or lookup guidance beyond it, leaving the 3 baseline appropriate for a one-parameter tool.

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?

The first clause states a specific verb and resource — 'Mark a branch retired' — and adds the operational effect ('preserves records, frees the name') that a plain 'retire' would leave ambiguous. It does not differentiate itself from the many adjacent sibling retire/archive tools (retire_feature_branch, retire_design_release, archive_design, delete_design), so the reader must rely on the name alone to pick it.

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

Usage Guidelines2/5

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

There is no statement of when to choose retirement over deleting (delete_design), archiving (archive_design), or retiring a different object class (retire_feature_branch, retire_decoration_preset_branch). The second sentence is a pricing-tier blurb, not usage guidance, so the agent gets no routing help.

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

Deploy Server

Other Tools