Where it goes
Contoso keeps contract-renewal-desk in capabilities/contract-renewal-desk.yaml. The loader reads every YAML file under the package root, so folders are a convention you can change. Name it in lowercase kebab-case. The name must be unique among the package's Capability resources.
Limits
A Capability that no Deployment lists is inert. Every request carries exactly one Capability, and the decision point denies reads and actions outside its reads and runs, even for someone who holds the permission.
Fields
The keys under spec. Nested shapes follow CapabilitySpec in the GOL JSON Schema.
| Field | Presence | Shape |
|---|---|---|
purpose | Required | localized |
affects | Required | array |
prohibited | Required | array |
reads | Required | array |
runs | Optional | array |
tools | Optional | array |
skills | Optional | array |
output | Optional | skillRef |
riskTier | Required | enum: A, B, C, D |
riskRationale | Optional | string |
legalClassification | Optional | object |
maxAutonomy | Required | enum: L0, L1, L2, L3, L4 |
answerMode | Optional | object |
budget | Optional | object |
models | Optional | array |
tests | Required | array |
gates | Optional | gates |
baseline | Optional | object |
lifecycle | Required | lifecycle |
expose | Optional | expose |
verifyClaims | Optional | boolean |
retrieval | Optional | object |
Syntax and rules
The examples are fragments. Put them in a package next to the resources they reference. A ... stands for a CEL expression you write yourself.
9.5 Capability (intended use)
An ontology is too broad to score, promote or retire, and an action is too narrow. A Capability is one intended business use of the ontology: what it may read, what it may run, for whom, with what ceiling, and what evidence it needs. Chat scopes, MCP clients and API clients bind to a Capability; the decision point denies a request outside the Capability's reads and runs even when the subject holds the permission. Scorecards (F16) are computed per Capability, per deployment, per action type and per chat scope. Agents live elsewhere (Agent OS, PIA, Copilot); a Capability is what any of them is allowed to be.
kind: Capability
metadata: {
name: contract-renewal-desk,
title: Contract renewal desk,
owners: ["team:procurement-data"],
} # flat resource, kebab name like Policy and Segment
spec:
purpose: Answer questions about supplier contracts and start renewals with approval.
affects: [employees in procurement, suppliers]
prohibited: [supplier performance ranking of individual account managers]
reads: ["segment:procurement-emea", "view:procurement.ContractsRenewingSoon"] # segment:, domain: or view: refs
runs: ["procurement.RenewContract"] # allow-list of action refs; everything else is denied for this capability
riskTier: C
riskRationale: Sends renewal webhooks to the ERP.
maxAutonomy: L3 # never above; Deployment.maxAutonomy may lower it per audience
budget: { maxSteps: 12, maxDuration: PT2M, maxTokens: 40000 }
models: [model:eu-gpt-5-2026-08] # Model resources (10.5), the approved matrix
tests: ["test:contract-access", "test:contract-answers"]
gates: { citationSupport: 0.92 }
baseline:
{
currentProcess: manual lookup in the ERP and SharePoint,
simplerAlternative: SmartSearch,
outcome: renewal started within one working day,
kpi: renewal cycle time,
minutes: 25,
source: declared,
}
lifecycle: { reviewBy: 2027-03-31, expires: 2027-09-30, evaluation: eval-2026-09 }
expose: { chat: true, mcp: true, api: true }
riskTier and maxAutonomy on a Capability follow the rules in 9.1.1 and combine restrictively with the action's own: the effective level is the minimum of the Capability's ceiling, the Deployment's cap and the action's derived level, and an ActionType approval is never waived by any of them. Changing riskTier, maxAutonomy, reads or runs is an access-widening candidate for the compatibility pass (W651/W652) and needs the security approver.
Added 2026-10-10 for Gluon Context:
spec:
reads: ["segment:procurement-emea", "source:erp-live"] # source: refs too; a Source outside reads has no tools here
tools: ["tool:erp-live/*", "tool:crm/get_account"] # the tool pack: globs over enabled read tools
skills: ["skill:assess-renewal-risk"] # the skills the planner may bind
output: "skill:renewal-brief" # the default output skill; must be use: output (GLN-E273)
baseline.minutes is how long one outcome takes without Gluon, and baseline.source (required with minutes) says where that number comes from: declared (the process owner's estimate) or measured (timed). Drift (F28, planned) will estimate time saved as verified completions times the baseline minutes less Gluon's own time, and always show the source; a Capability without minutes will show time saved as not applicable. Until the Drift scorer lands, nothing reads these fields. Added 2026-10-15.
Added 2026-10-22 (Waseem), answer modes:
spec:
answerMode: { default: fast, pinned: true } # fast | accurate; pinned: people may not choose the other mode
answerMode.default is the mode a request gets when it names none: fast (one hybrid search, then the answer; it may search further by itself when its results look thin) or accurate (the search loop, the reranker and the wide pick, about a minute). Without answerMode the default is fast. With pinned: true a request for the other mode is refused (HTTP 422 mode_pinned at body.mode) on chat, the API and MCP alike, and a pinned fast never searches further by itself, so a cost-capped Capability stays one search. The mode's search settings are the server's (GLUON_FAST_*, GLUON_ANSWER_*), never the package's.
Added 2026-10-27 (F31), the claim check: verifyClaims: false on a Capability turns off the check that runs after every answer citing a passage (a fast call on the planner's route that quotes the passage words behind each claim; code checks each quote; partial and unsupported claims get the dotted underline and count in the attention card, and Drift's claimAccuracy reads the verdicts). Without the field the check runs. A skill has the same switch (9.7).
Added 2026-11-06 (F31), retrieval switches on a Capability:
spec:
retrieval: { multiQuery: true, listwiseRerank: true } # each off unless set
multiQuery: true has the planner's route write up to two rewordings of the question; each is searched as the question is (the pre-filter, the PDP re-check) and the lists are fused by reciprocal rank, in Fast and Accurate alike (Accurate already writes three; multiQuery: false writes none in either mode). listwiseRerank: true has the planner's route order the top 20 passages in one call, in place of the reranker Model; it orders passages, not documents, so a law's articles compete with each other, and the passages it leaves out follow in their retrieval order. Without the field each step follows the answer mode. Neither is on by default: each was measured on the legal golden set by passage recall at 8 against the same pipeline with the switch off, and a switch is on by default only where it gains at least 2 points with no loss on the other golden sets (docs/plans/gluon-ingest.md, 5d).
A Capability without tools gets the ontology and memory tools only. A new tools entry, or a new Capability with tools, is GLN-W653 (tool access possibly widened) and needs the security approver, like W651.
Binding contract. A Deployment lists the Capabilities it makes available (capabilities: in 11.2); a Capability that no deployment lists is inert. Every request on every channel carries exactly one Capability: a chat scope is bound to one, an MCP or API client is approved for a set and names one per request (a client approved for several picks per request, never per token), the designer and the admin console bind to the built-in capability:console. A request that names no Capability, or one the deployment does not list for that subject, is denied before step 1. reads bounds retrieval and traversal, not only the first call; runs bounds every action a run reaches, including through call and nested tool use; models bounds every model the run touches, embeddings and rerankers included; budget counts steps, elapsed time and model tokens across the whole run including nested calls, and exhaustion ends the run with a refusal, never a partial action. A reranker is bounded by its cost, not its tokens: each call's cost is reserved against the department cap before it runs, and the passages it was sent never count toward maxTokens (decided 2026-10-23 by Waseem: about 37,000 tokens a call for 100 passages, never model context, which left an Accurate answer's facts no allowance). Budgets reset per request. Missing affects, prohibited or tests is a validation error, not a warning.
Check your package
gluon validate examples/contoso
gluon test examples/contoso
validate reports each problem with a GLN code and its place in the file. test runs the package's Test resources. See the language guide and the diagnostics.
