Skip to main content
Glama
Sign In
Kiln

Kiln

by codeofaxel
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python

grant_scope

Destructive

Grant a read, push, release, or admin capability on a scope key to a tenant or team, with optional expiry. Enables scoped access control in Kiln Business organisations.

Instructions

Grant capability on scope_key to a tenant OR a team.

Needs the organisation to be on 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": {
      "org_id": "<org_id>",
      "scope_key": "<scope_key>",
      "capability": "<capability>",
      "granted_by": "<granted_by>"
    },
    "name": "grant_scope"
  }
}

Input Schema

NameRequiredDescriptionDefault
ask_idNoThe id an earlier ``APPROVAL_REQUIRED`` answer returned. Pass it on the repeat call to learn whether the person approved; omit it on the first call.
org_idYesThe org the grant is made in.
team_idNoThe team that receives the grant, for every current and future member. Give exactly one of ``tenant_id`` and ``team_id``.
scope_keyYesWhat the grant covers, for example ``design:<id>``, ``branch:<id>`` or ``*`` for every artifact in the org.
tenant_idNoThe account that receives the grant. Give exactly one of ``tenant_id`` and ``team_id``.
capabilityYesWhat the grant allows: ``"read"``, ``"push"``, ``"release"`` or ``"admin"`` (which implies the others). Any other value is refused.
expires_atNoWhen the grant stops applying, in Unix epoch seconds. Omit it for a grant that does not expire.
granted_byYesWho is making the grant, recorded on it. On Kiln's hosted server it is read from the signed-in session.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed8 schema fields changedv1.5.1
    • addedInput schema / properties / ask_id
      Added value: +{
+  "description": "The id an earlier ``APPROVAL_REQUIRED`` answer returned. Pass it on the repeat call to learn whether the person approved; omit it on the first call.",
+  "title": "Ask Id",
+  "type": "string"
+}
    • addedInput schema / properties / capability / description
      Added value: +"What the grant allows: ``\"read\"``, ``\"push\"``, ``\"release\"`` or ``\"admin\"`` (which implies the others).  Any other value is refused."
    • addedInput schema / properties / expires_at / description
      Added value: +"When the grant stops applying, in Unix epoch seconds. Omit it for a grant that does not expire."
    • addedInput schema / properties / granted_by / description
      Added value: +"Who is making the grant, recorded on it.  On Kiln's hosted server it is read from the signed-in session."
    • addedInput schema / properties / org_id / description
      Added value: +"The org the grant is made in."
    • addedInput schema / properties / scope_key / description
      Added value: +"What the grant covers, for example ``design:<id>``, ``branch:<id>`` or ``*`` for every artifact in the org."
    • addedInput schema / properties / team_id / description
      Added value: +"The team that receives the grant, for every current and future member.  Give exactly one of ``tenant_id`` and ``team_id``."
    • addedInput schema / properties / tenant_id / description
      Added value: +"The account that receives the grant.  Give exactly one of ``tenant_id`` and ``team_id``."
  2. Addedv1.5.0

TDQS

A3.5/5.0
Behavior3/5

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation risk profile is conveyed structurally. The description adds the plan-level prerequisite, which is useful context not in the annotations, but says nothing about what happens on duplicate grants, how the approval handshake works, or that grants persist until expiry or revocation.

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 action and followed by the prerequisite — no filler. Slightly telegraphic: the plan requirement could have been folded into a single clause rather than reading as an afterthought, but nothing is wasted.

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?

There is no output schema, so the description carries no burden there, and the 8 parameters are fully documented in the schema including the ask_id approval retry. Still, for a destructive permission-mutation tool the prose is thin: it omits idempotency, the effect of scope wildcards, and the fact that revocation is a separate tool.

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

Parameters4/5

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

Schema description coverage is 100% and each parameter is well documented in the schema itself, so the baseline is met; the description nonetheless reinforces the capability and scope_key semantics it names in italics. The one-of tenant/team constraint and the capability vocabulary, while also in the schema, are surfaced in the prose where an agent will see them first.

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?

States a specific verb and resource pair — 'Grant capability on scope_key' — plus the recipient dimension ('to a tenant OR a team'), which maps directly to the tenant_id/team_id parameters. It is clear what the tool does, but it never names or distinguishes itself from sibling tools such as revoke_scope, list_scopes, or check_capability.

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?

The second sentence gives a real precondition ('Needs the organisation to be on Kiln Business'), which is genuine usage guidance. However, there is no statement of when to reach for this versus revoke_scope, list_expiring_grants, or check_capability, and no mention of the approval/ask_id retry flow that the schema hints at.

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