Skip to main content
Glama
Sign In
Kiln

Kiln

by codeofaxel
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python

annotate_design_branch

Destructive

Stores or updates a human-readable purpose string for a design branch, replacing any earlier annotation; an empty string clears it.

Instructions

Set the human-readable purpose string for a branch.

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>",
      "annotation": "<annotation>"
    },
    "name": "annotate_design_branch"
  }
}

Input Schema

NameRequiredDescriptionDefault
branch_idYesId of the design branch to describe.
annotationYesThe purpose text to store on the branch. It replaces any earlier annotation; an empty string clears it.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv1.5.1
    • addedInput schema / properties / annotation / description
      Added value: +"The purpose text to store on the branch.  It replaces any earlier annotation; an empty string clears it."
    • addedInput schema / properties / branch_id / description
      Added value: +"Id of the design branch to describe."
  2. Addedv1.5.0

TDQS

C2.7/5.0
Behavior2/5

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

The annotations already declare readOnlyHint=false and destructiveHint=true, so the safety profile is covered by structured data. The description adds nothing about why the operation is destructive (overwriting or clearing an existing annotation), nor about permissions or tier gating in a usable way; the tier blurb restates plan marketing without explaining behavioral consequences.

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 useful content is a single well-formed sentence. It is followed by an irrelevant pricing/tier comparison ('Free door, tiered answer — Free: ... Pro: ... Business: ✓ · Enterprise: ✓') that does not help an agent decide or call the tool and bloats the definition.

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

Completeness2/5

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

For a destructive mutation with no output schema, the description should at minimum explain the overwrite/clear consequence and how it differs from sibling annotation tools. It omits both, and the space it does use is spent on unrelated tier information.

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 description coverage is 100%, and the schema itself already explains that the value replaces any earlier annotation and that an empty string clears it. The description adds no parameter meaning beyond that, so the baseline 3 applies.

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 opening sentence states a specific verb and resource: setting a human-readable purpose string on a branch. It is clear enough to act on, though it never distinguishes itself from the near-identical siblings annotate_feature_branch and annotate_decoration_preset_branch, and only the tool name (not the description) establishes that the branch is a design branch.

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 guidance on when to use this versus rename_design_branch, annotate_feature_branch, or other branch-metadata tools. The only additional sentence discusses plan tiers and pricing, which is marketing content rather than usage guidance.

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