Skip to main content
Glama
Sign In
Kiln

Kiln

by codeofaxel
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python

list_cherry_pick_candidates

Read-only

Lists semantic modifications that can be cherry-picked from a source design version relative to a common ancestor, so you can choose which changes to apply.

Instructions

Enumerate the semantic modifications cherry-pickable from source_version_id relative to ancestor_version_id.

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": {
      "ancestor_version_id": "<ancestor_version_id>",
      "source_version_id": "<source_version_id>"
    },
    "name": "list_cherry_pick_candidates"
  }
}

Input Schema

NameRequiredDescriptionDefault
source_version_idYesDesign version id holding the changes to list. Both versions need a recorded mesh fingerprint, or the call returns ``FINGERPRINT_UNAVAILABLE``.
ancestor_version_idYesDesign version id of the common ancestor the source is compared against.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv1.5.1
    • addedInput schema / properties / ancestor_version_id / description
      Added value: +"Design version id of the common ancestor the source is compared against."
    • addedInput schema / properties / source_version_id / description
      Added value: +"Design version id holding the changes to list.  Both versions need a recorded mesh fingerprint, or the call returns ``FINGERPRINT_UNAVAILABLE``."
  2. Addedv1.5.0

TDQS

C2.9/5.0
Behavior3/5

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safe-read profile is covered. The description adds the plan-gating dimension (which tier can branch/merge/cherry-pick), which is genuine behavioral context, but it is vague and promotional rather than precise. It says nothing about volume of results, ordering, or what the FINGERPRINT_UNAVAILABLE failure means at the tool level.

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 first sentence is tight and front-loaded, but the second half is a repetitive marketing tier blurb ("Branch · merge · cherry-pick · undo" listed twice with checkmarks) that spends roughly half the description on noise. It obscures rather than reinforces what the tool returns.

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?

With only two fully documented parameters and read-only annotations, the definition is close to sufficient, but with no output schema the agent gets no sense of the returned structure (a list of modifications with ids/kinds) or how to feed results into cherry_pick_modification. The tier line occupies space that should have covered that gap.

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 parameter descriptions already explain both ids and the FINGERPRINT_UNAVAILABLE precondition, so the schema does the heavy lifting. The description only restates the two parameter names and the ancestor/source comparison framing, adding no new semantics. 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 first sentence gives a specific verb ("Enumerate") and a specific resource ("semantic modifications cherry-pickable from source_version_id relative to ancestor_version_id"), so the agent knows it is a diff-of-candidates listing. It does not name the closely overlapping siblings (list_feature_cherry_pick_candidates, list_decoration_cherry_pick_candidates, cherry_pick_modification), so differentiation is left implicit, which keeps it below a 5.

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 explicit when-to-use statement and no exclusion or alternative named, despite several near-identical sibling tools that list cherry-pick candidates for other artifact types. The only usage-adjacent content is the plan-tier line, which implies access limits rather than workflow 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