Skip to main content
Glama

skycloak_create_openfga_instance

Creates an OpenFGA instance bound to one cluster realm for realm-scoped token authorization. Starts asynchronously in 'provisioning', so poll the instance status until it reaches 'ready' or 'failed'.

Instructions

Create an OpenFGA instance bound to one realm of a cluster; a realm has at most one. Asynchronous: it starts in 'provisioning', so poll skycloak_get_openfga_instance until the status is 'ready' or 'failed'. The instance accepts only tokens from that realm that carry the instance's audience. Fails with 403 when the workspace's plan does not include OpenFGA or the workspace reached its instance limit, 409 when the realm already has an instance, and 422 when the realm is 'master', does not exist or is disabled.

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": {
      "cluster_id": "<cluster_id>",
      "realm": "<realm>"
    },
    "name": "skycloak_create_openfga_instance"
  }
}

Input Schema

NameRequiredDescriptionDefault
realmYesthe realm to bind; it must exist and be enabled, must not be master, and must not already have an instance
cluster_idYesthe cluster that holds the realm

Output Schema

NameRequiredDescriptionDefault
idYes
realmYes
issuerYes
statusYes
api_urlYes
audienceYes
cluster_idYes
created_atYes
updated_atYes
status_messageNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.4/5.0
Behavior4/5

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

Goes well beyond the annotations by disclosing the asynchronous lifecycle (starts in 'provisioning'), the required polling loop, and the exact failure semantics with status codes and their causes. The only remaining gap is what the response body looks like, which the output schema presumably covers. The described write-plus-async behavior is fully consistent with readOnlyHint=false and idempotentHint=false.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with what is created and the one-per-realm invariant, then the async contract, then the error contract. No filler and no repetition of the annotated title.

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

Completeness4/5

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

An output schema exists so return values need not be explained, and the async polling story plus error matrix cover the operational essentials. A minor gap is that the token/audience semantics are stated as a property of the created instance but not fleshed out further.

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 both parameters are already documented. The description reinforces the realm constraints and ties them to specific error codes, but cluster_id gets no added meaning beyond the schema and the realm constraints largely restate the schema text.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (create an OpenFGA instance) plus a precise scope (bound to one realm of a cluster, at most one per realm). This alone separates it from the get/delete/list siblings of the same object.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly names the follow-up tool and the condition that selects it: poll skycloak_get_openfga_instance until status is 'ready' or 'failed'. It also specifies when this call is not valid via the 403/409/422 conditions (plan lacks OpenFGA, instance limit reached, realm already has an instance, realm is master/missing/disabled).

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