Veris is a behavioral verification infrastructure for autonomous coding agents that analyzes codebases, detects risk, and guides verification — locally with no cloud or telemetry.
Repository Analysis: Parse the repository AST for file/entity counts, export the full behavioral graph (nodes, edges: DependsOn + Invokes, workflow domain coloring), and auto-cluster code into semantic workflow domains (Authentication, Billing, Checkout, etc.).
Change Impact & Risk Assessment: Compute real git-worktree diffs vs a base ref, identify impacted workflows, and score risks by blast radius, fragility, and runtime criticality.
Verification Planning: Generate Tier 1/2/3 verification directives keyed to impacted nodes, with Tier 3 producing adversarial test hypotheses (concurrency, idempotency, retry storms, replay attacks, cache stampedes, etc.).
Budget Allocation: Greedily select the highest-leverage verification targets given a time budget using (tier × criticality × risk) / cost.
Counterfactual Simulation: Simulate reverting specific nodes (what_if_revert) to see which behaviors recover and how risk changes.
Confidence Tracking: Report execution results (pass/fail/flaky/skipped) per node/tier/directive; confidence scores update via half-life decay over real execution history.
Drift Detection: Compare current workflow fingerprints against historical state to catch silent rewrites, topology expansion/contraction, and oscillating refactors.
History & Insights: Review confidence/execution-depth trends over time and inspect per-node execution/risk history across runs.
Onboarding Export: Generate workflow-first onboarding markdown packages (one file per workflow + index) in veris-reports/onboarding/.
Cross-Repo Management: Register multiple repositories and get a fleet-wide confidence and drift snapshot across all registered repos.
Plugin Extensibility: Add custom workflow rules and runtime risks via JavaScript plugins.
Every one is published — what broke, why it mattered, the fix, and the test that proves it: docs/internal/BUG_TRACKER.md
The worst three, in our own tool:
It invented baselines. When git was unavailable, Veris built a "before" state from the first 70% of the current graph and reported the comparison as a real behavioral diff. No flag. No warning. A verification tool was fabricating the thing it verified against.
91% of its call edges were guesses.
It matched the trailing name of a call against every declaration sharing that name.
console.log() drew an edge to the project's own Logger.log. Measured on a real
dependency: 2,804 of 3,077 edges pointed at an ambiguous name.
The graded agent could erase its own failures.
Execution results were stored with INSERT OR REPLACE. Post fail, then post
pass, and the failure was gone.
We could have fixed these quietly. Publishing them is the point: a tool that tells you what is unverified has no standing to hide its own unverified claims.
This is also the demo. That is the analysis Veris performs, run on itself.
Related MCP server: Total Recall
A behavioral diff for AI-written code, speaking the Model Context Protocol so your agent can ask while it is still working — not after you find out in review.
It answers two questions a line diff cannot:
What behavior changed? Not which lines — which behaviors, and what reaches them.
Was any of it actually checked? Published research puts roughly 65% of agent-authored PRs at zero coverage of their own changed lines.
Veris never executes anything. No tests, no sandboxes, no runtime. It reads, models, and tells your agent what is at risk and what evidence exists. Running things stays with the tools that are good at running things.
$ npx veris-core . --base-ref=origin/main
-> Baseline: origin/main @ 1bebd2ce2e08 -> head 3ed9031421-dirty
Working tree has 4 uncommitted changes; this run is not reproducible from commits alone.
-> Graph: 326 nodes, 602 edges (head), 131 tracked files
-> Call resolution: 403 resolved (97.1%), 6 single-candidate, 6 ambiguous (no edge emitted)
-> Workflows: 15 detected, 3 affected in diff
-> Adversarial probes generated: 4Read lines 2 and 4 again — they are the whole philosophy.
Six calls were too ambiguous to resolve, so Veris drew no edge rather than
guessing. The head is marked -dirty because uncommitted changes were included, so
the result is not reproducible from commits alone.
Most tools report only what they found. Veris also reports what it could not determine, because a confident wrong answer is worse than an admitted gap.
As an MCP server — one config block, then restart your client:
{
"mcpServers": {
"veris": {
"command": "npx",
"args": ["-y", "veris-core", "mcp"]
}
}
}17 tools light up in Claude Code, Cursor, or any MCP-compatible agent.
As a CLI:
npx veris-core . # analyze against origin/main
npx veris-core . --base-ref=HEAD~1 # explicit baseline
npx veris-core . --budget=10 --onboarding # 10-min plan + onboarding map
npx veris-core doctor # check git, base ref, depsNeeds a git repository with real history. Veris diffs against the merge-base with your base ref. If it cannot establish one, it fails and says why rather than inventing a baseline. In CI:
fetch-depth: 0.
On npm 12, run history needs one extra line. npm 12 no longer runs dependency install scripts by default, so
better-sqlite3never fetches its prebuilt binding. Veris still analyzes, diffs, scores risk and plans verification — only run history and cross-run drift need it. The allowlist is per-project and is not inherited from a dependency, so it has to go in yourpackage.json:{ "allowScripts": { "better-sqlite3": true } }Then
npm rebuild better-sqlite3.veris-core doctorreports which mode you are in, and never claims persistence is working when it is not.
flowchart TD
A[git-tracked source] -->|ts-morph + TypeScript checker| B[Behavioral graph]
B -->|worktree at merge-base| C{Baseline exists?}
C -->|no| X[Fail loudly<br/>never fabricate]
C -->|yes| D[Diff: added / removed<br/>rewritten-body / edges]
D --> E[Risk · Workflows · Fingerprints · Drift]
E --> F[Probes · Tiered plan · Budget]
F --> G[Coverage from<br/>trust-weighted evidence]
G --> H[17 MCP tools · Dashboard · Reports]
H -->|agent or CI executes| I[report_execution]
I -->|append-only, hash-chained| G
style X fill:#ff5d6c,stroke:#c1121f,color:#fff
style G fill:#8b5cf6,stroke:#6d28d9,color:#fff
style B fill:#0ea5e9,stroke:#0369a1,color:#fffThe red box is a feature. So is the loop back into coverage.
Most graph tools give you an edge. Veris tells you why it believes the edge:
| Meaning |
| The TypeScript checker identified the declaration. Trustworthy. |
| Checker couldn't, but exactly one declaration bears that name. |
| Containment or an import relationship. |
(no edge) | Several candidates and nothing distinguishes them. Silence, not a guess. |
Anything that must not reason on a guess — a gate, a policy rule — filters for
resolved. Missing edges understate coupling. They never invent it.
The agent posting results is usually the agent being judged. So:
{ "nodeId": "src/pay.ts::charge",
"result": "pass",
"trustClass": "harness-observed", // ← default is "agent-asserted"
"producer": "github-actions:e2e" }Trust class | Who | Weight |
| Veris computed it | full |
| An external runner saw it | full |
| The agent says so — the default | half |
Records are hash-chained. A later pass never overwrites an earlier failure; editing
the database directly breaks the chain and verifyEvidenceChain() reports exactly
where. An agent cannot raise its own assurance by asserting harder.
- function chargeCard(amount) { return gateway.charge(amount); }
+ function chargeCard(amount) { return gateway.charge(amount * 100); }Same name. Same callees. Same graph shape. Every name-and-topology comparison sees
nothing. Veris hashes the normalized body, so this surfaces as a modifiedNode —
while renaming a directory, which used to look like 100% drift, now correctly looks
like nothing at all.
veris: analyze_pr_behavior with baseRef=origin/main
veris: list_workflows, then analyze_workflow for the highest-risk one
veris: generate_adversarial_probes, then allocate_budget minutes=15
veris: detect_drift
veris: what_if_revert nodeIds=[...]Probes are concrete, not nudges:
Payments / idempotency — Submit a charge twice with the same idempotency key inside a 500 ms window. Invariant: exactly one ledger entry; the second call returns the first result.
Webhooks / replay — Replay a 24-hour-old signed payload with its original signature. Invariant: rejected by timestamp window even though the signature is valid.
Semantic workflows | 25 domains — Authentication, Payments, Checkout, Webhooks, Queue, Caching… So the unit is "checkout reliability", not |
Risk model | Coupling magnitude, inbound-coupling dominance, runtime criticality — three inputs measuring different things. Every weight in |
Drift detection | Fingerprints across runs. Catches silent rewrites, surface changes, oscillating refactors, and deletions. |
Budget allocation | Given N minutes, the highest-leverage subset to actually run. |
Counterfactual |
|
Onboarding export | Workflow-first markdown for a new engineer, or a new agent, on an unfamiliar codebase. |
Dashboard | Standalone HTML. Click a workflow, everything filters. Click-to-copy directives. |
Stated plainly, so nobody discovers them the hard way.
A workflow is a label, not a path. Classification is a weighted keyword vote over directory names, imports and symbol names. It does not traverse the call graph. Rate-limiting code that imports Redis lands in Caching. Making workflows real paths is the top roadmap item.
Coverage is not assurance. It measures how much planned verification has evidence behind it. It is not calibrated against real incidents and does not estimate the probability your code is correct.
Risk is a heuristic. Good for ranking what to look at first. Not a defect predictor. No ground truth behind it.
Probes are a curated library — real failure modes, written by hand, selected by domain. Not generated from your code.
TypeScript and JavaScript only. Python and Go are on the roadmap.
Some calls can't be resolved. Dynamic dispatch and untyped JS defeat the checker. Those produce no edge, and the count is in the output.
Upgrading from 2.x? 3.0 has real breaking changes — see UPGRADING.md.
Local-first. All analysis runs on your machine. No telemetry, ever. Nothing about your code leaves the machine.
Zero-retention mode — VERIS_STATE_DISABLED=1.
No network sockets in the analyzer. stdio and the filesystem only.
Veris is usually pointed at repositories you did not write, so repository content is
untrusted input. Plugins execute code from the analyzed repo, so they are off by
default — --allow-plugins opts in, and each plugin's path and SHA-256 is printed
before it runs. There is no sandbox, and SECURITY.md says so plainly
instead of implying otherwise.
All 17 tools with recommended flows | |
Design invariants and the defect each replaced | |
All 55 findings, with evidence | |
2.x → 3.0 | |
Threat model and reporting | |
What is next — and what will never be built | |
Extending classification and risk |
The five things that move the needle most:
Entry-point detection for a framework you know — routes, handlers, queue consumers. This is what turns a workflow from a label into a path.
Labelled repositories for a classification benchmark. The accuracy claim needs ground truth, not more rules.
Probe provenance. The shipped probes are good and uncited; one backed by a public postmortem is worth ten that aren't.
Language adapters — Python, Go.
Calibration data — what Veris flagged that broke, and what it missed. The second is more valuable.
See CONTRIBUTING.md. Open source, sponsor-supported. No paid tier, no gated features, no open-core bait.
Given a time budget in minutes, greedily selects the highest-leverage subset of verification targets that fits, ranked by (tier leverage x workflow criticality x node risk) / estimated cost. Returns the selected targets in execution order (up to 200), the counts selected and skipped, estimated seconds and coverage. The skipped list itself is not returned — it is the complement of the selection and can be the entire plan.
| Name | Required | Description | Default |
|---|---|---|---|
| minutes | Yes | Minutes available. Typical: 5 (quick check), 15 (default), 60 (pre-release sweep). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does a solid job: it discloses the greedy selection logic, the ranking formula, the output limit (200), and the notable fact that the skipped list is not returned but is the complement of the selection. It does not explicitly state whether the tool is read-only or has side effects, but for a selection operation this is a minor gap given the detailed behavioral description.
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, information-dense sentence followed by one clarifying sentence about the skipped list. It is front-loaded with the purpose and algorithm, and every clause carries useful information. It is concise enough for the amount of content, though it could be slightly more scannable with bullet points for the output elements.
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 has only one parameter and no output schema, the description must explain the return values and behavior. It covers the selected targets, counts, estimated seconds, coverage, the 200-item limit, and the complement nature of the skipped list. It does not explicitly state a prerequisite that a verification plan must exist, but this is implied by the context of sibling tools and the term 'verification targets'. Overall, it is sufficiently complete for an agent to call it 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?
The schema already fully documents the single parameter 'minutes' with typical values (5, 15, 60). The description merely restates that it is a time budget and does not add any new meaning beyond the schema. Since schema coverage is 100%, the baseline of 3 is appropriate; the description adds no extra parameter-specific semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (selects), the resource (highest-leverage subset of verification targets), and the specific algorithm (greedy, ranked by a formula). It also enumerates the outputs, making the tool's purpose unmistakable. Though it doesn't name a sibling, its specificity distinguishes it from the general planning and analysis tools in the list.
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 when a time budget is given and a subset of verification targets must be chosen, but it does not explicitly state when to prefer this tool over alternatives like generate_verification_plan or identify_unverified_behaviors. No exclusions or alternative conditions are provided, so the guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Computes a behavioral diff between the working tree and the merge-base of HEAD with a base ref, using a detached git worktree. Returns added, removed and modified node counts (modified = same declaration, changed body hash — a rewrite that keeps its name and callees), the affected workflows with narratives, and the top 25 nodes by risk. Reports whether the working tree was dirty, since that makes the result non-reproducible from commits alone. Requires a git repository with a resolvable base ref: if none exists the call returns an error rather than a fabricated baseline. Base ref defaults to origin/main, then origin/master, main, master, HEAD~1.
| Name | Required | Description | Default |
|---|---|---|---|
| baseRef | No | Git ref to find the merge-base against. Example: 'origin/develop' or a commit SHA. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses the use of a detached worktree, the non-reproducibility implication of a dirty tree, and the error-on-unresolvable-base behavior. It stops short of explicitly stating whether the operation is read-only or has side effects (e.g., worktree cleanup), but the passive 'computes' and focus on diff analysis suggest a safe read. The dirty-tree flag is a thoughtful behavioral disclosure.
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 detailed but well-organized: it leads with the core computation, then lists outputs, then notes the dirty-tree caveat, and ends with prerequisites and defaults. Every sentence adds relevant information, and the structure is logical, though slightly dense for a quick scan. It earns its length given 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?
For a complex tool with no output schema, the description is thorough: it explains what is computed, defines 'modified' precisely, lists all return categories (counts, workflows, risk nodes), and covers edge cases (dirty tree, unresolvable base). It also states the default base ref resolution. An agent has enough to call it correctly and interpret results, making this 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 already documents baseRef with an example, so coverage is 100%. The description adds meaningful context beyond the schema: the default resolution order (origin/main, origin/master, main, master, HEAD~1) and the condition that an unresolvable base returns an error rather than fabricating a baseline. This enriches the parameter's meaning beyond a simple string type.
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 ('Computes') and resource ('behavioral diff'), and precisely defines the scope ('working tree vs merge-base of HEAD with a base ref'). It clearly distinguishes this tool from siblings like detect_drift or analyze_repository by focusing on PR-specific diff analysis, and enumerates concrete outputs (added/removed/modified counts, workflows, risk nodes).
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 for invocation: it requires a git repository with a resolvable base ref and explains the default fallback order. It does not explicitly contrast with alternative tools or state when not to use it, but the specificity of 'behavioral diff for PRs' implies its niche. The error behavior for missing base refs gives a clear precondition.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Parses the git-tracked TypeScript and JavaScript files in the current repository via ts-morph and returns a structural summary: file, class, method, function and exported-function counts, a per-file breakdown (capped at 100 files, ranked by declaration count), and call-resolution statistics showing how many call sites the TypeScript checker resolved exactly versus left ambiguous. Untracked and ignored files are excluded. Results are cached until a source file changes on disk.
| 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 important behavior: it parses files (implying read-only), excludes untracked/ignored files, and caches results until source files change. It does not explicitly state it makes no modifications, but the wording strongly implies a read-only analysis.
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, dense, well-organized sentence that covers purpose, scope, exclusions, output details, and caching without unnecessary fluff. It is information-dense yet easy to follow.
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?
Since there is no output schema, the description must explain what the tool returns. It does so thoroughly: counts, per-file breakdown with a cap, ranking criteria, and call-resolution statistics. It also notes exclusions and caching behavior, making the tool's behavior fully understandable.
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 no parameters in the schema, so parameter explanation is not needed. The description focuses on behavior and output, which is appropriate for a parameterless tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action (parses git-tracked TypeScript and JavaScript files via ts-morph) and the resource (the current repository). It also details the output (structural summary, counts, per-file breakdown, call-resolution statistics), making it easy to distinguish from sibling 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 implies when to use the tool (to analyze repository structure and get call-resolution stats) but does not explicitly state when to prefer it over alternatives or mention any exclusions. No sibling tools are referenced.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Deep-dive on one workflow by id: member nodes (up to 500), the inference signals that placed each member there with their weights, the top 5 members by risk with full score breakdowns, and runtime-risk hypotheses. Use after list_workflows identifies the workflow you care about.
| Name | Required | Description | Default |
|---|---|---|---|
| workflowId | Yes | Workflow identifier from list_workflows (e.g. 'payments', 'authentication'). |
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 lists the output components (useful) but does not state whether the operation is read-only, potential side effects, or error behavior. This is a partial disclosure for an analysis 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 with no redundancy. The first sentence front-loads the core purpose and outputs; the second gives a clear usage directive. 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?
With only one parameter and a clear description of the tool's returns, the essential usage is covered. It lacks error handling and side-effect disclosure, but for a deep-dive analysis tool, it's fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema already describes workflowId as a workflow identifier from list_workflows. The description reinforces this but adds no new semantics beyond the schema, 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?
States a specific verb 'Deep-dive' on 'one workflow by id' and enumerates the returned data (member nodes, signals with weights, top 5 risk members, runtime-risk hypotheses). Clearly distinguishes from list_workflows which lists workflows, and from other analyze_* siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to use after list_workflows identifies the workflow, providing a clear prerequisite and sequencing. However, it doesn't mention alternatives or when not to use this tool, so it misses the 'when-not' aspect.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns verification-coverage and execution-depth values across recent runs recorded in .veris/state.db, newest first. Defaults to 30 runs, capped at 100. Returns an empty trend with stateEnabled:false when persistence is disabled (VERIS_STATE_DISABLED=1).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum runs to return. Default 30, maximum 100. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It transparently describes what is returned, the default and maximum number of runs, and the special empty-trend behavior when persistence is disabled. It does not mention side effects, but the read-only nature is strongly implied.
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 and well-structured, using three short sentences that each convey a distinct piece of information: the primary output, the default/cap, and the disabled-persistence behavior. There is no redundant or irrelevant content.
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 description is complete for a simple retrieval tool: it specifies the data returned, ordering, default and maximum limits, and behavior when persistence is disabled. It does not describe an output schema, but none is provided and the return concept is clear enough for likely use cases.
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 fully describes the limit parameter with default and maximum values, and the description largely repeats this information. Since schema coverage is 100%, the baseline is 3, and the description adds no additional semantic detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool returns verification-coverage and execution-depth values across recent runs, which is specific and action-oriented. It does not explicitly name or contrast sibling tools, but the resource and scope are distinctive enough to infer its purpose.
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 useful context about default limits, maximum limits, and disabled-persistence behavior, but it does not explicitly state when to use this tool versus alternatives like node_history or report_execution. The guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reads the last recorded run for each repository registered in ~/.veris/registry.json and returns their coverage values, weakest first. Reports repositories that have no Veris state yet as 'no data' rather than analyzing them — this tool reads existing state and never runs an analysis or writes to a registered repository.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses the tool's behavior: it reads existing state, never runs analysis, and never writes. It also transparently reports how repositories without state are handled ('no data'), providing complete side-effect and edge-case transparency.
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 composed of two concise sentences that front-load the primary action (reads last run, returns coverage values) and immediately follow with the key behavioral caveat (never runs analysis or writes). Every sentence contributes essential information without redundancy or padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, no output schema), the description is complete. It specifies the input source, the output content and ordering, and the handling of repositories without state. No additional context is needed for an agent to invoke it 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?
The input schema has zero parameters, so the baseline is 4. The description adds no parameter-specific information because there are none to describe, but it does clarify the scope (all repositories in the registry), which is useful contextual meaning beyond 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 clearly states the tool reads the last recorded run for each repository in the registry and returns coverage values sorted weakest first. It also explicitly distinguishes itself from analysis tools by stating it never runs an analysis or writes, 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 provides direct usage guidance by contrasting with analysis: it reads existing state and never runs analysis or writes. This implicitly tells the agent to use this tool for quick read-only snapshots instead of triggering analyses, and the mention of 'no data' for unregistered repos sets expectations for edge cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compares current workflow fingerprints against those from prior runs in .veris/state.db. A fingerprint is the SHA-256 of the workflow's sorted member ids, its internal edge signatures, and each member's normalized body hash — so a rewritten function body is detected even when its name and call targets are unchanged. Member ids are repository-relative, so renaming a directory does not register as drift. Surfaces added, removed, expanded, contracted and silently-rewritten workflows, and distinguishes a first observation from an absence of drift. Persists the current fingerprints for future comparisons.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description thoroughly discloses behavior, including side effects: it reads from .veris/state.db, computes fingerprints, and persists current fingerprints for future comparisons. It also details edge cases like ignoring directory renames and distinguishing first observations from drift absence. With no annotations, this description fully carries the transparency burden.
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 well-structured, covering fingerprint definition, detection capabilities, and persistence in a logical flow. It is slightly lengthy due to technical detail, but every sentence adds value and none are redundant. Could be trimmed slightly, but overall concise for the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description explains the tool's behavior and side effects but does not specify the return format (e.g., a list of drift types). It mentions what is 'surfaced' but not the structure. Given the absence of an output schema, the description is largely complete, though a note on return shape would improve completeness.
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, and the schema contains no parameter descriptions. Since all (zero) parameters are covered, the baseline of 3 applies. The description does not need to add param semantics, and it does not, which 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: comparing current workflow fingerprints against prior runs. It specifies the exact computation (SHA-256 of member ids, edge signatures, and body hashes) and what outcomes it surfaces (added, removed, expanded, contracted, silently rewritten). This makes the purpose precise and distinguishes it from generic 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 explains what the tool does but does not explicitly state when to use it over alternatives. It implies usage for detecting drift, but does not compare with sibling tools like analyze_repository or analyze_pr_behavior, nor mention conditions that would favor this tool. Guidance is present implicitly but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Exports the behavioral graph as JSON. Nodes are classes, methods, constructors, accessors and top-level functions, each tagged with its inferred workflow domain; edges are DependsOn (containment and imports) and Invokes (call targets). Every edge carries a 'resolution' field: 'resolved' means the TypeScript checker identified the target, 'heuristic' means exactly one declaration matched by name, 'structural' means containment or import. Calls whose target is ambiguous produce no edge at all. Returns full counts plus up to 500 nodes and 1000 edges, with a 'truncated' field when the graph is larger.
| 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 transparency burden. It discloses the output format, node/edge semantics, resolution classification, and truncation behavior, but does not address side effects or permissions.
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 detailed yet tightly organized, covering all relevant output aspects without unnecessary padding. Each sentence adds meaningful information about nodes, edges, resolution, and limits.
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 description fully explains the output structure and limits, making the tool's behavior clear even without an output schema. It provides enough context for an agent to understand what the export contains and how results are formatted.
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 no parameters, so there is no ambiguity. The description focuses on the output and semantics, which is sufficient given the empty parameter 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 clearly states the tool exports the behavioral graph as JSON and details the node and edge types. It is specific and distinct from sibling tools like export_onboarding and analyze_repository.
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 explains what the tool does but does not explicitly state when to use it versus alternatives, nor does it mention any exclusions or conditions. No comparison to sibling tools is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Writes a workflow-first onboarding package under veris-reports/onboarding/: one markdown file per workflow describing its purpose, members, risks and suggested first reads, plus a README.md index. Returns the output directory and the paths written.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that it writes files and returns paths, which is a side effect. However, it does not mention whether it overwrites existing files, requires prior analysis, or any potential destructive actions. Given no annotations, this is partial transparency but not comprehensive.
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, consisting of two sentences that directly state the action and the return value. Every word contributes to understanding the tool's function, with no redundant or ambiguous 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?
The description provides sufficient detail about the output (file types, location, contents) and return value, making it usable without additional context. It lacks any mention of dependencies on other tools (e.g., analyze_repository) or environmental prerequisites, but for a tool with no inputs, 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?
There are no parameters in the schema, so there is nothing to explain. The description does not introduce any parameter-like concepts, and the absence of parameters means no additional semantic information is needed.
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 writes an onboarding package with specific contents (markdown files per workflow and a README.md index) and its location. It uses a specific verb 'writes' and describes the output structure, making the purpose unambiguous. It does not explicitly contrast with sibling tools, but the purpose is distinct enough.
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. The description does not mention any conditions, prerequisites, or scenarios where this tool is preferred, leaving the agent without direction on selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns concrete Tier-3 failure scenarios for the affected workflows, each paired with the invariant that must hold — for example 'submit charge twice with the same idempotency key inside 500ms; exactly one ledger entry'. Probes are selected from a curated per-domain library (concurrency, idempotency, retry storms, replay, partial failure, cache stampede, ordering); they are not generated from your code, so they name the failure mode rather than the specific call site. Returns up to 100.
| 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 carries the full burden. It discloses that it returns up to 100 probes, that they are selected from a curated per-domain library, and that they are not generated from the user's code. However, it does not mention side effects, permissions, rate limits, or whether the operation is read-only. For a generation tool, this is likely safe, but the description leaves these unstated.
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 (two sentences) and front-loaded with the primary action and an example. It avoids fluff but could be slightly more explicit about usage context. The structure is clear and 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?
With no output schema, the description must explain return values, and it does: 'Returns concrete Tier-3 failure scenarios... paired with the invariant... example... Returns up to 100.' However, it does not clarify what constitutes 'affected workflows' or how they are determined, which may be ambiguous without additional context. It also does not specify any prerequisites or error conditions.
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 schema is empty. The description does not need to explain parameters. Per the baseline rule for zero parameters, a score of 4 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 states a specific action: 'Returns concrete Tier-3 failure scenarios for the affected workflows, each paired with the invariant that must hold.' It provides a concrete example and explicitly contrasts itself with code-generated probes ('they name the failure mode rather than the specific call site'), which distinguishes it from sibling 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 implies usage for generating adversarial failure scenarios and clarifies that probes come from a library, but it does not explicitly state when to use this tool over alternatives (e.g., 'use when you need known failure modes' or 'use instead of analyze_workflow'). It does not provide exclusions or alternative tool names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generates a tiered verification plan for every impacted node. Tier 1 is structural (lint, schema, types), Tier 2 behavioral (contracts, integration boundaries), Tier 3 adversarial (concurrency, idempotency, retries, replay, partial failure). Directives are templates parameterized by node id — for concrete failure scenarios use generate_adversarial_probes instead. Returns tier counts plus up to 200 targets ranked by node risk, with a 'truncated' field when there are more.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the return structure (tier counts, up to 200 targets, a 'truncated' field) and the nature of directives as templates parameterized by node id. It stops short of stating whether the tool is read-only or has side effects, but as a plan generator that is implicit. The behavioral context provided is substantial, though not exhaustive.
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 efficiently organized: purpose first, then the tier definitions, then the directive detail and the alternative tool, and finally the return format. Every sentence adds value, 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?
Given there is no output schema and no parameters, the description explains the output format in enough detail (tier counts, ranked targets, truncation) and describes the tiers themselves. It also points to the alternative tool, leaving an agent with everything needed to call it 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?
The tool has zero parameters, so schema description coverage is effectively 100%. The rubric gives a baseline of 4 for zero-parameter tools, and the description correctly adds no parameter-specific detail because none exist.
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 ('generates') and a concrete resource ('tiered verification plan for every impacted node'). It immediately distinguishes itself from the sibling generate_adversarial_probes by name, making the tool's role unmistakable even without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when not to use this tool: 'for concrete failure scenarios use generate_adversarial_probes instead.' This gives a clear alternative and a condition that selects it, which is exactly what the rubric asks for. No other exclusions are needed given the distinct purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns verification coverage: how much of the planned work has supporting execution evidence, weighted by tier, decayed by age, and weighted by trust class (agent-asserted evidence counts for half). Also returns the count of failing and flaky targets, the highest single impacted-node risk, and the specific unverified assumptions (capped at 20). 'overallConfidence' is an alias of coverage retained for compatibility — it measures evidence, not the probability that the code is correct, and is not calibrated against observed outcomes. Coverage is reported as unknown, not 100%, when nothing was planned.
| Name | Required | Description | Default |
|---|---|---|---|
| executedTargetsCount | No | What-if override: model coverage as if this many targets had been executed. Only applies when persistent state is unavailable. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It transparently explains output semantics (overallConfidence is an alias, not a probability; coverage is unknown when nothing planned), and details the what-if override behavior. It does not explicitly state side effects, but the read-only nature is implied by the 'returns' language.
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 well-organized, packing necessary clarifications (alias meaning, weighting factors, edge cases) without redundancy. Every sentence adds value, and the structure flows logically from core functionality to caveats.
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 description covers the main outputs and edge cases (unknown when nothing planned, what-if override scope). While it does not enumerate all possible response fields or error conditions, the essential context for a caller—what the tool computes and when to use the parameter—is adequately provided.
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 single parameter executedTargetsCount has a clear, self-contained description explaining its purpose (what-if override) and its condition (only when persistent state is unavailable). Schema coverage is 100%, so no parameter is left undocumented.
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 returns verification coverage and related metrics (failing/flaky counts, risk, unverified assumptions). It also clarifies the meaning of overallConfidence and the unknown-coverage edge case, making the purpose unambiguous and distinguishing it from sibling tools like analyze_repository or generate_verification_plan.
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 some usage context, notably that executedTargetsCount is a what-if override only applicable when persistent state is unavailable. However, it does not explicitly compare with sibling tools or state when to prefer this tool over alternatives, leaving some ambiguity about its role in a workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Groups repository nodes into semantic domains (Authentication, Payments, Webhooks, Caching, Queue and 20 more) and returns per-workflow member counts, impact counts, risk aggregates, narrative and runtime-risk hypotheses. Classification is a weighted keyword vote over directory segments, import specifiers and symbol names — it does not traverse the call graph, so a workflow is a labelled set of declarations rather than an execution path. Nodes matching no rule are grouped as Uncategorized. Returns up to 50 workflows.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description fully discloses the classification mechanism, output contents, and the important limitation that workflows are treated as labelled declaration sets rather than execution paths. It also notes the 50-workflow limit and the Uncategorized grouping, leaving no ambiguity about side effects or 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?
The description is slightly long but every sentence adds meaningful information about behavior, limitations, and output. It is well-structured and free of 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 no-parameter tool, the description is complete: it states what it operates on, what it returns, how classification works, and its key limitation. It also specifies a result count limit, making the expected response clear.
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 no parameters and the input schema is empty, so there is nothing additional for the description to document. The description's mention of output fields and constraints compensates for the lack of parameter detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool groups repository nodes into semantic domains and returns per-workflow counts, risk aggregates, and hypotheses. It distinguishes this from deeper execution analysis by explicitly noting that it does not traverse the call graph.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context about what the tool returns and its limitations, such as the weighted keyword vote and lack of call-graph traversal. It does not explicitly name sibling alternatives, but the behavior is specific enough to guide appropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Timeline for one node: its risk and blast-radius values across previous runs, plus every execution-evidence record posted against it with result, tier, trust class, producer and timestamp. Use for forensics ('this function broke production — what does its history look like?') or to check whether a high-risk node has accumulated trustworthy passing evidence.
| Name | Required | Description | Default |
|---|---|---|---|
| nodeId | Yes | Node id. Format: 'relative/path.ts::Symbol' or 'relative/path.ts::Class::method'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries the burden of conveying behavior. It clearly indicates this is a retrieval operation (provides a timeline and records) with no mention of side effects or destructive actions. While it does not explicitly state 'read-only,' the language strongly implies a non-mutating query, which is transparent enough for a user to understand what to expect.
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, consisting of two sentences that succinctly summarize the tool's purpose and provide usage examples. It is well-structured, front-loading the core functionality and then adding practical context without any unnecessary words.
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 parameter and no output schema, the description provides sufficient context. It explains what the tool returns (timeline with risk, blast-radius, execution-evidence records, including specific fields) and when to use it. It does not leave essential gaps about the tool's function or expected behavior.
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 only parameter, nodeId, is described both in the schema and in the tool description. The schema gives the exact format ('relative/path.ts::Symbol' or 'relative/path.ts::Class::method'), and the description clarifies that a node is a function or method. This fully explains the parameter's meaning and expected values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool provides a timeline for a single node, including risk and blast-radius values across previous runs and execution-evidence records. It also gives concrete use cases ('forensics' and checking for trustworthy passing evidence), making the purpose unambiguous and distinct from sibling tools that analyze broader aspects.
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 explicitly says 'Use for forensics...' and 'or to check whether a high-risk node has accumulated trustworthy passing evidence,' providing direct guidance on when to employ this tool. It implies the context (investigating past behavior of a specific node) and differentiates from other tools that might handle multiple nodes or perform different analyses.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Adds a repository to the user-level registry at ~/.veris/registry.json so cross_repo_snapshot includes it. The path must exist, be a directory, and contain a .git directory. Setup-time call, typically run once per repository.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Human-readable name shown in snapshots. | |
| path | Yes | Absolute path to the repository root. | |
| tags | No | Optional grouping tags, e.g. ['prod','checkout']. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses side effects (writes to ~/.veris/registry.json) and prerequisites (path must exist, be a directory, contain .git). This goes beyond the schema and gives the agent essential behavioral context. It doesn't mention error handling or overwrite semantics, but for a one-time setup call this is acceptable.
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: first states purpose and effect, second lists constraints and timing. All information is front-loaded, no filler, and every clause 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?
For a simple registration tool, the description covers what, where, prerequisites, and when to use. No output schema is needed, and an agent has all information required to call it correctly without additional inference.
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 descriptive parameter comments. The description adds meaningful constraints on the path parameter (must exist, be a directory, contain .git), which is critical for correct invocation. This goes beyond the schema's basic 'Absolute path to the repository root'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Adds'), a resource (repository to user-level registry), the target file path, and the downstream effect (included in cross_repo_snapshot). Clearly distinguishes from sibling tools like cross_repo_snapshot, which consumes the registry, and 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?
Explicitly calls out 'Setup-time call, typically run once per repository,' giving clear timing and frequency guidance. While it doesn't list alternative tools for comparison, the setup vs. usage distinction is sufficient and directly implied by the description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Posts verification results back to Veris. Evidence is append-only and hash-chained: a later record for the same target is added alongside the earlier one, never replacing it, so a failure cannot be overwritten by a subsequent pass. Each record carries a trust class — 'agent-asserted' (default; the caller's own claim, counts at half weight), 'harness-observed' (an external runner observed it), or 'veris-derived' — and a producer identity. Accepts a batch, written in one transaction: if any entry is invalid, none are recorded.
| Name | Required | Description | Default |
|---|---|---|---|
| executions | Yes | Batch of results. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does so well. It explicitly discloses append-only and hash-chained behavior, atomic batch semantics, trust-class defaults, and the fact that failures cannot be overwritten. This gives an agent accurate expectations about side effects and data integrity.
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 compact and front-loaded with the primary purpose, followed by important behavioral constraints. It avoids redundant wording, though the dense explanation of trust classes and atomicity could be slightly streamlined 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?
The description covers critical side effects, trust-class semantics, and batch atomicity, but does not explain how nodeId relates to an existing verification plan or when this tool should be invoked relative to other verification workflow steps. It is sufficient for basic use but lacks some surrounding workflow 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 clarifies the top-level executions batch, tier labels must match a planned tier, and producer identity. However, key nested properties like nodeId, directive, workflowId, and result values are not explicitly explained beyond the schema's types and enums, leaving some ambiguity for callers.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence, 'Posts verification results back to Veris', uses a specific verb and object, clearly identifying the tool's function. It also distinguishes this from planning/analysis tools by focusing on recording execution results rather than generating plans or detecting drift.
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 does not explicitly state when to use this tool versus alternatives like generate_verification_plan or identify_unverified_behaviors. It implies use for recording results, but lacks direct guidance or conditions for choosing it over sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Counterfactual: removes the named nodes from the head graph, recomputes the diff and risk against the real baseline, and reports what changes. Answers 'what recovers if I revert this?'. Models deletion only — it cannot model reverting a modified body back to its prior form. Requires a resolvable baseline; returns an error rather than a fabricated one.
| Name | Required | Description | Default |
|---|---|---|---|
| nodeIds | Yes | Node ids to remove. Format: 'relative/path.ts::Symbol' or 'relative/path.ts::Class::method', as returned by export_behavioral_graph. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description transparently explains the operation: removing nodes, recomputing diff and risk, and reporting changes. It also discloses failure behavior (returns an error) and prerequisites (resolvable baseline). The counterfactual nature is explicitly labeled, avoiding misinterpretation as a destructive mutation.
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 yet information-dense. Each sentence contributes meaningful content: purpose, scope limitation, prerequisite, and failure behavior. There is no redundancy or unnecessary detail.
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 description provides complete context for an agent to decide when and how to use the tool: it defines the counterfactual scenario, specifies the exact operation, clarifies limitations, states requirements, and explains error handling. No critical information is missing.
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 nodeIds parameter, including its type and format. The description does not add additional semantic detail beyond referring to 'named nodes', which is already covered. With 100% schema coverage, the baseline of 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 clearly states the tool's purpose: it removes named nodes from the head graph, recomputes diff and risk against the baseline, and reports changes. It also explicitly frames itself as a counterfactual analysis answering a specific question, which distinguishes it from other 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 direct usage guidance by stating the question it answers ('what recovers if I revert this?') and clearly delimits its scope: it models deletion only and cannot handle reverting modified bodies. It also states the prerequisite of a resolvable baseline and the failure behavior (returns an error rather than fabricating).
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.
v3.0.1allocate_budget1 field changedInput schema / properties / minutes / descriptionPrevious value: -"Total minutes available for verification work. Typical values: 5 (quick PR check), 15 (default), 60 (pre-release sweep)."New value: +"Minutes available. Typical: 5 (quick check), 15 (default), 60 (pre-release sweep)."analyze_pr_behavior1 field changedInput schema / properties / baseRef / descriptionPrevious value: -"Git ref to diff against. Defaults: origin/main → main → HEAD~1. Example: 'origin/develop' or a commit SHA."New value: +"Git ref to find the merge-base against. Example: 'origin/develop' or a commit SHA."analyze_workflow1 field changedInput schema / properties / workflowId / descriptionPrevious value: -"Workflow identifier from list_workflows (e.g., 'payments', 'authentication', 'webhooks')."New value: +"Workflow identifier from list_workflows (e.g. 'payments', 'authentication')."confidence_history1 field changedInput schema / properties / limit / descriptionPrevious value: -"Maximum number of runs to return. Defaults to 20."New value: +"Maximum runs to return. Default 30, maximum 100."identify_unverified_behaviors1 field changedInput schema / properties / executedTargetsCount / descriptionPrevious value: -"Override the count of executed verification targets used in the math. Useful for what-if scenarios or when execution data lives outside Veris state.db."New value: +"What-if override: model coverage as if this many targets had been executed. Only applies when persistent state is unavailable."node_history1 field changedInput schema / properties / nodeId / descriptionPrevious value: -"Full node identifier. Format: 'absolute-path::SymbolName' or 'absolute-path::Class::method'."New value: +"Node id. Format: 'relative/path.ts::Symbol' or 'relative/path.ts::Class::method'."register_repo3 fields changedInput schema / properties / name / descriptionPrevious value: -"Human-readable repo name. Shown in cross-repo snapshots."New value: +"Human-readable name shown in snapshots."Input schema / properties / path / descriptionPrevious value: -"Absolute filesystem path to the repository root."New value: +"Absolute path to the repository root."Input schema / properties / tags / descriptionPrevious value: -"Optional tags for grouping (e.g. ['frontend','prod','checkout-flow'])."New value: +"Optional grouping tags, e.g. ['prod','checkout']."report_execution4 fields changedInput schema / properties / executions / descriptionAdded value: +"Batch of results."Input schema / properties / executions / items / properties / producerAdded value: +{
+ "description": "Who produced this result, e.g. 'github-actions:test' or an agent name.",
+ "type": "string"
+}Input schema / properties / executions / items / properties / tier / descriptionAdded value: +"Tier label, e.g. 'Tier 1 - Structural Verification'. Must match a planned tier."Input schema / properties / executions / items / properties / trustClassAdded value: +{
+ "enum": [
+ "veris-derived",
+ "harness-observed",
+ "agent-asserted"
+ ],
+ "type": "string"
+}what_if_revert1 field changedInput schema / properties / nodeIds / descriptionPrevious value: -"Node identifiers to remove from the head graph for the counterfactual simulation. Format: 'filepath::SymbolName' or 'filepath::Class::method'. Get them from export_behavioral_graph."New value: +"Node ids to remove. Format: 'relative/path.ts::Symbol' or 'relative/path.ts::Class::method', as returned by export_behavioral_graph."v2.1.10allocate_budget1 field changedInput schema / properties / minutes / descriptionAdded value: +"Total minutes available for verification work. Typical values: 5 (quick PR check), 15 (default), 60 (pre-release sweep)."analyze_pr_behavior1 field changedInput schema / properties / baseRef / descriptionAdded value: +"Git ref to diff against. Defaults: origin/main → main → HEAD~1. Example: 'origin/develop' or a commit SHA."analyze_workflow1 field changedInput schema / properties / workflowId / descriptionAdded value: +"Workflow identifier from list_workflows (e.g., 'payments', 'authentication', 'webhooks')."identify_unverified_behaviors1 field changedInput schema / properties / executedTargetsCount / descriptionAdded value: +"Override the count of executed verification targets used in the math. Useful for what-if scenarios or when execution data lives outside Veris state.db."node_history1 field changedInput schema / properties / nodeId / descriptionAdded value: +"Full node identifier. Format: 'absolute-path::SymbolName' or 'absolute-path::Class::method'."register_repo3 fields changedInput schema / properties / name / descriptionAdded value: +"Human-readable repo name. Shown in cross-repo snapshots."Input schema / properties / path / descriptionAdded value: +"Absolute filesystem path to the repository root."Input schema / properties / tags / descriptionAdded value: +"Optional tags for grouping (e.g. ['frontend','prod','checkout-flow'])."what_if_revert1 field changedInput schema / properties / nodeIds / descriptionAdded value: +"Node identifiers to remove from the head graph for the counterfactual simulation. Format: 'filepath::SymbolName' or 'filepath::Class::method'. Get them from export_behavioral_graph."v0.1.0confidence_history1 field changedInput schema / properties / limit / descriptionAdded value: +"Maximum number of runs to return. Defaults to 20."allocate_budgetanalyze_pr_behavioranalyze_repositoryanalyze_workflowconfidence_historycross_repo_snapshotdetect_driftexport_behavioral_graphexport_onboardinggenerate_adversarial_probesgenerate_verification_planidentify_unverified_behaviorslist_workflowsnode_historyregister_reporeport_executionwhat_if_revertScored across 17 tools
Tool purposes are mostly distinct and clearly described, with analyze_* and generate_* prefixes differentiating targets. A few names like cross_repo_snapshot vs analyze_repository could require reading descriptions, but overlap is minimal.
Most tools follow a verb_noun pattern (register_repo, analyze_repository, list_workflows), but several are noun phrases (cross_repo_snapshot, confidence_history, node_history) and one is a question phrase (what_if_revert). The pattern is readable but not fully consistent.
At 17 tools, the surface is slightly above the typical 3-15 range, but each tool addresses a distinct part of the verification workflow. The count feels a bit heavy yet justifiable for the domain.
The toolset covers setup, analysis, planning, reporting, history, and onboarding comprehensively. It lacks an obvious direct 'execute verification' tool, but the server appears focused on planning, analysis, and evidence recording rather than test execution.
Writes adversarial test suites for AI-built code. Your agent's test engineer.
Code intelligence platform for AI agents. 20 tools for architecture, security & impact analysis.
Project registry, behavioral specs, and engineering threads for AI coding agent workflows.
Zero-config MCP security scanner for AI-generated apps. 25K+ vulnerability patterns.
