Skip to main content
Glama
Sign In
Kiln

Kiln

by codeofaxel
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python

create_decoration_preset

Create or version decoration presets on a branch, specifying pattern, target faces, depth, and optional image assets for 3D designs.

Instructions

Create or version a decoration preset on a branch.

Needs Kiln Pro.

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>",
      "pattern_family": "<pattern_family>",
      "pattern_id": "<pattern_id>"
    },
    "name": "create_decoration_preset"
  }
}

Input Schema

NameRequiredDescriptionDefault
nameYesDisplay name for the preset. Must not be empty.
notesNoFree-form editorial note stored on the version. Omit it for none. Default: "".
depth_mmNoEmboss or deboss depth in millimetres. Defaults to ``1.2``; a value outside 0.05 to 5.00 mm is refused. Default: 1.2.
design_idNoId of the design the preset belongs to. Omit it for a portfolio-wide preset usable on any design.
preset_idNoId of an existing preset to add a new version to. Omit it to create a new preset at version 1; an id that does not exist is refused.
created_byNoAuthor label stored on the version as given. Omit it to record the computer's user name.
pattern_idYesWhich pattern within the family, e.g. ``"wave"`` or ``"hex_grid"``, or for an image family a content hash or asset file name. Must not be empty.
branch_nameNoBranch the new version lands on, created if absent. Defaults to ``main``. Default: "main".
pattern_familyYesThe kind of decoration: ``"procedural_texture"``, ``"photo_emboss"``, ``"photo_deboss"``, ``"logo_emboss"``, ``"logo_deboss"``, ``"brand_asset"`` or ``"custom_image"``. Any other value is refused.
image_asset_pathNoPath to the source image for an image family. The file is copied into Kiln's own asset store so the preset does not depend on it staying where it is. Omit it to save the preset before the image is attached.
selected_face_idsNoThe face ids to decorate. Required (and non-empty) when ``surface_selection`` is ``"selected_faces"``; dropped for any other selection.
surface_selectionNoWhich faces of a host mesh receive the decoration: ``"all_faces"``, ``"outer_faces"`` (default), ``"vertical_walls"``, ``"horizontal_caps"`` or ``"selected_faces"``. Default: "outer_faces".
image_asset_sha256NoSHA-256 of the image, its identity across renames. Omit it to have it computed from ``image_asset_path``.
posterization_tierNoOptional posterize tier, an integer from 1 to 8; outside that range is refused. Omit it for none.
parent_preset_version_idNoThe preset version this one was forked from, recorded for ancestry. Omit it for a root version.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed15 schema fields changedv1.5.1
    • changedInput schema / properties / branch_name / description
      Previous value: -"Default: \"main\"."New value: +"Branch the new version lands on, created if absent.  Defaults to ``main``. Default: \"main\"."
    • addedInput schema / properties / created_by / description
      Added value: +"Author label stored on the version as given.  Omit it to record the computer's user name."
    • changedInput schema / properties / depth_mm / description
      Previous value: -"Default: 1.2."New value: +"Emboss or deboss depth in millimetres.  Defaults to ``1.2``; a value outside 0.05 to 5.00 mm is refused. Default: 1.2."
    • addedInput schema / properties / design_id / description
      Added value: +"Id of the design the preset belongs to.  Omit it for a portfolio-wide preset usable on any design."
    • addedInput schema / properties / image_asset_path / description
      Added value: +"Path to the source image for an image family.  The file is copied into Kiln's own asset store so the preset does not depend on it staying where it is.  Omit it to save the preset before the image is attached."
    • addedInput schema / properties / image_asset_sha256 / description
      Added value: +"SHA-256 of the image, its identity across renames.  Omit it to have it computed from ``image_asset_path``."
    • addedInput schema / properties / name / description
      Added value: +"Display name for the preset.  Must not be empty."
    • changedInput schema / properties / notes / description
      Previous value: -"Default: \"\"."New value: +"Free-form editorial note stored on the version.  Omit it for none. Default: \"\"."
    • addedInput schema / properties / parent_preset_version_id / description
      Added value: +"The preset version this one was forked from, recorded for ancestry.  Omit it for a root version."
    • addedInput schema / properties / pattern_family / description
      Added value: +"The kind of decoration: ``\"procedural_texture\"``, ``\"photo_emboss\"``, ``\"photo_deboss\"``, ``\"logo_emboss\"``, ``\"logo_deboss\"``, ``\"brand_asset\"`` or ``\"custom_image\"``.  Any other value is refused."
    • addedInput schema / properties / pattern_id / description
      Added value: +"Which pattern within the family, e.g. ``\"wave\"`` or ``\"hex_grid\"``, or for an image family a content hash or asset file name.  Must not be empty."
    • addedInput schema / properties / posterization_tier / description
      Added value: +"Optional posterize tier, an integer from 1 to 8; outside that range is refused.  Omit it for none."
    • addedInput schema / properties / preset_id / description
      Added value: +"Id of an existing preset to add a new version to. Omit it to create a new preset at version 1; an id that does not exist is refused."
    • addedInput schema / properties / selected_face_ids / description
      Added value: +"The face ids to decorate.  Required (and non-empty) when ``surface_selection`` is ``\"selected_faces\"``; dropped for any other selection."
    • changedInput schema / properties / surface_selection / description
      Previous value: -"Default: \"outer_faces\"."New value: +"Which faces of a host mesh receive the decoration: ``\"all_faces\"``, ``\"outer_faces\"`` (default), ``\"vertical_walls\"``, ``\"horizontal_caps\"`` or ``\"selected_faces\"``. Default: \"outer_faces\"."
  2. Addedv1.5.0

TDQS

B3.3/5.0
Behavior3/5

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the safety profile is known. The description's only added behavioral fact is the Kiln Pro entitlement gate, which is genuinely useful, but it says nothing about failure behavior, whether a new version supersedes the prior head, or how 'on a branch' interacts with existing branch state.

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?

Two sentences, front-loaded with the core action, and zero filler. The brief 'Needs Kiln Pro.' fragment is efficient signposting, though the whole definition is arguably under-sized for a 15-parameter mutation tool.

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 15-parameter write tool with no output schema and no annotations beyond a bare safety profile, the description is thin: it does not say what is returned (a preset id? a version id?), whether creating a version on a missing preset fails, or how branch creation side effects work. The entitlement note is helpful but not enough for this complexity.

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 every one of the 15 parameters carries a detailed description including defaults, enum-like value lists, and refusal conditions. The description only echoes the branch concept and adds no semantics the schema lacks; baseline 3 applies when the schema does the heavy lifting.

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 description uses a specific verb pair and resource: 'Create or version a decoration preset on a branch.' The 'or version' phrasing usefully signals the dual create/append-version behavior that the preset_id parameter controls. However, it never distinguishes itself from close siblings such as create_decoration_preset_branch, save_decoration, or apply_decoration_preset.

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?

'Needs Kiln Pro' is a real precondition an agent must check before calling, which is more than most tools offer. But there is no guidance on when to choose this over sibling tools (e.g. save_decoration, batch_decorate, create_decoration_preset_branch) and no statement that an omitted preset_id creates v1 while a supplied one appends a version.

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