Deciding what leaves the building
Anything published can say who may reach it and what calling it does:
export default agent({
role: "Review the ledger and flag anything unusual.",
description: "Audits transactions for a named account.",
access: "gated", // open (default) · gated · internal
effect: "read", // read · write (default) · destructive
});internal is the useful one. The agent still exists and your other agents still
use it, it simply never leaves — it is absent from the published list and cannot
be called even by a caller who knows the name, because refusing is not the same
as admitting it is there.
This is worth doing for a reason beyond privacy. A caller shown twenty tools
starts acting where it should have declined, so the smallest honest surface is
also the most accurate one. effect feeds the same judgement: it tells a caller
what a call would cost before it makes it, and an undeclared tool is assumed to
change something.
Both mcp and package will narrow further on request, and packaging says so
when the surface has grown past what a caller can weigh:
praecise mcp --groups workflows # one part of the app, not all of it
praecise package ./dist --read-only # only what changes nothingThe same two narrow the dev server: POST /mcp?groups=workflows&read.
An agent can also say what a catalogue should show about it:
export default agent({
role: "Review the ledger and flag anything unusual.",
description: "Audits transactions for a named account.",
meta: { version: "2.1.0", tags: ["finance", "ledger"], languages: ["en", "pt-BR"], examples: ["Review account 4021 for March."] },
});meta is read by every surface that lists the agent: its skill on the A2A agent
card (where tags replace the group it is published in, and inputModes and
outputModes are stated), its MCP tool's _meta["com.praecise/meta"],
llms.txt and the JSON-LD. It is never shown to a model.
Nothing published can be undescribed. praecise package refuses an app whose
tools say only their own name back, because a caller reads the description and
nothing else before deciding — describe it, or mark it internal if it was
never meant to leave.
Deciding call by call
access and effect settle what an agent may reach for. What it may do with a
particular call is a different question, and a guard.ts at the root answers it:
import { guard } from "@praecise/harness";
export default guard(({ tool, args }) => {
if (tool === "refund" && Number(args.amount) > 500) {
return "A refund over 500 needs a person to approve it.";
}
});Say nothing and the call goes ahead. Say a sentence and it does not — and the sentence goes back to the model as that tool's own result.
That last part is the point. A model told a refund needs approval can say so to the customer and offer to raise it; a model handed an exception can only stop, and the run ends somewhere nobody chose. So write the reason for the model to read, because it will read it. A guard that throws is treated as a refusal too, for the same reason: the app was asked and did not manage to say yes.
A refusal is not counted against the model that asked for it. It says nothing about whether that model was good enough — a stronger one would have been refused in the same place.
After a tool, and before stopping
A guard speaks before a call. hooks.ts at the root speaks at the moments after:
import { hooks } from "@praecise/harness";
export default hooks({
afterTool: ({ tool, result }) => (tool === "lookup" ? { result: withoutCardNumbers(result) } : undefined),
beforeStop: ({ transcript }) => (ranTheTests(transcript) ? undefined : "Run the tests before answering."),
beforeCompact: () => ({ keep: true }),
});Each answers as a guard does: say nothing and what was going to happen happens.
afterTool sees every result before the model does, and may replace it
({ result }) or withhold it with a sentence the model reads instead
({ reject }). beforeStop is asked when an agent answers instead of calling a
tool; a sentence back sends it to work again with that as the reason, three
times in one conversation and no more. beforeCompact is asked before earlier
work is replaced by a summary: { keep: true } forbids the summary and
{ summary } supplies one. beforeRecord decides
what a self is sent.