Skip to main content
Glama
ahmedxuhri

Big Indexer

by ahmedxuhri
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

BGI - Big Indexer

ahmedxuhri/bigindexer MCP server PyPI version License Tests Interactive Demo MCP Registry PR Risk Bot Action

BGI is a static architecture analysis tool for large codebases. It groups code units by behavioral role and emits explicit architectural boundaries. Project domain: bigindexer.com

Use via MCP Registry

Big Indexer is published in the MCP Registry as io.github.ahmedxuhri/bigindexer.

pip install bigindexer==0.1.3
bgi mcp --graph bgi-graph.json --fuse-graph fuse-graph.json

Validation: https://bigindexer.com/validation

Related MCP server: mcp-codebase-index

What problem this solves

Most architecture graphs fail at scale in two ways:

  • too many noisy edges

  • giant clusters that collapse unrelated components together

BGI is built to keep both under control, so the output remains usable on large repos.

What you can do with it

  1. "Where should this boundary be before we refactor?"
    BGI groups units by behavioral role (COV tokens + DRS clustering) so likely component boundaries are visible.

  2. "Which subsystem coupling is risky?"
    BGI surfaces high-coupling seams and fuse-boundary signals between clusters so integration risk is easier to spot.

  3. "How do we plug architecture data into automation?"
    BGI emits machine-readable artifacts (bgi-graph.json, fuse-graph.json) plus optional human context (bigindexer.md).

  4. "How do we make AI changes less random?"
    MCP tools (task_fingerprint, behavioral_twins, twin_context) ground prompts in in-repo behavior patterns.

  5. "Can I run this automatically on PRs as a live example?"
    Yes — use the dedicated action repo ahmedxuhri/bigindexer-pr-risk-bot to auto-comment PRs with blast radius, seams, and risk hints.

30-second demo

Run BGI on the included fixture repo:

git clone https://github.com/ahmedxuhri/bigindexer
cd bigindexer
pip install -e .
bgi scan tests/fixtures --lang python --out /tmp/bgi-example.json
head -50 /tmp/bgi-example.json

Observed result on this repository:

  • units: 12

  • edges: 14

  • clusters: 2

  • max cluster in sample: 6 units

One produced edge looks like:

{
  "source": "auth_module.py::AuthService::__init__",
  "target": "auth_module.py::AuthService::__del__",
  "key": "COV.INIT",
  "lock": "COV.TEARDOWN",
  "type": "HARD"
}

Why this matters: instead of raw syntax references only, you get behavioral relationships plus cluster structure that can drive architecture decisions.

Plain-English glossary

BGI term

Plain meaning

COV token

A behavior label for a unit (for example: FETCH, PERSIST, AUTHENTICATE)

Key-Lock edge

A behavioral connection between two units with complementary roles

DRS cluster

A unit-level grouping by behavioral role. Mostly intra-file in practice. File-level architectural components are better expressed via the BGI edge graph or the fuse-graph boundary signal — see external benchmark

Fuse edge / fuse event

A refused merge because cluster growth hit the cap; treated as boundary signal

Spectral masks

Scope rules that limit where matching is allowed (global, directory, file)

Architecture in one view

Source files
   ->
Gate 1: fingerprint unit behavior (COV tokens)
   ->
Gate 2: create behavioral edges with scoped matching
   ->
Gate 3: cluster with hard size cap + boundary emission
   ->
Artifacts: bgi-graph.json, fuse-graph.json, bigindexer.md, optional routes/graphml/html

Core approach:

  1. TOKEN-CENSUS - classify token frequency per repo.

  2. SPECTRAL-MASKS - restrict match scope by token frequency.

  3. FUSE-MAP - cap cluster growth and record refused merges.

  4. MASK-4-GATE-3 - use import proximity as clustering signal.

  5. WATER-CLOCK + .scm - single-pass query extraction path in Gate 1.

Why BGI is different from common alternatives

Capability

LSP / SCIP index

Call-graph + generic community detection

BGI

Fast symbol lookup

Strong

Medium

Available (Phase 6 index)

Behavioral token model

No

Usually no

Yes

Hard-bounded clustering

No

Usually no

Yes (unit-level)

First-class boundary artifact

No

Usually no

Yes (fuse-graph.json)

Scope-constrained edge generation

Limited

Rare

Yes (spectral masks)

