Skip to main content
Glama
Cyan Eclipse License Server

Cyan Eclipse License Server

Official

Show seat usage for one licence

seat_usage
Read-onlyIdempotent

Retrieve a licence’s seat cap, live activation count, and complete activation records to audit assigned seats and spot stale check-ins. Read-only; requires licence ID and authorized principal.

Instructions

Show the seat picture for one licence: its seat cap, how many activations are live, and every activation on record (install label, status, activated-at, last check-in, stale flag; install ids are truncated off the owner surface). Caller must be a principal of class tenant_owner, issuer, or support_reader. An unknown licence returns state LICENSE_UNKNOWN. Use activation_list to browse activations across licences and activation_inspect for one activation with its receipts. Read-only.

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

Input Schema

NameRequiredDescriptionDefault
_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.
license_idYesLicence whose seats to report.
_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.

Output Schema

NameRequiredDescriptionDefault
stateNo
seats_capNo
license_idNo
live_countNo
activationsNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.6/5.0
Behavior5/5

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

Beyond the readOnly/idempotent annotations, the description discloses the authorization gate (principal classes), the failure mode for an unknown licence (state LICENSE_UNKNOWN), and a data-redaction trait ('install ids are truncated off the owner surface') that no annotation or schema field conveys. The trailing 'Read-only' merely restates annotations but does not contradict them.

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?

Front-loaded with purpose, then prerequisites, error behavior, and alternatives in a logical order; nearly every clause carries information. The first sentence is heavily parenthetical and the closing 'Read-only' is redundant given readOnlyHint, keeping it just short of a 5.

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

Completeness5/5

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

For a read-only, three-parameter reporting tool with a full output schema and complete annotations, the description covers the remaining gaps an agent needs: who may call it, what an unknown licence produces, what data is redacted, and which siblings handle adjacent cases.

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 all three parameters are already documented, including the tenant-scoping versus authentication distinction and the mandate requirement for the principal. The description only implies licence_id via 'one licence' and adds no syntax, format, or edge-case detail 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.

Purpose5/5

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

Opens with a specific verb and resource ('Show the seat picture for one licence') and enumerates exactly what the response contains: seat cap, live activation count, and the full activation roster with named fields. This is clearly distinguishable from activation_list and activation_inspect, which are named as the cross-licence and single-activation alternatives.

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 routes the agent: use activation_list to browse activations across licences and activation_inspect for a single activation with its receipts, implying this tool is for per-licence aggregate seat state. It also states the caller-class precondition (tenant_owner, issuer, or support_reader), which is a genuine when-you-may-use-it constraint.

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