quern is a Python substrate for trees whose semantics are written in prose, at the node that needs them, while the work is happening. Rules go red on the node that breaks them, and nothing reaches anybody else without the evidence for what it claims.
The claim it rests on: meaning does not have to be formal to be actionable.
Designing anything takes three kinds of knowledge — semantics (what the things mean), models (what must hold between them), solvers (what computes over them). Until now you could write them down cheaply, or you could make them actionable. Not both.
Cheap is a document, a spreadsheet, a wiki. A new column, a new heading, a new paragraph costs seconds and needs nobody's agreement — which is why most of what a team knows lives there. What you cannot do is get anything to act on it. A spreadsheet computes over the numbers and knows nothing about what they are: the column name is a string, the rule you had in mind is a comment or nothing at all, and a figure somebody guessed in a meeting sits in a cell that looks exactly like the one that was measured. It travels perfectly well — a spreadsheet is the most effective thing most organisations have for moving knowledge around — but nothing that arrives with it says whether any of it holds.
Actionable meant formal. Give a machine a schema, a type system, an ontology, and it can validate, infer, compute, and exchange with a team on another continent that never met you. The price is the formalizing: the terms have to be settled before anybody uses one, by whoever owns the definitions, and extending them means going back to that owner and waiting.
The shared model is that second road taken as far as it goes — one ontology, one canonical schema, authored up front and handed to everyone else. Sometimes it works, and it is worth being precise about when. SNOMED CT and the Gene Ontology are maintained by permanent institutions over domains whose subject matter exists independently of any project — a disease and a gene are there whether or not you are modelling them today — and both are load-bearing infrastructure for entire fields.
The failures share the opposite shape, and they are not small. HL7 v3 spent a decade building a canonical Reference Information Model for health information; implementers largely would not adopt it, and FHIR exists because the industry needed something it could actually build against. Cyc spent forty years encoding common sense into one consistent ontology and never reached the general reasoning it was for. The Semantic Web's vision of universal linked ontologies produced, in the end, mostly schema.org — small, pragmatic, and nothing like the plan. In each case the ambition was to finish the vocabulary before the work, and in each case the vocabulary was itself part of what was being worked out.
Not because formalism is wrong — a schema that fits its subject is a gift, and the two above are proof of it. Because formalizing had to come first, and the work is what teaches you the words. You find the distinction that turns out to matter halfway through; you find the rule you should have had just after something has broken for want of it. A vocabulary that must be finished before the work can only be finished before anyone knows what it is for.
What changed is not that meaning got cheaper to write down. It is that meaning no longer has to be formal to be actionable.
A model needs no reduction to structure at all. It reads the sentence a practitioner would have written anyway — something known-unsound, carried deliberately, with its cost stated rather than forgotten — and acts on it: finds the nodes that are one, tells you which of them are unpaid, refuses to let one past a gate. Nothing was formalized. So semantics can be prose, and prose can be partial where the work is partial, provisional where the thinking is provisional, invented on the spot and sharpened the next time somebody reads it.
That is why this substrate interprets none of it. What must be mechanical is kept deliberately narrow — whether a value is grounded, whether a rule holds on a node, whether a package demonstrated its claims, what a digest says — and everything that must be meaningful stays in language, where it can be argued with and rewritten. So semantics, models and solvers are authored on the go, while the design is happening, by the intelligence sitting at the work: not centralized in the heads of the people who once specified the system, and not frozen in its code. Meaning is written at the node that needs it, the moment it is needed, and kept.
That buys a new failure, and it is the obvious objection: cheap local meaning is a thousand private vocabularies that never converge — everyone inventing words, nobody able to read anyone else's tree. The proof gate is the answer to it, and it is the load-bearing part of the design. Local content costs nothing and binds nobody: invent whatever word the work needs. Leaving the local tree costs evidence.
A rule enters a package only if the package's own examples exercise it and pass, and only if a counter-example staged alone makes it fire — because every rule here passes its examples, and so does 1 == 1. A contract enters only if it has been shown answering worked cases, at least two of them expecting different answers, since a gate reading solve(…) == 0 cannot otherwise tell a contract that counts from one that returns zero.
What ships is pinned by digest at an exact version, which answers the other half of how knowledge is shared today. A spreadsheet passed to another team arrives as a copy: no evidence for its rules, and no version anybody can name, so the copy and the original drift apart with nothing anywhere reporting that they have. A pinned package cannot drift silently — the digest either matches or it does not — so adopting one is a fork rather than a negotiation, and the diamond that would force a negotiation is refused at pin time.
So quern does not replace the shared model — it changes what one costs to make and what it costs to be wrong: small, local, provable and disposable, in place of central, permanent and therefore unreachable. Innovation and capitalization become organic by design — every endeavor is a research project that is operative on the go, and the boundary between research and operations disappears, because the model you reason with is the model you run.
Related MCP server: lal
A Quern is a tree of nodes, plus the semantics that give it meaning: a vocabulary saying what each kind of node means, rules that must hold over it, and solvers that compute across it. All three are data — registered at runtime, per tree, by whoever designs there — which is why the code can interpret none of them and be mechanics and safety only.
A node carries a free-text kind, params where every number is a Quantity (its unit, where it came from, and whether it is grounded), named links, an opaque payload, and children.
A vocabulary entry is a name and a paragraph of prose. Nothing parses it.
A rule is one expression in a small safe language, bound to a kind or to a path, which goes red on the exact node that violates it.
A solver is a sandboxed module that proposes values, stamped with the hash of the code that produced them, and never writes the tree itself.
A package is all of that, versioned and pinned by digest — and it can only be published through the proof gate.
That is the whole model. The detail is below; everything between here and there is what it looks like in use.
Four trees that sit about as far apart as they can, each the same three ingredients in different clothes — because the domain supplies the words, and the substrate supplies none of them:
A design ledger. Kinds: decision, debt, hypothesis, gate. Rules: a decision names at least one alternative it rejected; a debt names how it is discharged; nothing unsound passes a gate. This is the tree quern keeps about itself, and the one shown below.
A research notebook. Kinds: thesis, kill-criterion, confirming-signal. Rules: a belief carries at least one observation that would falsify it; a conviction is a probability. Contracts compute over a data window, so a criterion is watched rather than remembered.
A survey of a place. Kinds: space, opening, boundary. Every dimension carries whether it was measured or estimated, so a rule can refuse to let anything be cut against a guess, and contracts solve the geometry the measurements leave under-determined.
A specification of a running system. Kinds: promise, and the evidence that enforces it. Rules: a promise claiming to be proven must name what proves it — so a sheet of claims can be checked against the artifacts underneath instead of believed.
None of those vocabularies is quern's, and the substrate knows nothing of any of them. They are shapes, not products: each is a package of kinds, rules and contracts, authored in its own repository and pinned by digest like any other content.
git clone https://github.com/xag/quern && cd quern && uv syncThe core needs only pydantic and wasmtime. The MCP host and the navigator need one extra: uv sync --extra host.
The tree most projects meet first is a design ledger: the decisions a codebase rests on with the alternatives they rejected, the debts it carries on purpose, the hypotheses still open, and the gates that refuse to go green while a debt is unpaid. Two commands open one, and neither needs any per-project wiring.
quern brief — one line per claim that still binds:
uv run quern brief # the ledger of the current directory
uv run quern brief path/to/projectquern - ledger brief
[decision] native-contracts-bypass-the-sandbox — A package may ship a first-class contract that does not run in wasm {2 alternative}
[debt] a-native-contract-is-unmetered — run_native grants no fuel, no memory cap and no clock !meter {1 discharge}
[debt] a-host-tool-runs-on-the-event-loop — A CPU-bound tool makes the whole host deaf for its duration !concurrency {1 discharge}
[hypothesis] heavy-compute-is-a-proposer-never-a-judge — A contract that is expensive never needs to be authoritative {1 falsification}
...
[gate] the-host-surface — What quern's MCP host exposes to a caller admits->a-native-contract-is-unmetered,a-host-tool-runs-on-the-event-loop RED(nothing-unsound-passes-a-gate)
21 entr(y/ies), ~5546 words of prose.
omitted as no longer current: 1 debt (the tree keeps them; --all shows them).Every marker on a line is read off the node, never annotated by hand. !meter names a param that is not grounded — the unsound value the entry is carrying, and precisely what a gate reads to refuse. admits->… are the node's links, {2 alternative} counts its children by kind, and RED(…) names the rule failing on it.
Superseded entries are counted away rather than printed, with a trailer saying what was omitted; the tree keeps them and --all prints them marked with what superseded them. --fat appends each entry's wordcount and sorts by it, heaviest first — the curation view, where the first line is the first thing to tighten.
A tree can be organised in branches. A kind whose definition says section=True is a heading and not a claim: the brief prints such a node as == algorithms — The algorithms (14 entries, 1 RED) with its entries indented beneath it, sections nest, and --under algorithms briefs one branch alone. The navigator opens the same tree folded by its sections, each with its count and its reds, and buckets by kind inside each. A tree with no section kinds reads as one list, as before.
The reds are the ones the project's check recorded. Running every rule is the slow part of a brief - on a ledger of two thousand rules it took 52 s where building the tree took 1 s - and the check runs them all before every commit anyway, so the check keeps that run: quern.verdicts.record(tree, run_rules(tree), "ledger") writes ledger/verdicts.json (per entry, a digest of what it says and the rules failed on it) and ledger/brief.txt (the brief as text, searchable with no build at all). The brief reads them, marks UNCHECKED an entry whose words changed since, and says its reds are as recorded; --fresh runs every rule, --write FILE writes the brief instead of printing it.
Two ways into one chapter, neither running a rule: quern get <path-or-id> prints an entry in full - its links, params, payload and its children with their reasons - and quern find <words> lists the entries whose path, name or payload carry every word.
A model reads it the same way: tree_brief serves exactly this over MCP, with the same flags. It is the table of contents and tree_get is the chapter — reading a tree by tree_get('') spends its whole history to find the dozen claims that still bind, which is the cost the brief exists to refuse.
quern navigate — the same tree in a browser, read-only:
uv run quern navigate # serves http://localhost:8765 and opens it
uv run quern navigate path/to/projectOutline, kind prose, params with their provenance and grounding, links, and each rule's pass or fail against the node it names. The same view is served in-conversation as an MCP App, where the model browses through exactly the tools you are looking at.
Both rest on one convention, which is the contract of the commands: the project keeps its tree in a package ledger/ — an __init__.py beside a tree.py — and tree.py exposes build() -> Quern that takes no arguments and resolves its own registry. A project whose tree lives elsewhere declares it once, in its pyproject.toml — [tool.quern] ledger = "epure/tree.py:build" — and every command finds it; --module PATH[:ATTR] overrides either for one invocation. The convention is the default, not a requirement.
quern serve — the same tools as an MCP server, over a directory, editable:
pip install "quern[host]"
quern serve # stdio; the tree lives in ./.quern (tree.json + library/)
quern serve path/to/dir --transport streamable-http --port 8000Point any MCP client at it ({"command": "quern", "args": ["serve", "/path/to/dir"]}) and it holds every tree_* verb and the navigator app over an empty tree: define kinds with tree_vocabulary or pin a published vocabulary with tree_package, then author. This is the Workspace every hosted domain otherwise writes by hand, for the case where there is no domain yet — a tree, a client, and a first hour. A Dockerfile at the root builds the same server with the tree under /data.
Checking it is a separate act from reading it, and it is what makes a ledger worth keeping. A project's own gate is an ordinary Python module — quern ships one for itself:
uv run python -m ledger.check # exit 1 while any rule is redThis repo's own ledger is red today, on purpose: the host's compute boundary carries two open debts, recorded as data a gate can see, refusing to call the surface sound until the work is done. A caveat that fires is the pitch.
Author a kind, write a rule — meaning first, as data:
from quern import KindDef, Node, Quantity, Quern, Rule, run_rules
tree = Quern(
vocabulary=[KindDef(kind="task",
description="A piece of work. Params: spent and budget, in hours.")],
rules=[Rule(name="never-over-budget", kind="task",
description="a task's spent hours stay within its budget",
expr="param(self, 'spent') <= param(self, 'budget')")],
)Add a node that violates it, and watch the rule fire — every number is a Quantity carrying its unit, where it came from, and whether it is grounded enough to act on:
tree.root.children = [Node(id="migration", kind="task", params={
"spent": Quantity(value=120, unit="h", provenance="measured", grounded=True,
source="the timesheet"),
# Ungrounded: a figure somebody said, that nobody has checked. It still computes —
# this is the value a gate refuses to let travel, and what `!budget` marks in a brief.
"budget": Quantity(value=100, unit="h", provenance="asserted", grounded=False,
source="quoted in the kickoff, never agreed"),
})]
for r in run_rules(tree):
print(("ok " if r.ok else "RED"), r.rule, "@", r.node)
# RED never-over-budget @ migrationTry to publish it, and watch the proof gate refuse — it asks for referents before anything else: a kind no node is, is a private word, and a rule nothing demonstrates is a claim nobody has to believe:
from quern.library import Library, Package
Library("registry").publish(Package(name="work", version="0.1.0", description="tasks and budgets",
publisher="you", vocabulary=tree.vocabulary,
rules=tree.rules), {})
# ValueError: 1 kind(s) that no example is: task. A word with no referent is what a
# private vocabulary is made of — ship a node that is one, or mark the
# entry `convention=True` if nothing ever should beAdd the demonstration, and the same call publishes — an example the rule passes, and a counter-example it must reject:
from quern.library import CounterExample
agreed = dict(provenance="measured", grounded=True, source="the agreed scope")
Library("registry").publish(Package(
name="work", version="0.1.0", description="tasks and budgets", publisher="you",
vocabulary=tree.vocabulary, rules=tree.rules,
examples=[Node(id="within", kind="task", params={
"spent": Quantity(value=80, unit="h", **agreed),
"budget": Quantity(value=100, unit="h", **agreed),
})],
counter_examples=[CounterExample(
rule="never-over-budget", because="a task that spent more than it was given",
node=Node(id="overrun", kind="task", params={
"spent": Quantity(value=120, unit="h", **agreed),
"budget": Quantity(value=100, unit="h", **agreed),
}))],
), {})
# registry/packages/work/0.1.0.json — versioned, immutable, pinned by digestThat is the whole loop: meaning is authored where the work happens, checked where it stands, and only what demonstrates itself becomes something others can build on.
Vocabulary is checked for the one thing about it that is not prose. What a kind means is judged by a reader and no gate can pretend otherwise — but whether anything in the package is one is mechanical, and that is the failure the gate exists against: a word entering the library with no referent. So every kind must be instantiated by an example, or declare convention=True for an entry that names a namespace its contracts hang prose on. The flag is held both ways — say a kind is a convention and nothing in the package may be one — because an exemption anyone could flip would read as a check while being none.
quern declares its nondeterminism boundary — text on disk, the registry listing, solver blobs, $QUERN_REGISTRY — and writes one small JSONL tape per invocation into .quern/flight/. A tape is that run, compressed: replay it and the real code re-executes with the recorded answers fed back, every internal variable observable.
uv run python -m quern.replay .quern/flight/<tape>.jsonl # what does it hold?
uv run python -m quern.replay .quern/flight/<tape>.jsonl --call 0 # play itSet QUERN_FLIGHT=0 to turn it off. It is on by default because a recorder you have to remember to switch on is a recorder that was off on the run that mattered — and the point of a bug report is that nobody knew it was coming.
Everything above in full. The Quern type is the model — vocabulary, rules, solvers, packages, and a root node tree — a tree of typed-by-data objects with a vocabulary that rules are written against (the pattern BRMS engines call a "Business Object Model"), generalized so semantics are data, not code. The code here is mechanics and safety only; everything that means something is content:
Nodes: free-text kind, params (every number is a Quantity: value, unit, tolerance, a free-text provenance label the domain names, the fixed grounded predicate — is this an observation you may act on? — plus source and derived_from lineage), named links, an opaque payload, children. Path-addressed, partially updatable.
Vocabulary: what kinds mean — prose, registered at runtime, discovered with each node you read (semantics_at). An entry that names a namespace rather than a shape a node can have says convention=True, which publication holds it to. A kind may also declare operations — name → {contract, description, params_doc, medium} — binding it to solver contracts that make sense on it, so every read answers "what is this, what must hold, what can be computed here". Capability attaches to what a node means, as data: nodes get affordances everywhere the kind appears, the tool surface stays closed, and the core never branches on an operation name.
Rules: a tiny safe expression language (no eval). Builtins are structural (param, nodes, params_of, count, sum, len, ctx, superseded, uses, where_used, rollup, tally, the trace verbs before, preceding, following, index, at, parent, the payload read payload(node, 'a.b', default), text containment contains(text, part), the binding forms some(x, xs, cond) / every(x, xs, cond) over a list's elements with field(x, 'a.b', default) to read inside one, arithmetic, comparisons, booleans) plus one bridge to meaning: solve('contract', …).
Expressions (quern.expr): the rule language is also a first-class object. compile_expr(src) parses once into an immutable Expr; Expr.evaluate(rule_env(tree), {"self": path}) runs it against any tree without staging a rule; Expr.reads says what the source names before it runs — the functions it calls, the variables it expects, the literal ctx() keys a caller must supply, and the numbers and strings it carries. Ask for the trace and every call comes back as data (RuleResult.reads under run_rules(…, trace=True)): the function, its arguments, the value it returned — so a red is reported with the values behind it rather than re-derived by whoever reports it.
Solvers: sandboxed WASM (wasmtime: fuel + memory caps, zero imports, no clock/net) that propose — outputs stamped derived with the code hash — and never write the tree. Content-addressed blobs; clients may fetch and run them locally (same artefact, same ABI). The store is medium-general: one artifact://{sha} channel serves wasm (universal compute), web (a self-contained bundle a host renders against a node slice, for the user) and prose (a skill an agent follows with the generic verbs) — the medium is data on the descriptor, and only wasm output may enter the tree as derived. The purity boundary is the point: replayability survives exactly because only the sandboxed, content-addressed medium can propose values. A contract also carries demonstrations — the worked cases it must answer, as data — because a gate reading solve(…) == 0 cannot tell a contract that counts from one that returns zero. A blob's travel in its package; a native's register beside the implementation (register_native(…, spec=…)), since a package must not be able to soften the proof of code it does not ship.
Library: versioned, immutable packages {requires, vocabulary, rules, solvers, examples, counter_examples, demonstrations} — publication is proof-gated, once per kind of knowledge that can be checked. Every kind must be instantiated by an example, or declare itself a convention — a namespace entry, then held to naming nothing. Every rule must be exercised by the package's own examples and pass (with the requires closure staged beneath, so a package proves itself in the semantics it will actually live in) and be refused by a counter-example staged alone. Every executable contract must hold against demonstrations — a tree state, the call, the answer it must give — including two that expect different answers, since one expected number is satisfied by a contract that returns it and computes nothing. A package extends others by requiring them — exact versions only, no ranges, fork-or-republish over resolver algebra — and a Quern pin pulls the whole closure, nearer layers winning; local content always wins over packages. Two versions of one name in a closure is a diamond conflict, refused at pin time.
The roll (quern.roll): every rule runs against the tree as it is now, so no rule can see what was removed. The roll is the smallest artifact that makes absence mechanical — each node's path, kind, and a digest of what it says, committed beside the tree. A vanished entry, a re-kinded one, or one that quietly no longer says what the record said it did is then a fact in the diff rather than a memory. audit is the git-backed gate; compare(tree, previous) is the same three findings against any roll a caller kept, which is what a tree mirroring external objects asks on every refresh.
Host (quern.host, extra quern[host]): registers the generic tree_* MCP tools once over a Workspace — the few seams a domain provides (its live quern, its effective read view, the write guard, persistence, its blob store, its library, its starter vocabulary). One endpoint hosts several domains by resolving a different Workspace per call — same code, separate stores.
Navigator (quern.app_host, same extra): the Quern is the shared context of codesign, so the human needs the same grip on it as the model. register_app(mcp, get_ws) serves it as an MCP App (SEP-1865) — a ui://quern/navigator.html resource plus a tree_app entry tool — and every browse or edit in the UI goes through the same generic tree_* tools the model uses. serve_dev(get_ws) serves the identical HTML on localhost, which is what quern navigate runs. Deliberately not geometric: this is the meaning view, and shapes stay a domain concern.
Domains are authored in their own repositories and travel the registry as data. A domain package may be nothing but vocabulary and rules; it may also carry native implementations of its contracts, registered when its Python is imported — a native is an optimisation of content, never a semantics of its own, and a plain import quern pulls in no domain at all. The one asymmetry is deliberate: the contracts every gate leans on are authored as content like anything else, while their implementations ship here in quern.grounding, because a gate that could be handed its own grounding is not a gate. Meaning is data, safety is code.
The substrate knows nothing of its consumers. A domain lives entirely outside this library — as a package (vocabulary, rules, solvers) plus a Workspace embedding quern — and domain safety invariants stay in that consumer code. ledger@0.6.0, the vocabulary this repo's own brief is written in, is one such package; it is pinned in quern.lock like any other content.
Canonical repo: xag/quern. Depend on it by git rev, never a range; a consumer that vendors it instead (e.g. via git subtree under some <prefix>) syncs with:
git subtree pull --prefix=<prefix> https://github.com/xag/quern main --squashApache-2.0 — see LICENSE.
© 2026 Xavier Grehant
Open the Quern navigator — an interactive view of the tree and its semantics (kinds, params with provenance, links, rules) where the user can browse and coedit. Returns the root slice; the UI then navigates and edits through the same tree_* tools you use.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does disclose the key non-obvious behavior: this opens an interactive UI (a side effect beyond a data read), returns the root slice, and the UI subsequently routes edits through the same tree_* tools. It omits whether the UI requires a live user session, whether it blocks, or what permissions are needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the action and resource, followed by the interaction model. The parenthetical field list (kinds, params with provenance, links, rules) is compact and informative rather than padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists, so return values need not be spelled out, and with zero params the schema needs no explanation. The description covers purpose, return, and cross-tool interaction, leaving only session/permission behavior unstated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate and it correctly introduces no parameter concepts.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
"Open the Quern navigator — an interactive view of the tree and its semantics" gives a concrete verb and resource, and the closing clause clarifies that this launches a UI rather than performing a data operation like the tree_* siblings. The term "Quern navigator" is undefined jargon, and the distinction from siblings is left implicit rather than named.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: the description notes the UI lets the user "browse and coedit," suggesting a human-in-the-loop scenario, but it never states when to choose this over tree_get/tree_find/tree_brief or whether it should be called only on explicit user request. No exclusions or preconditions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The working set — one line per current entry: kind, path, name, the links
it declares, the params still ungrounded, the rules red on it; under headings
where the tree has sections (a kind declared section), under=PATH for one
branch alone.
START HERE on an unfamiliar tree. This is the table of contents and tree_get
is the chapter: reading a tree by tree_get('') costs its whole history to
find the dozen claims that still bind, which is the cost this exists to
refuse. What is settled is counted in a trailer rather than spent on —
all=True shows superseded entries instead of omitting them, fat=True
appends each entry's word count and sorts by it (the curation view: the
first line is the first thing to tighten). Vocabulary-blind, like every
verb here — kinds are labels, and nothing in it knows what a debt is.
| Name | Required | Description | Default |
|---|---|---|---|
| all | No | ||
| fat | No | ||
| under | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does disclose real behavior: settled claims are counted in a trailer rather than emitted, superseded entries are omitted by default, and the output is vocabulary-blind. It never explicitly states that the call is a side-effect-free read, which is the main residual gap for an un-annotated tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It is front-loaded with what the tool returns, then usage, then flags — a sensible order. But the prose is heavily woven and metaphor-laden ('the cost this exists to refuse', 'like every verb here'), and the closing debt remark costs the reader effort for little operational payoff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-required-param read tool with an output schema, the description covers return content, filtering behavior, and the two view flags. Combined with the output schema it is sufficient to invoke correctly; only the absence of an explicit read-only guarantee keeps it from full marks.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate, and it does for all three params: `under=PATH` restricts to one branch, `all=True` substitutes superseded entries for omission, `fat=True` appends word counts and sorts by them. Types and defaults come only from the schema, but the meaning and intent of each flag is fully supplied.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the concrete return shape (one line per current entry: kind, path, name, declared links, ungrounded params, red rules) and explicitly frames the tool as a table of contents against tree_get as the chapter. That distinguishes it from its closest sibling. The metaphor 'the working set' is jargon, but the enumeration that follows grounds it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit entry condition ('START HERE on an unfamiliar tree') and names the alternative it replaces (tree_get('')) together with the reason (reading the whole history to find a dozen binding claims). There is no explicit 'do not use this when X' clause, but the conditional is strong enough for an agent to route correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run every applicable rule at or under path — the domain's data checks.
Structural only; domain summaries (e.g. geometry's bounding box / volume via
tree_measure) are registered by the domain's own tools, not here.
rule narrows the run to the rule(s) named. That is the "is this still
wrong?" question — one rule, one node, asked after doing something about it
— and it costs that rule's reads instead of the whole tree's. Naming a rule
also prints what each evaluation READ: every param, solve, linked and ctx
call with its arguments and the value it returned, so a red arrives with the
values behind it. A name no rule carries is an error, never an empty pass.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | ||
| rule | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description does substantial work: it discloses structural-only scope, that domain summaries are not included, that narrowing by rule changes read cost, that named-rule evaluations print all reads with arguments and returned values, and that an unknown rule name is an error rather than an empty pass. It stops short of explicitly stating whether the operation is read-only or what permissions are required.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and then adds behavioral detail. Some phrasing is dense and rhetorical, such as the 'is this still wrong?' framing and 'a red arrives with the values behind it,' but it remains informative rather than padded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter tool with an output schema, the description covers scope, filtering behavior, structural-only semantics, read-cost implications, and error behavior. Return formatting is appropriately left to the output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description compensates well. It explains `path` as the scope root with checks applying at or under it, and explains `rule` as narrowing execution to one or more named rules, including cost and error semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: run every applicable rule at or under `path` for data checks. It also distinguishes this structural checking tool from domain summary/measurement tools, noting that summaries like tree_measure are registered elsewhere.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a clear use case for the `rule` parameter: asking whether one specific rule is still failing after a fix, and paying only that rule's read cost. It does not explicitly compare against sibling tools like tree_rule or tree_solve, so it lacks full when-not/alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Apply a change-set — [{op: 'set'|'delete', path, node?}] — atomically,
under authoring's one invariant: the committed tree's red set never changes
silently. Green stays green; a set that would CREATE reds is refused whole
(nothing written) and returns them by name; commit deliberately by naming
each in acknowledge — the acknowledgment is recorded on the root. Use
this over bare tree_set when a change should stand or fall with its
consequences; drafts that are legitimately incomplete belong in one
change-set with what completes them.
| Name | Required | Description | Default |
|---|---|---|---|
| changes | Yes | ||
| acknowledge | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so well: it discloses atomicity, all-or-nothing refusal, that nothing is written when refused, that refused reds are returned by name, and that acknowledgments are recorded on the root.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The definition is dense and front-loads the core action and invariant. It is longer than ideal and uses considerable jargon, but nearly every clause contributes useful behavior or routing information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
It covers the mutation behavior, failure mode, acknowledgment mechanism, and sibling routing needed to call it correctly. The remaining gap is that `red`/`green` vocabulary is not fully defined, which may require inference or the sibling vocabulary tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It usefully defines the `changes` item shape (`op: set|delete`, `path`, optional `node`) and explains the `acknowledge` parameter as naming refused reds; only `node` semantics remain thin.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action—applying a change-set atomically to the committed tree—and explicitly differentiates this tool from sibling `tree_set`. It is somewhat reliant on domain jargon (`red set`, `green`), but the core purpose is clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says when to use this instead of `tree_set`: when a change should stand or fall with its consequences. It also gives a concrete alternative case—legitimately incomplete drafts belong in one change-set with what completes them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete the node at path, with its whole branch.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It does disclose the most important trait — that deletion extends to the entire branch, not just the single node — but says nothing about permanence, whether a missing path errors or no-ops, or any confirmation/permission requirements, which are critical for a destructive tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single short sentence with the destructive scope front-loaded and zero filler. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The output schema covers return values, so those need not be explained. However, for a destructive, zero-annotation tool, the description omits irreversibility, error behavior for nonexistent paths, and path format — gaps an agent must resolve before invoking safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for the single `path` string parameter, so the description must compensate. It ties `path` to a node identity, which is marginally useful, but adds no format, syntax, or resolution rules (e.g., slash-delimited vs. opaque id).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Delete') and resource ('the node at `path`') plus the scope of the effect ('with its whole branch'). This clearly distinguishes it from read/write siblings like tree_get and tree_set, though no sibling is named explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives such as tree_set or other mutation siblings, nor any stated preconditions. The only hint of context is the branch-wide scope, which implies a cascading delete but does not say when that is desired or how to avoid it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the Quern instead of walking it — when the user names an element,
locate it in one call. query is a case-insensitive substring over a
node's prose — id, name, kind, meta, every string in its payload and the
sources its params cite — so the external identifier, definition or
field name a user arrives with resolves to its node without knowing the
path; kind/has_param match exactly; links_to finds every node
referencing a path; payload matches payload FIELDS by value —
{"state": "Opened"}, or {"state": ["Opened", "Proposed"]} for any of
several — which is how you scope by state without a substring also
matching the word in a description; under scopes to a branch;
current_only drops nodes another node supersedes (the "what do we hold
now?" query). Returns paths + a one-line summary each; then tree_get the
one you meant. Purely structural.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | ||
| limit | No | ||
| query | No | ||
| under | No | ||
| payload | No | ||
| links_to | No | ||
| has_param | No | ||
| current_only | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and it does disclose return shape ('paths + a one-line summary each') and that matching is 'purely structural'. It implies a non-mutating read but never states side effects, result caps beyond the schema's `limit` default, or what happens with broad matches — modest gaps for an unannotated tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core purpose, then a dense semicolon-delimited parameter tour with no filler sentences. It is a single heavy block, but every clause maps to a distinct parameter behavior rather than restating the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists, yet the description still gives enough return context to chain into tree_get. For an eight-parameter search tool with no annotations, the filter semantics and the follow-up step are both covered; an agent can call this correctly from the description alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate — and it explains seven of the eight parameters with matching semantics (case-insensitive substring scope, exact match for `kind`/`has_param`, reference search for `links_to`, field-value matching plus multi-value arrays for `payload`, branch scoping for `under`, supersession for `current_only`). Only `limit` is left to the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Search the Quern ... locate it in one call') and frames it against the alternative behavior of walking the tree. The closing 'Returns paths + a one-line summary each; then tree_get the one you meant' cleanly separates it from the tree_get sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage conditions are spelled out per filter: `query` for when a user arrives with an identifier or field name, `payload` for state scoping 'without a substring also matching the word in a description', `current_only` for 'what do we hold now?'. It also routes to tree_get when the full node is needed rather than a match summary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the Quern at path (default: whole tree), pruned to depth levels if
given. Each slice arrives with its own semantics: the kinds present (with
the operations they afford — full contract at operation://{kind}/{name}),
the rules that apply, the solvers whose reads cover the slice. A workspace
may expose derived branches (recomputed from their source on every read) —
inspect and link to them, don't edit.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | ||
| depth | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It discloses the read-only nature, slice semantics, and the important behavior that derived branches are recomputed on every read, but it omits permissions, error behavior, and explicit confirmation that ordinary reads never mutate the tree.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose is front-loaded in the first clause, and the paragraph is mostly substantive with little repetition. It is dense with domain jargon and parenthetical asides, but every sentence contributes to invocation or interpretation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so the description need not explain return values in detail, and it does describe the semantics of returned slices. However, for a tool in a large `tree_*` family, it is incomplete on sibling routing and path format, which are important for correct selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does compensate by explaining both parameters: `path` defaults to the whole tree and `depth` prunes the result. It still does not define the expected path syntax or depth limitations, so parameter meaning is only partially fleshed out.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb and resource: 'Read the Quern at `path`', with default whole-tree and optional depth pruning. It clearly describes a read/get operation, but does not explicitly distinguish it from closely named siblings such as `tree_find`, `tree_brief`, or `tree_check`.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It implies usage through the path/depth controls and notes that derived branches should be inspected and linked rather than edited. However, it gives no guidance on when to choose this tool over any of the many `tree_*` alternatives, nor does it state prerequisites or exclusions beyond the derived-branch note.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The semantic package library — capitalized vocabulary, rules and solvers, shared across every account on this server. No arguments: list the library and this workspace's pins. install='name@version' pins a package — its whole dependency closure applies (its requires, transitively), your own entries always winning; a broken closure (missing dep, two versions of one name) is refused at pin time. The pin records the package's content digest, so it keeps meaning these exact semantics even against another library. uninstall removes the pin. publish submits {name, version, description, requires: [{name, version}], vocabulary, rules, solvers: [{name, description, reads, wasm_b64, medium: wasm|web|prose}], examples}. Publishing is proof-gated: every rule must be exercised by the package's own examples and pass — examples run with the requires closure staged beneath, so extending packages prove themselves in the semantics they will live in; every wasm solver must meet the ABI (web/prose artifacts are stored content-addressed, served from artifact://{sha}, never executed). requires pin exact versions of already-published packages. Versions are immutable — ship a new one to evolve.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| install | No | ||
| publish | No | ||
| uninstall | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so well: it discloses transitive dependency-closure resolution, that the caller's own entries always win, that broken closures are refused at pin time, that the pin records a content digest, that publishing is proof-gated with examples run atop the requires closure, and that wasm is ABI-checked while web/prose artifacts are never executed. Missing is any mention of permissions/authorization or what a failed publish/install returns, which keeps it from a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose and the zero-argument behavior are front-loaded, and nearly every sentence conveys a distinct rule. It is dense and flows as long run-on sentences rather than structured mode-by-mode, which slightly blunts scanability for a four-mode tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex multi-mode package tool with an output schema available (so return shapes need no explanation) and no annotations, the description supplies the essential semantics: pinning, closure resolution, precedence, immutability, and proof-gated publishing. The main gap is the undocumented `name` parameter and the absence of any side-effect or permission framing for the mutating modes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It does for install ('name@version'), uninstall, and publish (enumerating name, version, description, requires, vocabulary, rules, solvers with their fields, and examples). However the top-level `name` parameter is never explained, and how multiple arguments interact (e.g., name plus install) is left to inference.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence names the resource concretely (semantic package library of vocabulary, rules, solvers shared across the server) and the rest enumerates distinct operations: list, install, uninstall, publish. An agent can tell this is the package-registry tool rather than the per-artifact tools like tree_vocabulary or tree_solver, though it never explicitly contrasts itself with those siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Mode dispatch is spelled out: no arguments lists the library and this workspace's pins, install='name@version' pins, uninstall removes, publish submits. That is clear guidance on which argument selects which behavior. It stops short of exclusions such as when to use this versus the individual vocabulary/rule/solver tools, or how to combine arguments.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What the tree holds now, as {path, kind, digest} per node — and, given a roll you kept from last time, what changed since.
Every rule runs against the tree as it is, so no rule can see what was
REMOVED: a deleted node is not red, it is absent. The roll is what makes
absence and silent rewriting mechanical. Keep the roll this returns; hand
it back as against on the next read and you get vanished (on the roll,
no longer here), rewritten (still here, still its kind, no longer saying
what it said — the digest covers name, payload and each param's value, and
deliberately not grounding or meta, so re-reading an unchanged record is not
a change) and rekinded (here, under a different kind).
excused spares paths whose removal was intended, and spares their whole
subtree. The comparison is against the roll you hold, never against git —
a gate diffing a committed roll is quern.roll.audit, not this.
| Name | Required | Description | Default |
|---|---|---|---|
| against | No | ||
| excused | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does so richly: it explains that absence rather than color marks removals, defines `vanished`, `rewritten`, and `rekinded`, states exactly what the digest covers and deliberately excludes, and clarifies that comparison is against the held roll rather than git.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and then layers in diff semantics without filler. Despite its density, every sentence contributes useful behavioral or usage context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter diff/snapshot tool with no annotations, an output schema, and no schema descriptions, the description supplies enough context to call it correctly: what it returns, how to chain rolls, what the diff categories mean, and when to use an alternative audit tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain both parameters, and it does: `against` is the roll kept from a prior call, and `excused` spares intended removed paths and their subtrees. It could be slightly more precise about the exact path-matching rules for `excused`, but the semantic meaning is clear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool reads the current tree as {path, kind, digest} per node and optionally compares it against a previously returned roll. It is specific about the resource and operation, but it does not explicitly distinguish itself from sibling read tools such as tree_get or tree_check.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explains the key usage pattern: keep the returned roll and pass it back as `against` on the next read, and use `excused` for intended removals. It also names a when-not case by directing committed-roll gating to `quern.roll.audit`, though it does not broadly compare against most tree_* siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The tree's checks, as data. No arguments: list the rules. With name +
expr: register one — a boolean expression whose builtins are STRUCTURAL only
(param, nodes, params_of, count, sum/len/abs/min/max, ctx, superseded,
unsupported(p, rel) — how many of what p leans on via rel are superseded
or gone, so a rule can ask whether a claim's supports still stand —
uses/where_used, the reuse folds rollup(under, mult, value) /
tally(under, kind, mult) — mult/value name params, data not schema —
the trace verbs over event subtrees: before(a, b) document order,
preceding/following(p, kind?) earlier/later siblings, index(p),
at(parent, i), parent(p) — so a scenario whose children are events is
checkable ('the confirmation email precedes the charge') — and
and/or/not) plus one bridge to meaning: solve('contract', args…), e.g.
solve('geometry/bbox_h', 'pieces/x'). Contracts come from packages. Scope
with kind (per node of that kind; its params + self in scope) or path;
neither = global. Rules run in tree_check; remove deletes one.
| Name | Required | Description | Default |
|---|---|---|---|
| expr | No | ||
| kind | No | ||
| name | No | ||
| path | No | ||
| remove | No | ||
| description | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses key lifecycle behavior: registration, deletion via `remove`, and execution through `tree_check`. However, it does not mention permissions, reversibility, duplicate-name handling, validation behavior, or side effects of registration. The expression-language details add context, but mutation behavior remains only partially transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core modes are front-loaded, but the description becomes a dense single paragraph with a very long parenthetical and nested dashes. The expression-builtin list is useful, but the structure makes it harder to parse than necessary. It is not redundant, but it is not concise or well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex rule-management tool with a custom expression DSL, the description covers the main modes, scoping, expression builtins, and the `tree_check` execution link. The output schema exists, so return values need not be explained. It is still missing the `description` parameter and some mutation-behavior details, but it is largely complete for invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must carry parameter meaning. It explains `name`, `expr`, `kind`, `path`, and `remove` well, including the expr builtins and scoping semantics. It omits any explanation of the `description` parameter, which is a clear gap for a 6-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's modes: with no arguments it lists rules, with name + expr it registers one, and `remove` deletes one. It also distinguishes rule management from execution by noting that rules run in `tree_check`. This is a specific verb-and-resource statement with sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says how to use each mode (no args to list, name + expr to register, remove to delete) and how to scope rules with `kind` or `path`. It also tells the agent that rules run in `tree_check`, giving a clear operational context. It does not explicitly state when not to use the tool or compare it to other siblings beyond `tree_check`.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create or update the node at path (e.g. 'wardrobe/frame'). Fields given
replace those fields; missing intermediates become plain groups. A node:
{kind, name, params: {name: {value, unit, provenance, tolerance, source}},
links: {name: [paths]}, meta, payload, children}. Geometry lives in payload:
{shape: box {size:[w,d,h]} | prism {polygon, height} | cylinder {diameter,
height} | mesh {uri} | union|difference|intersection over children,
transform: {translate:[x,y,z] mm, rotate_z_deg}}. Numeric shape args may
name a param from any ancestor — so a shape written in terms of its params
follows them when they are corrected, and cannot disagree with them.
Declare what a kind MEANS with tree_vocabulary.
The write answers with any rule it broke — on the branch itself or on one that contains it. Treat that as the verdict: it is the same thing tree_check would tell you, said at the moment you caused it.
| Name | Required | Description | Default |
|---|---|---|---|
| node | Yes | ||
| path | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and does well: it discloses partial-update semantics ('Fields given replace those fields'), that missing intermediates become plain groups, and that the write returns rule violations as a verdict. It does not mention permission or auth requirements, a minor gap for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose is front-loaded and every section (node shape, geometry, param references, validation verdict) earns its place given the nested data model. It is dense and merges several concerns with inline braces, but the length is largely justified by the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a nested two-parameter tool with an output schema already covering returns, the description supplies the structural and semantic detail needed to build a valid node. It leaves some fields (meta, payload, links) under-explained relative to geometry, but is broadly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the `node` object is a bare additionalProperties map, so the description must compensate — and it does, defining the node shape (kind, name, params, links, meta, payload, children) and the geometry payload formats. The `path` parameter gets only an example, not format rules, keeping it from a 5.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence states a specific verb ('Create or update') and resource ('the node at `path`') with a concrete path example, so the agent knows exactly what it does. It also distinguishes from siblings by naming tree_vocabulary for declaring kind meaning and tree_check as the equivalent validation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear context: create-or-update semantics, use tree_vocabulary to declare a kind's meaning, and that the write's returned rules are equivalent to tree_check. It does not explicitly state when NOT to use it versus other write-ish siblings like tree_app or tree_commit, so it stops short of full alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a registered solver on a branch it may read — sandboxed wasm, or a
native contract a package ships (native contracts see the effective tree;
wasm sees only the slice at path). Returns diagnostics and proposals —
each proposal carries a ready-to-apply Quantity stamped provenance='derived'
with the solver's identity, so a computed number is distinguishable from a
measured one. Nothing is written: apply the proposals you accept with
tree_set. Clients may instead fetch a wasm module at solver:// and run
the same ABI locally.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| path | No | ||
| params | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations available, the description carries the full behavioral burden and does so thoroughly. It discloses sandboxing, the different read scopes of native contracts versus wasm modules, the diagnostic/proposal return shape, provenance stamping, and the crucial fact that nothing is written. It also states how accepted proposals should be applied via tree_set.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core operation and then layers in only useful distinctions: sandboxing, visibility scope, return shape, write behavior, and the local-execution alternative. Every sentence adds information, and the parenthetical about native versus wasm read scope is compact and relevant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema, so the description need not fully explain return values, but it still helpfully summarizes diagnostics and proposals. It covers the operation's side effects and apply-via-tree_set workflow well. The main remaining gap is that `params` is not explained despite 0% schema description coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description needs to compensate. It explains `path` by noting that wasm sees only the slice at that path, and `name` is implicitly the registered solver name. However, the important `params` object is never described, so a caller cannot tell what solver-specific parameters are expected or how they are interpreted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: run a registered solver on a branch it may read. It explains the two solver kinds and contrasts native-contract visibility with wasm visibility at `path`. It also distinguishes the operation from writing by stating that proposals must be applied with tree_set.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context: the solver must be registered, it may read a branch, and the operation produces proposals rather than writes. It names tree_set as the alternative for applying accepted proposals and mentions fetching the wasm module to run locally. It does not explicitly state when to prefer local execution over this tool, but the alternatives are concrete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The tree's artifacts, as data — capabilities you submit, stored by
content hash and served from artifact://{sha}. No arguments: list them.
With name + wasm_b64 (base64 of the content, whatever the medium): register
one. medium says what the content is — 'wasm' (default): sandboxed
compute; ABI: export 'memory', 'alloc(len)->ptr',
'run(ptr,len)->(ptr<<32|len)'; input JSON {path, slice, params}; output
{diagnostics:[str], proposals:[{path, param, value, note?}]}; run it with
tree_solve (fuel + memory only: no filesystem, network or imports), and it
never writes the tree — it proposes, you apply with tree_set. 'web': a
self-contained HTML/JS bundle a host renders against a node slice, for the
user. 'prose': instructions an agent follows with the generic verbs. Only
wasm output may enter the tree as derived — the other media serve
experience and guidance, never values. reads declares the only branch
prefixes wasm may see.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| reads | No | ||
| medium | No | wasm | |
| remove | No | ||
| wasm_b64 | No | ||
| params_doc | No | ||
| description | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description does real work: it discloses the sandbox profile (fuel + memory only, no filesystem/network/imports), the ABI contract, that wasm never writes the tree and only proposes, and that only wasm output may become derived tree values. These are exactly the traits an agent cannot get from the schema. It omits the semantics of `remove` (whether it is destructive or gated).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The content is dense and useful, but a single run-on block mixes registration, medium taxonomy, ABI, input/output shapes, sandbox rules, and read scoping with no structure. The load-bearing call modes are buried mid-paragraph rather than front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is an output schema, so return values need not be explained, and the ABI/output shape is still spelled out helpfully. But with 7 parameters at 0% coverage and no annotations, leaving `remove`, `params_doc`, and `description` undefined leaves real gaps an agent must guess at before calling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% across 7 parameters, so the description must compensate. It explains name, wasm_b64, medium (with the three enum-like values wasm/web/prose) and reads (branch prefixes wasm may see), but never mentions remove, params_doc, or description. Four of seven parameters are covered, so it only partly fills the gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
It names the resource precisely (tree artifacts stored by content hash, served from artifact://{sha}) and implicitly gives two verbs: list with no arguments, register with name + wasm_b64. It also distinguishes itself from tree_solve, which runs the artifact. The purpose is clear, but the opening clause 'The tree's artifacts, as data' delays the actual operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit call modes ('No arguments: list them', 'With name + wasm_b64 ... register one') and points to tree_solve for execution and tree_set for applying proposals. That is genuine when-to-use routing. However, it never covers the removal path even though a `remove` parameter exists.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The tree's semantics, as data. No arguments: list every kind defined
(stored + pinned packages + the domain's starter kinds). With kind +
description: define or refine what that kind means, and optionally what its
params/links stand for and what operations it affords — name:
{contract, description, params_doc, medium}, binding the kind to a solver
contract that makes sense on it (fetch the full contract at
operation://{kind}/{name}, execute with tree_solve). Nothing branches on
kinds — they mean exactly what this vocabulary says.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | ||
| links | No | ||
| params | No | ||
| operations | No | ||
| description | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, so the description carries the full burden. It discloses that kind definitions are pure data with no branching behavior and explains the solver-contract binding format, which is genuinely useful. However, it says nothing about mutation semantics: whether redefining a kind overwrites prior definitions, who may do it, or whether existing bindings are preserved.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the core concept ('The tree's semantics, as data') and wastes no sentences, but the body is a dense run-on relying on em dashes and semicolons that makes the two modes harder to parse than they need to be. It would benefit from explicit mode separation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be explained. Given five undocumented parameters and a write-capable path with no annotations, the description covers the shape of the calls but leaves the consequences of defining/refining a kind under-specified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description has to compensate and it partially does: kind, description, params, links, and operations are each mentioned with a role, and the operations shape (name: {contract, description, params_doc, medium}) is spelled out. But 'what its params/links stand for' is the only treatment of two of the five parameters, so the map is thin for a 5-param tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource: it is the vocabulary of kinds, with two clear arg-driven modes (list vs. define/refine). It names related artifacts (operation://{kind}/{name}, tree_solve) but doesn't explicitly distinguish itself from sibling tree_rule / tree_package, which likely also deal with kind semantics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The when-to-use is encoded cleanly by argument presence: no arguments = list everything; kind + description = define/refine. It also tells the agent that execution happens via tree_solve rather than here. What's missing is an explicit statement of when NOT to use this (e.g., vs. tree_rule or tree_package).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.2tree_apptree_brieftree_checktree_committree_deletetree_findtree_gettree_packagetree_rolltree_ruletree_settree_solvetree_solvertree_vocabularyScored across 14 tools
Most verbs have distinct purposes, and the descriptions sharply separate read modes (tree_get, tree_brief, tree_find, tree_roll) from write modes (tree_set, tree_commit). However, tree_solver versus tree_solve and the adjacent semantic tools (tree_vocabulary, tree_rule, tree_solver, tree_package) could cause brief hesitation.
All 14 tools consistently use the tree_ prefix plus a snake_case verb/noun, e.g. tree_get, tree_set, tree_commit, tree_vocabulary. The convention is predictable across reads, writes, checks, and semantic operations.
Fourteen tools are well-scoped for a rich tree workspace covering CRUD, search, validation, atomic commits, semantics, solvers, packages, and UI. Each tool maps to a distinct operational layer without feeling padded.
The surface covers the core lifecycle: read/search, create/update/delete, validation, atomic commit, semantic vocabulary/rules, solvers, and package sharing. Minor gaps exist around explicit move/rename/copy or import/export operations, though these can be approximated with existing set/delete and package tools.
Provenance-first database for teams and agents: every value carries sources, rules and coverage.
Author rules from policy docs, then decide: a Rete engine gives the verdict, an LLM explains why.
Governed decision engine: yes/no, score, choice and rank answers about cases, from past outcomes.
Zero-trust logic judge: your AI writes a claim as a ZFL table, the ZTL core judges it.