Skip to main content
Glama
Cyan Eclipse License Server

Cyan Eclipse License Server

Official

Manage principals and mandates

principal_manage
Destructive

Create tenant principals and grant or revoke product-scoped mandates with expiries, giving tenant owners the only journaled path to control who can issue, renew, or revoke licences.

Instructions

Administer the tenant's principals and mandates -- the only path that creates either. Tenant_owner only; grants and revocations are journalled. action create_principal registers a principal (principal_id + principal_class: tenant_owner, issuer, support_reader, auditor). action grant_mandate gives a principal a mandate scoped to products and operation classes until expires_at, and returns the mandate_id. action revoke_mandate revokes a mandate by id, effective immediately. There is deliberately no self-service mandate escalation: mandate_self_grant is denylisted and does not exist as a tool.

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": {
      "action": "<action>",
      "_tenant_id": "<_tenant_id>",
      "_principal_id": "<_principal_id>"
    },
    "name": "principal_manage"
  }
}

Input Schema

NameRequiredDescriptionDefault
nameNoDisplay name for create_principal.
actionYesOne of create_principal, grant_mandate, revoke_mandate (required).
productsNoFor grant_mandate: product ids the mandate covers ('*' covers all).
_tenant_idYesTenant the call acts for. The tenant must exist; an unknown tenant is refused with state LICENSE_UNKNOWN. Transport authentication is a deployment concern -- this parameter scopes the call, it does not authenticate it.
expires_atNoFor grant_mandate: ISO-8601 mandate expiry (required).
mandate_idNoFor revoke_mandate: mandate to revoke (required).
op_classesNoFor grant_mandate: operation classes covered, e.g. issue, renew, revoke, supersede, transfer, deactivate, reclaim.
principal_idNoPrincipal the action targets (required for create_principal and grant_mandate).
_principal_idYesActing principal inside the tenant. Principal-gated tools refuse unknown principals and principals of the wrong class; executions (tier T2) additionally require a live, unexpired mandate covering the product and the operation class.
principal_classNoClass for create_principal: tenant_owner, issuer, support_reader, or auditor.

Output Schema

NameRequiredDescriptionDefault
receiptNo
mandate_idNo
principal_idNo
principal_classNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.3/5.0
Behavior4/5

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

Annotations already declare destructiveHint=true, readOnlyHint=false and idempotentHint=false, so the safety profile is covered; the description still adds real context beyond them — tenant_owner authorization requirement, that grants and revocations are journalled (audit trail), that revocation is 'effective immediately', and that grant returns a mandate_id. It does not address reversibility of a revocation (whether a revoked mandate can be re-granted, or the effect on already-issued licenses), which is the main residual behavioral gap for a destructive tool.

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?

The opening sentence front-loads scope and exclusivity, then actions are presented in a consistent 'action X does Y' pattern, with the security caveat last. It is dense but every clause carries information; the only mild redundancy is restating the principal_class and op_classes value sets, which the schema already enumerates.

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?

For a 10-parameter, three-mode mutation tool with an output schema and full annotations, the definition covers authorization, audit, immediacy of revocation and the absence of an escalation path. Gaps are minor: it does not say what create_principal returns or how a principal's existing mandates behave when revoked or when a principal is deleted/reclassified.

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 the baseline is 3 and the schema already documents every field. The description does add an action-to-parameter mapping (which fields matter for create_principal vs grant_mandate vs revoke_mandate) and restates the principal_class and op_classes value sets, but it adds no semantics the schema lacks — the '*' product wildcard, ISO-8601 expiry and enum-like values are all already there.

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?

The description names a specific verb+resource ('Administer the tenant's principals and mandates') and then enumerates the three concrete actions (create_principal, grant_mandate, revoke_mandate) with the resource each operates on. It also claims a unique scope ('the only path that creates either'), which lets an agent distinguish it from authorization-adjacent siblings like license_issue or activation_deactivate without opening a schema.

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?

Each action is paired with its purpose and required inputs, and the caller gate is stated explicitly ('Tenant_owner only'). It goes further than most definitions by naming a non-existent alternative that an agent might otherwise attempt ('mandate_self_grant is denylisted and does not exist as a tool'), which is exactly the kind of when-not guidance that prevents wrong tool selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.