Skip to main content
Glama
Cyan Eclipse License Server

Cyan Eclipse License Server

Official

Get one journal receipt

receipt_get
Read-onlyIdempotent

Retrieve one journal receipt by sequence number from a tenant's hash-chained issuance journal. Missing sequences return null with LICENSE_UNKNOWN; use for read-only auditing and chain checks.

Instructions

Return a single journal receipt by its sequence number in the caller's tenant journal. Caller must be a principal of class tenant_owner, issuer, support_reader, or auditor. A sequence that does not exist returns receipt null with state LICENSE_UNKNOWN. Use journal_list to browse and chain_verify to validate the chain the receipt sits in. 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": {
      "sequence": "<sequence>",
      "_tenant_id": "<_tenant_id>",
      "_principal_id": "<_principal_id>"
    },
    "name": "receipt_get"
  }
}

Input Schema

NameRequiredDescriptionDefault
sequenceYesJournal sequence number of the receipt (1-based, contiguous per tenant).
_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.
_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
receiptNo

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?

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, so the bar is lower; the description nonetheless adds real context by naming the required principal classes and specifying the not-found outcome (receipt null with state LICENSE_UNKNOWN). It does not cover rate limits or pagination, but neither is relevant to a single-record lookup.

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?

Four short sentences ordered well: what it does, who may call it, failure behavior, then alternatives. The trailing "Read-only" largely restates the readOnlyHint annotation rather than earning its place.

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?

An output schema exists, so return values need no explanation; the description supplies exactly the missing pieces — authorization class, not-found semantics, and sibling routing. Nothing an agent needs to invoke it correctly is absent.

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 coverage is 100%, so the schema already documents sequence, _tenant_id, and _principal_id in depth. The description's only added meaning is restricting _principal_id to four named classes, which is a marginal increment, so the baseline of 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?

The first sentence gives a specific verb and resource ("Return a single journal receipt") plus the lookup key (sequence number) and scope (caller's tenant journal). It is immediately distinguishable from journal_list (browse) and chain_verify (validate).

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?

It states when this tool applies (one receipt by sequence) and explicitly routes the agent elsewhere for adjacent needs: journal_list for browsing, chain_verify for validating the chain the receipt belongs to. Eligibility classes are also spelled out.

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