External head-to-head benchmark (Louvain on BGI's edges vs Louvain on raw imports, scored against package layout): BGI's edges win on Python (django F1 0.38 vs 0.29, MoJoFM 0.45 vs 0.34) and currently tie/lose on Go due to lower cross-file edge density on tier-2 scanners. Full results and methodology in docs/VALIDATION_EVIDENCE.md.

Evidence (current, verifiable)

Large-repo scale evidence

Comparable kubernetes sample (go comparable mode, 162,917 units):

  • Gate 1: 141.964s

  • Gate 2: 67.261s (historical comparable baseline: 138.869s)

  • Gate 3: 9.359s

  • Total: 218.584s

  • Max cluster: 1.113%

  • Fuse events: 0

Artifact: output/validation/kubernetes-optionb-controlled-median-v21.json

Quality guard evidence (beyond raw speed)

  • Gate 2 scope safety tests block invalid cross-scope merges (see tests/test_gate2.py).

  • Gate 3 tests verify no legacy namespace over-merge without import evidence (see tests/test_gate3.py).

  • Current full suite status: python3 -m pytest tests/ -x -q (project baseline target remains passing).

Evidence summary

  • Current published validation set: 100 scored runs across 5 repos and 3 models.

  • Full 20-run post-shipment benchmark refresh for BGI-TWIN context (task → COV → top-3 twins + seam + rubric) is complete: actionability 4.75/5 (p04 slice: 4.8/5), boundary 1.0, hallucinations 0.

  • Independent-model replication is now complete on azure/gpt-4o (20 runs) and gemini/auto (20 runs): GPT-4o actionability 4.85/5, Gemini actionability 4.25/5, both with zero hallucinations; Gemini boundary 0.95 reflects one genuine django/p02 miss.

  • Still missing: labeled precision/recall benchmark on an external corpus and head-to-head quantitative benchmark vs external tools on the same labeled dataset.

Language support tiers (explicit)

BGI does not treat all languages equally; support is tiered:

  1. Query-backed (.scm): python, typescript, tsx, javascript, go, rust, java, csharp, php, ruby, kotlin, scala

  2. Tree-sitter scanner + rule path: c, lua, elixir

  3. Generic regex fallback by extension: swift, r, dart, bash, nim, zig, haskell, ocaml, fsharp, clojure, erlang, matlab, vb, crystal, cobol, groovy

Use this as a reliability signal: query-backed and dedicated scanner tiers are stronger than generic fallback.

Cross-file edge density caveat: the language tiers above describe parser quality. A separate axis is cross-file behavioral edge density — how many key-lock pairs the scanner produces that link units in different files. Tier-1 (.scm-backed) languages produce dense cross-file edges. Tier-2 scanner-backed languages currently produce sparser cross-file edges because their token mix is dominated by structural tokens (INTAKE/OUTPUT/CONDITIONAL/LOOP) that gate-2 deliberately scopes to same-file to prevent O(N²) noise. The user-visible MCP product (boundary detection, twin retrieval, AI-assistant context) still works on tier-2 languages — see the validation evidence — but cluster-recovery benchmarks against import-graph baselines reflect this density gap. Concrete numbers in docs/VALIDATION_EVIDENCE.md.

Limitations and non-goals

  1. BGI is static analysis; it does not ingest runtime traces.

  2. Cross-file semantic resolution is heuristic and language-dependent.

  3. Cluster-size health is measured; full external precision/recall is not yet published.

  4. Shared-host benchmarking introduces variance; decisions should use controlled medians.

Install

pip install -e .

Quickstart commands

# scan
bgi scan /path/to/repo --lang auto --out bgi-graph.json

# optional outputs
bgi scan /path/to/repo --lang auto \
  --fuse-graph fuse-graph.json \
  --routes routes.json \
  --graphml graph.graphml \
  --html

# incremental
bgi scan /path/to/repo --lang auto --incremental --cache .bgi-cache.json

# diff
bgi diff /path/before /path/after --lang auto --out diff.json

# run MCP server over generated artifacts
bgi mcp --graph bgi-graph.json --fuse-graph fuse-graph.json

Example MCP usage pattern (from your client prompt):

Use MCP tool twin_context for:
"Add endpoint that validates input and persists data."
Return top twin candidate, seam suggestion, and rubric checklist.

Telemetry

BGI ships with opt-in, off-by-default anonymous telemetry. To enable:

export BGI_TELEMETRY=1
bgi mcp --graph bgi-graph.json --fuse-graph fuse-graph.json

What's collected when enabled: BGI version, OS, repo size bucket, and a 12-char hash of your repo's git remote (so we can deduplicate "same repo seen twice" without ever knowing which repo). What's never collected: file paths, source code, repo names, user identity, or IP addresses. Full schema and disable instructions in docs/TELEMETRY.md.

Documentation map

  • MEMORANDUM.md - design contracts and invariants

  • docs/LANGUAGE_SUPPORT.md - language implementation details

  • docs/CONTRIBUTING_LANGUAGES.md - language contribution guide

  • docs/INDEX_SCHEMA.md - interactive index schema

  • docs/QUERY_PLANNER.md - query planner scoring

  • docs/MCP_SETUP.md - MCP server setup and usage

  • docs/MCP_WITH_CONTINUE.md - 5-minute Continue + BGI walkthrough

  • docs/TELEMETRY.md - opt-in telemetry: what we collect and how to disable

  • https://bigindexer.com/validation - public validation evidence

  • docs/MCP_QUICKSTART_DEMO.md - 5-minute demo walkthrough

  • docs/MCP_EXAMPLE_TRANSCRIPTS.md - real-world MCP tool invocation examples

  • docs/MCP_REAL_TRANSCRIPT.md - unedited transcript from FastAPI analysis

  • scripts/mcp-demo.sh - automated demo script for multiple CLIs and repositories

License and Copyright

  • License: Apache License 2.0 (LICENSE)

  • Contributor terms: Developer Certificate of Origin (DCO) enforced on pull requests

Legal

Big Indexer is a product of SUDO SOFTWARES LTD, registered in England and Wales (Company No. 16976948). Contact: ahmed@bigindexer.com · https://bigindexer.com

Available Tools

8 tools
architecture_summaryC

Get compact architecture summary for context injection.

ParametersJSON Schema
NameRequiredDescriptionDefault
path_scopeNo
seam_limitNo
top_clustersNo

TDQS

C2.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description must fully disclose behavior. It only mentions obtaining a compact architecture summary, without detailing side effects, authorization needs, rate limits, or output characteristics.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence with no wasted words. It is front-loaded with the core purpose, though it could benefit from slightly more detail without losing conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and three optional parameters, the description does not explain what the summary contains, how to interpret parameter impact, or what the return value looks like. This is insufficient for an agent to use the tool reliably.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the tool description does not explain any of the three parameters. The parameter names and defaults provide minimal hints, but the agent lacks clarity on how 'path_scope', 'top_clusters', or 'seam_limit' affect results.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a clear action ('Get') and resource ('compact architecture summary') and adds context ('for context injection'). However, it does not differentiate from sibling tools like 'guided_arch_context' or 'twin_context', which may also provide architectural summaries.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, limitations, or exclusions, leaving the agent without decision support.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

behavioral_twinsC

Return top behavioral twin candidates ranked by COV overlap.

ParametersJSON Schema
NameRequiredDescriptionDefault
taskYes
limitNo
min_scoreNo
include_sourceNo

TDQS

C2.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Since no annotations are provided, the description carries the full burden for behavioral disclosure. It indicates a read operation (returning candidates) but lacks detail on side effects, authorization needs, rate limits, or output format. This is minimal transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no wasted words. While very concise, it could be slightly more informative without harming brevity. Overall, structure is efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is severely incomplete given the tool has 4 parameters, no output schema, and no annotations. It does not explain key terms ('COV overlap'), expected outputs, or how results are used. For a moderate-complexity tool, this fails to provide necessary context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, yet the description does not mention any of the four parameters (task, limit, min_score, include_source). The agent receives no information beyond the schema structure, so the description adds no semantic value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Return top behavioral twin candidates ranked by COV overlap.' It uses a specific verb ('return') and noun ('behavioral twin candidates'), and the ranking criterion distinguishes it from sibling tools like 'twin_context' or 'task_fingerprint'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives, no prerequisites, and no exclusions. The agent must infer usage from the name alone, which is insufficient.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

classify_promptC

Classify a prompt into scope and retrieval requirements.

ParametersJSON Schema
NameRequiredDescriptionDefault
promptYes

TDQS

C2.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, and the description does not disclose behavioral traits such as whether the tool is read-only, requires specific permissions, or has side effects. The agent has no additional context beyond the basic purpose.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no extraneous content, achieving conciseness. However, it is too brief to be fully informative; the structure is minimal but functional.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the absence of an output schema and annotations, the description fails to explain return values or the classification output. With only one parameter and no behavioral context, the description is incomplete for an agent to reliably use the tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 0% description coverage, and the description adds minimal semantic value beyond naming the parameter. It does not clarify expected format, constraints, or examples for the 'prompt' string, leaving the agent to guess.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool classifies a prompt into scope and retrieval requirements, which distinguishes it from sibling tools that focus on architecture analysis. However, the terms 'scope' and 'retrieval requirements' are somewhat vague and could benefit from elaboration.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

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. Sibling tools include various analysis functions, but the description does not specify scenarios where classify_prompt is appropriate or when to choose another tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

guided_arch_contextC

Get staged architecture context with scope-first escalation gates.

ParametersJSON Schema
NameRequiredDescriptionDefault
promptYes
max_itemsNo

TDQS

C2.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden, but it merely states 'Get' without disclosing whether it is read-only, destructive, or has side effects. No mention of auth needs, rate limits, or edge cases.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence is concise but under-specified. It front-loads the core action, but lacks important details, making it borderline too terse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the absence of output schema and annotations, the description should provide more context about return values, usage context, and behavior. It is insufficient for a tool with 2 parameters and no structured supporting fields.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description adds zero information about the 'prompt' or 'max_items' parameters. The description does not clarify their roles, formats, or expected values, making it hard for an agent to use correctly.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'Get' and resource 'staged architecture context', and includes jargon 'scope-first escalation gates' that hints at a distinct approach. It loosely distinguishes from siblings like 'architecture_summary' or 'boundary_edges' but could be clearer.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives (e.g., 'architecture_summary'). No when-not or context provided, leaving the agent to infer usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

reload_artifactsA

Reload graph and fuse artifacts from disk.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, and description only says 'from disk' without disclosing whether it overwrites state, requires artifacts to exist, or is synchronous. Minimal 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.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single concise sentence with verb first, no wasted words. Every part carries meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, no-output-schema tool, the description adequately conveys purpose. Could mention when it's used (e.g., after modifications) but not essential.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters, so schema coverage is 100%. The description adds no parameter-specific info but is not needed; baseline of 4 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the verb 'reload' and specifies the resources 'graph and fuse artifacts' from disk, distinguishing it from siblings which are analytical or classification tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool, prerequisites, or alternatives. Does not mention typical scenarios or when to avoid.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_symbolsC

Search symbols via index DB if available, else graph fallback.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
queryYes
context_unit_idNo

TDQS

C2.7/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description must bear the burden of behavioral disclosure. It reveals a dual execution path (index DB first, then graph fallback), which is valuable but does not cover side effects, safety (presumably read-only), or failure modes.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely short (one sentence) but at the cost of omitting essential parameter and behavioral details. It is under-specified rather than efficiently concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, no annotations, and zero parameter coverage in the description, the tool is severely incomplete. The agent lacks understanding of what symbols are, how parameters work, what the output looks like, and fallback behavior details.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description does not mention any of the three parameters (query, limit, context_unit_id). The agent receives no semantic help beyond the schema titles.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action 'search' and the resource 'symbols', and provides a specific implementation detail (index DB fallback to graph). This distinguishes it from sibling tools which are all about architecture analysis, not symbol search.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use or not use this tool. It only mentions a technical fallback mechanism but does not suggest alternatives or provide usage conditions. The sibling tools are different domains, so no explicit comparison is offered.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

task_fingerprintB

Translate natural-language task text into COV tokens.

ParametersJSON Schema
NameRequiredDescriptionDefault
taskYes
max_tokensNo

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, and the description only says 'translate', providing no behavioral details such as side effects, statelessness, or required permissions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence conveying the core functionality; all words add value with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the low schema coverage and lack of annotations, the description lacks critical details for correct invocation, such as parameter constraints or output format.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description must compensate, but it only implicitly maps 'task' to 'natural-language task text' and does not explain 'max_tokens' beyond the default value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb 'translate' with a clear resource 'natural-language task text' and output 'COV tokens', distinguishing it from sibling tools on the server.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives, nor any when-not or prerequisite information. Usage is only 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.

twin_contextC

Return task COV + top twins + seam + rubric for implementation guidance.

ParametersJSON Schema
NameRequiredDescriptionDefault
taskYes
limitNo
min_scoreNo
include_sourceNo

TDQS

C2.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided. The description implies a read operation (returning data) but does not disclose side effects, permissions needed, or behavior under different inputs (e.g., what happens with invalid task?). It lacks any behavioral context beyond the opaque list of returned elements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single short sentence, which is very concise. However, it could be more structured by front-loading the core purpose and then adding parameter or usage details. The conciseness is positive, but the lack of additional information is a trade-off.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations, no output schema, and 4 parameters with no description coverage, the description is woefully incomplete. It fails to explain what the tool actually does, how parameters affect results, or what the response looks like. A tool with this complexity requires a much richer description to be usable.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 4 parameters (task, limit, include_source, min_score) with 0% description coverage. The tool description does not explain these parameters at all, leaving the agent to rely solely on the schema titles and defaults. Since the description does not add any semantic value, the score is minimal.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states the tool returns 'task COV + top twins + seam + rubric' for implementation guidance. The verb 'Return' is clear, but the resource identifiers are jargon (COV, twins, seam) that may not be understood without domain knowledge. It distinguishes somewhat from siblings like 'behavioral_twins' and 'high_coupling_seams' by combining these concepts, but the differentiation is implicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives. Sibling tools like 'behavioral_twins', 'high_coupling_seams', and 'task_fingerprint' have overlapping themes, but no comparative context is provided. The description does not mention prerequisites, limitations, or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updatesv0.1.4
    • Removedboundary_edges
    • Removedcluster_of_file
    • Removedhigh_coupling_seams
    • Removedimpact_neighbors
  2. 12 tool updatesv1.0.0
    • First observedarchitecture_summary
    • First observedbehavioral_twins
    • First observedboundary_edges
    • First observedclassify_prompt
    • First observedcluster_of_file
    • First observedguided_arch_context
    • First observedhigh_coupling_seams
    • First observedimpact_neighbors
    • First observedreload_artifacts
    • First observedsearch_symbols
    • First observedtask_fingerprint
    • First observedtwin_context
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.1/5.0

Scored across 8 tools

Disambiguation4/5

Most tools have distinct purposes, but architecture_summary and guided_arch_context both provide architectural context, and behavioral_twins and twin_context both involve twins, which could cause confusion. Descriptions help differentiate by emphasizing different outputs and use cases.

Naming Consistency4/5

All tool names use consistent snake_case and lowercase style. However, the naming pattern mixes verbs (classify, reload, search) and nouns (architecture_summary, behavioral_twins, twin_context), which is slightly inconsistent.

Tool Count5/5

With 8 tools, the server covers a reasonable scope for architecture indexing and context retrieval without being bloated or too sparse. Each tool serves a clear purpose within the workflow.

Completeness4/5

The tool set adequately covers core operations like getting architecture summaries, searching symbols, classifying prompts, and retrieving twin context. Minor gaps exist, such as lacking tools to modify or create index entries, but the main read and analysis workflows are supported.

Maintenance

ActivityMaintained
ResponsivenessUnresponsive

Resources

Related MCP Connectors

Related MCP Servers

  • OpenLore

    clay-good
    A
    license
    Not graded
    quality
    A
    maintenance
    Provides persistent architectural memory and structural cognition for AI coding agents, enabling efficient orientation, graph-aware context, and drift detection across codebase evolution.
    1,150 npm
    304
    MIT

  • mcp-codebase-index

    MikeRecognex
    A
    license
    Not graded
    quality
    D
    maintenance
    A structural codebase indexer that exposes 18 tools via the Model Context Protocol for AI-assisted code navigation, enabling efficient querying of functions, classes, dependencies, and call chains without reading entire files.
    87 PyPI
    62
    AGPL 3.0

  • Code Index MCP

    marksolly
    A
    license
    A
    quality
    D
    maintenance
    Intelligent code indexing and analysis for Large Language Models, enabling advanced search, file analysis, and real-time monitoring of codebases.
    12
    MIT

  • code-intel

    nairraf
    A
    license
    Not graded
    quality
    B
    maintenance
    Provides semantic code search and code insights via a knowledge graph, enabling AI to understand, navigate, and modify complex projects with deep dependency and architecture analysis.
    MIT