Analyzes Dockerfiles for infrastructure and security issues as part of the whole-program code analysis.
Analyzes Kubernetes YAML manifests for configuration and security issues within the codebase analysis.
Integrates with a local Ollama model to make keep/delete/deprecate decisions on ambiguous analysis findings.
Analyzes Terraform configuration files for infrastructure and security issues within the codebase analysis.
Verum is a deterministic, whole-program code analyzer. It maps a codebase into a single intermediate representation - symbols, call graph, routes, data flows - then runs a set of analyses over that map: dead code, duplicates, taint-based security checks, complexity, naming, and infrastructure (Kubernetes, Dockerfile, Terraform). It's a single static binary with no build step and no language server, so it runs on a fresh checkout in a fraction of a second.
Same input, same output. Every symbol id, finding, and report is derived from a stable hash of the source, so two runs on the same tree produce byte-identical results. That makes Verum usable as a CI gate, a baseline you can diff against, and a fact layer that tools and agents can rely on.
Supported languages: PHP, Rust, JavaScript, TypeScript, Python, Go, and Java, plus Kubernetes YAML, Dockerfiles, and Terraform.
Related MCP server: Ferret MCP
cargo install verum # compile from crates.io
cargo binstall verum # or grab the prebuilt binary, no compile
docker run --rm -v "$PWD:/work" ghcr.io/ibmark/verum audit . # or no installPrebuilt binaries for Linux (gnu/musl), macOS (x86_64/arm64), and Windows are attached to each release.
cargo install builds a verum binary on your PATH (Verum builds on stable Rust
1.82 or newer). To build from a checkout instead, use
cargo install --path crates/verum. For a static Linux binary you can copy
anywhere:
cargo build --release --target x86_64-unknown-linux-muslThe same crate is a library. Add verum as a dependency to parse a tree into
the IR and run the analyses programmatically:
use verum::{Atlas, AtlasConfig, Prism, Standard};
let ir = Atlas::new(AtlasConfig { root: ".".into(), ..Default::default() }).build()?;
let result = Prism::analyse(&ir, &Standard::default())?;
println!("score: {}", result.score.overall);verum analyse <path> # map the code into the IR - symbol/call/route counts
verum audit <path> # map + analyse - findings and a score, no changes
verum clean <path> # audit + preview the dead-code/duplicate fixes
verum map <path> # module/symbol graphs, cycles, SPOFs, data flows
verum gate <path> # exit non-zero if the deploy-gate thresholds fail
verum baseline <path> # snapshot findings so gate only fails on new ones
verum report <path> # markdown | json | sarif | a self-contained html report
verum explain [kind] # what a finding kind means, why it matters, how to fix it
verum init [path] # write a default verum.standard.jsonaudit scores the code and lists findings by severity, and prints the offending
source line with two lines of context under each one. clean reports the fixes
it would apply - symbols with no caller, duplicate bodies to remap - and
identifies each by file and line. It runs report-only and does not modify your
files; treat its output as a worklist to apply by hand.
verum explain <kind> prints what a detector looks for, the concrete
consequence of ignoring it, a flagged and a fixed example, and when suppressing
it is a defensible call. It takes the name as reported or its kebab alias:
verum explain NonConstantTimeComparison
verum explain non-constant-time-comparison
verum explain # every kind, one line eachThe same entries, for every detector Verum has, are in
docs/detectors.md. That file is generated from the table
the command reads (verum explain --all --format markdown), so the docs and the
tool cannot disagree.
report counts every file - total, code, comment and blank lines - and rolls
the counts up per language and per top-level directory. Alongside them it walks
the resolved call graph from the test suite and reports, per file and overall,
how many functions a test provably reaches, plus the files that no test reaches
at all.
That number is reachability, not coverage. It says what the tests demonstrably reach by name; it cannot see code driven through trait dispatch, generics or macros, and a reachable function need not actually run. Verum never runs your tests and never invents a coverage figure.
When you have measured coverage, hand it over and it supersedes the estimate:
verum report . --coverage lcov.infoThe file is read in lcov format (DA/FN/FNDA records, as written by
cargo llvm-cov --lcov, nyc, pytest-cov or gcov). The measured numbers
appear in the report labelled as measured and replace reachability in the score.
A coverage file that does not parse is an error, never a silent zero.
verum gate <path> exits 1 when the deploy-gate thresholds fail and 0 when
they pass, so a pipeline can rely on the exit code rather than parsing output.
verum report <path> --format json emits the findings and score as JSON for a
dashboard or a custom check.
# .github/workflows/verum.yml
name: verum
on: [push, pull_request]
jobs:
gate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: IBMark/verum-action@v1 # runs `verum gate .` by defaultOn an existing codebase, snapshot the current findings once with
verum baseline . and commit the result; the gate then fails only on findings
that are new relative to that baseline, so you can adopt it without first
fixing everything it reports.
verum report <path> --format sarif emits SARIF 2.1.0, so findings show up as
inline pull-request annotations and in the repository's Security tab:
- run: verum report . --format sarif --out verum.sarif
- uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: verum.sarifverum mcp <path> serves the analysis as an MCP tool server over stdio, so an
agent can query the map instead of grepping. It exposes the call graph
(callers_of, callees_of, impact_of), dead_code, duplicates, audit,
audit_delta (findings only in files changed vs a git ref), and endpoints
(which client HTTP calls hit which routes). The map is re-checked against the
tree's mtimes on each call, so answers track your edits.
Any MCP-capable client can connect over stdio. For example, with Claude Code:
claude mcp add verum -- verum mcp /path/to/projectRegistry listing (the token below is how the official MCP registry verifies this crate belongs to the listed server):
mcp-name: io.github.ibmark/verum
docs/agents.md is the command reference written to be read
in-context by an agent: one screen per command with when to use it, the exact
invocation, the JSON schema field by field, the exit codes, and a worked example
of real output. A test asserts every flag it documents against --help, so it
cannot drift from the CLI.
integrations/ holds ready-to-copy configuration for the
places code actually changes - a Claude Code PostToolUse hook and MCP
registration, a Cursor rule, a pre-commit hook, and a GitHub Actions workflow
that uploads SARIF and runs the gate. Every snippet is syntax-checked in CI.
Verum parses every supported language into one IR, so a fetch('/api/users') in
a TypeScript frontend links to the route handler that serves it - even when that
handler is in another language. verum mcp's endpoints tool reports the
matches, plus frontend calls that hit no route (likely 404s) and routes that no
client calls (possibly dead).
verum full can send the ambiguous findings - the ones deterministic analysis
can't resolve on its own - to a language model for a keep/delete/deprecate
decision. It's provider-neutral: it speaks the OpenAI-compatible chat API and is
configured entirely through the environment, so it works with a hosted API or a
local runner (ollama, llama.cpp, vLLM, LM Studio). Nothing is contacted unless
you set an endpoint.
export VERUM_AI_ENDPOINT="http://localhost:11434/v1/chat/completions"
export VERUM_AI_MODEL="qwen2.5-coder"
verum full <path>verum init writes verum.standard.json - analysis thresholds, per-language
naming rules, the weak-crypto allowlist, and the deploy-gate limits. Everything
has a sensible default, so the file is optional.
files -> map (mappa) -> IR -> analyse (lumen) -> findings + score
-> plan (faber) -> fix worklistmappa parses files in parallel via tree-sitter and merges them into one IR.
Ids are a stable FNV-1a hash of the path, which keeps them reproducible and lets
files be parsed independently without a shared counter. lumen runs the
analyses over the merged IR; faber turns the safe findings into a concrete
list of edits (report-only in this release).
The workspace splits along that pipeline: verum-nucleus (shared IR and finding
types), verum-mappa (parsers), verum-lumen (analyses), verum-faber (fix
planner), verum-arbiter (optional AI layer), and verum (the binary and the
library facade).
Dual-licensed under either of
Apache License, Version 2.0 (LICENSE-APACHE)
MIT License (LICENSE-MIT)
at your option.
Call after finishing an edit, and before telling the user the work is done. Runs the full deterministic audit - security, dead code, duplicates, naming, complexity, infrastructure - and returns the score plus the findings with file:line, severity and a suggested fix. Use min_severity to cut noise. For a diff-sized answer, prefer audit_delta.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max findings listed (default 100); `total_findings` and `by_severity` are always exact. | |
| min_severity | No | Only findings at or above this severity. Use "high" to see just what must be fixed. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations already declaring readOnlyHint, idempotentHint, and destructiveHint, the description adds meaningful context: it is deterministic, runs a full audit, and returns a score plus findings with file:line, severity, and suggested fixes. No contradiction with annotations.
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 with no filler. The when-to-use instruction is front-loaded, the tool's purpose and output are compactly described, and the sibling routing and parameter tip are placed in the final sentence.
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 when to use it, what it scans, what it returns, how to filter results, and when to use the sibling tool instead. Given the read-only annotations and fully documented schema, nothing essential 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?
Schema description coverage is 100%, so the schema already documents both limit and min_severity. The description adds one practical tip about min_severity cutting noise, but does not materially extend the schema's parameter explanations.
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 runs the full deterministic audit across security, dead code, duplicates, naming, complexity, and infrastructure, and returns a score plus findings. This is a specific verb-resource pairing and it is distinguished from audit_delta, its most similar sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to call it: after finishing an edit and before telling the user work is done. It also gives a concrete alternative — prefer audit_delta for a diff-sized answer — plus guidance on using min_severity to cut noise.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Call to judge your own diff, or to review a branch, without wading through pre-existing findings. Returns only the findings in files changed versus a git ref (uncommitted and untracked files included). The whole tree is still analysed, so cross-file facts like dead code stay correct.
| Name | Required | Description | Default |
|---|---|---|---|
| git_ref | Yes | Base git ref to diff against, e.g. "HEAD" for uncommitted work or "origin/main" for a branch. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnly, idempotent, non-destructive), the description adds valuable behavioral details: uncommitted and untracked files are included, the entire tree is still analyzed, and cross-file facts like dead code remain accurate. This meaningfully explains what the user should expect without contradicting any annotations.
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 compact sentences, each earning its place: the first states the use case, the second defines the output scope, and the third explains the whole-tree analysis nuance. The most important differentiator is front-loaded, and there is no 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 single-parameter tool with full schema coverage and safety annotations, the description covers the scope, inputs, and behavioral nuances sufficiently. There is no output schema, but the description clearly communicates that the tool returns findings scoped to changed files, which is enough for correct 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 already documents git_ref well, including examples like HEAD and origin/main, and coverage is 100%. The description does mention diffing 'versus a git ref' and untracked files, but it adds little semantic meaning beyond what the schema provides, so the baseline score 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 action: 'judge your own diff, or to review a branch' and precisely defines its output as 'only the findings in files changed versus a git ref.' It also distinguishes itself from the sibling audit-style tools by emphasizing the diff-scoped nature, so an agent can tell it apart from tools like audit or dead_code.
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 explicit use cases: reviewing your own diff or reviewing a branch, and explains the benefit of avoiding pre-existing findings. It does not explicitly name alternatives or state when not to use the tool, but the clear diff-focused context is enough to route an agent appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Call to understand what a function does without reading its body, or to find its dependencies. Returns resolved callees with call sites, plus the unresolved names (external crates, stdlib) and dynamic calls it makes.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Symbol name - short (`getUserById`) or fully qualified (`App\Helpers\UserHelper::getUserById`). An ambiguous short name is refused with the candidate list; re-ask with one of those. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only, idempotent, non-destructive behavior. The description adds useful behavioral detail about the return value: it returns resolved callees with call sites, unresolved external/stdlib names, and dynamic calls, which sets expectations about completeness and 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 two sentences, front-loaded with the primary purpose, and each sentence adds meaningful information: why to call it and what it returns. There is no repetition 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 single-parameter, read-only tool with no output schema, the description is complete enough. It explains the purpose, the returned content, and the limits of resolution (unresolved and dynamic calls), while the schema covers parameter behavior and annotations cover safety.
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 query parameter is already well documented with examples and ambiguity handling. The tool description adds no further parameter semantics beyond what the schema provides, so the baseline score of 3 applies.
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 purpose ('understand what a function does without reading its body, or to find its dependencies') and clearly identifies the returned resource: resolved callees with call sites, plus unresolved names and dynamic calls. This makes it easily distinguishable from the sibling callers_of and references_of 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 gives clear context for when to use the tool: to understand a function's behavior without reading its body, or to discover dependencies. It does not explicitly exclude alternatives like callers_of or references_of, but the purpose is distinct enough that an agent can infer the right choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Call to answer "who uses this?" one level up. Returns the direct callers with exact call sites (file:line) from the resolved call graph - facts, not guesses. For the full blast radius use impact_of; for dynamic-dispatch hits too use references_of.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Symbol name - short (`getUserById`) or fully qualified (`App\Helpers\UserHelper::getUserById`). An ambiguous short name is refused with the candidate list; re-ask with one of those. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds valuable context beyond this: it returns only direct callers, provides exact file:line call sites, and is based on the resolved call graph rather than guesses. This is genuine disclosure of behavioral traits.
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, each earning its place: what it returns, how it behaves, and when to choose siblings instead. The core value is front-loaded and there is no 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 single-parameter tool with a fully described schema and strong annotations, the description is complete. It covers the return content, the granularity (direct callers, exact call sites), and the key alternative tools, leaving no important gap for an agent deciding or invoking the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and thoroughly documents the query parameter, including short and fully qualified names and the ambiguous-name refusal behavior. The description's 'one level up' phrasing slightly reinforces the query's meaning, but it does not add material semantic value 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 states a specific verb and resource: returns direct callers with exact call sites (file:line) from the resolved call graph. It also differentiates this tool from siblings like impact_of and references_of, making its scope clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly frames when to use this tool: to answer 'who uses this?' one level up. It even gives alternatives for adjacent cases: use impact_of for full blast radius and references_of for dynamic-dispatch hits, which is strong routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Call before deleting code, or when asked what is unused. Returns the symbols with no resolved caller, no name-match caller, and no path from any entry point, each with a confidence score - dynamic dispatch and reflection lower it, so check anything below ~0.9 by hand.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial behavioral detail beyond the read-only and idempotent annotations: it defines what counts as dead code, explains that dynamic dispatch and reflection reduce confidence, and advises manual review below ~0.9. This gives the agent realistic expectations about the tool's heuristic nature and 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 one dense sentence that front-loads the call trigger ('Call before deleting code, or when asked what is unused') followed by output semantics and a practical caveat. Every clause earns its place, and there is no redundant or ornamental language.
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 input parameters and no output schema, the description carries the full burden of explaining the tool. It adequately explains what is returned (unused symbols with confidence scores) and how to interpret the result (check below 0.9). The tool is fully usable from this description alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and schema coverage is 100%, so there are no parameter semantics to document. The description appropriately focuses on output meaning rather than inputs. Baseline 4 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 tool's function: it returns symbols with no resolved caller, no name-match caller, and no path from any entry point, each with a confidence score. This is a specific verb-plus-resource definition that makes the core purpose obvious. It does not explicitly name sibling tools for comparison, so it stops short of full differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit triggers: 'Call before deleting code, or when asked what is unused.' This tells an agent when to invoke the tool. It does not mention alternatives or exclusions, so it misses the opportunity to route agents away from similar analysis tools like impact_of or callers_of.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Call to jump to where a symbol is defined before reading or editing it. Returns the definition sites with file:line, plus a provenance field saying whether the match was exact (fully qualified), exact (short name), or a substring fallback - so you know how much to trust it.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Symbol name or name fragment. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (read-only, idempotent, non-destructive), the description discloses the return structure: definition sites with file:line and a provenance field explaining match trust. This adds meaningful behavioral detail not available elsewhere.
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 fluff. The first sentence states purpose and timing; the second explains return format and trust meaning. It is front-loaded and 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?
For a single-parameter read-only tool with no output schema, the description is complete: it covers purpose, usage timing, return format, provenance semantics, and trust considerations. No essential 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 schema already documents 'query' as a symbol name or fragment (100% coverage). The description adds meaning by explaining that substring fallback can happen and that provenance indicates match reliability, which enriches the parameter 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 tool jumps to where a symbol is defined, a specific action and resource. It also distinguishes itself from sibling reference, caller, and callee tools by focusing on definition sites and their provenance.
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 clear usage context: call this before reading or editing a symbol to locate its definition. It does not explicitly name alternative tools or exclusion conditions, but the situational guidance is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Call before adding a helper, to check one already exists, or when consolidating repeated logic. Returns groups of duplicate implementations - exact, renamed (identifier-insensitive), and structural - each with a canonical pick to keep, the copies to remap onto it, and a confidence score.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as read-only, idempotent, and non-destructive. The description adds meaningful behavioral detail by specifying the output categories (exact, renamed, structural), the canonical pick, remapped copies, and confidence score, which goes beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, information-dense sentence that front-loads the usage context and then describes the output structure without waste. Every clause contributes: when to call, what it returns, and how results are categorized.
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 read-only tool, the description is complete. It covers the trigger conditions, the analytical scope (duplicate implementations), the three detection flavors, and the actionable output (canonical pick, remap targets, confidence). No output schema exists, so this description adequately fills that 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 tool has zero parameters, so there is no parameter burden on the description. The description fully conveys what the operation analyzes and returns, satisfying the baseline for parameterless tools.
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 clear purpose: detect duplicate implementations before adding a helper or when consolidating logic. It distinguishes itself from siblings like find_symbol and dead_code by describing exact, renamed, and structural duplicate groups with canonical picks and confidence scores.
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 when-to-use scenarios: before adding a helper to check for existing duplicates, or when consolidating repeated logic. It does not name when-not-to-use or discuss alternatives among siblings, but the context is clear enough for an agent to select it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Call when changing an API route or a client fetch, or to check a frontend and backend still agree. Matches client HTTP calls (fetch/axios) to the route handlers that serve them across the language boundary, and returns the calls that hit NO route (likely 404s or typos) and the routes NO client calls (possibly dead) - findings a single-language tool cannot produce.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare the tool read-only and idempotent, and the description adds meaningful behavioral detail: it matches calls across the language boundary and returns two categories of findings (calls with no route, routes with no calls), including interpretive hints like likely 404s and possibly dead routes.
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 purposeful sentences: the first front-loads when to use it, the second explains what it computes and why that is valuable. 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 zero-parameter read-only analysis tool, the description fully explains what the agent needs to decide when to invoke it and what kind of results it will produce, even without 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?
The tool has zero parameters, so parameter semantics are a non-issue. The baseline of 4 applies because there is no parameter burden and the schema coverage is trivially complete.
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 precise action: matching client HTTP calls to route handlers across the language boundary. It clearly distinguishes itself from single-language tools by producing cross-boundary findings, and the scope is 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 opens with explicit trigger conditions: when changing an API route, when changing a client fetch, or when verifying frontend/backend agreement. It also contrasts itself with single-language tools, implying when those alternatives are insufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Call instead of grepping when you know part of a name but not where it lives. Matches exactly first, then by substring; returns kind, file:line, visibility, and entry-point status for each match, plus the total match count.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max symbols listed (default 20); `total_matches` is always exact. | |
| query | Yes | Name or name fragment. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses useful behavioral details beyond the annotations: exact matches are returned first, then substring matches, and each result includes kind, file:line, visibility, and entry-point status. Annotations already declare read-only, idempotent, non-destructive behavior, and the description adds matching semantics without contradicting them.
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 short sentences with no filler. The primary instruction and use case are front-loaded, followed by the essential behavioral and output details, making it easy for an agent to parse quickly.
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 two-parameter lookup tool, the description is complete: it explains when to use it, what inputs mean, what output fields to expect, and the total match count behavior. With no output schema, describing the return shape in prose is sufficient here.
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 the baseline is 3, but the description adds meaning by explaining matching precedence ('exactly first, then by substring') and emphasizing that the total match count is always exact even when results are limited. The limit parameter's default and behavior are already covered by 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 a specific verb and resource: call this tool when you know part of a name and want to locate the symbol. It also explains the matching behavior and return fields. However, it does not explicitly differentiate itself from sibling symbol-focused tools like definition_of, references_of, or callers_of.
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 an explicit when-to-use rule ('when you know part of a name but not where it lives') and names an alternative ('instead of grepping'). It does not state when-not-to-use relative to the sibling tools, so agents are left to infer that exact-definition or reference lookups would go elsewhere.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Call before a breaking change to size its blast radius. Returns every symbol that transitively reaches this one and the files they live in - the set that could break if it changes, and the set worth reviewing or testing after. The symbol list is capped at 100; the count and file list are exact.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Symbol name - short (`getUserById`) or fully qualified (`App\Helpers\UserHelper::getUserById`). An ambiguous short name is refused with the candidate list; re-ask with one of those. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnly, idempotent, and non-destructive safety. The description adds meaningful behavioral detail beyond that, including the exactness of the count and file list and the 100-symbol cap. This helps set expectations without contradicting the annotations.
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 no filler. The when-to-use guidance is front-loaded, followed by the precise return semantics and the cap/exactness caveat.
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 one well-documented parameter, rich annotations, and no output schema, the description fully covers what the agent needs: the use case, result set, file association, and truncation behavior. The ambiguity-refusal behavior is already in the schema, so nothing critical 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?
Schema coverage is 100%, and the schema already explains short vs. fully qualified names and the ambiguous-name refusal behavior. The description adds no new parameter-level semantics, so a 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 uses a specific verb and resource: 'Returns every symbol that transitively reaches this one and the files they live in,' clearly defining impact analysis. It also states the use case ('Call before a breaking change to size its blast radius'), which distinguishes it from direct-reference siblings like callers_of, callees_of, and references_of.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit when-to-use guidance: 'Call before a breaking change to size its blast radius.' It does not explicitly name alternative tools or give when-not-to-use conditions, but the transitive impact framing makes the intended context clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Call first in an unfamiliar repository, before planning any change. Returns size, languages, call-graph shape (resolution rates, critical depth, the most central symbols by PageRank), the overall score, and the finding count.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds useful behavioral context by enumerating the computed outputs, including unusual details such as PageRank-based central symbols and resolution rates, going beyond the structured hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence delivers the usage instruction first, then the output summary. Every clause adds information, with no filler or redundant restatement of the tool name.
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 input schema and no output schema, the description carries the full burden of explaining what the tool returns; it does so by listing the key output dimensions. For a zero-parameter overview tool, this is complete and actionable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so no parameter documentation is required. The description clarifies that the tool operates over the entire repository, which is the only meaningful semantic 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 identifies the tool's purpose: a first-call repository overview that reports size, languages, call-graph shape, overall score, and finding count. It uses a specific resource ('repository') and differentiates itself from the more targeted sibling tools by being the entry-point summary.
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 first phrase 'Call first in an unfamiliar repository, before planning any change' explicitly states when to use this tool. This positions it as a preface to the more specific sibling tools and gives an agent a clear decision rule.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Call ONLY when the user asks about performance - it is advisory, not scored, and noisy otherwise. Returns the constructs that hurt the chosen objective (hot-path allocations, locks, unbounded channels, blocking-in-async), ranked by impact, each with locations and a concrete design fix such as a bounded ring buffer in place of an unbounded channel. Tuned for Rust; other languages give limited signal.
| Name | Required | Description | Default |
|---|---|---|---|
| profile | No | What to optimise for; `realtime` means latency plus determinism. Defaults to all. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only, idempotent, non-destructive behavior; the description goes further by revealing that results are advisory, ranked by impact, and include locations and concrete design fixes. It also discloses the noisy failure mode when misused, adding meaningful context beyond the annotation flags.
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 cover usage, output, and limitations with no repetition or fluff. The most important instruction ('Call ONLY when ...') is front-loaded. Excellent balance of brevity and information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With one self-documenting parameter and strong annotations, the description covers the essential output format (ranked constructs with locations and fixes) despite lacking an output schema. It also provides critical operational context (noisy outside performance, language limitations). Nothing needed for an agent to decide to call and interpret results 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 schema already documents the single `profile` parameter fully, including its enum values and default, giving 100% coverage. The description does not add parameter-specific detail, which is acceptable but not additive. Baseline 3 is appropriate since the schema carries the full semantic load.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: it returns performance-impacting constructs with locations and fixes, and is explicitly advisory rather than scored. It clearly distinguishes itself from sibling analysis tools by limiting itself to performance questions and noting noise otherwise.
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 directs when to call: 'Call ONLY when the user asks about performance' and warns that it is 'noisy otherwise.' It adds a language constraint (tuned for Rust, other languages give limited signal) that helps avoid wasted calls. It does not name alternative sibling tools, but the when/when-not boundary is unmistakable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Call before renaming, changing a signature, or deleting a symbol. Returns resolved_references (exact call-graph edges with file:line) and name_match_references (dynamic or unresolved calls with the same final name) separately, so high- and low-confidence hits stay distinguishable.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Symbol name - short (`getUserById`) or fully qualified (`App\Helpers\UserHelper::getUserById`). An ambiguous short name is refused with the candidate list; re-ask with one of those. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds meaningful behavioral context by distinguishing exact resolved references from low-confidence name-match references, and by implying ambiguous queries are refused until disambiguated. This goes beyond the structured annotations.
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 most important usage instruction. The second sentence adds necessary output details without redundancy. Every clause contributes useful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read-only tool with a clear output contract described in the text, the definition covers invocation timing, query format, ambiguity behavior, and output semantics. No critical information is missing for an agent to select and call this tool 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 100%, so the query parameter is already well documented, including short vs. fully qualified names and ambiguity handling. The tool description itself does not add much parameter detail, but the schema carries that burden effectively.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: call before renaming, changing a signature, or deleting a symbol, and it returns reference data split into exact and name-match categories. This clearly identifies what the tool does, though it does not explicitly contrast it with sibling tools like callers_of or definition_of.
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 opening sentence gives explicit usage context: use this tool before renaming, changing a signature, or deleting a symbol. It does not state when not to use it or name alternatives, but the intended scenarios are clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.8auditaudit_deltacallees_ofcallers_ofdead_codedefinition_ofduplicatesendpointsfind_symbolimpact_ofoverviewperf_advicereferences_ofScored across 13 tools
Each tool has a distinct scope: find/define/reference/caller/callee/impact layer by resolution confidence and traversal depth, while audit/audit_delta/dead_code/duplicates/perf_advice target different finding types. The only mild overlap is references_of vs callers_of and audit vs its sub-analyses, but descriptions draw explicit boundaries.
There is a recognizable cluster of possessive-style names (definition_of, references_of, callers_of, callees_of, impact_of) and an audit/audit_delta pair, but the set mixes noun names (overview, endpoints, dead_code, duplicates), imperative verb_noun (find_symbol), and adjective-noun (perf_advice). The conventions are readable but not unified.
Thirteen tools is within the well-scoped range and each covers a necessary analysis task without redundancy. The count supports a coherent workflow from orientation through navigation to audit.
The surface covers the full analysis workflow: repo overview, cross-language endpoint integrity, symbol lookup/definition/reference/caller/callee traversal, blast-radius impact, dead-code detection, full and delta audits, performance advice, and duplicate detection. No obvious dead-end or missing operation blocks the stated purpose.
Code intelligence platform for AI agents. 20 tools for architecture, security & impact analysis.
Enterprise code intelligence for M&A, security audits, and tech debt. Hosted server with 200k free.
Codebase intelligence for AI agents — dead code, blast radius, ownership.
Codebase intelligence for agents: 152 structured artifacts across 21 programs, one call.
