← Back to Guides

Companion to the book Harness Engineering for Production AI Systems · this part maps to Book Ch 10

GuideFor: AI Engineers, ML Engineers, Platform Engineers, AI Systems Architects

Strict Tool Schemas Aren't Enough: Narrow LLM Tool Calls

A strict schema makes a refund call well-formed. It does not stop the model from choosing the account and the amount, and every check after it is judging those choices.

#harness-engineering#tool-calling#structured-outputs#llm-agents#ai-safety#production-ai-systems

An LLM tool call refunded the wrong customer, and the strict tool schema and every control in the gate policy passed it.

Account acct_4417 had sent the ticket the billing agent was working. Invoice inv_9107 carries a single sign-on (SSO) add-on of 120.00 charged twice, so the customer is owed 120.00. What the model proposed was issue_refund(account_id="acct_4471", amount=120.00). It had swapped two digits of the account number.

A strict schema guarded the tool. account_id had to match ^acct_[0-9]{4,8}$, and amount had to fall between 0.01 and 2,000. Both did. Next, the comparator asked whether 120.00 appears on one of the account's invoices, and for acct_4471 it does: that customer pays 120.00 for an extra seat. Then the gate from Part 9 put 120.00 under its 200.00 automatic band. So the refund went out with no person involved, to a customer who had asked for nothing.

This is the series' constructed billing agent, running the Chapter 9 gate policy on the issue_refund(account_id, amount) signature my book used through that chapter. Every control in that policy did its job. Each one judged a value the model had chosen, and the model chose wrong.

The series' own harness has one more check. Part 7 compares the proposed account_id with the account the ticket came from, and it would have refused this slip. That check is the pattern this part questions: it exists only because the signature asked the model for a value the system already knew.

d2
grid-rows: 2
grid-columns: 3
grid-gap: 24
classes: {
  model: {style: {fill: "#FFA07A"; stroke: "#D9785A"; font-color: "#2C2C2A"}}
  ctl: {style: {fill: "#7B68EE"; stroke: "#5A4BC4"; font-color: "#FFFFFF"}}
}
m: "1. model writes\naccount_id=acct_4471\namount=120.00" {class: model}
s: "2. strict schema:\npattern and range hold" {class: ctl}
c: "3. comparator: 120.00 is on\nan acct_4471 invoice" {class: ctl}
g: "4. gate: 120.00 is under\nthe 200.00 band" {class: ctl}
out: "5. refund sent to\nthe wrong customer" {style: {fill: "#E74C3C"; stroke: "#A93226"; font-color: "#FFFFFF"}}
blank: "" {style: {opacity: 0}}

The wrong value enters once, at step 1, and every step after it checks that value against a rule the value can satisfy. Nowhere does a step ask where the account number came from.

Strict tool schemas check how an LLM tool call is spelled

Strict tool use is the industry's answer to malformed tool calls, and it works. With strict: true, OpenAI and Anthropic both constrain decoding so the arguments match the JSON Schema you sent. Anthropic's strict tool use page lists the benefit as "No need to validate and retry tool calls". OpenAI is more careful. Its Structured Outputs guide says your application must still "validate any business rules that the schema does not express".

Anthropic's sentence is about schema conformance. The reading I want to argue with is the one teams take from it: once the schema is enforced, the tool call needs no more checking. My own April post on tool registries went one step further. It set out to make "hallucinated tool calls structurally impossible" with parameters validated by type, enum and min-max range, and treated that as the deterministic constraint layer. The misreading moves effort to the wrong place. A team that trusts the schema spends its review time on the controls downstream, while the values those controls judge are still chosen by the model. I think that reading is wrong in a specific way. A schema constrains how a value is spelled. It does not constrain who chose the value. A static, hand-written schema cannot know which account this ticket belongs to or which charges are on its invoice, so every value it admits is one the model could get wrong about whose it is.

Here is the claim this part defends. What constrains an agent is what its tool signatures let the model supply. Every argument your system could have looked up for itself, such as the account a refund goes to or the amount it pays, is a decision you handed to the model. Every control after that point second-guesses the decision. That includes the gate's amount band, which then thresholds a number the model wrote. Take those arguments out of the signature and two things change. Ownership becomes the comparator's question, a lookup with one right answer, and the band reads the ledger's number. Choice still remains with the model, which now picks among records. So the worst single wrong call becomes a charge this customer actually paid, read from the account's own records, where the wide signature's worst call was the schema's ceiling, at any account.

The same claim has a second half, because a signature is never written down once. A tool's facts live in several artifacts: the signature, the gate policy, the retry table, a paragraph in the prompt, the set of callables the executor will dispatch. Those copies come in two kinds. Enforcing copies, such as the dispatch table, the gate policy and whatever admission reads, decide what can execute, so a stale one widens the set. Describing copies, such as the prompt paragraph and a server's annotations, decide what the model attempts, so a stale one wastes calls or steers the model toward a wider sibling tool. A narrowing holds only while both kinds agree with the one row the tool is declared in.

Here is where the part goes. It narrows a refund to a charge line and shows what that removes and what it leaves. It computes the worst single wrong call from the narrowed signature, the number a gate band should be set against. Then it builds a startup check that probes every required comparator with a proposal for each tool that requires it, and flags a pass that read no argument. Run through a three-line adapter against the real comparator at my companion repo's chapter tag, that probe flags a defect that passes every other check.

Strict mode is still useful, with one qualifier. A strict schema is exactly as narrow as the values you derive into it. A schema whose enum lists this account's charge lines, built for this run from the ledger, makes a foreign charge impossible to write at decode time, and strict mode enforces whatever that derivation produced.

d2
grid-rows: 1
grid-gap: 30
static: "Hand-written schema" {
  label.near: top-center
  style: {fill: "#FDECEA"; stroke: "#C0392B"; font-color: "#2C2C2A"}
  grid-columns: 1
  a1: "account_id: any acct_ pattern" {style: {fill: "#FFA07A"; stroke: "#D9785A"; font-color: "#2C2C2A"}}
  a2: "amount: 0.01 to 2000" {style: {fill: "#FFA07A"; stroke: "#D9785A"; font-color: "#2C2C2A"}}
  a3: "knows: spelling" {style: {fill: "#95A5A6"; stroke: "#6B7B7C"; font-color: "#FFFFFF"}}
}
derived: "Schema derived per run" {
  label.near: top-center
  style: {fill: "#EAF7EE"; stroke: "#3F9E52"; font-color: "#2C2C2A"}
  grid-columns: 1
  b1: "account: from the channel" {style: {fill: "#6BCF7F"; stroke: "#3F9E52"; font-color: "#2C2C2A"}}
  b2: "line_id: enum of 4 ledger lines" {style: {fill: "#6BCF7F"; stroke: "#3F9E52"; font-color: "#2C2C2A"}}
  b3: "knows: this account's records" {style: {fill: "#4A90E2"; stroke: "#2C6FB0"; font-color: "#FFFFFF"}}
}

Both columns are valid strict schemas, and the decoder enforces each of them with the same guarantee. On the left, the schema admits every account number with the right spelling. Its neighbour admits four values, and all four came from the ledger.

The wrong way: a strict refund schema with a range check

Here is the wide tool as code. It reuses the band-first gate from Part 9, trimmed to its dispositions, and adds a small ledger. That ledger has the duplicate SSO line on inv_9107 and one other customer, acct_4471, who pays 120.00 for a seat.

