How Policies Are Evaluated
When your agent attempts an action, Gatekeeper doesn't check one rule — it walks through several layers of policy in a fixed order. Understanding that order is the difference between a policy that does what you meant and one that quietly never fires.
The layers
Policy is organized into chains, evaluated in this sequence:
- Organization — rules that apply across every service your organisation has connected.
- Organization, per service — rules for one specific service, applying to everyone.
- User — rules for a specific person, across all services.
- User, per service — rules for a specific person on a specific service.
How a decision gets made
Each chain returns one of four things:
| Result | What it means |
|---|---|
| Allow | The action runs. Evaluation stops here. |
| Deny | The action is blocked. Evaluation stops here. |
| Require approval | The action pauses for a human decision. Evaluation stops here. |
| Pass | This chain has no opinion. Evaluation moves to the next chain. |
The first chain that returns anything other than Pass decides the outcome.
That last point is the one that catches people out. A broad rule sitting in an early chain will decide the request before a narrower, more carefully written rule in a later chain ever gets to run. Order beats specificity — always.
Worked example
An agent tries to create a HubSpot contact. The verdict trail looks like this:
chain "default" → pass chain "svc-hubspot" → allow (rule: svc-default)
The organization-level chain had nothing to say, so evaluation moved on. The HubSpot service chain allowed it, and evaluation stopped. Any user-level rule further down the stack was never consulted.
What your rules can see
Policies are evaluated against a context object describing the request. The fields available to you include:
- Request — the service, the tool being called, and the full parameters submitted
- Client — who is making the request, and which organisation they belong to
- Credential — whether the stored credential is still valid and when it expires
- Connection — source IP address and client user agent
- Activity — how many requests this agent has made in the last minute and today, and how many bytes it has moved today
- Time — the current timestamp
That activity data is what makes volume rules possible: you can require approval once an agent exceeds a request threshold for the day, or deny calls outside working hours using the timestamp.
Before writing a rule against any of these fields, check what's actually present for the request you care about — see Testing a Policy Before You Deploy It.
Practical guidance
- Put broad guardrails high, exceptions low — and expect the broad rule to win. If you need an exception to survive, it has to sit in an earlier chain than the rule it's excepting, not a later one.
- Use Pass deliberately. A chain that returns Pass is delegating, not permitting. That's usually what you want at the organisation level so per-service rules can do the detailed work.
- Simulate before you save. Chain interactions are the most common source of "my policy isn't working" tickets.