Inspect before you call

An agent composing a busy-week meal plan reaches for GenerateCandidates. Two packages exist: a general-week generator and a constrained-week variant tuned for low-effort evenings. The agent picks the general one because it ranked higher in a fuzzy embedding search. Tuesday's plan fails practicality review. Cost spent. Trust spent. The right package was one metadata read away.

Helpful context: Libraries of cognition packages judgments. A contract, not a prompt defines what inspect returns. Least trustworthy input wins explains why wrong substitution poisons downstream trust. This page is the API design rule: inspect, then call. It applies Principle 25 to library design: the invoke path is sealed, but the selection path must be legible.

What inspect must expose

Inspect reads a manifest, the way reading an OpenAPI spec precedes a POST. Dry-runs execute cognition and spend tokens. Inspect reads what the organisation already published about the package without running judgment.

Field class	Why callers need it
Contract	Decision sentence, inputs, outputs, abstain/refer
Authority	Grants required, side effects, escalation paths
Eval history	Suite scores, regression status, calibration age
Applicability	Terrain guards, known failure modes, fallback hints
Operational profile	Cost, latency, purity level, owner
Substitution	Compatible versions, contract hash, rollback notes

Missing manifest fields are not "minimal inspect." They are unpublished packages pretending to be library entries. Platforms that hard-fail invocation when the manifest is incomplete prevent callers from inheriting prompt archaeology.

Caller needInspect manifestMatch applicabilityInvoke contract

Inspect selects the package. Invocation performs the judgment.

Tie to the trust chain

Wrong package selection is a trust failure at the hole, because the least trustworthy input shapes everything downstream. If the agent invokes the general-week generator on a constrained busy week, every subsequent cognitive unit receives candidates tuned for the wrong terrain. AssessMealPracticality may still run correctly on each candidate, but the plan fails anyway because the candidate set was wrong for the week.

Inspectability is how autonomous callers avoid substituting the wrong judgment while believing they reused org knowledge. It is also how human architects audit agent behaviour without reading chain-of-thought: inspect logs show which package matched which applicability flags.

Agents are not exempt from this discipline. A meta-agent proposing an arrangement inspects before recommending packages. A composing agent choosing mid-run inspects when terrain shifts, because busy week versus dinner party week is not the same catalog row. Working state changes. Applicability must be re-checked.

Inspect versus search

Sealed, evaluated, searchable covers catalog queries that return candidate packages. Inspect covers deep read on one chosen entry before invoke. The flow moves from search to shortlist to inspect to invoke, not from search directly to invoke.

Search answers "what exists?" Inspect answers "is this one fit for this run?" Both depend on metadata, not template bodies. The distinction matters because skipping the inspect step lets the caller trust the search ranking alone, and search rankings reflect keyword or embedding similarity rather than applicability for the current terrain.

What this looks like in practice

In the Meal Companion, before invoking GenerateCandidates, the agent inspects. Applicability requires an interpreted week with evening labels, and the constrained variant requires two or more low-time evenings flagged. Authority is read household knowledge with no purchase grants. Eval shows a grader floor on variety for four-person weeks with regression green on the current train. Substitution confirms v2.1 compatibility with v2.0 contract for callers on meal schema v3. Limitations note the package is not for medical diet interpretation. Busy week detected in working state, and the agent selects GenerateCandidates/constrained-week instead of the general package. No prompt archaeology. No embedding guess.

The invoice intake parallel works the same way. Before a field interpretation cognitive unit run, inspect confirms PO-matching mode versus accrual mode, which carry different authority and different suites. Mixing them posts silently wrong totals. Inspect catches mode mismatch before invocation.

For the organisational library, before AskTargetedQuestion, inspect confirms materiality policy version and authority to interrupt the household. Products share the package. Inspect confirms they share the same policy, not a forked prompt variant.

API shape

Platforms implement inspect as first-class infrastructure. A manifest endpoint returns a JSON contract summary, eval snapshot, semantic version, owner, limitations, and substitution notes, callable without model spend. Catalog search provides metadata filters returning entry IDs and summary fields, as sealed and searchable describes. Hard failure on missing manifest means unpublished or incomplete packages are not callable, because silent fallback to "best effort" invites rediscovery. An inspect audit log records which caller inspected which package, which applicability flags matched, and which version was invoked, supporting incident review and compliance without exposing sealed innards.

Debug grants may expose additional implementation detail for maintainers. Default inspect remains contract-level, consistent with encapsulation. Debug views that expose template bodies belong behind explicit debug grants, not in default catalog browse. Teams that expose innards for convenience teach callers to depend on prose rather than manifests.

Inspect for humans and agents

Human engineers inspect during integration and incident review. Autonomous agents inspect during loop iterations. The manifest schema serves both with structured fields, not prose essays.

The Meal Planning Agent runs inspect at predictable points: after InterpretWeek when evening labels change applicability, before first GenerateCandidates invoke, when critique flags a weakness that might change repair package choice, and before AskTargetedQuestion when authority gaps appear. Each inspect is cheap relative to wrong invoke. Loop budget accounts for manifest reads because they are not optional overhead.

Agents treat inspect as mandatory when terrain flags change mid-loop (busy evenings added, allergy bridged), when library version updates since the last iteration, when composing from multiple shelves (domain cognitive units library plus judge library), and when authority grants change in working state. Skipping inspect saves milliseconds. Wrong-package invocation costs dollars and trust.

Connection to rediscovery

Callers that skip inspect inherit do not rediscover known work violations. They rewrite in prompts what the library already packaged because they never read the manifest. Rediscovery is often a symptom of missing inspect discipline, not missing catalog entries. The inspect endpoint makes the alternative concrete: read what was published before deciding to write something new.

Common mistakes

The most frequent error is an "inspect" endpoint that actually runs judgment. Teams expose "preview" endpoints that call the model, but that is expensive, non-deterministic selection, not inspect. Manifests without applicability are a close second: the contract is readable but terrain guards are missing, so callers invoke on unfit cases. Missing substitution fields mean callers cannot tell v2.1 from v2.0 compatibility before invoke. Inspect bypass for "trusted" agents assumes trust per agent name rather than earning it per selection.

Inspect latency and caching

Manifest reads stay sub-second in a well-designed system. Slow inspect endpoints push agents to skip inspect and guess. Platform teams cache manifest payloads with semantic-versioning-aware invalidation so inspect stays cheap enough to run every loop iteration that needs it.

Working state can cache inspect results with semantic version pins. When the library publishes a new version, the cache invalidates and inspect re-runs. Stale manifest cache is another form of silent drift: substitution without re-inspect. Cached manifests work like cached dependencies, convenient until the version moves.

Inspect audit trails matter for regulated workflows. Logging inspect reads with package identity, semantic version, applicability match result, and caller context lets operators answer why an agent invoked v2.1 instead of v2.0 without reading chat transcripts. Inspect logs also reveal search gaps when agents repeatedly inspect then bypass library invoke.

What to do next

Every library publish path benefits from an inspect endpoint, because no publish is complete without a manifest. Teaching agents to inspect when terrain flags change mid-loop makes the discipline operational. Logging inspect decisions for audit, capturing which package and which applicability match, supports incident review. Pairing inspect with substitution rules ensures version swaps stay contract-safe. Hard-failing invoke on incomplete manifests prevents unpublished packages from being rewarded with production traffic.

See Skill library versus cognitive unit library when inspect must distinguish inventory types, substitution rules for version compatibility, and do not rediscover known work for the anti-pattern inspect prevents.

Read next: Do not rediscover known work.