python
from dataclasses import dataclassfrom decimal import Decimalfrom enum import Enumimport reimport textwrapclass Mode(str, Enum):    COPILOT = "copilot"    QUEUE_DRAIN = "queue-drain"class Disposition(str, Enum):    ALLOW = "allow"    ESCALATE = "escalate"    REFUSE = "refuse"@dataclass(frozen=True)class Verdict:    name: str    passed: bool    detail: str = ""@dataclass(frozen=True)class Rule:    tool: str    mode: Mode    requires: tuple[str, ...]    auto_below: Decimal | None = None  # None: the tool has no amount band    review_below: Decimal | None = None@dataclass(frozen=True)class Decision:    disposition: Disposition    reason: strdef decide(rule: Rule | None, amount: Decimal | None,           verdicts: dict[str, Verdict]) -> Decision:    """Part 9's band-first gate, trimmed to the dispositions."""    if rule is None:        return Decision(Disposition.REFUSE, "no rule")    failed = [n for n in rule.requires if not verdicts.get(n, Verdict(n, False)).passed]    if rule.auto_below is None:  # not thresholded: the verdicts decide alone        if failed:            return Decision(Disposition.REFUSE, f"{failed[0]} failed")        return Decision(Disposition.ALLOW, "no band for this tool")    if amount is None:        return Decision(Disposition.REFUSE, "no amount")    reviewable = rule.review_below is not None and amount < rule.review_below    if failed:        if reviewable:            return Decision(Disposition.ESCALATE, f"{failed[0]} failed: edit or reject")        return Decision(Disposition.REFUSE, f"{failed[0]} failed: no review path")    if amount < rule.auto_below:        return Decision(Disposition.ALLOW, "automatic band")    if reviewable:        return Decision(Disposition.ESCALATE, "review band")    return Decision(Disposition.REFUSE, "no path in this mode")@dataclass(frozen=True)class Line:    account_id: str    invoice_id: str    line_no: int    item: str    amount: Decimal    @property    def line_id(self) -> str:        return f"{self.invoice_id}.L{self.line_no}"D = DecimalLEDGER = (    Line("acct_4417", "inv_9002", 1, "onboarding fee", D("120.00")),    Line("acct_4417", "inv_9107", 1, "team plan", D("960.00")),    Line("acct_4417", "inv_9107", 2, "SSO add-on", D("120.00")),    Line("acct_4417", "inv_9107", 3, "SSO add-on", D("120.00")),  # the duplicate    Line("acct_4471", "inv_9311", 1, "extra seat", D("120.00")),  # another customer)def lines_for(account_id: str) -> list[Line]:    return [ln for ln in LEDGER if ln.account_id == account_id]

As written, the wide schema's parameters object is valid OpenAI strict JSON Schema; the wire format wraps it in a function definition, and Anthropic calls the same object input_schema. Anthropic's strict mode rejects minimum, maximum and multipleOf with a 400 error, so on Claude the range check moves into your own code, which is what schema_problems stands in for. It checks what strict decoding guarantees and nothing else. For the comparator, the demo widens the book's proxy, which checks invoice totals, to lines as well: does this number appear on one of the account's invoices, as a line or as a total? The transposed account passes under the book's totals-only version too, because inv_9311 totals 120.00.

