The hypotree server provides a persistent, self-revising hypothesis DAG for agentic R&D, backed by SQLite, with an ATMS-style belief engine for automated inference and experiment management.
Hypothesis Management: Create and manage hypotheses (individually or in batches) with parent dependencies, exclusion groups, goal flags, and parametric configurations. List, filter, sort, and paginate nodes; manually update statuses when needed.
Experiment Navigation & Leasing: Get the next hypothesis to test via Thompson sampling (Beta-distribution), with lease reservation to avoid duplicate work. Renew, release, or list active leases.
Evidence Recording & Inference: Record experimental results (success/failure, metrics, notes) to trigger automatic write-back propagation: cascading pruning of dependent subtrees, exhaustion of mutually exclusive alternatives, verification by elimination, invalidation/verification upstream along refinement chains.
Conflict Resolution: Detect unresolved conflicts (integration failures) and suggest discriminating experiments to isolate culprits via differential ablation.
Visualization & Context: Retrieve bounded subgraphs with credible intervals, render Mermaid flowcharts, get detailed evidence history, check goal status and progress, and inspect workspace connectivity.
Learning & Reporting: Generate a chronological learning path narrating what was settled, distinguishing experiment-paid conclusions from inferred ones, and highlighting withdrawn beliefs.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@hypotree What should I test next?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A persistent, self-revising hypothesis DAG for agentic R&D — exposed as an MCP server and a Python API.
Current agent memory is passive: vector stores and scratchpads accumulate facts but never revise them. Hypotree structures the agent's working knowledge as a directed acyclic graph of hypotheses backed by SQLite-WAL. When an experiment fails, the engine walks the dependency edges and retracts what rested on it. When a premise collapses, every dependent subtree is pruned automatically.
Write-back belief revision — an ATMS-style engine (de Kleer, 1986) that propagates evidence failures upstream through the dependency graph.
Cascading prune — invalidating a parent hypothesis instantly transitions its entire subtree to PRUNED. No tokens spent on dead branches.
Exclusion-group inference — confirming one member of a mutually exclusive group retires the rest as EXHAUSTED without probing them.
Deduction by elimination — last-man-standing: when all but one alternative in an exclusion group are refuted, the survivor is VERIFIED without a probe.
Backward pruning over a complete question — the dual of the above: when every candidate answer to a question is ruled out on its own evidence, nothing that assumes one of them can be satisfied, so those branches are PRUNED and the navigator names the question that ran out.
The closed-world assumption is declared, not assumed. Both inferences above are sound only if the listed answers are all the answers. exclusion_closed=False says they are not — "which learning rate?" always admits another — and the engine then withholds both. And when a deduction it did draw turns out to rest on an incomplete list, it is withdrawn rather than defended: the node goes back on the frontier and one probe settles which premise was wrong.
Thompson Sampling navigation — Beta-distribution sampling over the open frontier, giving bounded worst-case regret (no catastrophic lock-in).
Conflict resolution via differential ablation — when an integration test fails but every component passes alone, the engine rebuilds the failing combination one swap at a time to pinpoint the culprit.
A derivation trail, not just a state — generate_learning_path narrates what was settled, in order, separating what an experiment paid for from what the engine inferred for free, and calling out beliefs that were later withdrawn.
Persistent across sessions, models, agents, users, and projects — the belief state is a SQLite database, not a context window.
Related MCP server: Mnemograph
Everything here is on by default and covered by the pre-registered benchmark.
Feature | What it is for |
Write-back belief revision | An experiment that fails does not just get logged — the engine walks the dependency edges and retracts what rested on it. This is the thing passive memory cannot do. |
Cascading prune | Invalidating a premise transitions its whole subtree to |
Exclusion-group inference | Declare competing answers to one question; confirming one retires the rest without probing them. In the benchmark this is where most of the saving comes from — 342 questions closed for free in the latest run. |
Deduction by elimination | Rule out all but one candidate and the survivor is confirmed with no probe at all. |
Backward pruning over a dead question | The dual: when every candidate answer is ruled out on its own evidence, nothing that assumes one of them can be satisfied, and the navigator names the question that ran out instead of reporting an empty frontier. |
A declared closed-world assumption | Both inferences above are sound only if your list of answers is complete. |
Conflict sets and differential ablation | When components pass alone but fail together, the engine records what cannot all hold and narrows it by rebuilding the combination one swap at a time. Each swap is decisive; m assumptions cost at most m probes. |
Confirmation depth | "It passed the unit test" and "it works in production" are different claims. A confirmation supports nothing tested deeper than itself, and blame lands only on assumptions confirmed shallower than the failure. |
What would change my mind | For any goal, the cheapest experiments that would overturn its current conclusion, weakest evidence first. A belief confirmed by elimination ranks top however confident the posterior is — nothing ever measured it. Available as a tool, and as a dashboard panel. |
Learning-path diff |
|
Thompson Sampling navigation | Beta sampling over the open frontier: bounded worst-case regret and no catastrophic lock-in. Seeded, so a run is reproducible. |
Goal scoping |
|
Bi-temporal history | Every status and posterior change is stored as an interval, so "what did we believe on Tuesday" is a |
Live read-only dashboard | Runs beside the MCP server by default. Watch the graph grow, replay any instant, read the narrative typeset. Nothing on it writes evidence. |
Leases for long-running work | A dispatched node is reserved until you report it. |
Batch-native everywhere |
|
Off by default, and staying off until a full evaluation with a live model has scored them. Behaviour with the flag absent is bit-identical to a build that has never heard of the feature.
Feature | Status |
Cost-aware selection ( | Ranks candidates by expected value per unit cost instead of by promise alone, using the |
Why the saving exists, since it is not obvious: the last surviving answer to a closed question is deduced rather than probed, so whichever answer you never reach is never paid for. Ordering cheapest-first puts the expensive answer in that free slot. Probe count barely moves — the winner's position is uniform, so any order settles a question in the same expected number of probes — while probe cost falls a long way.
A belief state that revises itself is hard to appreciate from a status column. The dashboard runs by default, beside the MCP server, so the graph is already there the first time you look for it:
That is a real run. Nodes arrive as the agent creates them and glow at their actual chance of being dispatched next; confirmed answers turn green and their rivals retire without ever being probed; a refuted premise takes its subtree with it. Optional 128-character titles keep large graphs readable while preserving stable ids in details. Goal progress names pending dependencies, evidence can be filtered and paged with attestation and trend context, and dedicated conflict and live-claim views expose why work is blocked or leased. The layout remains usable on compact screens by stacking the narrative and graph. The bar along the bottom is the run's own activity — drag it and the whole graph rewinds to what was believed at that moment, narrative included.
Nothing on that page writes evidence. If a belief moved, an experiment moved it.
# From PyPI
uvx hypotree
# or
pip install hypotree
# From source
git clone https://github.com/tygryso/hypotree.git
cd hypotree
uv syncRequires: Python 3.10+ · Runs on: Linux, macOS, Windows
Check the install without wiring up a client — the server speaks JSON-RPC on stdin, so starting it in a terminal otherwise looks like a hang:
hypotree --version # or: uvx hypotree --version
hypotree --info # which belief state am I connected to, and where is it?Add hypotree to your MCP client config (Cursor, Cline, Claude Desktop, etc.):
{
"mcpServers": {
"hypotree": {
"command": "uvx",
"args": ["hypotree"],
"env": {
"HYPOTREE_WORKSPACE_ID": "my-project"
}
}
}
}Or run directly:
uvx hypotreeTo view a database owned by an embedding host without workspace resolution or an MCP server:
uv run hypotree --no-mcp --db-path /path/to/state.dbHYPOTREE_DB_PATH provides the same override.
If your agent is Python, it does not need a transport to reach the belief state. HypoTreeToolset hands you OpenAI function-calling schemas and executes calls by name:
from hypotree import HypoTreeToolset
with HypoTreeToolset("beliefs.db", preset="essential") as ht:
tools = ht.tools() # drop straight into your `tools=` argument
result = ht.call("get_next_targets", {"count": 1}) # returns a JSON stringBoth paths project the same schemas through the same dispatch, so the embedded surface and the MCP surface cannot drift apart.
Three things worth knowing:
preset="essential" exposes the six tools that run the loop instead of all twenty. Most clients re-send every schema on every turn, and an agent that already carries its own forty tools cannot also carry twenty of ours.
ht.mutating_tool_names is the set that changes the belief state — what to put behind an approval or reasoning gate. get_next_targets is in it: it reads like a query and it issues leases, so it writes.
ht.call never raises. A bad node id or a malformed argument dict comes back as {"error": ...}, because those are recoverable by the model that caused them and killing the session over one is not.
Pass read_only=True for a reviewer or an untrusted sub-agent: it exposes the eleven sensors and refuses every write, including by name if the model asks for one it was not given.
Embedded hosts can keep state in their own isolated storage namespace and later launch
hypotree --no-mcp --db-path .../state.dbwithout copying it into hypotree's global workspace resolver.
The agent creates a tree with parent_ids wiring combinations to their premises and exclusion_group declaring competing answers to one question:
# Agent calls over MCP:
create_hypotheses(hypotheses=[
{"node_id": "catalyst_A", "statement": "Pd/C catalyst works", "exclusion_group": "catalyst"},
{"node_id": "catalyst_B", "statement": "Pt catalyst works", "exclusion_group": "catalyst"},
{"node_id": "catalyst_C", "statement": "Ni catalyst works", "exclusion_group": "catalyst"},
# Enumerable question → closed by default, so eliminating two confirms the third.
# For "which learning rate?" pass exclusion_closed=False: there is always another,
# and the engine then refuses to deduce a survivor it cannot justify.
{"node_id": "yield_target", "statement": "reach 90% yield",
"is_goal": True, "target_metric": 0.9, "parent_ids": ["catalyst_A"]},
])# Probe catalyst_A → fails outright, catalyst_B → fails outright.
# Two experiments, one call:
record_evidence(results=[
{"node_id": "catalyst_A", "success": 0.0},
{"node_id": "catalyst_B", "success": 0.0},
])
# Engine: catalyst_A, catalyst_B → INVALIDATED; anything depending on them → PRUNED
# catalyst_C → VERIFIED by elimination — no probe spentgenerate_learning_path()
# → markdown briefing + counters:
# probes_spent = 2, conclusions = 3, conclusions_without_a_probe = 1Additionally, you can start the server with these flags:
hypotree # MCP server + dashboard on 127.0.0.1:7331
hypotree --dashboard-port 8080 # start probing from a port you choose
hypotree --no-dashboard # MCP server only, no socket opened
hypotree --no-mcp # dashboard alone, against an existing belief state
hypotree --experimental-cost-aware # rank by value per unit of probe cost (see Experimental features)It binds 127.0.0.1 only and mints a session token at startup; the URL, token included, goes to stderr (stdout is the JSON-RPC channel). Ask the agent for it instead — get_workspace_info returns dashboard_url, and so does the hypotree://dashboard resource. If no port in the range is free the MCP server still starts and says so: a viewer must never be able to take the server down.
--no-mcp opens the database read-only, so it is safe to point at a workspace an agent is actively writing — and it needs no client configured to try.
What you get:
A live graph. Nodes are laid out server-side with networkx and rendered as SVG with d3-zoom for hardware-accelerated pan and zoom. Untested nodes glow at their real chance of being dispatched next; in-progress nodes pulse; pruned branches desaturate instead of disappearing, because the point being shown is that they were considered and cut.
New nodes fade in. When the agent creates a hypothesis, it arrives as a ghost and resolves — you watch the search grow without touching the page.
An activity timeline. status_history is bi-temporal, so any past instant is a WHERE clause. The bar chart is the shape of the run — where the bursts were, where it stalled — and the handle travels along it. Drag back to see what was believed then, or press play and watch the whole investigation replay.
Provenance on every card. What each belief cost: the score, the depth, the commit, the source_ref, any files the experiment left behind, when it was created and when it settled. The graph is a ledger, not a drawing.
The learning path as typeset markdown, ready to paste into a report — and it rewinds with the graph, so a rewound picture is never captioned with conclusions it has not reached.
Pin and suspend. Redirect the search without faking evidence — directives change what is offered, never what is believed.
Everything is vendored (Vue 3, d3 micromodules, marked — 276 KB total). No CDN, no npm, no build step: it works on a plane and in an air-gapped network.
The API is JSON and every /api/* call needs the token. Everything is a read except one route — pin and suspend are scheduling instructions, and they never touch a posterior:
Route | What it returns |
| workspace identity and the goal list |
| nodes and edges with server-computed layout; |
| one node's evidence, provenance and status intervals |
| the top candidates and how likely the navigator is to pick each next |
| the beliefs holding a conclusion up on the least evidence, and what would overturn each |
| the narrative, same as the MCP tool; |
| every status change in order |
| server-sent revision numbers — the client refetches what it is showing |
| pin / suspend / clear (the only write, and only when an engine is attached) |
p_select is the real thing, not a proxy: Thompson Sampling picks the argmax of one draw per candidate, so the number is how often each candidate wins that draw.
Exposed over MCP, and in OpenAI function-calling form via hypotree.openai_tools() — one set of schemas, two projections. The six marked · make up preset="essential", the smallest surface that can still run the loop.
Tool | What it does |
| Create one or many nodes with |
| Wire hypotheses that already exist, without recreating either. Takes |
| Thompson Sampling — returns the next hypothesis to test, under a lease. |
| Record one result — or every result from a turn at once with |
| What we learned, in order, and what it cost — separates conclusions an experiment paid for from ones the engine inferred free. |
| Which belief state you are connected to and which layer chose it — start here when the graph is unexpectedly empty |
| Manually set node status (rarely needed — the engine does it) |
| Get a subgraph view for the agent's context window |
| Mermaid.js diagram of the current belief state |
| Check whether the goal node is met. |
| List unresolved conflicts (integration failures) |
| For a conflict, suggest the swap that separates the culprits |
| Name the cheapest experiments that would overturn a goal's current conclusion, weakest evidence first |
| List/filter nodes by status, depth, or exclusion group |
| Full evidence trail for a node |
| List nodes with active leases |
| Extend a lease on a node |
| Release one or all leases |
| Revert |
| Propagate confirmation up the dependency chain |
The server ships three MCP prompts. Clients that support them (Cursor, Claude Desktop, Cline) surface them as slash commands, so a human can steer the loop without retyping the protocol — and, more usefully, without the agent paraphrasing it.
Command | What it does |
| Create the goal node and the first 3–5 hypotheses under it, with exclusion groups where the hypotheses are competing answers to one question |
| Get the next target, actually test it, and record the result against that same node — including what to do for each DONE reason |
| Brief you on what is established, what was ruled out, what changed, and how many conclusions cost no experiment |
/hypotree-init takes an optional task argument. Exact invocation depends on the client (Cursor and Claude Desktop namespace prompts under the server, e.g. /hypotree:hypotree-init).
Three MCP resources, pulled on demand rather than carried in context:
URI | What it is |
| The full agent contract — every tool, the status lifecycle, exclusion groups, leases, confirmation depth, conflict sets, and the rules. ~23 KB, so it belongs nowhere near a system prompt |
| The current belief state as a narrative: what was established, how, and what it cost |
| Where a human can watch this belief state move, token included — so the agent can answer "send me the link" without you going near a terminal |
For agents written in Python, MCP is a process boundary and a JSON round-trip between two objects in the same interpreter. Import them instead:
from hypotree import HypoTreeToolset, HypoTreeEngine, openai_toolsWhat | Why you'd reach for it |
| The whole surface: |
| Add the tool surface to an engine you already hold. Does not take over its lifecycle |
| Just the schemas, if you route calls yourself |
| Typed Pydantic results instead of JSON strings |
Selection is composable — start from a preset and narrow:
openai_tools(preset="essential") # the 6 that run the loop
openai_tools(read_only=True) # the 11 sensors, no writes
openai_tools(preset="essential", exclude=["add_edges"])Every tool also carries the metadata a host needs and no JSON schema can express:
from hypotree import TOOL_SPECS
{s.name for s in TOOL_SPECS if s.mutates} # gate these
{s.name for s in TOOL_SPECS if s.essential} # ship these when context is tightThe whole integration is three touch points: build the tool list once, execute by name, close on the way out. Everything else your loop already does.
from hypotree import HypoTreeToolset
belief = HypoTreeToolset(session_dir / "beliefs.db", preset="essential")
try:
tools = my_own_tools() + belief.tools()
while not done:
reply = llm.chat(messages, tools=tools)
for call in reply.tool_calls:
if call.name in belief.tool_names:
# Your gate, your policy — hypotree only tells you which calls
# are consequential.
if belief.is_mutation(call.name) and not gate.open:
result = "Belief writes are gated; think first."
else:
result = belief.call(call.name, call.arguments)
else:
result = my_dispatch(call)
messages.append(tool_result(call, result))
finally:
belief.close()Four things that are easy to get wrong and cheap to get right:
Point the database at storage that survives the session, not at the working directory. The belief state outliving the run is the entire feature; a path under a git worktree forks it the first time you switch branches.
Open the session by reading what is already known. generate_learning_path is in the essential preset for a measured reason: across three full evaluation runs the agent called it after a context reset exactly zero times, and every redundant probe in those runs followed a reset.
Do not charge belief writes against a code-mutation budget. Recording what you learned is not the work. An agent that runs low on budget and stops writing down its findings loses the memory exactly when it is worth most.
call never raises. A bad node id comes back as {"error": …}, so the loop can hand it straight to the model and let it correct itself rather than dying on a typo.
Pass read_only=True for anything that should observe without writing — a reviewer, a monitoring pass, an untrusted sub-agent. It exposes the eleven sensors and refuses every write, including by name if the model asks for one it was never given.
Testing an integration costs nothing: the engine runs against a temporary SQLite file in milliseconds, so the full create → dispatch → record → conclude loop is a unit test, not an inference bill.
The operating contract reaches the model through four channels. You do not have to wire any of them up; they are listed so you know what is already in context and what is not.
Server instructions. MCP hands a server-level instructions block to the client during initialize, and every major client puts it in front of the model. Hypotree uses it for four rules: one hypothesis per node, mark the goal with is_goal=True and wire it to the work, record against the node you actually tested, and report what you were leased. Nothing to configure.
Tool descriptions. Each tool description carries the one rule that tool is misused without — that a goal never accepts evidence, that a lease reserves a node until you report it, that confirming one member of an exclusion group retires the rest. These are the only text guaranteed to be in context at the moment a tool is chosen.
Resources. The full guide is hypotree://guide. An agent that hits something surprising can read it without you pasting 23 KB into a system prompt. hypotree://dashboard hands over the live link.
Your project rules file — optional, and the only part you touch. If you want the agent to reach for hypotree unprompted on multi-day work, add the block below.
.cursorrules / AGENTS.md / CLAUDE.md## Long-running R&D: use hypotree
For any task that spans more than one session, branches into competing
approaches, or where an early assumption could turn out wrong later, keep the
belief state in hypotree rather than in the conversation.
- Before starting, call `generate_learning_path`. Something may already be
settled, and re-deriving it costs an experiment you do not have to run.
- Create the objective with `is_goal=True` and wire hypotheses to it with
`parent_ids`. Progress is then derived, not asserted.
- Competing answers to one question share an `exclusion_group`. Confirming one
retires the rest without testing them — this is where most of the saving is.
If the list could always grow ("which learning rate?"), add
`exclusion_closed: false` so the engine does not deduce a survivor it cannot
justify.
- Ask `get_next_targets` for work and record every result you were handed. A
target is leased to you; anything you hold and never report is work nobody
can do. Probed several things in one turn? Report them in one call with
`record_evidence(results=[...])`.
- Record against the node whose statement you actually tested. A composition's
failure filed against a premise destroys a confirmation that is still true.
- When `get_next_targets` returns DONE, read the reason. Only `all_goals_met`
and `empty_frontier` mean stop; the rest are instructions. `dead_question`
means one of your questions ran out of candidate answers — add the one you
have not thought of to the same `exclusion_group`.┌──────────────────────────┐ ┌──────────────────────────┐
│ MCP Client (agent) │ │ Python agent (in-proc) │
│ Cursor / Cline / Claude │ │ HypoTreeToolset │
└────────────┬─────────────┘ └────────────┬─────────────┘
│ MCP (stdio/HTTP) │ direct call
┌────────────▼─────────────┐ │
│ hypotree MCP server │ │
└────────────┬─────────────┘ │
│ │
┌────────────▼──────────────────────────────▼─────────────┐
│ toolkit — 20 tool specs + dispatch (no transport) │
│ one description of the contract; both paths project it │
└────────────────────────┬────────────────────────────────┘
┌────────────────────────▼────────────────────────────────┐
│ Engine │
│ • Write-back propagation • Cascading prune │
│ • Exclusion-group inference • Differential ablation │
│ • Thompson Sampling navigator │
└────────────────────────┬────────────────────────────────┘
┌────────────────────────▼────────────────────────────────┐
│ SQLite-WAL │
│ • Bi-temporal history │
│ • Belief state + evidence + conflicts │
│ • Keyed by workspace_id │
└─────────────────────────────────────────────────────────┘The toolkit layer is the reason the two entry points cannot drift: neither owns the schemas, and neither owns the routing.
Hypotree is validated by a pre-registered adversarial benchmark using qwen3.6:27b-q8_0 and gemma4:31b-it-q4_K_M. The benchmark is a set of 30 seeded combinatorial R&D problems, each with 3125 combinations (5 axes × 5 values). Each arm is run on all seeds, and the gate criteria are scored against the pre-registered thresholds.
Three arms across 30 seeded combinatorial R&D problems:
Arm A — LLM agent with a manual Markdown scratchpad (ergonomic floor)
Arm F — LLM agent with perfect-recall auto-transcript (steel-man baseline)
Arm B — LLM agent on the full hypotree DAG belief state
The moat is inferential, not mnemonic. Arm F remembered every raw fact it ever saw — zero duplicate probes across the whole run — and still lost 30/0/0, because hypotree closes questions it never has to ask: 329 exclusion inferences, 37 answers deduced without a probe, 12 values eliminated by a swap that fell short. None of those is something you can look up.
# Pre-flight: confirm the engine solves every seed (no GPU)
uv run python -m eval.runner.engine_selfplay
# Pre-flight: score the cost-aware falsifier on a cost-weighted tariff (no GPU)
uv run python -m eval.cost_gate
# Full gate: 30 seeds × 3 arms
./eval.sh --run-iteration <X> --llm-model <model>The eval harness lives in eval/ and includes the frozen landscape generators, the agent runner, and the gate scorer. Run artifacts are gitignored (eval/runs/).
eval.sh is bash — on Windows, run it under WSL or Git Bash. The Python parts of the harness (engine_selfplay, runner, analyse_gate, seed_reader) are cross-platform and can be driven directly.
The belief-state database is isolated by workspace. Four resolution layers, highest priority first:
HYPOTREE_WORKSPACE_ID env var — an explicit name. Use this for global MCP configs, where the server's working directory is not your project.
hypotree.yaml — copy hypotree.yaml.template to your project root:
workspace_id: my-project-nameGit remote hash — SSH and HTTPS spellings of one remote resolve to the same id.
Project path hash — the fallback, and the weakest: it changes if the project moves or is mounted differently.
Layer 4 is where nearly every "my belief state is empty" report comes from. Run hypotree --info, or have the agent call get_workspace_info, to see which layer actually fired:
$ hypotree --info
{
"workspace_id": "d94da5f61c664f94",
"resolved_from": "git_remote",
"database": "/home/you/.local/share/mcp_hypotree/d94da5f61c664f94/state.db",
"database_exists": true,
"warnings": []
}Workspace names are lowercase [a-z0-9._~-], up to 128 characters.
Platform | Location |
Linux / macOS |
|
Windows |
|
XDG_DATA_HOME overrides on every platform, Windows included — that is how you run isolated instances side by side.
Keep it on a local disk. SQLite runs in WAL mode, which needs shared memory that network shares and most mapped drives do not provide. Pointing
XDG_DATA_HOMEat a UNC path or a mounted share will fail or corrupt the database.hypotree --infowarns when it detects one.
Everything but eval.sh runs natively; the evaluation harness is a bash script and needs WSL or Git Bash.
Git is optional. Without it on PATH, layers 3 and 4 both fall through to the path hash — pin the workspace with layer 1 or 2 instead.
# Install in dev mode
uv sync
# Run tests
uv run pytest tests/ -x -q
# Lint + format
uv run ruff check src/ tests/ eval/
uv run ruff format src/ tests/ eval/
# Type check
uv run mypy src/hypotree/MIT — Copyright © 2026 Damian Borowski
GitHub: github.com/tygryso/hypotree
Changelog: CHANGELOG.md — version history with gate results
Agent guide: src/hypotree/AGENT_GUIDE.md — the full contract, also served live as the hypotree://guide MCP resource
Wire hypotheses that already exist, without recreating either. Use it to grow a graph forward: when a pipeline gains a stage, the goal must depend on the NEW last stage, or it reports itself achieved as soon as the first stage verifies while the rest sit untested. You do not need to remove the old edge — DEPENDENCY is AND and the later stage already depends on the earlier one, so adding only tightens the condition. Validated like creation: unknown nodes, a goal used as a DEPENDENCY parent, and cycles are refused before anything is written, and an edge that already exists is a no-op.
| Name | Required | Description | Default |
|---|---|---|---|
| edges | Yes | Edges to add. Each runs FROM the hypothesis being assumed TO the one assuming it, so src is the parent. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description thoroughly discloses validation behavior (unknown nodes, goal as parent, cycles refused before writing, existing edge no-op) and the semantic nuance that adding a dependency edge tightens the condition due to AND logic. With no annotations provided, the description carried the full transparency burden and did so comprehensively.
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 consists of three sentences, each serving a distinct purpose: core action, usage scenario, and behavioral/validation details. It is front-loaded with the primary verb and resource and avoids redundant phrasing.
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 mutation tool with no annotations and no output schema, the description covers purpose, usage, validation, and idempotency, which is strong. It lacks an explicit statement about the success return value, but the behavioral details (no-op on existing edge, refusal on invalid input) give the agent sufficient expectations.
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 100%, so parameters are already well-documented with direction and type. The description adds context about pipeline dependencies and edge direction but does not elaborate on the 'type' enum or parameter format beyond what the schema provides. Baseline 3 is appropriate.
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 opens with 'Wire hypotheses that already exist, without recreating either,' clearly identifying the action (adding edges) and the resource (existing hypotheses). It distinguishes itself from creation tools like create_hypotheses by explicitly stating no recreation. The 'grow a graph forward' phrase adds specificity about the intended use.
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 provides a concrete scenario—when a pipeline gains a stage and the goal must depend on the new last stage—and explains the AND semantics for not needing to remove old edges. It implicitly contrasts with creation by saying 'without recreating either,' but does not explicitly name alternative tools or a when-not-to-use case, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one or many hypothesis nodes (with optional parent edges). Pass a list of one to create a single hypothesis. Parents may be created by the same call in any order. The whole batch is validated before anything is written, so a rejected call creates nothing.
| Name | Required | Description | Default |
|---|---|---|---|
| hypotheses | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden and does usefully disclose batch atomicity: 'The whole batch is validated before anything is written, so a rejected call creates nothing.' It also reveals dependency handling ('Parents may be created by the same call in any order'). This is solid but does not cover permissions, reversibility, or return behavior.
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?
Three sentences, front-loaded with the core purpose, and every sentence earns its place: what it adds, how to express a single creation, and the safety-relevant atomicity guarantee. No redundant phrasing or filler.
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 creation tool with nested policies (if_exists, is_goal, exclusion groups) and no output schema, the description covers the core operation and atomicity but omits return shape and decision points not already in the schema. The schema's field descriptions help compensate, so this is adequate but not fully 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?
The description adds useful parameter-level meaning beyond the raw schema: it explains list cardinality ('Pass a list of one') and parent-edge ordering behavior. The schema itself already contains rich nested descriptions for fields like is_goal, if_exists, parent_ids, and exclusion_group, so the description does not need to repeat them, though top-level schema coverage is low.
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 starts with a specific verb and resource: 'Add one or many hypothesis nodes (with optional parent edges).' It clearly distinguishes this from sibling tools like add_edges by scoping the action to creating hypothesis nodes, and clarifies the one-or-many behavior.
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 operational guidance like 'Pass a list of one to create a single hypothesis' and notes that parent edges can be included in the same call, implying when this tool is useful. However, it never explicitly contrasts with sibling tools such as add_edges or states when NOT to use it, so guidance is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Narrate what has been settled so far, in order, and how — separating what an experiment paid for from what the engine inferred for free, and calling out beliefs that were later withdrawn. Use it to brief a human, to write a summary, or to re-orient yourself after a context reset: the other read tools show the current state, this one shows how it was arrived at. Pass since to get a diff instead — what changed between then and now, which is the answer a standup or a PR description wants.
| Name | Required | Description | Default |
|---|---|---|---|
| as_of | No | ISO-8601 instant. Reconstruct the report as it stood then, so it can be read beside a rewound graph. | |
| limit | No | Cap on narrated transitions (most recent first). Counters always cover the whole history. | |
| since | No | ISO-8601 instant. Report only what settled or was withdrawn since then — 'what changed this week' rather than 'how we got here'. Combine with as_of for a closed window. | |
| goal_id | No | Narrate one objective only. A workspace pursuing several otherwise interleaves their dead ends into one story. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses important behavioral traits: separating experiment-paid facts from engine-inferred ones, calling out withdrawn beliefs, and clarifying that it shows provenance rather than current state (implying a read-only operation).
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 two sentences with the main action front-loaded. The second sentence is long but packs in use cases and a parameter note without wasted words. It could be slightly more structured, but it remains efficient.
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?
Given no output schema and no annotations, the description covers purpose, use cases, and key parameter behavior thoroughly. It does not specify the return format, but for a narration tool this is likely prose and not a critical omission.
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?
All 4 parameters have schema descriptions (100% coverage), so the baseline is 3. The description adds extra meaning for `since` by framing it as 'a diff' and tailoring it to standup/PR needs, going beyond the schema. Other parameters rely on schema, which is adequate.
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 the specific verb 'Narrate' and clearly defines the resource: what has been settled, in order, and how. It distinguishes itself from sibling tools by noting that 'the other read tools show the current state, this one shows how it was arrived at'.
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?
Explicitly states when to use the tool: 'to brief a human, to write a summary, or to re-orient yourself after a context reset'. It contrasts with alternatives ('other read tools') and gives a specific use case for `since` as a diff for standups or PR descriptions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return live (unconsumed, unexpired) claims for resuming work.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the filtering behavior ('unconsumed, unexpired') and implies a read-only operation via 'Return'. For a tool with no parameters and no side effects mentioned, this is reasonably transparent, though it doesn't describe error scenarios or the return envelope.
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 a single sentence, front-loads the verb and object, and every word earns its place. No fluff or repetition; it states what it returns, the filter criteria, and the purpose in a compact form.
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?
Given no parameters, no output schema, and a simple read-like behavior, the description is sufficient. It explains the tool's core function and filter criteria. The presence of sibling tools like renew_claim and release_claims fills in the broader context of what 'claims' are, so the description doesn't need to define the domain.
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 input schema has zero parameters, so there is nothing to explain. The baseline for 0 parameters is 4, and the description adds no extraneous parameter info. It correctly focuses on the tool's semantics instead.
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 ('Return') and resource ('live claims') with precise qualifications ('unconsumed, unexpired') and a clear purpose ('for resuming work'). This distinguishes it from siblings like renew_claim or release_claims, which handle different aspects of claim management.
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 phrase 'for resuming work' clearly implies the use case: fetching current active claims when a user wants to pick up where they left off. While it does not explicitly name alternatives or exclusions, the context is unambiguous enough for an agent to select this tool over renew_claim or release_claims.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List recorded conflicts — sets of assumptions that cannot all hold together, with which members are exonerated and which remain suspects.
| Name | Required | Description | Default |
|---|---|---|---|
| open_only | No | Only conflicts whose culprit is not yet pinned. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full transparency burden. It goes beyond a simple imperative by explaining the output structure (which members are exonerated vs. suspects) and implies a read-only operation via 'List'. This provides meaningful behavioral context, though it stops short of disclosing details like ordering or pagination, which would be nice but are not critical for a simple list 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?
The description is a single, efficiently written sentence. It opens with the action ('List recorded conflicts') and follows with a clarifying clause. No redundant words or filler, making it concise and 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?
Given the tool's simplicity (1 optional parameter, no output schema, no annotations), the description provides sufficient context. It explains the concept of conflicts and hints at the return content. It could mention that it only lists open conflicts by default, but that is covered in the schema, so the overall package is reasonably 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?
The input schema already fully describes the sole parameter (open_only) with a clear description. The tool description does not add any further meaning about the parameter, so it does not need to compensate. Baseline 3 is appropriate since schema coverage is 100%.
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 function ('List recorded conflicts') and provides a precise definition of what a conflict is ('sets of assumptions that cannot all hold together'). It also distinguishes this tool from siblings by focusing on conflicts and their outcome (exonerated vs. suspects), making its purpose unambiguous.
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 offers no guidance on when to use this tool versus alternatives like get_active_claims or suggest_discriminating_experiment. It does not mention any prerequisites or scenarios where this tool is preferred, nor does it exclude cases where other tools would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return a depth+width-bounded subgraph with credible intervals.
| Name | Required | Description | Default |
|---|---|---|---|
| node_id | No | ||
| max_depth | No | ||
| max_children | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden for behavioral disclosure. It only states the return value, but does not mention that this is a read-only operation (though implied), nor does it explain the nature of 'credible intervals' or any side effects/limitations.
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 a single concise sentence that front-loads the key action and bounds without unnecessary words. 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?
There is no output schema, so the description should explain the return format and semantics. It does not define 'credible intervals' or what nodes/edges are included, leaving significant ambiguity for an agent without prior context.
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 description maps 'depth+width-bounded' to max_depth and max_children, giving them meaning. However, node_id is not explicitly explained, and with 0% schema coverage, it does not fully compensate for all parameter details such as defaults or how the bounds are applied.
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 identifies the action (Return), the resource (subgraph), and the specific parameters (depth+width-bounded) that distinguish it from sibling tools like render_dag_map or list_nodes. The mention of credible intervals adds further specificity.
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 implies usage for retrieving a local, bounded view of a DAG around a node, which is distinct from siblings like get_conflicts or generate_learning_path. However, it does not explicitly state when to use this tool over alternatives or any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the evidence trail for a node (newest-first).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No | ||
| node_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses the ordering behavior ('newest-first') and implies a read-only operation via 'return', but it does not specify pagination semantics, error handling, or any access requirements. These gaps are moderate for a read 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?
The description is a single, front-loaded sentence that directly states the tool's purpose and ordering without unnecessary words. It is concise and 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?
The tool has 3 parameters with 0% schema coverage and no output schema, so the description must provide context. It states the primary action and ordering but omits return format, pagination behavior, and parameter roles, leaving significant gaps for an agent to invoke correctly.
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 not explain any of the three parameters (node_id, limit, offset). It only mentions 'node' generically, failing to compensate for the lack of schema descriptions.
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 ('return') and resource ('evidence trail for a node'), and adds ordering information ('newest-first'), clearly distinguishing it from sibling tools like get_active_claims or get_conflicts. It precisely states what the tool does.
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 provides no guidance on when to use this tool versus alternatives, such as when to audit evidence history versus viewing active claims or conflicts. There is no mention of prerequisites, use cases, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report all goal nodes, target metrics, progress counts, and whether the global stop holds.
| Name | Required | Description | Default |
|---|---|---|---|
| goal_id | No | Report on one objective and count only the nodes forming its case. Omit for every goal in the workspace. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full transparency burden. It fails to state whether the tool is read-only, what permissions are required, or any side effects. It only lists output contents without behavioral caveats.
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 a single concise sentence that starts with the action verb and enumerates the four report components. Every word contributes meaning, with no redundancy or filler.
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?
With no output schema, the description gives a reasonable idea of the report contents but does not explain the response structure, error cases, or whether the report includes all goals by default versus the optional filtering. It is adequate but lacks depth for a tool with zero annotations.
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 100% with a clear description for goal_id explaining the filtering behavior and default scope. The tool description itself adds no param-specific details, but the schema already provides sufficient semantics, so baseline 3 is appropriate.
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 the specific verb 'Report' and enumerates the exact resources: goal nodes, target metrics, progress counts, and global stop status. This clearly distinguishes it from sibling tools like get_workspace_info or list_nodes by focusing on goal-level status tracking.
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 implies usage for checking goal status but does not provide explicit when/when-not guidance or mention alternatives. The schema's goal_id description adds some usage context by allowing filtering to a single objective, but this lives outside the main description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reclaim stale leases and select the next target(s). A claimed node is reserved for you until you record its result, so ask only for what you will probe before your next call — anything you hold and do not report is work nobody can do. A batch never contains two competing answers to the same question. Returns a list; each entry may carry min_depth when the node is under conflict review.
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | How many targets to claim in this call. | |
| dry_run | No | Peek at the selection without issuing a claim or TTL. | |
| goal_id | No | Work on one objective only: that goal, everything it depends on, and the competing answers to those questions. Omit to draw from the whole workspace. If the filter leaves nothing testable while untested work sits outside it, the reason is goal_scope_empty and the fix is usually a missing DEPENDENCY edge, not a finished search. | |
| lease_ttl_s | No | Override the claim TTL in seconds (default 900). Raise it for experiments that run for hours or days, or keep it short and call renew_claim while the work is still going. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses claiming semantics (reservation until result recorded), the negative consequence of holding without reporting ('work nobody can do'), that a batch never contains competing answers, and that entries may include min_depth under conflict review. It also mentions stale lease reclamation and TTL behavior. Some side-effect details (e.g., exact state changes to claims) are implied but not fully spelled out.
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?
Four sentences, each earning its place: purpose, usage rule, batch property, and return format. The most important information is front-loaded in the first sentence. No filler or redundancy.
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?
With no output schema, the description covers the return format (list, optional min_depth). It also explains edge-case behavior (goal_scope_empty) and claim lifecycle. It lacks explicit details on error responses or authentication, but for a tool with 4 optional params and no output schema, it is reasonably 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 description coverage is 100%, so the baseline is 3. The description adds context beyond the schema: it reinforces the count parameter with the 'only ask for what you will probe' rule and explains the goal_scope_empty reason for goal_id. It also ties lease_ttl_s to renew_claim. This extra context elevates the score above baseline.
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 opens with a specific verb+resource: 'Reclaim stale leases and select the next target(s).' This clearly states the tool's core function and distinguishes it from siblings like get_active_claims (which lists claims) or renew_claim (which extends TTL). It further differentiates by mentioning batch semantics and conflict-review context.
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?
Provides actionable guidance: 'ask only for what you will probe before your next call' sets a clear usage rule, and the schema description for lease_ttl_s explicitly mentions calling renew_claim as an alternative. The dry_run parameter description clarifies when to peek without claiming. However, it does not explicitly compare to list_nodes or get_active_claims, missing some sibling differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Which belief state you are connected to, and how it was chosen. Reports the workspace id, which of the four resolution layers produced it, where the database lives and whether it exists yet. Call it when the graph is unexpectedly empty or two clients disagree about what has been established — that is almost always one project resolving to two workspaces.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry behavioral context. It discloses what is reported (including database existence and resolution layers), implying a read-only operation. It stops short of explicitly stating side effects or failure modes, but the disclosed behavior is sufficient for a get-info 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?
Two sentences front-load the purpose and then give usage guidance. Every clause adds value: what is reported, why it matters, and when to call. No filler or redundancy.
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 parameterless tool with no output schema, the description fully covers what the tool returns, the meaning of 'belief state', and typical usage scenarios. It leaves no major gaps for the agent to infer.
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 has zero parameters, so the baseline is 4. The description adds no parameter-specific meaning, but none is needed. It instead explains the context and outputs, which aligns with the empty 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?
The description uses a specific verb 'reports' and clearly identifies the resource (workspace info), listing concrete outputs (workspace id, resolution layer, database location, existence). It distinguishes this tool from siblings by focusing on workspace identity rather than claims, graph, or hypotheses.
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?
Explicitly says 'Call it when the graph is unexpectedly empty or two clients disagree about what has been established' and provides the likely cause. This gives clear when-to-use guidance and implicitly distinguishes it from alternatives that operate on graph content.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Walk DEPENDENCY ancestors, flip VERIFIED → NEEDS_REVISION.
| Name | Required | Description | Default |
|---|---|---|---|
| leaf_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries full behavioral burden. It does disclose the core effect (status transition from VERIFIED to NEEDS_REVISION) and scope (walking ancestors). However, it leaves ambiguity about whether the leaf itself is affected, what happens to non-VERIFIED ancestors, and whether the operation is reversible or has side effects.
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 a single, concise sentence that front-loads the object (dependency ancestors) and the action (flip status). Every word earns its place, with no filler or redundancy. It is a model of efficiency.
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 is relatively simple with one parameter and no output schema, but the description still leaves critical context missing. It does not mention return values, error behavior (e.g., missing leaf_id, no ancestors), or whether the leaf itself is affected. More detail about the traversal and status update semantics would make the description 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?
The schema only provides the parameter name leaf_id with no description, and schema coverage is 0%. The description implicitly suggests that leaf_id is the starting point for walking ancestors, but it never explicitly defines the parameter, expected format, or its relationship to the dependency graph. This is insufficient for a tool with one required parameter.
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 action: walk dependency ancestors and flip their status from VERIFIED to NEEDS_REVISION. It distinguishes itself from sibling verify_upstream, which likely does the opposite. However, it does not explicitly frame the purpose around 'invalidation' beyond this status transition, which leaves a bit of ambiguity.
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?
No guidance is provided about when to use this tool versus alternatives like update_status or verify_upstream. The description is purely action-oriented and does not mention the context in which invalidation is appropriate (e.g., when a dependency is outdated) or any preconditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Query/filter/sort nodes and return a Markdown table. Use view for the questions actually worth asking — 'frontier' (what is still open), 'settled', 'verified', 'revision' (what is under revision), 'stale' — rather than assembling a status filter by hand. stale_only=true keeps only confirmations made against a commit that is no longer checked out: they are not refuted, but nothing has re-established them since the code moved.
| Name | Required | Description | Default |
|---|---|---|---|
| view | No | Named filter preset; overridden by an explicit status_filter. | |
| limit | No | ||
| offset | No | ||
| order_by | No | created_at | |
| ascending | No | ||
| stale_only | No | Keep only VERIFIED nodes confirmed against a non-HEAD commit. | |
| query_filter | No | Case-insensitive statement search. `*` = multi-char wildcard, `_` = single-char. Literal % and _ are escaped. | |
| status_filter | No | Filter to these statuses only |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It adds valuable nuance, especially around `stale_only=true`, explaining that stale confirmations are 'not refuted, but nothing has re-established them since the code moved.' It also defines the view presets. This goes beyond basic query semantics, though it does not cover pagination or side-effect-free guarantees explicitly.
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 concise (about 80 words) and front-loaded with the core purpose, followed by the view guidance and then the stale_only nuance. Every sentence adds value, and there is no fluff or repetition of schema details.
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 an 8-parameter tool with no output schema and no annotations, the description covers the key decision points (view vs manual filter) and the nuanced stale semantics. It does not explain pagination behavior, but that is partially inferable from the limit/offset defaults. The return format is specified as a Markdown table, which is sufficient.
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 50%, so the description must compensate. It does so for the two most complex parameters: 'view' (with named presets and meanings) and 'stale_only' (with a detailed explanation). The remaining parameters (limit, offset, order_by, ascending) are straightforward and have enum/default metadata in the schema, so the lack of extra description is acceptable.
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 function: 'Query/filter/sort nodes and return a Markdown table.' It uses a specific verb and resource, and the output format is explicit. This distinguishes it from sibling tools that have more specialized purposes (e.g., get_active_claims, get_evidence_history).
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 provides explicit guidance on using the 'view' parameter instead of hand-assembling status filters, saying 'Use `view` for the questions actually worth asking... rather than assembling a status filter by hand.' This gives clear contextual direction, though it does not directly reference sibling tools as alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record one result, or many in one call, and update the belief state. Auto-captures git context_hash + git_branch when unset. Record against the hypothesis whose statement you actually tested: evidence against a goal is refused, and evidence against a premise a composition assumed corrupts a confirmation that is still true on its own. Ran several experiments this turn? Report them together with results — one call, applied in order.
| Name | Required | Description | Default |
|---|---|---|---|
| depth | No | Rigour/scale of the test that produced this result. A confirmation at depth d only supports claims tested no deeper than d. | |
| notes | No | ||
| message | No | ||
| metrics | No | ||
| node_id | No | ||
| results | No | Several results at once, applied in the order given. Use this whenever you ran more than one experiment: reporting k results costs one call instead of k. Each entry takes the same fields as a single result. When present, the single-result fields below are ignored. | |
| success | No | ||
| claim_id | No | The claim this result answers. Optional: omit it entirely for a probe you initiated yourself, which is always safe. Pass the one get_next_targets issued for work it handed you, so the lease is released. | |
| duration_s | No | How long the experiment took, in seconds. Optional, and worth sending whenever your probes differ in cost: it is what lets the navigator rank by value per unit cost rather than treating a three-day run and a one-second check as interchangeable. | |
| error_type | No | ||
| source_ref | No | What was actually run to produce this number — a file path, a URL, a CI run id, a commit. Optional, but a trail that says '0.85, from pytest run #4412' is worth more later than one that says '0.85'. | |
| lease_ttl_s | No | TTL for the fused dispatch, if any. | |
| evidence_kind | No | logical | |
| attestation_id | No | Runner-minted attestation id. Provenance fields cannot be supplied here; unknown ids degrade to self-reported. | |
| count_next_targets | No | How many targets you want to be holding when this returns — a top-up, not an addition, so recording a batch of results leaves you with this many, not this many per result. Saves a separate get_next_targets round-trip. Leave at 0 when you are reporting a long-running experiment and are not ready to claim more work — anything claimed and not reported is work nobody else can do. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and does disclose key behaviors: auto-captures git context when unset, refuses evidence against goals, and corrupts confirmations for premises assumed corrupt. It also explains the order-of-application for batch results. Minor gap: does not disclose that it mutates state, but the verbs 'record' and 'update' imply it.
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 dense but every sentence adds value: batch guidance, auto-capture, hypothesis targeting rule, and a concrete example of batch usage. It's front-loaded with the core action and quickly moves to important constraints.
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?
Given 15 parameters, low schema coverage, and no output schema, the description covers the most decision-relevant parameters but not all (e.g., error_type, metrics, attestation_id are not explained). Since the schema covers those partially, this is acceptable; however, for a complex tool, more coverage would improve completeness. The absence of an output schema is noted, but the description doesn't need to explain return values.
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 low (53%), so the description must add meaning. It explains the critical `results` parameter (batch usage), the `claim_id` parameter (optional vs. lease release), `duration_s` (for ranking), `source_ref` (provenance value), and `count_next_targets` (top-up semantics). This goes beyond the schema with actionable context.
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 primary action ('Record one result, or many in one call') and the resource (evidence) and explicitly includes the belief state update. It distinguishes from siblings by focusing on recording evidence versus creating hypotheses or managing claims.
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?
Provides explicit guidance on when to use the batch mode ('Ran several experiments this turn? Report them together') and clarifies the rule about which hypothesis to record against. However, it does not mention when NOT to use this tool compared to siblings like get_evidence_history or update_status.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Hand leased nodes back without recording a result — for work you have decided not to run, or for resuming after a context reset you cannot report on. Omit claim_ids to release everything you hold.
| Name | Required | Description | Default |
|---|---|---|---|
| claim_ids | No | Release only these; omit to release every live lease. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses a key behavior: releasing without recording a result. However, it does not mention whether the action is reversible, any side effects on related data, or permissions. This is adequate but leaves some uncertainty about consequences.
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 main action and purpose. Every word earns its place, with no fluff or redundancy that isn't already present in the schema (which is acceptable).
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 tool with one optional parameter and no output schema, the description gives sufficient context to understand what it does and when to use it. It lacks a description of return values, but for this simple action that is not a significant gap.
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 schema already explains the claim_ids parameter and its omission behavior, and the tool description merely repeats the same information ('Omit claim_ids to release everything you hold'). Since schema coverage is 100%, the description adds no additional semantic value.
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 action ('hand leased nodes back') and distinguishes it from recording results, explicitly contrasting with tools like record_evidence. It also gives specific scenarios (work not run, context reset) that clarify its scope.
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 provides clear when-to-use guidance ('for work you have decided not to run, or for resuming after a context reset you cannot report on'). It does not explicitly name alternatives or exclusions, but the context is strong enough to guide an agent in selecting this tool over siblings like record_evidence or renew_claim.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Render a Mermaid flowchart with depth+width bounding + elision.
| Name | Required | Description | Default |
|---|---|---|---|
| node_id | No | ||
| max_depth | No | ||
| max_children | No | ||
| hide_statuses | No | Drop nodes matching these statuses (e.g. ['PRUNED']). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavior on its own. It does reveal that rendering is bounded by depth/width and that nodes may be elided, which gives some insight into output shaping. However, it does not mention side effects, error behavior, or the exact nature of the output beyond being a Mermaid flowchart, leaving some behavior implicit.
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 a single, front-loaded sentence with no fluff. Every phrase ('Mermaid flowchart', 'depth+width bounding', 'elision') adds distinct value, making it concise and appropriately sized for the tool's 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?
The tool has 4 parameters, no output schema, and no annotations, but the description is very brief. It does not clarify whether node_id is required or what happens if omitted, nor provide examples or usage context. While it conveys the core purpose, it leaves too many operational details unresolved for confident 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 only 25% (only hide_statuses has a description). The tool description partially compensates by linking 'depth+width bounding' to max_depth and max_children, and 'elision' to hide_statuses. However, node_id is left without explanation, and the relationship between the bounding/elision terms and specific parameters is not explicit.
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 ('Render a Mermaid flowchart') and adds key differentiators ('depth+width bounding + elision'). It clearly indicates this tool produces a visual rendering rather than a raw data list, which helps distinguish it from siblings like list_nodes or get_dag_context, though it does not explicitly name alternatives.
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?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, typical scenarios, or cases where another tool would be preferable. The description only states what the tool does, not when it should be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Restart a live lease's clock because the experiment is still running. Use this instead of a very long TTL: the lease exists so work held by a caller that vanished comes back, and a long TTL makes that recovery as slow as the longest experiment.
| Name | Required | Description | Default |
|---|---|---|---|
| claim_id | Yes | ||
| lease_ttl_s | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the behavioral disclosure burden. It explains the lease mechanism (work recovery after caller vanishes) and the downside of long TTLs, which is useful context. However, it does not mention failure modes, idempotency, or what happens with invalid claims, leaving gaps.
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 two sentences that are dense with meaning. The first sentence states the action and condition; the second provides the alternative and rationale. No wasted words, and the key information is 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?
For a tool with two params, no output schema, and no annotations, the description explains the core concept well but omits parameter semantics and expected return values. It is adequate for a simple renew operation but leaves important operational details unspecified.
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 not explain either parameter (claim_id, lease_ttl_s). The names hint at their roles, but the description provides no units, defaults, or behavior for lease_ttl_s, nor does it clarify how the lease is identified. It fails to compensate for the lack of schema descriptions.
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 opens with a specific action: 'Restart a live lease's clock because the experiment is still running.' It clearly distinguishes this from siblings like release_claims or invalidate_upstream by framing it as a renewal operation for an ongoing lease.
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?
Explicitly states when to use (while experiment is still running) and provides an alternative ('Use this instead of a very long TTL') with a strong rationale that explains the trade-off in lease recovery time. This is concrete, actionable guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Propose the single most informative next experiment: re-test a conflict suspect at depth while any remains, otherwise the closest alternative combination that no recorded conflict rules out.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It discloses the internal decision logic (re-test conflict suspect at depth, otherwise closest alternative), which is good, but it does not state whether the tool is read-only, has side effects, or what the output format is. Since 'suggest' implies non-mutating, the description is adequate but not rich.
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 a single, front-loaded sentence with no wasted words. It immediately states the purpose and then specifies the decision rule, earning its place efficiently.
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 no output schema and no annotations, yet the description does not explain what the agent will receive (e.g., a string, a structured object) or any prerequisites. However, it gives a clear decision rule for a zero-input tool, so it is reasonably complete for its simplicity but leaves return-value expectations open.
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 has zero parameters, so schema coverage is vacuously 100%. The baseline for 0 params is 4, and the description adds no parameter-specific detail because none exist. The description's context about conflict resolution complements the empty schema without redundancy.
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 a specific verb ('Propose') and resource ('the single most informative next experiment'), with a clear decision rule distinguishing it from generic tools. However, it does not explicitly contrast with sibling tools like get_next_targets, so differentiation is only implicit.
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 implies when to use (when you need to select the next experiment) and even provides algorithmic guidance, but it does not state explicit alternatives or when not to use the tool. Sibling comparisons would strengthen this.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manually override the status of one or many nodes. Every id is validated before anything changes, so a bad id never leaves a partial update.
| Name | Required | Description | Default |
|---|---|---|---|
| reason | No | ||
| node_ids | Yes | ||
| new_status | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the behavioral disclosure burden. It provides one important guarantee: all IDs are validated before any changes, preventing partial updates. However, it does not disclose other relevant behaviors such as whether the override is reversible, whether it affects dependent nodes, or what permissions are required. This is helpful but incomplete.
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 two sentences long and front-loaded with the core action. The second sentence adds a key safety behavior without unnecessary verbosity. Every word earns its place, making it highly efficient for an agent to parse.
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?
Given the tool's moderate complexity (3 params, no output schema, no annotations), the description covers the basic purpose and a key behavioral guarantee, but it omits usage context, parameter details, and what the agent should expect in return. It is enough for simple invocation but leaves gaps for an agent navigating among many related sibling tools.
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 for explaining parameters. It indirectly covers node_ids and new_status via 'status of nodes', but the 'reason' parameter is completely unmentioned. The new_status enum is self-explanatory, but the description adds no additional meaning or context for the parameters beyond what the schema already shows.
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 ('override') and resource ('status of nodes'), clearly distinguishing it from sibling tools that perform narrower status changes like 'verify_upstream' or 'invalidate_upstream'. The qualifier 'manually' further clarifies that this is a direct, user-driven action rather than an automated process.
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?
No guidance is given on when to use this tool versus the many sibling tools that also alter node state. The word 'manually' implies a fallback for when automated flows are not appropriate, but this is not explicit. There is no mention of prerequisites, alternatives, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Walk REFINEMENT ancestors, flip IN_PROGRESS → VERIFIED (depth-capped).
| Name | Required | Description | Default |
|---|---|---|---|
| child_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must bear the full burden of disclosing side effects. It reveals a mutating operation (status flip) and a depth cap, but omits critical details: how non-IN_PROGRESS ancestors are handled, whether the child_id itself is modified, side effects on already-VERIFIED nodes, and error conditions. This is insufficient 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?
One short sentence with a compact verb phrase; no filler or redundant content. The key elements (traversal direction, status change, depth limitation) are packed efficiently, making it easily scannable.
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 single-parameter mutation tool with no annotations or output schema, the description is minimal. It explains the algorithm but misses context like what the function returns, whether it is idempotent, how depth is determined, and what conditions might cause failure. An agent would be under-informed for safe 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?
The schema provides only the parameter name 'child_id' with no description (0% coverage). The description never explicitly connects child_id to the walking operation. While inferable from the tool name and 'ancestors', the semantics are not stated, leaving ambiguity about whether child_id is the starting node or something else.
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 ('Walk') and resource ('REFINEMENT ancestors') with an explicit status transition ('flip IN_PROGRESS → VERIFIED'). This clearly differentiates it from sibling tools like invalidate_upstream and generic update_status.
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?
No information about when to use this tool versus alternatives. It does not mention prerequisites, exclusions, or contextual triggers such as 'use when a claim's upstream dependencies need batch verification.' The depth-capped hint is a constraint, not usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Name the cheapest experiments that would OVERTURN what a goal currently concludes, ranked by how little evidence holds each belief up. Answers the question a reviewer actually asks — not what do you believe, but what would it take to be wrong. A belief confirmed by elimination ranks first however confident the engine is: nothing ever measured it, which makes it both the weakest link and the cheapest thing in the graph to settle. Read-only — it issues no lease and changes nothing.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | How many beliefs to return, most fragile first. | |
| goal_id | No | Restrict to one objective. Omit for every goal. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses behavioral traits: it explicitly states 'Read-only — it issues no lease and changes nothing,' and it explains the ranking logic (beliefs confirmed by elimination rank first regardless of confidence). This goes beyond basic safety and provides insight into the tool's operation.
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 efficiently covers key aspects, but it includes some rhetorical phrasing like 'Answers the question a reviewer actually asks' and the explanatory third sentence. While all sentences add value, a more streamlined version could reduce wordiness without losing meaning.
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 read-only tool with two parameters and no output schema, the description covers the essential context: what it does, the ranking principle, and its side-effect-free nature. It lacks explicit mention of the response format, but that is not required given the simplicity and the absence of an 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 100%, and the schema already describes both parameters ('How many beliefs to return, most fragile first' and 'Restrict to one objective. Omit for every goal.'). The description adds little beyond the schema's parameter details, so it meets the baseline without further elaboration.
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 names the cheapest experiments that would overturn a goal's conclusion, specifying the verb 'Name' and the resource 'cheapest experiments' within the goal context. It distinguishes itself from siblings by answering the reviewer's question — 'not what do you believe, but what would it take to be wrong' — which sets it apart from other analysis tools.
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 provides clear context: it is for identifying weak beliefs and cheap ways to falsify them, framing it as what a reviewer would ask. However, it does not explicitly mention when not to use this tool or directly name alternatives, so it stops short of full usage guidance.
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. Dates show when Glama detected each change.
v0.6.0-releasecreate_hypotheses1 field changedInput schema / properties / hypotheses / items / properties / titleAdded value: +{
+ "description": "Optional short human label; node_id remains the identity.",
+ "maxLength": 128,
+ "type": "string"
+}record_evidence3 fields changedInput schema / properties / attestation_idAdded value: +{
+ "description": "Runner-minted attestation id. Provenance fields cannot be supplied here; unknown ids degrade to self-reported.",
+ "type": "string"
+}Input schema / properties / results / items / properties / attestation_idAdded value: +{
+ "type": "string"
+}Input schema / properties / results / items / requiredPrevious value: -[
- "node_id",
- "success"
-]New value: +[
+ "node_id"
+]v0.5.0add_edgescreate_hypotheses3 fields changedInput schema / properties / hypotheses / items / properties / estimated_costAdded value: +{
+ "description": "Roughly what testing this will cost, in seconds. A hint for ordering, never a claim about the hypothesis: it changes what gets tried next and never what the belief state asserts, and the first real `duration_s` supersedes it. Worth giving when the competing answers to one question differ in cost — a 30-second unit test against an overnight fine-tune — because the last answer standing is deduced rather than probed, so putting the expensive one last means never paying for it. Omit it when they all cost about the same; ordering is then free of it anyway.",
+ "exclusiveMinimum": 0,
+ "type": "number"
+}Input schema / properties / hypotheses / items / properties / exclusion_closedAdded value: +{
+ "default": true,
+ "description": "Whether these are ALL the candidate answers. True (the default) licenses the engine to confirm the last one standing for free once every rival is ruled out — sound over a complete list, and an assertion of something false over a partial one. Pass false when the next candidate always exists: 'which learning rate', 'which prompt wording'. Confirming one member still retires the others either way; only the last-one-standing deduction is withheld.",
+ "type": "boolean"
+}Input schema / properties / hypotheses / items / properties / parent_ids / descriptionPrevious value: -"Ids this hypothesis is wired to. They may be created by this same call, in any order — dependencies are sorted out for you."New value: +"What this hypothesis RESTS ON — its premises, not its sub-tasks. Edges run from the thing assumed to the thing assuming it, so a premise is the PARENT of the combination that uses it, and a goal is the LAST node in that chain: put the work in the goal's parent_ids, never the goal in the work's. They may be created by this same call, in any order — dependencies are sorted out for you."generate_learning_path3 fields changedInput schema / properties / as_ofAdded value: +{
+ "description": "ISO-8601 instant. Reconstruct the report as it stood then, so it can be read beside a rewound graph.",
+ "type": "string"
+}Input schema / properties / goal_idAdded value: +{
+ "description": "Narrate one objective only. A workspace pursuing several otherwise interleaves their dead ends into one story.",
+ "type": "string"
+}Input schema / properties / sinceAdded value: +{
+ "description": "ISO-8601 instant. Report only what settled or was withdrawn since then — 'what changed this week' rather than 'how we got here'. Combine with as_of for a closed window.",
+ "type": "string"
+}get_goal_status1 field changedInput schema / properties / goal_idAdded value: +{
+ "description": "Report on one objective and count only the nodes forming its case. Omit for every goal in the workspace.",
+ "type": "string"
+}get_next_targets2 fields changedInput schema / properties / goal_idAdded value: +{
+ "description": "Work on one objective only: that goal, everything it depends on, and the competing answers to those questions. Omit to draw from the whole workspace. If the filter leaves nothing testable while untested work sits outside it, the reason is goal_scope_empty and the fix is usually a missing DEPENDENCY edge, not a finished search.",
+ "type": "string"
+}Input schema / properties / lease_ttl_s / minimumAdded value: +1list_nodes3 fields changedInput schema / properties / stale_onlyAdded value: +{
+ "default": false,
+ "description": "Keep only VERIFIED nodes confirmed against a non-HEAD commit.",
+ "type": "boolean"
+}Input schema / properties / status_filter / items / enumPrevious value: -[
- "UNTESTED",
- "IN_PROGRESS",
- "VERIFIED",
- "INVALIDATED",
- "PRUNED",
- "BLOCKED",
- "NEEDS_REVISION"
-]New value: +[
+ "UNTESTED",
+ "IN_PROGRESS",
+ "VERIFIED",
+ "EXHAUSTED",
+ "INVALIDATED",
+ "PRUNED",
+ "BLOCKED",
+ "NEEDS_REVISION"
+]Input schema / properties / viewAdded value: +{
+ "description": "Named filter preset; overridden by an explicit status_filter.",
+ "enum": [
+ "frontier",
+ "settled",
+ "verified",
+ "revision",
+ "stale"
+ ],
+ "type": "string"
+}record_evidence5 fields changedInput schema / properties / duration_sAdded value: +{
+ "description": "How long the experiment took, in seconds. Optional, and worth sending whenever your probes differ in cost: it is what lets the navigator rank by value per unit cost rather than treating a three-day run and a one-second check as interchangeable.",
+ "minimum": 0,
+ "type": "number"
+}Input schema / properties / lease_ttl_s / minimumAdded value: +1Input schema / properties / resultsAdded value: +{
+ "description": "Several results at once, applied in the order given. Use this whenever you ran more than one experiment: reporting k results costs one call instead of k. Each entry takes the same fields as a single result. When present, the single-result fields below are ignored.",
+ "items": {
+ "properties": {
+ "claim_id": {
+ "type": "string"
+ },
+ "depth": {
+ "default": 0,
+ "minimum": 0,
+ "type": "integer"
+ },
+ "duration_s": {
+ "minimum": 0,
+ "type": "number"
+ },
+ "error_type": {
+ "type": "string"
+ },
+ "evidence_kind": {
+ "default": "logical",
+ "enum": [
+ "logical",
+ "infra"
+ ],
+ "type": "string"
+ },
+ "message": {
+ "type": "string"
+ },
+ "metrics": {
+ "type": "object"
+ },
+ "node_id": {
+ "type": "string"
+ },
+ "notes": {
+ "type": "string"
+ },
+ "source_ref": {
+ "type": "string"
+ },
+ "success": {
+ "maximum": 1,
+ "minimum": 0,
+ "type": "number"
+ }
+ },
+ "required": [
+ "node_id",
+ "success"
+ ],
+ "type": "object"
+ },
+ "minItems": 1,
+ "type": "array"
+}Input schema / properties / source_refAdded value: +{
+ "description": "What was actually run to produce this number — a file path, a URL, a CI run id, a commit. Optional, but a trail that says '0.85, from pytest run #4412' is worth more later than one that says '0.85'.",
+ "type": "string"
+}Input schema / requiredPrevious value: -[
- "node_id"
-]New value: +[]what_would_change_my_mindv0.3.0create_hypothesesgenerate_learning_pathget_active_claimsget_conflictsget_dag_contextget_evidence_historyget_goal_statusget_next_targetsget_workspace_infoinvalidate_upstreamlist_nodesrecord_evidencerelease_claimsrender_dag_maprenew_claimsuggest_discriminating_experimentupdate_statusverify_upstreamMost tools have clearly distinct purposes: creation vs. evidence vs. status vs. topology. However, `verify_upstream` and `invalidate_upstream` are closely related (opposite actions on ancestors), and `update_status` could be seen as a general-purpose override that overlaps with the more targeted status-changing tools, though the descriptions help differentiate them.
The majority of tool names follow a verb_noun pattern (e.g., create_hypotheses, add_edges, record_evidence). A few exceptions like `what_would_change_my_mind` and `get_dag_context` break the pattern but are still understandable. The inconsistency is minor but noticeable.
With 20 tools covering a complex domain (hypothesis management, evidence, claims, conflicts, and workspace introspection), the count is justified. Each tool serves a distinct operational need, from low-level CRUD (create_hypotheses, add_edges) to high-level analysis (what_would_change_my_mind, generate_learning_path). The set is comprehensive without being bloated.
The tool surface covers the full lifecycle: creating hypotheses, managing evidence, handling leases, updating statuses, resolving conflicts, and reporting goal progress. Critical gaps like missing delete operations are intentionally avoided (hypotheses are retained for auditability), and read-only introspection tools provide a complete view of the belief state.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Persistent, inspectable memory for AI agents with lineage, correction, and a hosted MCP endpoint.
Graph-native persistent memory for AI agents — 33 MCP tools, zero-LLM writes.
Self-hosted AI-native knowledge workspace with hybrid search, GraphRAG, and MCP.
Persistent, portable memory for AI assistants — your private memory graph, from any MCP client.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/tygryso/hypotree'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
