> For the complete documentation index, see [llms.txt](https://docs.openiam.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openiam.com/administration-guide/risk/policies.md). # Risk policies How the risk policy turns factor scores into one number and one band, what every field on the policy screen does, and a recommended starting configuration. This page is for the administrator who owns risk configuration. It explains every field on **Administration → Risk policies**, what happens when you change it, and what a sensible starting point looks like. The factors themselves, and their own settings, are on the [Risk factor reference](/administration-guide/risk/factors.md). If you have not read the [overview](/administration-guide/risk/overview.md), start there. **On this page** * [What a risk policy is](#policies-what) * [The Membership scoring policy](#user-policy) * [Aggregation policy: how factors become one number](#user-policy-aggregation) * [Band thresholds](#bands) · [Medium at](#user-policy-medium-threshold) · [High at](#user-policy-high-threshold) · [Critical at](#user-policy-critical-threshold) * [Scoring strategy](#user-policy-scoring-strategy) · [Soft](#user-policy-strategy-soft) · [Balanced](#user-policy-strategy-balanced) * [Toxic factors](#user-policy-toxic-factors) · [Toxic factors needed to escalate](#user-policy-escalation-min-toxic-count) * [Fine-tuning](#advanced-tuning) · [Breadth uplift weight](#tuning-breadth-uplift-weight) · [Breadth uplift cap](#tuning-breadth-uplift-cap) · [Context uplift cap](#tuning-context-uplift-cap) · [The toxic cutoff](#user-policy-toxic-cutoff) * [Band impact](#user-policy-band-impact) · [Live score preview](#user-policy-live-preview) * [Saving and recalculating](#user-policy-save-and-recalculate) * [Tuning factors inside the policy](#factors-tab) * [Enabled](#user-policy-factor-enabled) · [Weight](#user-policy-factor-weight) · [Level groups](#user-policy-factor-level-badge) · [The expander](#user-policy-factor-expander) · [Add factor](#user-policy-factor-add) · [Detach](#user-policy-factor-detach) * [Recommended starting configuration](#policies-recommended) * [What changed: the entitlement policy, Severe and Custom](#entitlement-policy) · [Severe](#user-policy-strategy-severe) · [Custom](#user-policy-strategy-custom) ## What a risk policy is A risk policy is the object that decides how a score is made. It says which factors count, how much each one counts, how they combine into one number, and where on the 0 to 100 scale the Low, Medium, High and Critical bands begin. The factors are the ingredients; the policy is the recipe. **Administration → Risk policies** lists the policies that exist. One ships, named **Membership scoring policy**, and it governs all three kinds of score: every entitlement score, every membership score and every identity score. Click its card to open it. There is no control for creating another; a later release adds that, together with the rules that would decide which policy applies to whom. The card shows the policy's name, a **Default** chip, a **Disabled** chip if someone switched it off, how many of its factors are enabled, the band ruler, and when it was last modified and by whom. Inside, the policy has two tabs. **Scoring** holds the numbers described in the first half of this page. **Factors** holds the factors attached to it, described in the second half. Most controls carry a small book icon that opens the matching section of this documentation. {% hint style="info" %} **The name is narrower than the job.** The policy is called *Membership scoring policy*, but it also holds the entitlement-level and identity-level factors and the bands those scores are judged by. Read it as "the risk policy". {% endhint %} ## The Membership scoring policy Tom Becker's grant of `Finance-Reports-Read` is the running example through this section, because it is the kind of grant a plain average hides: | Factor | Tom's reading | Factor score | | ------------------- | ------------------------------------------------------------------ | ------------ | | Membership Origin | Assigned directly by an administrator | 75 | | Reinstated Access | A reviewer revoked it in the spring campaign; it came back in June | 75 | | Certification Age | Never certified | 50 | | Stale Membership | Granted 80 days ago | 0 | | Membership Duration | Dated to the end of his contract | 0 | | Expired Membership | Not expired | 0 | The entitlement's own score, the floor, is 25. All six factors carry the shipped weight of 1.0. ### Aggregation policy: how factors become one number The **Aggregation Policy** card is where a set of factor scores becomes one score and one band. It happens in two fixed steps and one step you can shape. **Step 1, the weighted average.** The enabled factors of a level are averaged, each multiplied by its weight. Tom's six factors average (75 + 75 + 50 + 0 + 0 + 0) ÷ 6 = **33**. **Step 2, the context uplift.** For a membership, that average is not the score. It says how much of the [Context uplift cap](#tuning-context-uplift-cap) to add on top of the entitlement's floor. The cap ships at 40, so an average of 33 adds 33% of 40, about 13 points. Tom's membership scores 25 + 13 = **38**. A membership can never score below its entitlement's floor, and never above 100. **Step 3, the band.** The three thresholds on this card turn the number into a band. With the shipped 25 / 50 / 75, a 38 is **Medium**. For an identity the arithmetic is different, and there is no average of memberships: the identity score takes the higher of the person's riskiest membership and their identity-level factors, then adds a [breadth uplift](#tuning-breadth-uplift-weight) for **each** of their high-risk memberships. Tom's riskiest membership is 98 and he holds one high-risk grant, so his identity score is 98 + 1 = **99**. Step 1 is where a real problem hides. Tom's grant carries three of the strongest warning signs the system has, and it scores Medium, because three zeros sit in the same average. The setting that changes that is the [Scoring strategy](#user-policy-scoring-strategy), not the aggregation policy. ### Band thresholds Three sliders on the Aggregation Policy card set where each band begins. A score equal to a threshold is in that band: with **Medium at** 25, a 25 is Medium and a 24 is Low. The sliders keep themselves in ascending order. | Field | Shipped value | What a score at or above it is called | | ----------- | ------------- | ------------------------------------- | | Medium at | 25 | Medium | | High at | 50 | High | | Critical at | 75 | Critical | One threshold set now governs everything, so a change here re-bands entitlement scores, membership scores and identity scores together. The thresholds also do more than colour a pill. **High at** is the line that makes a membership count as "high risk" for the breadth uplift, the default [toxic cutoff](#user-policy-toxic-cutoff), and the ceiling for auto-certification in a campaign. Move it and all four things move. Changing a threshold never changes a score. It changes what the score is called, everywhere, once scores are recalculated. The [Band impact](#user-policy-band-impact) panel shows how many memberships would change band before you save. #### Medium at The lowest score called Medium; everything below it is Low. Low is the band reviewers are told they can handle in bulk, so this line decides how much of a campaign is routine. Raise it to 30 or 35 and more grants read as Low; Maria Rossi's `Finance-Reports-Read` at 37 would still be Medium. Lower it to 15 and almost nothing is Low. Start at 25. #### High at The lowest score called High. This is the most consequential threshold: it is where bulk certification stops being allowed, where auto-certification can never reach, where the breadth uplift starts counting a membership, and where the toxic cutoff sits by default. Raise it to 60 and fewer grants are High, but a factor now has to score 60 to be toxic. Lower it to 40 and Tom's 38 becomes High while the toxic cutoff drops with it. Start at 50 and tune the other settings first. #### Critical at The lowest score called Critical. Critical is what the reviewer screen counts in its red badge and lists first in the priority queue, so it should be rare enough to mean something. If more than a few percent of memberships are Critical, raise it toward 85 rather than lowering the factors that put them there. Start at 75. ### Scoring strategy The **Scoring strategy** card decides how strongly a single alarming factor is allowed to drive the final membership score. It is the answer to the problem in Step 1 above. The card folds behind its header once you have settled the choice. Readers confuse this card with the aggregation policy, so the distinction first. The aggregation policy is the **ruler**: it fixes the arithmetic that combines factors and marks where each band starts. The scoring strategy is **how you read the readings**: do you report the average, or do you report the worst reading once enough of them are alarming? Same ruler, different reading. The strategy changes the number; the thresholds change what the number is called. Two options are offered, and here is Tom's grant under each. The data does not change; the reading does. | Option | What happens to Tom's grant | Score | Band | | -------- | ----------------------------------------------------------------------------------------------------------------------------- | ----- | -------- | | Soft | Plain weighted average. Three zeros dilute three warning signs | 38 | Medium | | Balanced | Three factors are at or above the cutoff of 50, which is more than the two required. The score is raised to the worst of them | 75 | Critical | #### Soft *The score reflects the overall picture; one elevated factor won't dominate.* The weighted average, with escalation off. This is the shipped default. It is the right choice while you are still deciding whether your factor scores are calibrated, because it never surprises you. Its weakness is exactly Tom's grant: a revoked-and-reinstated, never-certified, admin-assigned grant reads as Medium. #### Balanced *Warning signs raise the score once enough factors turn toxic.* Escalation on. The tile shows the rule it is currently applying, for example *Escalation on · N ≥ 2 · score raised to the worst toxic factor*, and the number tracks the slider below it. One alarming factor could be a data quirk; two or more form a pattern. This is where most customers should end up once the first campaign has shown that the factor scores make sense. Tom's grant becomes Critical; a grant with a single odd reading does not, unless you set the count to 1. Choosing either tile also clears any explicit toxic cutoff, so the cutoff goes back to following the High threshold. ### Toxic factors A factor is **toxic** for a given grant when its own score, before weighting, is at or above the toxic cutoff. Toxicity is not a property of the factor in the catalogue and there is no toggle for it; it is decided grant by grant, at scoring time. On Tom's grant, Membership Origin at 75, Reinstated Access at 75 and Certification Age at 50 are toxic against a cutoff of 50. The three zeros are not. The mechanism is called escalation. When enough of a grant's membership factors are toxic, the grant's score becomes the **higher of** its normal average-based score and the highest toxic factor score. It can only raise a score, never lower one, and it applies to membership scores only. Entitlement factors and identity factors are never toxic; identity scores pick up the effect because they start from the riskiest membership. Weight does not make a factor toxic or non-toxic. A factor at weight 0.10 that scores 75 is still toxic. Only a factor at weight 0 is ignored. Weights govern the average; toxicity is an absolute property of the signal. The reasoning is the one Tom illustrates. A contractor's grant that a reviewer explicitly revoked, that an administrator then put back, and that nobody has certified since, is the pattern certification exists to catch. A plain average buries it under three factors that happen to read zero. Escalation refuses to let the average speak for the worst signal. When escalation fires, the reviewer's explanation says so in words: *Several warning signs add up*, followed by the factors responsible. ### Toxic factors needed to escalate How many of a grant's factors must be toxic before escalation fires. A slider from 1 to 6, shown on the strategy card once Balanced is chosen, and shipped at 2. At 1, a single alarming factor decides the headline: every grant assigned directly by an administrator scores at least 75 with the shipped factor scores, so if direct assignment is common in your organization this turns most of a campaign red. At 2, it takes a pattern. At 3 or more with the shipped six membership factors, escalation fires only on grants that are alarming in half their signals; Tom's grant, with three, is the edge case. Raise it if the Band impact panel shows Balanced firing on too many grants; lower it to 1 only when you accept the volume. ### Fine-tuning Below the strategy card is a red-bordered **Fine-tuning** card, folded every time you open the screen. It holds the four settings that change the arithmetic itself rather than the thresholds around it. Its own warning says it plainly: *These values change how every score is calculated. Edits take effect at the next recompute.* A second line adds that the impact preview does not cover them, so only a recompute shows what they do. Treat it as a danger zone. Most organizations should never open it, and the **Reset to defaults** button at the bottom puts the three uplift values back to 1.00, 20 points and 40 points and switches the explicit toxic cutoff off again. It asks for confirmation first, and it leaves the band thresholds, the strategy and the toxic count alone. Three of the four settings sit under the heading **Breadth & context uplift**. #### Breadth uplift weight How many points each high-risk membership adds to a person's identity score. "High risk" means at or above **High at**. A slider from 0 to 1 in steps of 0.05; shipped at 1.0, which adds one point per high-risk grant, counting every one of them. Tom has one high-risk grant, so his identity score is his riskiest membership, 98, plus 1. A service-desk lead with twelve High memberships gets plus 12. The idea is that breadth of dangerous access is itself a signal, separate from the single worst grant. At 0 the identity score is simply the worst membership. Remember that scores are whole numbers, so a weight of 0.3 across three grants rounds to a single point. #### Breadth uplift cap The most the breadth uplift can add in total. A slider from 0 to 40; shipped at 20. With the shipped weight, a person with thirty High grants gets plus 20, not plus 30. Lower it if a handful of people with very broad access are pinned at 100 and you want them ranked among themselves; raise it if breadth is the thing your campaign is about. At 0 breadth uplift is off regardless of the weight. #### Context uplift cap The most the membership factors can add above the entitlement's floor. A slider from 0 to 100; shipped at 40. The hint on screen puts it well: each grant starts at the entitlement's own risk score, and the circumstances of the grant can only raise that score, up to this cap. This is the setting that decides whether **what the access is** or **how it was granted** dominates a membership score. At 40, a benign entitlement with a floor of 0 can reach at most 40 from context alone, so under Soft it can never be High. Tom's `Finance-Reports-Read`, floor 25, tops out at 65 however alarming the context. Lower it toward 20 if reviewers say context is drowning out sensitivity. Raise it toward 100 if grant hygiene is the thing you want reviewed, and accept that harmless roles will then score High when granted badly. The visible misconfiguration is at the bottom: with the cap at 40 and many unclassified roles at floor 0, every membership of those roles sits at Medium or below whatever the reviewer knows about it. Classify the roles first; the cap is rarely the fix. #### The toxic cutoff The fourth setting in the Fine-tuning card. By default the cutoff **follows the High threshold**, and the card says so in a sentence: *A toxic factor is any factor whose score falls in the High or Critical range (currently 50 and above).* The switch **Use an explicit toxic cutoff** unpins it and reveals a slider from 0 to 100, and the sentence changes to name the number you chose. Below the cutoff a factor is just a reading in the average. At or above it, the factor counts toward the required number and its score becomes a candidate for the anchor. **Set too low**, say 20, and almost every non-zero reading is toxic: a grant that is merely due for review (25), merely aging (25), or merely granted through an access request (25) all qualify. Most of the population moves up a band and reviewers open a campaign that is a wall of red. The score has stopped ranking anything. **Set too high**, say 90, and with the shipped factor scores only an indefinite grant (100) can ever be toxic. The mechanism fires on grants without an end date and nothing else. At 95 it never fires at all, and Balanced silently behaves like Soft. Tune it against your real population, not in the abstract. Pick a strategy, read the Band impact panel, and only then decide whether the cutoff needs to move. Note that choosing a strategy tile again switches the explicit cutoff back off. ### Band impact The **Band impact** panel shows what the settings on this tab would do to the stored membership scores before you save. Change a threshold or a strategy setting and an **estimate** appears within a second: "1,240 of 18,000 memberships change band", followed by the largest transitions, such as "890 Medium → High". The estimate is drawn from a random sample of stored scores and scaled up, so it is fast and approximate. **Run exact preview** evaluates every membership and replaces the estimate with exact counts. Read it as the answer to "what will reviewers see next campaign". A move from Soft to Balanced that changes 7% of bands is a tuning; one that changes 40% is a new policy your reviewers need to hear about. The panel folds, and issues no queries while folded. Two limits are worth knowing: it simulates thresholds and strategy only, so nothing in the Fine-tuning card and no change to factor weights or settings is reflected; and it covers membership scores, not identity scores. ### Live score preview The **Live score preview** column follows your unsaved changes and walks one sample grant through the calculation: the entitlement floor, each membership factor, the context uplift, the escalation line if it fires, and the identity roll-up. The column collapses to a rail when you need the width. **Set values per factor**, the default mode, lets you describe a real case in the factors' own terms: how the grant was made, days since granted, whether it was ever certified, whether it was reinstated after a revoke, whether it has an end date, the entitlement's risk level, days since last login. The described case is scored by the real engine under your draft settings. A blank field means "no reading", exactly as it does for a real grant with missing data. Nothing you type is saved or affects a real score. **Set a risk score** lets you drag each factor's 0 to 100 score directly to see how the strategy and thresholds react. Its readings are illustrative, not real. {% hint style="warning" %} **The default preview mode does not react to the Fine-tuning sliders.** In *Set values per factor*, moving the context or breadth uplift leaves the sample score as it was until you change one of the described readings. Switch to *Set a risk score*, which does follow them, or change a reading to force a re-score. {% endhint %} ### Saving and recalculating One **Save policy** button, on the Aggregation Policy card, saves everything on the Scoring tab including the Fine-tuning values. It stays disabled until something differs from what is stored, and disarms again if you undo the change by hand. **Saving does not change any stored score.** Every membership and identity keeps the score and band it had, computed under the old settings, until it is recalculated. After a successful save a dialog asks **Recalculate risk scores now?** Choose **Recalculate now** to start a full recalculation of every entitlement, membership and identity immediately; scores refresh as it progresses, which can take a while on a large population. Choose **Wait for the nightly sweep** to let the scheduled nightly recalculation pick the change up. A grant that changes in the meantime is recalculated on its own, under the new settings, whichever you chose. Until recalculation, a reviewer can see a score computed under the old thresholds next to a colleague's computed under the new. Recalculate before launching a campaign you have just retuned for. ## Tuning factors inside the policy The **Factors** tab lists the factors attached to the policy, grouped by level. Each row shows the factor's name, a **Built-in** chip, its decay chip, its key, an enable toggle, a weight slider, and an expander with the factor's own settings. The policy owns the toggle, the weight and the settings. Changes to a row are saved with that row's **Save factor** button, not with the policy's Save policy. Like a policy save, a factor save changes no stored score until the next recalculation. ### Enabled The toggle at the left of each row. A disabled factor is skipped entirely: it is not evaluated, it does not appear in the breakdown, and it is not in the average. That is different from a weight of 0, where the factor still appears in the breakdown with no effect. Disabling a factor does nothing to scores already computed. They keep the contribution until the grant is recalculated, so disable and then recalculate if the change matters for the next campaign. Disable rather than detach; see [Detach](#user-policy-factor-detach). ### Weight A slider from 0 to 1 in steps of 0.05, shipped at 1.0 for every built-in factor. Weight is the factor's share of the average at its level, **relative to the other weights at that level**. The weights do not need to sum to 1, and they are not percentages: six factors at 1.0 is an even average, and six factors at 0.5 is exactly the same even average. You cannot make a factor count more than 1.0; you can only make the others count less. Two consequences follow. A level with a single factor is unaffected by that factor's weight: Entitlement Sensitivity is the only entitlement factor, so changing its weight changes nothing. And weight has no effect on toxicity; a factor at 0.10 that scores 75 still counts as toxic. **A worked change.** A customer in a regulated industry wants grant hygiene to outweigh how long a grant has existed. They leave Membership Origin, Reinstated Access, Certification Age and Expired Membership at 1.0 and drop Stale Membership and Membership Duration to 0.25. | Grant | Before | After | What moved | | ------------------------------ | ----------- | ------------ | --------------------------------------------------------------------------------- | | Maria's `Finance-Reports-Read` | 37 Medium | 31 Medium | Her three-year-old indefinite grant no longer dominates her context | | Tom's `Finance-Reports-Read` | 38 Medium | 43 Medium | His origin, reinstatement and missing certification now carry more of the average | | Tom's `Payments-Admin` | 98 Critical | 100 Critical | Already at the top | Before the change the two `Finance-Reports-Read` grants were one point apart. After it they are twelve apart, in the right order. Under Balanced, Tom's grant was already escalated to 75 and does not move; weights govern the average, not the anchor. ### Level groups Factors are listed under three headings that name their level and what it feeds: **Entitlement — floors membership risk**, **Membership — rolls up into identity risk**, and **Identity — the aggregate a reviewer sees**. The heading is the only place the level appears; the rows themselves carry no level mark. A factor's level is part of the factor and cannot be changed. Why the levels are kept apart is explained on the [Risk factor reference](/administration-guide/risk/factors.md#levels-binding). ### The expander Open a row to see the factor's own settings, described factor by factor on the [Risk factor reference](/administration-guide/risk/factors.md#factors). Banded factors show a timeline with draggable cutoffs and score markers; the other factors show a list of scores. The **Decay behavior** panel is read-only here and reads **None** for every built-in factor; see [Time windows and decay](/administration-guide/risk/factors.md#factor-decay). **Get explanation** writes out what the factor does in sentences, using the current values. One of them says how many points the factor's highest band contributes at its weight; read that as its largest share of the average, not as points added to the score. ### Add factor Opens a dialog listing the active factors the policy does not yet use. With all eight built-in factors attached the dialog says that every factor this policy can use is already attached. A newly attached factor arrives enabled, at the catalogue's default weight, with the catalogue's default settings. Since one policy now governs every level, a factor of any level can be attached. The one rule left is applicability: a membership-level or identity-level factor marked as applying only to non-human identities is refused, because this policy scores people. ### Detach Removes the factor from the policy after a confirmation. For a built-in factor, do not use it to stop the factor scoring. {% hint style="warning" %} **A detached built-in factor comes back.** Every time the risk service starts it re-attaches any built-in factor missing from the policy, with the catalogue's default weight and settings, discarding whatever you had tuned. To stop a built-in factor scoring, switch it off with **Enabled**; that is preserved. {% endhint %} ## Recommended starting configuration For the first cycle, change as little as possible and look at the data. | Setting | Start with | Why | | ------------------------------------------ | ---------------------------------------------------------------- | -------------------------------------------------------------- | | Scoring strategy | Soft | No surprises while you check that factor scores are calibrated | | Band thresholds | 25 / 50 / 75 | The shipped scale; every other default assumes it | | Fine-tuning | Leave folded | 1.00 / 20 / 40 and a cutoff that follows High | | All factor weights | 1.0 | An even average is the easiest to reason about | | Membership Origin: Unknown origin adds | 0 until origin tags are being stamped, then 50 | Otherwise every untagged grant adds 50 for nothing | | Certification Age: Never certified adds | 25 until the first campaign has run, then 50 | Otherwise every grant adds the same 50 | | Membership Duration: Indefinite grant adds | 100 if you use end dates; 25 to 50 if most grants are open-ended | A uniform 100 tells you nothing | | Dormant Identity | On, if OpenIAM records your users' logins; off if not | Otherwise everyone is dormant | Then run one campaign, or at least one recalculation, and read the distribution: the Band impact panel, a few known users on **User Risk**, and the reviewer screen. Ask whether the people and grants you would have ranked highest are near the top. Only then move to Balanced, and only then touch a weight. One change per cycle, with the Band impact panel open, is the pace that keeps scores explainable to the people who see them. ## What changed: the entitlement policy, Severe and Custom Earlier releases shipped **two** policies: a user policy and a separate **Entitlement scoring** policy that held the entitlement-level factors and its own band thresholds. They have been merged. One policy now holds every factor and one set of thresholds bands every score. On upgrade the entitlement policy's factors move across and its own thresholds are discarded, so entitlement scores are re-banded against the surviving thresholds at the next recalculation. The reason is that two threshold sets could disagree: an entitlement could be Medium on its own scale and contribute a floor that read High on the other, and no screen showed you both. One scale removes the question. A note for anyone reading old configuration: **Applies to** and **Population** no longer appear on a policy card, because there is nothing left to choose between. ### Severe A third strategy, *Severe*, once sat beside Soft and Balanced and escalated on a single toxic factor. It is gone as a separate choice: it was Balanced with the count set to 1, which the slider already expresses. Policies saved as Severe read as Balanced with a count of 1 and score exactly as before. ### Custom The card also used to show a **Custom** chip whenever the escalation settings matched no preset, in particular whenever an explicit toxic cutoff was set. That chip is gone. Setting a count other than 2, or an explicit cutoff, is now an ordinary part of Balanced rather than a state of its own. Policies saved as Custom read as Balanced and score exactly as before. ## Related * [Risk factor reference](/administration-guide/risk/factors.md) — every factor's settings, with examples * [Access certification and risk](/administration-guide/risk/certification.md) — where the thresholds and bands are consumed * [Reading risk on the reviewer screen](/administration-guide/risk/reviewer-experience.md) — how escalation appears to a reviewer * [Risk management overview](/administration-guide/risk/overview.md) — the concepts, without settings *Applies to OpenIAM 2026.9.1. Last reviewed 4 September 2026.* --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.openiam.com/administration-guide/risk/policies.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.