python
WIDE_REFUND = {    "name": "issue_refund",    "strict": True,    "parameters": {        "type": "object",        "properties": {            "account_id": {"type": "string", "pattern": "^acct_[0-9]{4,8}$"},            "amount": {"type": "number", "minimum": 0.01, "maximum": 2000,                       "multipleOf": 0.01},        },        "required": ["account_id", "amount"],        "additionalProperties": False,    },}def schema_problems(schema: dict, args: dict) -> list[str]:    """What strict decoding guarantees: keys, types, pattern, range, enum."""    params = schema["parameters"]    found = [f"{k} is not a parameter" for k in args if k not in params["properties"]]    found += [f"{k} is required" for k in params["required"] if k not in args]    for key, rule in params["properties"].items():        if key not in args:            continue        value = args[key]        if rule["type"] == "number" and not (            rule["minimum"] <= value <= rule["maximum"]        ):            found.append(f"{key} out of range")        if "multipleOf" in rule and D(str(value)) % D(str(rule["multipleOf"])):            found.append(f"{key} is not a multiple of {rule['multipleOf']}")        if "pattern" in rule and not re.fullmatch(rule["pattern"], value):            found.append(f"{key} does not match {rule['pattern']}")        if "enum" in rule and value not in rule["enum"]:            found.append(f"{key} is not one of {len(rule['enum'])} values")    return founddef amount_on_invoice(args: dict) -> Verdict:    """The proxy comparator: does this number appear on the account's invoices?"""    lines = lines_for(args["account_id"])    totals = {}    for ln in lines:        totals[ln.invoice_id] = totals.get(ln.invoice_id, D("0")) + ln.amount    seen = {ln.amount for ln in lines} | set(totals.values())    ok = D(str(args["amount"])) in seen    return Verdict("amount_on_invoice", ok, "on an invoice" if ok else "on no invoice")WIDE_POLICY = {    Mode.COPILOT: Rule("issue_refund", Mode.COPILOT, ("amount_on_invoice",),                       D("200.00"), D("2000.00")),    Mode.QUEUE_DRAIN: Rule("issue_refund", Mode.QUEUE_DRAIN, ("amount_on_invoice",),                           D("50.00"), None),}PROPOSALS = [  # what a model reading the inv_9107 ticket might write    ("misread total", {"account_id": "acct_4417", "amount": 940.00}),    ("invoice total", {"account_id": "acct_4417", "amount": 1200.00}),    ("wrong line", {"account_id": "acct_4417", "amount": 960.00}),    ("both SSO lines", {"account_id": "acct_4417", "amount": 240.00}),    ("transposed account", {"account_id": "acct_4471", "amount": 120.00}),    ("correct", {"account_id": "acct_4417", "amount": 120.00}),]def run_wide() -> None:    for label, args in PROPOSALS:        shape = schema_problems(WIDE_REFUND, args) or ["valid"]        v = amount_on_invoice(args)        d = decide(WIDE_POLICY[Mode.COPILOT], D(str(args["amount"])),                   {v.name: v})        print(f"  {label:<19} {args['account_id']} {args['amount']:>8.2f}  "              f"{shape[0]:<6} {v.detail:<14} {d.disposition.value}")

Four of the wrong answers come from Part 7, which listed the plausible wrong amounts for this ticket: a misread 940.00, the 1,200.00 invoice total, the 960.00 plan line, and both SSO lines. A fifth is the transposed account from the opening. One file runs every block in this part, with no model and no network. In copilot mode:

text
--- wide signature, strict schema, Part 9's band (copilot) ---  misread total       acct_4417   940.00  valid  on no invoice  escalate  invoice total       acct_4417  1200.00  valid  on an invoice  escalate  wrong line          acct_4417   960.00  valid  on an invoice  escalate  both SSO lines      acct_4417   240.00  valid  on no invoice  escalate  transposed account  acct_4471   120.00  valid  on an invoice  allow  correct             acct_4417   120.00  valid  on an invoice  allow

All six are valid. None of the five wrong ones was stopped by the schema, because none of them is badly spelled. Four reach a person, which is Part 9's gate doing its job: a failed proxy check escalates as edit-or-reject, and a large clean amount escalates for review. Transposing the account earns the same disposition as the correct refund. Both are 120.00, both pass the proxy, and both sit under the automatic band.

d2
grid-rows: 2
grid-columns: 3
grid-gap: 24
h1: "model writes" {style: {fill: "#95A5A6"; stroke: "#6B7B7C"; font-color: "#FFFFFF"; bold: true}}
h2: "control that judges it" {style: {fill: "#95A5A6"; stroke: "#6B7B7C"; font-color: "#FFFFFF"; bold: true}}
h3: "what the control can know" {style: {fill: "#95A5A6"; stroke: "#6B7B7C"; font-color: "#FFFFFF"; bold: true}}
v1: "account_id\namount" {style: {fill: "#FFA07A"; stroke: "#D9785A"; font-color: "#2C2C2A"}}
v2: "schema, proxy, band" {style: {fill: "#7B68EE"; stroke: "#5A4BC4"; font-color: "#FFFFFF"}}
v3: "is the value\nwell-spelled and plausible?" {style: {fill: "#FFD93D"; stroke: "#C9A800"; font-color: "#2C2C2A"}}

Below the header there is only one row, because the wide signature has one design: the model writes both values. Every value the gate decides on was written by the model, and every control in this policy can ask only whether that value looks plausible. The account question was decidable all along, which is why Part 7 could check it. The amount question was not. "Is 120.00 the right refund for this ticket" has no decidable answer, and a proxy is the check people reach for when the question they care about cannot be asked.

Narrow the tool signature: refund a charge line

Narrowing takes the two derivable values out of the signature. The account comes from the channel the ticket arrived on. Part 7's code already held that account in a CHANNEL_ACCOUNT constant, but it still let the model write account_id and then compared the two. Both follow Part 4's rule that origin comes from the channel. The amount comes from the ledger. One thing is left for the model to name: which charge line to refund. Part 7's Repair Ladder already had a rung that worked this way, asking the model for row ids and computing the amount in code. There it was a repair, run after a proposal had failed. Here it is the signature, so the amount is never asked for at all.

My book narrows issue_refund to an invoice id, refunded in full. On inv_9107 that shape fails. Its only expressible refund is the whole invoice, 1,200.00, which is one of the known wrong answers, and the correct 120.00 cannot be written at all. So this part narrows one level further, to the line. Stripe keys a refund on the charge, a payment, and takes an optional amount that cannot exceed what is left unrefunded on it. This signature keys on the line, so the executor passes that line's ledger amount to the charge refund. The amount the gate thresholds and the amount the executor sends must then come from the same read, or the two become a Split Declaration of their own.

A tool is a row of facts. Each parameter has one of four types, a closed set, and each type says how much the model is trusted to write. The modes field stands in for the Authority Bands that Part 14 builds.

python
class ParamType(str, Enum):    ID = "id"        # resolved against the system's records, per run    ENUM = "enum"    # one of a fixed list    MONEY = "money"  # a number the model writes; the expensive one    TEXT = "text"    # anything, up to a length@dataclass(frozen=True)class Param:    name: str    type: ParamType    resolves: str | None = None  # for ID: the ledger collection it must name    choices: tuple[str, ...] = ()    max_chars: int | None = None@dataclass(frozen=True)class ToolSpec:    name: str    summary: str    writes: bool    params: tuple[Param, ...]    modes: tuple[Mode, ...]    consequence: str | None = None  # "ledger:<param>" or "model:<param>"@dataclass(frozen=True)class Run:    mode: Mode    account_id: str  # from the channel (Part 4), never from the model

domain is the piece that makes the signature narrow. For an ID parameter it reads the values this run may write from the records. schema_for turns those values into a strict enum for the model. admission checks the same values in code, because strict mode may be off, unsupported by the provider, or bypassed by a caller that is not the model. Both read one domain. For a given ledger state, on a provider that accepts every constraint in the schema, the model is never told it may write a value the executor refuses. admission reports every problem at once, for the reason Part 7 gave: each complaint the model receives costs one repair round.

python
MONEY_RANGE = (D("0.01"), D("10000.00"))  # one copy, read by schema and admissiondef domain(p: Param, run: Run) -> list[str] | None:    """The values this run may write for p, read from the records. None: unbounded."""    if p.type is ParamType.ID and p.resolves == "lines":        return [ln.line_id for ln in lines_for(run.account_id)]    if p.type is ParamType.ENUM:        return list(p.choices)    return Nonedef schema_for(spec: ToolSpec, run: Run) -> dict:    """The strict schema the model is sent, derived per run from the spec."""    props = {}    for p in spec.params:        values = domain(p, run)        if values is not None:            props[p.name] = {"type": "string", "enum": values}        elif p.type is ParamType.MONEY:            low, high = MONEY_RANGE            props[p.name] = {"type": "number", "minimum": float(low),                             "maximum": float(high)}        elif p.type is ParamType.ID:            raise ValueError(f"{spec.name}.{p.name}: an id must resolve to records")        elif p.max_chars is None:            raise ValueError(f"{spec.name}.{p.name}: free text needs a limit")        else:            props[p.name] = {"type": "string", "maxLength": p.max_chars}    return {"name": spec.name, "strict": True, "parameters": {        "type": "object", "properties": props,        "required": [p.name for p in spec.params], "additionalProperties": False}}def admission(spec: ToolSpec | None, run: Run, args: dict) -> list[str]:    """The same check in code, against the same derived domains. Every problem."""    if spec is None:        return ["no such tool"]    if run.mode not in spec.modes:        return [f"{spec.name} is not offered in {run.mode.value}"]    names = {p.name for p in spec.params}    found = [f"{k} is not a parameter of {spec.name}" for k in args if k not in names]    for p in spec.params:        if p.name not in args:            found.append(f"{p.name} is required")            continue        value, values = args[p.name], domain(p, run)        if values is not None and value not in values:            found.append(f"{p.name}={value}: not one of {len(values)} allowed")        if p.type is ParamType.MONEY:            try:                money = D(str(value))            except ArithmeticError:  # decimal.InvalidOperation: not a number                found.append(f"{p.name}={value!r} is not a number")                continue            if not money.is_finite():                found.append(f"{p.name}={value!r} is not a finite number")            elif not MONEY_RANGE[0] <= money <= MONEY_RANGE[1]:                found.append(f"{p.name}={value} is outside {MONEY_RANGE}")        if p.max_chars is not None and len(str(value)) > p.max_chars:            found.append(f"{p.name} is over {p.max_chars} characters")    return found

schema_for above emits minimum, maximum and maxLength. OpenAI's guide lists minimum and maximum as supported in strict mode. Anthropic's strict mode rejects all three, so for Claude you drop them from the schema, and admission still enforces them. What matters is that both copies read one Param and one MONEY_RANGE.

d2
direction: down
classes: {
  rec: {style: {fill: "#98D8C8"; stroke: "#5FA898"; font-color: "#2C2C2A"}}
  code: {style: {fill: "#4A90E2"; stroke: "#2C6FB0"; font-color: "#FFFFFF"}}
}
ch: "channel: ticket from acct_4417" {class: rec}
led: "ledger: 4 lines on acct_4417" {class: rec}
dom: "domain(line_id, run)" {class: code}
sch: "schema_for: strict enum" {class: code}
adm: "admission: same values, in code" {class: code}
model: "model picks one line_id" {style: {fill: "#FFA07A"; stroke: "#D9785A"; font-color: "#2C2C2A"}}
ch -> dom: "1. account"
led -> dom: "2. lines"
dom -> sch: "3. values"
dom -> adm: "3. values"
sch -> model: "4. sent"
model -> adm: "5. proposal"

Two arrows leave domain, and that is the design. Four values are sent to the model, and the executor accepts the same four. Neither copy is written by hand.

Where the approval gate's amount comes from

Part 9's gate applies its bands to an amount. With no amount in the proposal, the gate has to get one from somewhere else, and that choice is the most consequential line in this part. consequence reads the spec's declaration. For issue_refund the declaration says the amount comes from the ledger through line_id, so the model supplies only the key.

python
def consequence(spec: ToolSpec, run: Run, args: dict) -> tuple[Decimal | None, str]:    """The number the gate thresholds, and where it came from."""    if spec.consequence is None:        return None, "none declared"    source, name = spec.consequence.split(":")    if source == "model":        return D(str(args[name])), f"the model's {name}"    for ln in lines_for(run.account_id):  # re-read at act time, not plan time        if ln.line_id == args.get(name):            return ln.amount, f"the ledger, {ln.line_id}"    return None, f"{args.get(name)} is not on {run.account_id}"
d2
grid-rows: 1
grid-gap: 36
wide: "Wide: the model's number" {
  label.near: top-center
  style: {fill: "#FDECEA"; stroke: "#C0392B"; font-color: "#2C2C2A"}
  grid-columns: 1
  w1: "model writes amount=120.00\nmatching some invoice line" {style: {fill: "#FFA07A"; stroke: "#D9785A"; font-color: "#2C2C2A"}}
  w2: "proxy passes,\nband reads 120.00" {style: {fill: "#7B68EE"; stroke: "#5A4BC4"; font-color: "#FFFFFF"}}
  w3: "automatic tier" {style: {fill: "#E74C3C"; stroke: "#A93226"; font-color: "#FFFFFF"}}
}
narrow: "Narrow: the ledger's number" {
  label.near: top-center
  style: {fill: "#EAF7EE"; stroke: "#3F9E52"; font-color: "#2C2C2A"}
  grid-columns: 1
  n1: "model writes line_id=inv_9107.L1" {style: {fill: "#FFA07A"; stroke: "#D9785A"; font-color: "#2C2C2A"}}
  n2: "ledger returns 960.00" {style: {fill: "#98D8C8"; stroke: "#5FA898"; font-color: "#2C2C2A"}}
  n3: "band reads 960.00: review" {style: {fill: "#6BCF7F"; stroke: "#3F9E52"; font-color: "#2C2C2A"}}
}

Both columns run the same band. On the left the model chose the number the band reads, and any number that also matches an invoice line under 200.00 passes the proxy and lands in the automatic tier, whatever the ticket was about. In the opening, the transposed account is one such number. On the right the model chose only a key, and the number came from the record that key names.

consequence repeats the lookup at act time. The schema was rendered when the model was called, and the ledger may have changed by the time the proposal arrives. In this demo admission refuses a missing line first, because it reads the same ledger in the same call. consequence returning no amount is the backstop if the two are ever split, and Part 9's gate refuses a thresholded tool with no amount in every mode. That rule matters more here than it did in Part 9. My book's gate sends a missing amount to review, so an unresolvable key would become a review request overnight with nobody present to review it.

Five tools sit in the registry. Tools with no amount get a rule with no band, and decide lets their verdicts decide alone. The refund rule requires line_on_account, the ownership lookup kept as a comparator, as my book keeps its InvoiceBelongsToAccount. Admission already refuses a foreign line, so the comparator never changes a decision in this demo. It exists so the answer is a verdict, which Part 6's Second Stream can record as one of the refund's owed decisions. act runs every comparator a rule requires from one map, CHECKS, and the startup check below reads the same map.

Three defects are planted in this policy on purpose, for the startup check later: close_ticket has no overnight rule, a rule survives for refund_invoice, the tool's old name, and the credit rule requires amount_on_invoice.

python
BOTH = (Mode.COPILOT, Mode.QUEUE_DRAIN)REGISTRY = {s.name: s for s in (    ToolSpec("get_account", "Read the account's plan and invoices.", False,             (), BOTH),    ToolSpec("issue_refund", "Refund one charge line to the card that paid it.",             True, (Param("line_id", ParamType.ID, resolves="lines"),), BOTH,             consequence="ledger:line_id"),    ToolSpec("apply_credit", "Add a goodwill credit to the account.", True,             (Param("amount", ParamType.MONEY),              Param("reason", ParamType.TEXT, max_chars=300)), BOTH,             consequence="model:amount"),    ToolSpec("post_ticket_reply", "Post a reply the customer will read.", True,             (Param("body", ParamType.TEXT, max_chars=4000),), BOTH),    ToolSpec("close_ticket", "Close the ticket with a resolution code.", True,             (Param("code", ParamType.ENUM,                    choices=("resolved", "duplicate", "no_reply", "refunded")),),             BOTH),)}POLICY = {(r.tool, r.mode): r for r in (    Rule("get_account", Mode.COPILOT, ()),    Rule("get_account", Mode.QUEUE_DRAIN, ()),    Rule("post_ticket_reply", Mode.COPILOT, ()),    Rule("post_ticket_reply", Mode.QUEUE_DRAIN, ()),    Rule("close_ticket", Mode.COPILOT, ()),  # queue-drain was never added    Rule("issue_refund", Mode.COPILOT, ("line_on_account",), D("200.00"),         D("2000.00")),    Rule("issue_refund", Mode.QUEUE_DRAIN, ("line_on_account",), D("50.00"), None),    Rule("apply_credit", Mode.COPILOT, ("amount_on_invoice",), D("500.00"),         D("5000.00")),    Rule("apply_credit", Mode.QUEUE_DRAIN, ("amount_on_invoice",), D("100.00"),         D("1000.00")),    Rule("refund_invoice", Mode.COPILOT, (), D("200.00"), D("2000.00")),  # old name)}def line_on_account(tool: str, args: dict, run: Run) -> Verdict:    """The ownership lookup as a comparator, so its answer is a recorded verdict."""    line = args.get("line_id")    ok = any(ln.line_id == line for ln in lines_for(run.account_id))    return Verdict("line_on_account", ok, "on this account" if ok else "not on it")CHECKS = {"line_on_account": line_on_account}  # verdict name -> comparatordef act(tool: str, args: dict, run: Run) -> str:    spec = REGISTRY.get(tool)    problems = admission(spec, run, args)    if problems:        return f"REFUSE   admission  {'; '.join(problems)}"    rule = POLICY.get((tool, run.mode))    needed = rule.requires if rule else ()    verdicts = {n: CHECKS[n](tool, args, run) for n in needed if n in CHECKS}    amount, source = consequence(spec, run, args)    d = decide(rule, amount, verdicts)    shown = "-" if amount is None else f"{amount:.2f}"    return f"{d.disposition.value.upper():<8} gate  {shown:>12} from {source}"def run_narrow() -> None:    copilot = Run(Mode.COPILOT, "acct_4417")    sent = schema_for(REGISTRY["issue_refund"], copilot)["parameters"]["properties"]    print("  line_id enum sent to the model:", ", ".join(sent["line_id"]["enum"]))    cases = [        ("wrong line", Mode.COPILOT, {"line_id": "inv_9107.L1"}),        ("correct", Mode.COPILOT, {"line_id": "inv_9107.L3"}),        ("correct", Mode.QUEUE_DRAIN, {"line_id": "inv_9107.L3"}),        ("wrong charge", Mode.COPILOT, {"line_id": "inv_9002.L1"}),        ("other customer", Mode.COPILOT, {"line_id": "inv_9311.L1"}),        ("smaller number", Mode.COPILOT, {"line_id": "inv_9107.L1",                                          "amount": 100.00}),    ]    for label, mode, args in cases:        print(f"  {label:<14} {mode.value:<11} "              f"{act('issue_refund', args, Run(mode, 'acct_4417'))}")

Two cases, "other customer" and "smaller number", are proposals the decoder would never produce under a strict enum. They are here because a caller other than the model, or a provider without strict mode, can still send them, and admission has to refuse them on its own.

text
--- narrow signature: account from the channel, line from the model ---  line_id enum sent to the model: inv_9002.L1, inv_9107.L1, inv_9107.L2, inv_9107.L3  wrong line     copilot     ESCALATE gate        960.00 from the ledger, inv_9107.L1  correct        copilot     ALLOW    gate        120.00 from the ledger, inv_9107.L3  correct        queue-drain REFUSE   gate        120.00 from the ledger, inv_9107.L3  wrong charge   copilot     ALLOW    gate        120.00 from the ledger, inv_9002.L1  other customer copilot     REFUSE   admission  line_id=inv_9311.L1: not one of 4 allowed  smaller number copilot     REFUSE   admission  amount is not a parameter of issue_refund

Go back to the five wrong proposals. Writing the transposed account is impossible now: the account is not a parameter, and the other customer's line is not in the enum. No single call can carry the misread 940.00, the 1,200.00 total or the 240.00 for both SSO lines, because no line carries those amounts. Still writable is the 960.00 plan line, and it reaches review at 960.00 read from the ledger. Four of the five wrong proposals are gone from what the model can ask for, and the fifth is thresholded on a number it cannot change.

Narrowing does not remove the "wrong charge" row, and I added it because leaving it out would make the result look cleaner than it is. inv_9002.L1 is this customer's onboarding fee, 120.00, and the duplicate is the SSO line, so refunding the fee is wrong. In copilot, the gate allows it automatically. Narrowing made ownership decidable: the line is this customer's, and the code knows it. It did not make the choice of line decidable. "Which of these four charges is the duplicate" is still the model's judgement.

What changed is the size of that judgement. Under the wide signature, a wrong refund could go to any of about 111 million well-formed account numbers, at any amount up to 2,000.00, and the opening shows one reaching the automatic tier. Under the narrow one, a wrong refund goes to the customer who wrote in, for the amount of a charge they actually paid. Its worst single wrong call is the largest line on the account, 960.00, and the band sends that one to a person.

A second route is closed by the "smaller number" row. Under the wide signature the model writes the number the band reads, so a wrong amount that happens to match an invoice line under 200.00 skips review. An honest mistake is enough for that. Under the narrow signature the amount is not a parameter, and admission refuses the proposal in one dictionary lookup.

Overnight, even the correct refund is refused. That is Part 9's band at work: queue-drain has no refund path at 50.00 or above, so the ticket waits for the morning.

Tool argument validation vs a lookup: what narrowing changes

A narrowed tool is easy to mistake for one that needs fewer checks, and my book warns against that reading. It still needs a check. What changed is the question the check asks.

Under the wide signature, the comparator had to answer "is this amount right for this customer?" Nobody can answer that, so the comparator answered a proxy: is the number on an invoice? Narrowing swaps in a different question: is this charge line on this account? That question is decidable. Its answer sits in the ledger, and it does not depend on who asks or when.

d2
grid-rows: 1
grid-gap: 36
before: "Wide: a proxy" {
  label.near: top-center
  style: {fill: "#FDECEA"; stroke: "#C0392B"; font-color: "#2C2C2A"}
  grid-columns: 1
  q1: "real question:\nis 120.00 right?" {style: {fill: "#E74C3C"; stroke: "#A93226"; font-color: "#FFFFFF"}}
  p1: "asked instead:\nis 120.00 on an invoice?" {style: {fill: "#FFD93D"; stroke: "#C9A800"; font-color: "#2C2C2A"}}
  r1: "acct_4471 also has\na 120.00 line: pass" {style: {fill: "#FFA07A"; stroke: "#D9785A"; font-color: "#2C2C2A"}}
}
after: "Narrow: a lookup" {
  label.near: top-center
  style: {fill: "#EAF7EE"; stroke: "#3F9E52"; font-color: "#2C2C2A"}
  grid-columns: 1
  q2: "question:\nis inv_9107.L3 on acct_4417?" {style: {fill: "#6BCF7F"; stroke: "#3F9E52"; font-color: "#2C2C2A"}}
  p2: "answered by\nthe ledger" {style: {fill: "#4A90E2"; stroke: "#2C6FB0"; font-color: "#FFFFFF"}}
  r2: "one right answer,\nevery time" {style: {fill: "#6BCF7F"; stroke: "#3F9E52"; font-color: "#2C2C2A"}}
}

On the left, the failure lands in the same place as the opening refund. Another customer's invoice can satisfy the proxy, because the value it checks was never tied to this customer. On the right, the question is about the key the model named, checked against the account the channel supplied.

Some lookups are still yours to write. Whether inv_9107.L3 was already refunded is a ledger check the demo does not make, and in production it belongs beside the ownership lookup at act time. Refunding both SSO lines in two calls is also open to the model, and counting refunds per run is a bound, which Part 13 builds.

Count what an LLM agent can ask for: The Expressible Set

An agent can name some actions and not others. That is a separate property from which actions it ought to name and which ones the gate would let through. My book calls this The Expressible Set: the set of actions a model can propose, fixed by the signatures it is given. An action removed from it needs no comparator to judge it, no gate to refuse it, and no bound to catch it, because there is no way to ask for it.

Neighbouring ideas exist, and each one bounds something different. My April post on tool registries named a Closed Action Vocabulary, which bounds which tool names exist. In the Open Worldwide Application Security Project (OWASP) entry on Excessive Agency, LLM06:2025, the advice is to "use extensions with more granular functionality", which bounds which tools you install. Yaron Minsky's rule "Make illegal states unrepresentable" bounds which states a type can hold. Applied to argument values, the same move gives the Expressible Set. It counts the proposals a signature admits, and for each argument it asks one question: could the system have derived this value? Both names in this part, the Expressible Set and Split Declaration, are my book's terms and have no standing as established vocabulary in the field.

What makes the set worth more than a definition is that you can compute two numbers from it before the model runs. One is its size. A second is the worst single wrong call it admits. The wide schema has one too, its 2,000.00 ceiling, but that number belongs to no customer. Once every value the model can write comes from a record, the most a wrong choice can move is the largest record this account has, so a gate band can be checked against what each customer could actually lose. The worst call says nothing about the automatic tier: a wrong refund under the band's automatic limit still goes through, and the wrong-charge row above is the proof.

python
def expressible(spec: ToolSpec, run: Run) -> int | None:    """How many distinct proposals this signature admits for this run."""    total = 1    for p in spec.params:        values = domain(p, run)        if values is None:            return None  # a number or text the model writes: not countable here        total *= len(values)    return totaldef worst_call(spec: ToolSpec, run: Run) -> tuple[Decimal, str]:    """The most one wrong call can move, known before the model runs."""    if spec.consequence is None:        return D("0"), "no consequence declared"    source, name = spec.consequence.split(":")    if source == "model":        return MONEY_RANGE[1], f"any {name} the model writes"    param = next(p for p in spec.params if p.name == name)    if param.type is not ParamType.ID:        return D("0"), f"{name} is not keyed on a record"    costs = {ln.line_id: ln.amount for ln in lines_for(run.account_id)}    if not costs:        return D("0"), "no records on this account"    key = max(domain(param, run), key=lambda k: costs[k])    return costs[key], keydef model_written(registry: dict, kinds=(ParamType.MONEY, ParamType.TEXT)):    return [(s.name, p.name, p.type.value) for s in registry.values()            for p in s.params if s.writes and p.type in kinds]def book_amount_on_invoice(tool: str, args: dict, run: Run) -> Verdict:    """The tag's comparator, reduced to its guard clause. It judges refunds only."""    if tool != "issue_refund":        return Verdict("amount_on_invoice", True, "not a refund")    raise KeyError("amount")  # the narrowed refund has no amount for it to readCHECKS["amount_on_invoice"] = book_amount_on_invoice  # the credit defect, planteddef run_count() -> None:    night = Run(Mode.QUEUE_DRAIN, "acct_4417")    # Hand arithmetic from WIDE_REFUND: acct_ plus 4 to 8 digits, 0.01 to 2000.00    # in steps of multipleOf 0.01. Without multipleOf the amounts are unbounded.    accounts = sum(10 ** n for n in range(4, 9))    amounts = 200_000    print(f"  wide, account from the model:  {accounts * amounts:,}")    print(f"  wide, account from the channel: {amounts:,}")    narrow = expressible(REGISTRY["issue_refund"], night)    print(f"  narrow issue_refund:            {narrow}")    for tool in ("issue_refund", "apply_credit"):        amount, where = worst_call(REGISTRY[tool], night)        print(f"  worst single {tool}: {amount:>8.2f} ({where})")    print("  model-written values into writes:")    for tool, param, kind in model_written(REGISTRY):        print(f"    {tool}.{param} ({kind})")    credit = {"amount": 99.00, "reason": "goodwill"}    print("  apply_credit 99.00 overnight:", act("apply_credit", credit, night))
text
--- how much the model can ask for ---  wide, account from the model:  22,222,000,000,000  wide, account from the channel: 200,000  narrow issue_refund:            4  worst single issue_refund:   960.00 (inv_9107.L1)  worst single apply_credit: 10000.00 (any amount the model writes)  model-written values into writes:    apply_credit.amount (money)    apply_credit.reason (text)    post_ticket_reply.body (text)  apply_credit 99.00 overnight: ALLOW    gate         99.00 from the model's amount

The Expressible Set of the wide refund holds about 22 trillion proposals per ticket, because every account string of four to eight digits pairs with every amount in steps of 0.01. That count is hand arithmetic, and it holds only because WIDE_REFUND declares multipleOf: 0.01, on a provider that accepts it. Without it, the set of well-formed amounts has no limit at all. Taking the account from the channel leaves 200,000. Taking the amount from the ledger leaves 4, and all 4 are lines this customer was actually charged for.

I would put the worst-call line in a design review. For the narrow refund it is 960.00 on inv_9107.L1, and Part 9's copilot band already sends 960.00 to a person, so no single wrong refund on this account can skip review by being large. For the credit it is whatever ceiling you allow the model to write, 10,000.00 here. No record bounds a wrong credit. Only the range in admission and the band do, and the band is the one that decides who sees it.

d2
grid-rows: 3
grid-columns: 2
grid-gap: 20
s1: "account and amount\nfrom the model" {style: {fill: "#E74C3C"; stroke: "#A93226"; font-color: "#FFFFFF"}}
n1: "22,222,000,000,000\nproposals" {style: {fill: "#FDECEA"; stroke: "#C0392B"; font-color: "#2C2C2A"}}
s2: "account from the channel" {style: {fill: "#FFA07A"; stroke: "#D9785A"; font-color: "#2C2C2A"}}
n2: "200,000 proposals" {style: {fill: "#FFF4E5"; stroke: "#D9785A"; font-color: "#2C2C2A"}}
s3: "line from the ledger" {style: {fill: "#6BCF7F"; stroke: "#3F9E52"; font-color: "#2C2C2A"}}
n3: "4 proposals" {style: {fill: "#EAF7EE"; stroke: "#3F9E52"; font-color: "#2C2C2A"}}

Going down one row removes one value the model used to write. The drop from 22 trillion to 4 came from the signature, not from a stronger check after it, and the lookup that remains has one right answer.

The widest tool sets the agent's limit

The Expressible Set is a property of the whole agent. Look at the last line of the output above: that is the leak. apply_credit still takes an amount, and it has to, because no record says what a goodwill credit should be. That number is the model's to write, and overnight the credit band allows anything under 100.00. So a model that cannot shrink a refund can still write a 99.00 credit, and the gate allows it automatically.

Credits also expose a defect I found in my own companion code, checked against the ch10-deterministic-constraints tag itself. Its gate policy requires amount_on_invoice for apply_credit. The comparator at that tag opens with if proposal.tool != "issue_refund": return Verdict(self.emits, True, "not a refund"), so the credit's requirement is met by a check that never reads the credit. The demo's book_amount_on_invoice is my reduction of that comparator to its guard clause, and it returns the same passing verdict on the credit. The startup check below finds it without being told. The requirement stays the same through the ch14-authority-bands tag, and the ch15-testing-the-harness tag replaces it with amounts_grounded. Until then, the gate rule for credits read no verdict that looked at the amount.

d2
grid-rows: 4
grid-columns: 2
grid-gap: 16
h1: "write tool" {style: {fill: "#95A5A6"; stroke: "#6B7B7C"; font-color: "#FFFFFF"; bold: true}}
h2: "what the model writes" {style: {fill: "#95A5A6"; stroke: "#6B7B7C"; font-color: "#FFFFFF"; bold: true}}
t1: "issue_refund" {style: {fill: "#4A90E2"; stroke: "#2C6FB0"; font-color: "#FFFFFF"}}
w1: "a key from 4 ledger lines" {style: {fill: "#6BCF7F"; stroke: "#3F9E52"; font-color: "#2C2C2A"}}
t2: "apply_credit" {style: {fill: "#4A90E2"; stroke: "#2C6FB0"; font-color: "#FFFFFF"}}
w2: "an amount and a reason" {style: {fill: "#E74C3C"; stroke: "#A93226"; font-color: "#FFFFFF"}}
t3: "post_ticket_reply" {style: {fill: "#4A90E2"; stroke: "#2C6FB0"; font-color: "#FFFFFF"}}
w3: "up to 4,000 characters" {style: {fill: "#FFD93D"; stroke: "#C9A800"; font-color: "#2C2C2A"}}

Red marks where the risk in this agent's Expressible Set now sits. Each cell in the right-hand column is a place where the model still chooses a value that matters, which is why model_written is worth printing on every release. Run it in CI and fail the build when the list gets longer without a reviewed change.

Ask one question of every write tool: which of its arguments does your system already hold? A key your records can resolve costs nothing. A number your records could have produced is a signature defect. Free text that lands in a record or in front of a customer has to justify itself. In this agent, issue_refund and close_ticket pass. post_ticket_reply keeps its free text, because somebody has to write the reply. apply_credit keeps its amount, because a goodwill credit has no record behind it.

Tool definition drift inside your own harness: Split Declaration

A narrow refund holds only if every copy of its declaration agrees with it. Count the copies in a normal agent. There is the tool's function signature and the JSON schema sent to the model. There is the paragraph in the system prompt that explains the tools, and the gate policy's own list of tools it has rules for. There is the idempotency table beside the retry code, and the set of tools whose output is marked untrusted. Then there is the set of callables the executor will actually dispatch, and for a third-party server, the annotations it sends about its own tools.

My book calls this Split Declaration: any fact about a tool recorded in more than one artifact, whether its name, parameters, safety, permissions or trust. A split declaration diverges silently, because each copy is valid on its own terms. Failure comes later, in a component that trusted the copy nobody updated. Derivation fixes it, or a check at startup does.

d2
direction: down
row: "ToolSpec row: issue_refund(line_id)" {style: {fill: "#4A90E2"; stroke: "#2C6FB0"; font-color: "#FFFFFF"; bold: true}}
copies: "" {
  grid-rows: 2
  grid-columns: 3
  grid-gap: 16
  style: {fill: "#FFFFFF"; stroke: "#95A5A6"}
  c1: "schema sent\nto the model" {style: {fill: "#6BCF7F"; stroke: "#3F9E52"; font-color: "#2C2C2A"}}
  c2: "admission\nin code" {style: {fill: "#6BCF7F"; stroke: "#3F9E52"; font-color: "#2C2C2A"}}
  c3: "retry safety\n(the book's matrix)" {style: {fill: "#6BCF7F"; stroke: "#3F9E52"; font-color: "#2C2C2A"}}
  c4: "gate policy\ntool list" {style: {fill: "#FFD93D"; stroke: "#C9A800"; font-color: "#2C2C2A"}}
  c5: "prompt paragraph\n(describing)" {style: {fill: "#FFA07A"; stroke: "#D9785A"; font-color: "#2C2C2A"}}
  c6: "callables the\nexecutor dispatches\n(enforcing)" {style: {fill: "#E74C3C"; stroke: "#A93226"; font-color: "#FFFFFF"}}
}
row -> copies

Green copies are derived from the row, so they cannot disagree with it about the tool. The schema can still go stale against the ledger between render and act, which is why consequence re-reads. Yellow marks the gate policy: its key set could be generated from the registry, but its bands answer a different question, who may authorise each tool, and a different owner signs them off, so it is checked rather than derived. The red copy is enforcing and the orange one is describing. In LangChain, the tool objects that build the schema are the ones its tool node executes, so the dispatch copy goes wrong only when something is callable outside the framework's tool list, which is exactly what an exported wrapper is. A framework that renders tools into the prompt renders them from its own tool objects too, and the copy that goes stale is the paragraph someone wrote beside it.

Related names for this idea already exist. Tian Pan calls the backend version manifest drift: "the slow, silent divergence between what your tool descriptions claim and what your endpoints actually do". Gabriel Anhaia describes the prompt half: "The toolset is in code. The prompt is in code. They are not the same code, they are not in the same file, and nothing in your CI fails when one moves without the other." OpenAI's guide tells you to "Avoid JSON schema divergence" by generating the schema from your types. Frameworks already do this for one copy. LangChain builds a tool's input schema from its type hints, and it can hide a runtime parameter from the model entirely.

Those posts describe a tool description diverging from the backend it describes, and a Split Declaration is narrower: two of your own harness artifacts disagreeing about one fact. Frameworks derive the schema, the dispatch table and their own tool rendering from one object. None of the frameworks I read derives the gate policy, the retry table or the paragraph someone wrote beside the tools.

One real case shows the shape. Adobe documents that its "Content (read-only)" Model Context Protocol (MCP) server for Experience Manager exposed write tools: "The Content (read-only) MCP Server exposes write operations because write-enabled tools are included in the MCP Server allowlist." By its name, the server declared one fact about its tools. Its allowlist declared another. Both were valid.

A startup check across the copies

Some copies cannot be derived, and the check for them belongs at startup. Five defects are planted in the demo. A retry path exported quick_refund, a convenience wrapper with no registry row. close_ticket is offered overnight with no rule. A rule for refund_invoice, the tool's old name, is still in the policy. Credit rules require a comparator that never reads credits. And the prompt still teaches the wide signature.

python
class Watched(dict):    """Proposal arguments that remember which keys a comparator read."""    def __init__(self, data: dict) -> None:        super().__init__(data)        self.read: set[str] = set()    def __getitem__(self, key):        self.read.add(key)        return super().__getitem__(key)    def get(self, key, default=None):        self.read.add(key)        return super().get(key, default)    def __contains__(self, key) -> bool:        self.read.add(key)        return super().__contains__(key)    def __iter__(self):        self.read.update(super().keys())  # iterating reads every key        return super().__iter__()    def items(self):        self.read.update(super().keys())        return super().items()    def values(self):        self.read.update(super().keys())        return super().values()    def keys(self):        self.read.update(super().keys())        return super().keys()SAMPLE = {ParamType.ID: "probe", ParamType.ENUM: "probe",          ParamType.MONEY: 1.00, ParamType.TEXT: "probe"}COMPARATORS = CHECKS  # the same map the executor runs, never a second copyPROBE_RUN = Run(Mode.COPILOT, "acct_0000")  # an account with no recordsdef probe(compare, tool: str, spec: ToolSpec) -> bool:    """True when a comparator passes a proposal for this tool without reading it."""    args = Watched({p.name: SAMPLE[p.type] for p in spec.params})    try:        verdict = compare(tool, args, PROBE_RUN)    except Exception:        return False  # it tried to use an argument: not the vacuous shape    return verdict.passed and not args.readDISPATCH = {  # what the executor will actually call, by name    "get_account": ..., "issue_refund": ..., "apply_credit": ...,    "post_ticket_reply": ..., "close_ticket": ...,    "quick_refund": ...,  # added by a retry path; exported with the rest}PROMPT = """You are the billing support agent.Use issue_refund(account_id, amount) when a customer was charged twice.Use apply_credit(amount, reason) for goodwill, never above 100 at night."""def startup_problems(registry, policy, comparators, dispatch, prompt) -> list[str]:    found = []    for name in sorted(set(dispatch) - set(registry)):        found.append(f"{name} is callable and not in the registry: no rule, no scope")    for name in sorted(set(registry) - set(dispatch)):        found.append(f"{name} is in the registry and nothing implements it")    for spec in registry.values():        for mode in spec.modes:            if (spec.name, mode) not in policy:                found.append(f"{spec.name} is offered in {mode.value} with no rule, "                             f"so every call refuses")    for (tool, mode), rule in sorted(policy.items(), key=lambda kv: kv[0][0]):        if tool not in registry or mode not in registry[tool].modes:            found.append(f"rule for {tool} in {mode.value} is dead")        for needed in rule.requires:            compare = comparators.get(needed)            if compare is None:                found.append(f"{tool} in {mode.value} requires {needed}, "                             f"which nothing emits")            elif tool in registry and probe(compare, tool, registry[tool]):                found.append(f"{tool} in {mode.value} requires {needed}, which passed "                             f"a probe {tool} proposal without reading one argument")    for tool, args in re.findall(r"(\w+)\(([^)]*)\)", prompt):        if tool in registry:            said = {a.strip() for a in args.split(",") if a.strip()}            has = {p.name for p in registry[tool].params}            if said != has:                found.append(f"prompt describes {tool}({', '.join(sorted(said))}); "                             f"the registry's takes ({', '.join(sorted(has))})")    return found
text
--- startup check ---  quick_refund is callable and not in the registry: no rule, no scope  close_ticket is offered in queue-drain with no rule, so every call refuses  apply_credit in copilot requires amount_on_invoice, which passed a probe apply_credit    proposal without reading one argument  apply_credit in queue-drain requires amount_on_invoice, which passed a probe    apply_credit proposal without reading one argument  rule for refund_invoice in copilot is dead  prompt describes issue_refund(account_id, amount); the registry's takes (line_id)

Five planted defects produce six lines, because the credit rule is wrong in both modes.

d2
grid-rows: 4
grid-columns: 2
grid-gap: 16
p1: "dispatch table vs registry" {style: {fill: "#7B68EE"; stroke: "#5A4BC4"; font-color: "#FFFFFF"}}
r1: "quick_refund: no rule, no scope" {style: {fill: "#E74C3C"; stroke: "#A93226"; font-color: "#FFFFFF"}}
p2: "gate policy vs registry" {style: {fill: "#7B68EE"; stroke: "#5A4BC4"; font-color: "#FFFFFF"}}
r2: "close_ticket: no overnight rule;\nrefund_invoice rule is dead" {style: {fill: "#FFD93D"; stroke: "#C9A800"; font-color: "#2C2C2A"}}
p3: "rule.requires vs a read probe" {style: {fill: "#7B68EE"; stroke: "#5A4BC4"; font-color: "#FFFFFF"}}
r3: "credit check passes unread" {style: {fill: "#E74C3C"; stroke: "#A93226"; font-color: "#FFFFFF"}}
p4: "prompt prose vs params" {style: {fill: "#7B68EE"; stroke: "#5A4BC4"; font-color: "#FFFFFF"}}
r4: "prompt teaches the old signature" {style: {fill: "#FFA07A"; stroke: "#D9785A"; font-color: "#2C2C2A"}}

Each check compares exactly two artifacts, and no single artifact holds enough to show any of these defects by itself.

My book names the dispatch comparison and does not write it. Its startup check compares the registry with the gate policy, and a callable that never reached the registry is invisible to that check. In this demo, act would refuse quick_refund, because admission looks every tool up in the registry. That protection holds only while every call goes through act. The real paths around it are ordinary: a retry path that calls quick_refund directly, or a tool list built from a module's exported callables, so the framework hands the wrapper to the model and dispatches it without calling act. On either path it inherits nothing: no rule, no comparator, no band and no scope. A test that the executor's callables equal the registry's tools is the assumption every other check in this part rests on.

Policy against registry has to run in both directions. A missing rule refuses every call, which is how the book's agent ended up unable to close a ticket, and here close_ticket would refuse every overnight call. A dead rule is quieter and worse. It reads like coverage in review, and after a rename it guards a tool that no longer exists.

I would add the probe to any harness first, because the defect it finds is invisible everywhere else. Part 3's loop closure asks whether every required verdict is emitted. The probe asks whether the comparator that emits it reads anything from a proposal for this tool. Watched records each key a comparator reads, and probe builds a sample proposal from the tool's own parameters. A comparator with a guard clause, if proposal.tool != "issue_refund": return passed, returns a pass and reads nothing, so every rule that requires it for another tool is flagged. Nobody had to declare which tools the comparator judges. My book's code passes Part 3's test, because the verdict is emitted, and fails this one: through a three-line adapter, the probe flags the tag's real AmountOnInvoice on apply_credit, the same as it flags the demo's reduction. Watched records indexing, get, membership tests, iteration, keys, items and values, so a comparator that reads its arguments in any of those ways is not flagged. The probe has a limit in the other direction: a comparator that reads an argument and then ignores it gets through. It catches the guard-clause shape, which is the one my book's code had. It also flags comparators that judge the run rather than the proposal, such as a business-hours check, and anything required by a tool with no parameters, so allow-list those by name. The demo's comparators take (tool, args, run), a reduction of the book's proposal object, so a real harness needs a small adapter to probe its own.

Prompt against parameters is the crudest check. A regex over the prompt catches issue_refund(account_id, amount) above. It cannot catch intent, so the better fix is to delete the paragraph and render it from the rows.

Generate tool descriptions and dispatch from the registry

Two of the five defects, the stale prompt and the exported wrapper, disappear once those copies are generated from the rows. Generation renders the prompt's tool section from the registry, and the dispatch table refuses to build with a callable that has no row.

python
def render_tools(registry: dict, run: Run) -> str:    """The prompt's tool section, generated from the rows the executor enforces."""    out = []    for spec in registry.values():        if run.mode in spec.modes:            args = ", ".join(p.name for p in spec.params)            out.append(f"{spec.name}({args}): {spec.summary}")    return "\n".join(out)def build_dispatch(registry: dict, impls: dict) -> dict:    extra = set(impls) - set(registry)    if extra:        raise RuntimeError(f"callables with no registry row: {sorted(extra)}")    return {name: impls[name] for name in registry}if __name__ == "__main__":    print("--- wide signature, strict schema, Part 9's band (copilot) ---")    run_wide()    print("\n--- narrow signature: account from the channel, line from the model ---")    run_narrow()    print("\n--- how much the model can ask for ---")    run_count()    print("\n--- startup check ---")    for line in startup_problems(REGISTRY, POLICY, COMPARATORS, DISPATCH, PROMPT):        print(textwrap.fill(line, 88, initial_indent="  ", subsequent_indent="    "))    print("\n--- after deriving the prompt and the dispatch table ---")    print(render_tools(REGISTRY, Run(Mode.QUEUE_DRAIN, "acct_4417")))    try:        build_dispatch(REGISTRY, DISPATCH)    except RuntimeError as e:        print("  build_dispatch:", e)
text
--- after deriving the prompt and the dispatch table ---get_account(): Read the account's plan and invoices.issue_refund(line_id): Refund one charge line to the card that paid it.apply_credit(amount, reason): Add a goodwill credit to the account.post_ticket_reply(body): Post a reply the customer will read.close_ticket(code): Close the ticket with a resolution code.  build_dispatch: callables with no registry row: ['quick_refund']

The helpful prose now lives in each tool's summary field, inside the same row as the parameters it describes. With quick_refund exported, the executor refuses to start. Deriving the prompt does not fix the policy defect, though: close_ticket is still advertised overnight and still refuses every call, until the missing rule is added. My book states the rule this way: "the description the model reads must be generated by the code that does the checking, in the same process, on every run." Chapter 10 of my book makes the same move for the retry-safety table that Chapter 8 kept by hand beside the retry code, the layer Part 8 covered; the demo's ToolSpec leaves those fields out to stay short. An untrusted-output flag belongs on the row as well: Part 2 assigned trust by origin, and the tool is the component that knows where its output came from.

Third-party MCP tools are copies too

A Model Context Protocol server sends its own tool list, descriptions and annotations, and each is a copy of a tool fact written outside your trust boundary. MCP's schema calls every annotation a hint, readOnlyHint included, and says: "Clients should never make tool use decisions based on ToolAnnotations received from untrusted servers." So re-declare each tool you admit in your own row, and treat the server's list as one more input to the startup check, compared per credential, because the specification lets the list "vary by the authorization presented on the request".

d2
grid-rows: 1
grid-gap: 36
server: "What the server sends" {
  label.near: top-center
  style: {fill: "#FFF4E5"; stroke: "#D9785A"; font-color: "#2C2C2A"}
  grid-columns: 1
  s1: "description (prose)" {style: {fill: "#FFA07A"; stroke: "#D9785A"; font-color: "#2C2C2A"}}
  s2: "readOnlyHint: true" {style: {fill: "#FFA07A"; stroke: "#D9785A"; font-color: "#2C2C2A"}}
  s3: "tool list, may change" {style: {fill: "#FFA07A"; stroke: "#D9785A"; font-color: "#2C2C2A"}}
}
mine: "Your registry row" {
  label.near: top-center
  style: {fill: "#EAF7EE"; stroke: "#3F9E52"; font-color: "#2C2C2A"}
  grid-columns: 1
  m1: "summary you wrote" {style: {fill: "#6BCF7F"; stroke: "#3F9E52"; font-color: "#2C2C2A"}}
  m2: "writes, scope, modes" {style: {fill: "#6BCF7F"; stroke: "#3F9E52"; font-color: "#2C2C2A"}}
  m3: "the 4 tools you admit" {style: {fill: "#6BCF7F"; stroke: "#3F9E52"; font-color: "#2C2C2A"}}
}

Your row, in the right column, wins every disagreement. Descriptions get the same treatment: in an undated post, Invariant Labs showed a malicious tool description making an agent send every email to an attacker "even if the user explicitly specifies a different recipient". That recipient was an argument the model wrote, and a recipient derived from the ticket's author leaves the injected sentence nothing to redirect, though an injection can still pick a real value the customer never chose. My book's deep dive on tools you did not write covers the rest.

When narrowing a signature costs you

Narrowing has three costs worth naming before you derive everything.

Per-run enums and the provider limits on strict mode

A derived enum changes from run to run. Anthropic's documentation says its cache "is invalidated if you change the JSON schema structure", and an enum that lists different values per account plausibly counts as a different structure, so expect a per-account enum to pay the grammar compile cost on the first request for each new schema. I have not measured that cost. The larger cost is probably prompt caching. Anthropic's prompt cache is built over a prefix that starts with the tool definitions, so a tool list that changes per account starts a new cache entry for every new account, system prompt included. The second branch of the grid below, a pattern in the schema and the lookup in admission, keeps the tool list the same for every account and is the cache-friendly choice. OpenAI caps a schema at "up to 1000 enum values across all enum properties", which an account with years of invoice lines will reach. Anthropic also warns that structured outputs "don't guarantee the capitalization of string enum and const values". That is one more reason admission checks the same values in code.

When the enum would be too large, keep the parameter an ID and drop the enum from the schema. Then the model can write any well-formed line id, admission refuses the foreign ones, and the Expressible Set is the same set enforced one step later.

d2
grid-rows: 3
grid-columns: 2
grid-gap: 22
q1: "1. Fewer values than\nthe provider's enum cap?" {style: {fill: "#7B68EE"; stroke: "#5A4BC4"; font-color: "#FFFFFF"}}
a1: "yes: strict enum\nplus admission" {style: {fill: "#6BCF7F"; stroke: "#3F9E52"; font-color: "#2C2C2A"}}
q2: "2. Schema changes per run\ncost too much latency?" {style: {fill: "#7B68EE"; stroke: "#5A4BC4"; font-color: "#FFFFFF"}}
a2: "yes: pattern in the schema,\nlookup in admission" {style: {fill: "#4A90E2"; stroke: "#2C6FB0"; font-color: "#FFFFFF"}}
q3: "3. Either way" {style: {fill: "#7B68EE"; stroke: "#5A4BC4"; font-color: "#FFFFFF"}}
a3: "the gate's amount\ncomes from the ledger" {style: {fill: "#6BCF7F"; stroke: "#3F9E52"; font-color: "#2C2C2A"}}
q1 -> q2
q2 -> q3

Whichever way the first two go, the bottom row holds. Where the enum lives is a cost decision, and the source of the gate's number stays fixed either way.

Credential scopes narrow verbs, not values

A tool that runs with a narrow credential is constrained by a system that does not import your code. That makes the scope the strongest constraint you have, for the thing it constrains. Stripe recommends restricted keys for agents: "RAKs are the recommended type of key for API keys you give to AI agents." Their permissions are per resource, set to Read, Write or None. From what those two pages describe, a refund-write key can refund any charge on the account, up to what is left on it. So a scope stops the refund tool from deleting a customer, and it does nothing about which line gets refunded. Use both: the scope for the verb, the signature for the value.

Tools whose name says read and whose effect is a write

A verb is half of a signature, and the registry's writes field is where a wrong one gets recorded. A get_ticket that marks the ticket as seen is declared as a read and gets read-shaped treatment downstream, including a free retry policy. Adobe's manage-aem-fragment-variations shows the opposite failure, one verb covering create, patch, delete, list and get. Chapter 10 has the full naming argument; check each row against what the endpoint actually does.

Narrow the values, then keep one declaration

The hand-written strict schema did its job on every proposal in this part, and it never stopped a wrong refund, because each wrong refund was spelled correctly. What made four of the five impossible to ask for was taking the account and the amount out of the signature, with strict mode then enforcing the narrower schema; under the wide signature they had reached a person only because a check failed or a band caught them, and what bounded the fifth and the wrong-charge refund was that the model could now name only this customer's records, at the amounts they carry. Part 9's Consequence Gating decides who may be wrong about a proposal. A signature decides what the proposal can be wrong about, and it is the cheaper of the two controls, provided every copy of it says the same thing.

Checklist: narrow tool signatures and one declaration per tool

In the order I would do them:

  1. Add the two startup checks first: callables against the registry, and a read probe on every comparator a rule requires. They find defects that exist today, before any signature changes.
  2. For every write tool, list each argument the model supplies and mark the ones your system already holds. Each marked argument is a signature defect: take it from the channel, the run or the ledger.
  3. Narrow to the unit your records refund or change. A whole-invoice refund cannot pay a duplicate line, and a line refund can.
  4. Make the gate's amount come from the records. If the key does not resolve at act time, refuse; never send it to review.
  5. Compute the worst single wrong call from the Expressible Set, before any run, and check that the gate band sends it to a person. Where no record bounds a value, as with a goodwill credit, only the range in admission and the band are left.
  6. Keep the lookup after narrowing, wherever it runs. Here it runs in admission and again as the line_on_account comparator at act time, which is also what records it as a verdict. Add the check you still owe: whether the record is still in a state where the action applies, such as not already refunded.
  7. Generate the schema the model sees and the admission check from one spec. Keep range limits in code for providers that reject them in strict schemas.
  8. Check the rest at startup, in both directions: registry against gate policy, and the prompt against the parameters. Better still, delete the prompt's tool paragraph and render it from the rows.
  9. Print the model-written values into writes (money and free text) on every release, and review every addition to the list.
  10. Re-declare third-party MCP tools in your own registry. Never read their annotations for decisions, and compare their live tool list per credential at startup.
  11. Run each tool with a credential scoped to its verb, and do not mistake the scope for a limit on values.

Tool registries and deterministic constraints: the full chapter

This is Part 10 of a series that follows Harness Engineering for Production AI Systems one chapter at a time. Chapter 10, "Deterministic Constraint Systems," builds the full tool-safety matrix as a TOML file, with a loader that refuses an id with no pattern, an enum with no choices, free text with no limit, and a write tool with no scope. It wires admission and the policy gate into a LangGraph graph in that order, shows how to test the matrix as a file, and covers deprecating a tool without deleting it from the model's memory. In the chapter, the refund narrows to a whole invoice. This part narrows it to a line, because the series' duplicate-charge ticket needs a partial refund. Code for the chapter lives in the ch10-deterministic-constraints tag of the companion repository, and its tests need no model and no API key.

References


AI Security

Agentic AI

Follow for more technical deep dives on AI/ML systems, production engineering, and building real-world applications:


Books by Ranjan Kumar

Federated AI Agents cover

Federated AI Agents

Right-Sized AI cover

Right-Sized AI

Harness Engineering for Production AI Systems cover

Harness Engineering

The 7 GenAI Architectures cover

The 7 GenAI Architectures

Building Real-World Agentic AI Systems with LangGraph cover

Building Real-World Agentic AI Systems

The ChatML Handbook cover

The ChatML Handbook

The Chat Templates Handbook cover

The Chat Templates Handbook

Comments