Skip to main content
Glama
Sign In
Kiln

Kiln

by codeofaxel
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python

set_approval_gate

Destructive

Create or update an approval gate on a design, preset, or feature branch to require a set number of approving reviews before merge. Restrict approvers by team, role, or path.

Instructions

Create or update an approval gate on a target branch.

Needs Kiln Business.

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": {
      "artifact_type": "<artifact_type>",
      "artifact_id": "<artifact_id>",
      "branch_name": "<branch_name>",
      "required_count": "<required_count>",
      "created_by": "<created_by>"
    },
    "name": "set_approval_gate"
  }
}

Input Schema

NameRequiredDescriptionDefault
created_byYesWho is setting the gate. On Kiln's hosted server it is read from the signed-in session and a different value is refused; on a local install it is the operator's name.
path_rulesNoOrdered per-path reviewer rules added on top of the gate, each ``{"path_pattern", "required_team_id", "required_role", "required_count"}``. Omit it to leave existing rules untouched; ``[]`` clears them. A pattern no merge can match is refused.
artifact_idYesThe id of the design, preset or feature whose branch is protected.
branch_nameYesThe target branch being protected, typically ``main`` or a release-channel name.
artifact_typeYesWhat the gate protects: ``"design"``, ``"preset"`` or ``"feature"``. Any other value is refused.
required_roleNoOnly approvers with at least this org role count: ``"owner"``, ``"admin"``, ``"member"`` or ``"viewer"``. Left empty with no team on an org-owned artifact, it becomes ``"member"``. Default: "".
required_countYesThe minimum number of approving reviews a merge needs. ``0`` is accepted; a negative number is refused.
required_team_idNoOnly members of this team count as approvers. Empty means no team restriction. Default: "".
allow_unsatisfiableNoWhen true, keep a gate whose rules ask for more qualifying reviewers than the org has, with the problem reported under ``rule_warnings``. When false (the default), such a gate is refused and nothing is saved. Default: false.
block_changes_requestedNoWhen true (the default), a ``REQUEST_CHANGES`` review blocks the merge until it is changed. Default: true.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed10 schema fields changedv1.5.1
    • changedInput schema / properties / allow_unsatisfiable / description
      Previous value: -"Default: false."New value: +"When true, keep a gate whose rules ask for more qualifying reviewers than the org has, with the problem reported under ``rule_warnings``.  When false (the default), such a gate is refused and nothing is saved. Default: false."
    • addedInput schema / properties / artifact_id / description
      Added value: +"The id of the design, preset or feature whose branch is protected."
    • addedInput schema / properties / artifact_type / description
      Added value: +"What the gate protects: ``\"design\"``, ``\"preset\"`` or ``\"feature\"``.  Any other value is refused."
    • changedInput schema / properties / block_changes_requested / description
      Previous value: -"Default: true."New value: +"When true (the default), a ``REQUEST_CHANGES`` review blocks the merge until it is changed. Default: true."
    • addedInput schema / properties / branch_name / description
      Added value: +"The target branch being protected, typically ``main`` or a release-channel name."
    • addedInput schema / properties / created_by / description
      Added value: +"Who is setting the gate.  On Kiln's hosted server it is read from the signed-in session and a different value is refused; on a local install it is the operator's name."
    • addedInput schema / properties / path_rules / description
      Added value: +"Ordered per-path reviewer rules added on top of the gate, each ``{\"path_pattern\", \"required_team_id\", \"required_role\", \"required_count\"}``.  Omit it to leave existing rules untouched; ``[]`` clears them.  A pattern no merge can match is refused."
    • addedInput schema / properties / required_count / description
      Added value: +"The minimum number of approving reviews a merge needs.  ``0`` is accepted; a negative number is refused."
    • changedInput schema / properties / required_role / description
      Previous value: -"Default: \"\"."New value: +"Only approvers with at least this org role count: ``\"owner\"``, ``\"admin\"``, ``\"member\"`` or ``\"viewer\"``. Left empty with no team on an org-owned artifact, it becomes ``\"member\"``. Default: \"\"."
    • changedInput schema / properties / required_team_id / description
      Previous value: -"Default: \"\"."New value: +"Only members of this team count as approvers.  Empty means no team restriction. Default: \"\"."
  2. Addedv1.5.0

TDQS

B3.4/5.0
Behavior3/5

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the write/destructive nature is known without the text. The description adds one genuinely new fact, the Kiln Business entitlement requirement. It does not disclose that an update replaces the existing gate's configuration, which is the main risk implied by destructiveHint.

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 short sentences, action front-loaded, with the prerequisite isolated on its own line. There is no filler, though "Needs Kiln Business" is terse enough to be slightly cryptic about the failure mode.

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 destructive 10-parameter mutation the prose is thin: nothing explains upsert behavior, what an approval gate governs in practice, or what a caller sees on refusal. The very detailed schema fields compensate for most of that, keeping this at a minimum-viable level rather than inadequate.

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%, so every one of the 10 parameters (including refusal conditions, defaults and path_rules clear-vs-omit semantics) is already documented. The description adds no meaning beyond the schema, 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?

"Create or update an approval gate on a target branch" gives a specific verb pair (upsert) plus the resource and scope (target branch). It is distinguishable from siblings like list_approval_gates, remove_approval_gate and evaluate_pr_approval, though it never names them explicitly.

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 Business" states a plan prerequisite, which is real usage context. However there is no guidance on when to set a gate versus inspecting it with list_approval_gates or deleting it with remove_approval_gate, and no mention of what happens if the gate already exists.

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