Skip to main content
Glama
Cyan Eclipse License Server

Cyan Eclipse License Server

Official

Verify the journal hash chain

chain_verify
Read-onlyIdempotent

Recompute a tenant's entire journal hash chain and report whether each receipt's sequence and previous-hash link are valid. Read-only check for tenant owners, issuers, support readers, and auditors.

Instructions

Recompute the caller's tenant journal hash chain end to end and report whether every receipt's sequence and previous-hash link check out. Returns ok, the receipt count, the head hash, and -- on failure -- the sequence it failed at and why (sequence_gap or prev_hash_mismatch). Caller must be a principal of class tenant_owner, issuer, support_reader, or auditor. Use chain_verify_anchored instead when an externally witnessed anchor must be honoured. 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": {
      "_tenant_id": "<_tenant_id>",
      "_principal_id": "<_principal_id>"
    },
    "name": "chain_verify"
  }
}

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.
_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
okNo
countNo
reasonNo
failed_atNo
head_hashNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.6/5.0
Behavior4/5

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is largely covered; the description adds real value beyond them by disclosing the authorization gate (allowed principal classes) and the failure taxonomy (sequence_gap vs prev_hash_mismatch) with the failing sequence. The trailing 'Read-only.' merely restates readOnlyHint, and nothing is said about cost or scale on very large journals.

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 the action and result, then precondition, then the sibling route -- a logical order with no filler. Minor waste: the return-value enumeration partly duplicates the output schema, and the closing 'Read-only.' repeats readOnlyHint.

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 two-parameter read with full schema coverage, an output schema, and rich annotations, the description supplies everything an agent still needs: authorization classes, failure modes, and the anchored variant route. No material gap remains for correct invocation.

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 coverage is 100%, so the baseline is 3; the description raises it by constraining _principal_id to four concrete principal classes, meaning that is not encoded in the schema. It adds no further syntax or format detail for _tenant_id beyond what the schema already documents.

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 ('Recompute the caller's tenant journal hash chain end to end') plus the exact result semantics (sequence and previous-hash link validation), and explicitly distinguishes itself from chain_verify_anchored by the anchor requirement. An agent can pick between the two without opening either 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?

Names the alternative tool and the precise condition that selects it ('when an externally witnessed anchor must be honoured'), and adds a caller-eligibility precondition (principal class tenant_owner, issuer, support_reader, or auditor). Both when-to-use and the exclusion are explicit.

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