Skip to main content
Glama

api-governance

by io.github.coderifts

preflight_change_set

Use this when: a change set of contract artifacts modifies OpenAPI, GraphQL, protobuf, AsyncAPI, MCP manifests, or agent tool schemas before merge, deploy, publish, or tool registration. Do not call for documentation-only changes, static readiness scoring, or receipt verification. Use analyze for risk only; authorize requires context.operation for permission. For receipt verification use coderifts.verify_receipt instead; for details of a past decision use coderifts.get_decision_details instead.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
contextNoOptional apply-site context folded into the bundle fingerprint. operation distinguishes merge vs deploy vs publish (and other labels); the server accepts any string for operation (change-set.js) — conventional values below.
artifactsNoContract artifacts to analyze together (max 20). Each is { id, type, before, after }.
derivationNoOpt-in (ID637 6b). "server" = the server derives artifacts[] from GitHub Compare via the App installation. Allowed only when the tenant has a proven binding for context.repository and context.base + context.head are present. Omit artifacts[] (caller-supplied artifacts[] with this flag is 400 — one source of truth). Default absent = today's caller-artifacts path (byte-identical).
state_nonceNoOptional ATOMIC-profile nonce. When include_execution_grant is true, copied into the signed grant as state_nonce (a separate signed field — NOT folded into scope_hash). Absent → BEARER grant (today's default). See docs/cr-exec-v1.md.
preflight_modeYesREQUIRED. "analyze" = informational risk only (no decision/execution_action/safe_for_agent; analysis_outcome + may_execute:false). "authorize" = operation-bound path; may mint a receipt (requires context.operation). Decision Spec 2.0: omission is an error unless decision_spec_version is '1.0' (30-day legacy pin with soft-default analyze).
idempotency_keyNoOptional client key; in authorize mode, a repeat with the same key + body replays the original decision (24h). Analyze responses are not replayed.
previous_receiptNoOptional prior chain receipt token to link
decision_spec_versionNoOptional pin. '1.0' = legacy contract (soft-default mode + analyze still carries decision/execution_action) until the sunset date. Omit or '2.0' = current contract.
include_execution_grantNoOpt-in (authorize only). When true on allow-class authorize, the response includes a signed execution_grant (cr.exec.v1) alongside chain_receipt, or HTTP 503 SIGNER_UNAVAILABLE — never unsigned. Default false. Analyze ignores this flag. See docs/cr-exec-v1.md.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault

No arguments

TDQS

A4.5/5.0
Behavior4/5

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

Annotations provide only readOnlyHint=false and openWorldHint=false, so the description carries most of the behavioral burden. It discloses mode-dependent behavior: analyze is risk-only, authorize is permission-bound and requires context.operation. It also implies authorization may produce receipts by pointing receipt verification elsewhere, giving useful behavioral context beyond the annotations.

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?

The description is dense but purposeful, with every clause adding a distinct routing or mode constraint. It front-loads the main use case and then efficiently lists exclusions and alternatives. There is no filler or redundancy.

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?

Given the complexity of the tool, the output schema, the fully documented input schema, and the explicit sibling references, the description plus structured metadata is complete. An agent can determine when to call it, what mode to use, what precondition must hold, and which sibling to use instead when the current tool is not appropriate.

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 schema already documents all parameters. The description reinforces the critical precondition that authorize requires context.operation, but it does not add substantial new meaning to the parameters beyond what the schema provides. Baseline 3 is appropriate here.

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 clearly identifies the tool as a preflight check for change sets that modify contract artifacts before merge, deploy, publish, or tool registration. It names the artifact types explicitly and differentiates itself from siblings by directing receipt verification and past-decision lookups to other tools. This is a specific, actionable purpose statement.

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?

The description gives explicit when-to-use guidance, states exclusions (documentation-only changes, static readiness scoring, receipt verification), and names the alternative tools for those cases. It also distinguishes the analyze vs authorize modes and notes that authorize requires context.operation. This is exemplary routing guidance.

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

All api-governance toolsInspect
Try in Browser
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.5/5.0
Disambiguation4/5

The three tools have clearly distinct purposes: preflight_change_set creates new decisions, get_decision_details retrieves past decisions, and verify_receipt checks receipt validity. Some semantic overlap exists between get_decision_details and verify_receipt (both inspect prior outcomes), but the detailed usage guidance disambiguates them effectively.

Naming Consistency4/5

Tool names follow a consistent verb_noun pattern (get_decision_details, preflight_change_set, verify_receipt). Minor inconsistency: preflight_change_set uses a compound noun while the others use verb_object, but all are snake_case with clear verbs.

Tool Count4/5

Three tools is a reasonable, minimal surface for an API governance decision workflow: analyze/decide, retrieve past decisions, and verify receipts. The count feels slightly thin for a governance server (e.g., no tool for listing decisions or managing rules), but it is well-scoped for its stated purpose.

Completeness4/5

The core lifecycle is covered: preflight creates the decision, get_decision_details retrieves it, verify_receipt validates authorization. Minor gaps include no explicit analyze-only or authorize-only split (mentioned in the preflight description but not exposed as separate tools) and no listing/cancellation capability.

Resources