Skip to main content
Glama
kvnpetit

SRC (Structured Repo Context)

by kvnpetit
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

SRC (Structured Repo Context)

Transform your codebase into AI-ready context — MCP server + CLI for semantic code search that makes your code truly understandable for AI assistants

SRC is both:

  • 🔌 An MCP Server — Integrates with Claude Desktop, Cursor, and any MCP-compatible AI assistant

  • 💻 A Standalone CLI — Use directly from your terminal for indexing and searching

CI codecov npm version npm downloads License: MIT MCP TypeScript Ollama

Table of Contents

  1. Overview

  2. Quick Start

  3. Installation

  4. MCP Tools Reference

  5. CLI Reference

  6. Configuration

  7. Supported Languages

  8. How It Works

  9. Comparison

  10. Troubleshooting

  11. Links

Related MCP server: code-context-mcp

Overview

The Problem

AI assistants struggle to understand your entire codebase:

  • They only see small snippets of code at a time

  • Manual copy-pasting of context is tedious and error-prone

  • Keyword search misses semantic relationships between code

  • Code changes get lost in conversation history

The Solution

SRC indexes your codebase into semantic, searchable chunks that LLMs actually understand:

Feature

Description

Hybrid Search

Vector + BM25 + RRF fusion for optimal results

Call Graph

Shows who calls what and what calls who

Cross-file Context

Resolves imports and path aliases automatically

Incremental Updates

SHA-256 hash detection for fast updates

Semantic Navigation

Local LSP/SCIP when available, with explicit Tree-sitter fallback

Project Context

Onboarding, repo map, artifacts, memory, Git and task context

Local Hardening

Strict contracts, snapshots, redaction, injection signals and audit metadata

55 Language Modes

18 Tree-sitter languages plus 37 configured fallback modes across 99 extensions

Use Cases

Scenario

Example Query

Code Review

"Show me all error handling in the payment module"

Debugging

"Find where user sessions are created"

Documentation

"Explain the authentication flow"

Refactoring

"List all deprecated API usages"

Onboarding

"How does the routing system work?"

Security Audit

"Find all database query locations"

Quick Start

1. Choose an embedding provider

The default provider is local Ollama:

# Install from https://ollama.com, then:
ollama pull nomic-embed-text

For a zero-service setup, use the deterministic lexical provider instead:

EMBEDDING_PROVIDER=lexical src-mcp serve

The lexical provider is a useful BM25/identifier baseline; Ollama remains the recommended provider for semantic vector quality.

2. Install SRC

Global installation:

npm install -g src-mcp

Or use npx:

npx -y src-mcp serve

3. Use as MCP Server (with AI Assistants)

Add to your MCP client configuration (e.g., Claude Desktop):

With global installation:

{
  "mcpServers": {
    "src-mcp": {
      "command": "src-mcp",
      "args": ["serve"]
    }
  }
}

With npx:

{
  "mcpServers": {
    "src-mcp": {
      "command": "npx",
      "args": ["-y", "src-mcp", "serve"]
    }
  }
}

The server indexes the current directory when requested and can watch for file changes. EMBEDDING_PROVIDER=lexical removes the requirement for a running Ollama service.

Then in your AI assistant:

"Search for authentication logic"
"Find error handling code with limit 20"
"Search for UserService in fts mode"

4. Use as CLI (Standalone)

# Start server (auto-indexes if needed and watches by default)
src-mcp serve

# Search for code
src-mcp search_code --query "authentication"
src-mcp search_code --query "error handling" --limit 20
src-mcp search_code --query "UserService" --mode fts

# Check index status
src-mcp get_index_status

Key Arguments

Tool

Argument

Default

Description

search_code

--limit

10

Max results

search_code

--mode

hybrid

hybrid / vector / fts

index_codebase

--concurrency

4

Parallel workers

index_codebase

--force

false

Re-index if exists

Installation

Global Installation

npm install -g src-mcp

Then use directly:

src-mcp serve
src-mcp search_code --query "authentication"
src-mcp --help

npx (No Installation)

npx -y src-mcp serve
npx -y src-mcp search_code --query "authentication"

Local Development

git clone https://github.com/kvnpetit/structured-repo-context-mcp.git
cd structured-repo-context-mcp
bun install --frozen-lockfile
bun run dev

MCP Tools Reference

SRC exposes 35 MCP tools, 7 reusable MCP prompts, 2 static MCP resources, and 1 project resource template. The same tool registry is also available through the CLI. All tools return structured content, bounded results, read-only/destructive annotations, and safe error messages. Indexing and updates report progress when the client supplies a progress token and honor request cancellation.

Source returned by analysis tools is untrusted project data. It is marked with source_is_untrusted; search_code and assemble_task_context redact common inline secrets by default. Exact source extraction keeps offsets stable and can opt into redaction with redact_secrets: true.

Responses also carry provenance, index freshness, confidence, coverage and truncation metadata. Potential prompt-injection patterns found in returned source are exposed as bounded instruction_signals without echoing matched source text. When SRC_AUDIT_LOG is enabled, only non-sensitive tool timing and project identifiers are written to the local audit log.

Every MCP tool response also has a stable top-level schema_version (currently 1) alongside success, optional data, message, and error fields. Clients should branch on this envelope before consuming a tool-specific data payload.

Tasks extension

Modern MCP clients that declare io.modelcontextprotocol/tasks in their per-request client capabilities can receive a durable task handle for the long-running index_codebase and update_index tools. Poll a handle with tasks/get; tasks/update and tasks/cancel are also implemented according to the current extension contract. Task state is stored atomically outside the project by default, expires after 24 hours, and is bounded to eight active tasks per server process. A shared store has a hard ceiling of 1,024 records and 16 MiB; reaching either refuses new writes without evicting existing IDs. Set MCP_TASKS=off to disable it, or configure MCP_TASK_TOOLS, MCP_TASK_STORE_DIR, MCP_TASK_TTL_MS, MCP_TASK_POLL_INTERVAL_MS, MCP_TASK_MAX_ACTIVE, and MCP_TASK_MAX_RESULT_BYTES.

The extension is opt-in per request: clients without the current capability continue to receive the normal synchronous tool result. Processes sharing a store coordinate read/modify/write operations with local filesystem locks. In-progress tasks owned by a living process are preserved; an abandoned task whose owner has exited is reported as failed because arbitrary source analysis cannot be resumed without its original runtime state. There is intentionally no tasks/list endpoint in the current extension; task IDs are unguessable and retrieval is explicit.

Use a local disk for this store. A persistence failure stops affected runners and rejects new asynchronous work until the server restarts; synchronous tools remain available. Failed states are retained in memory and retried against the store when it becomes writable again. Cross-process cancellation is polled at 500 ms. Owner detection is conservative if the OS reuses a process ID.

Tool profiles and allow-listing

The complete surface is enabled by default. Set SRC_TOOL_PROFILE=readonly to hide the seven local state/index-mutating tools, or SRC_TOOL_PROFILE=minimal to expose only server information, index status, search, diagnostics, project discovery, project context, project artifacts, semantic navigation, and compact context-orientation tools. SRC_TOOL_ALLOWLIST takes precedence when it contains explicit names; unknown entries are ignored by the registry. An explicitly non-empty but unusable SRC_ALLOWED_ROOTS value fails closed rather than falling back to the current directory.

index_codebase

Index a directory with semantic chunking, AST enrichment, and embeddings.

Parameter

Type

Required

Default

Description

directory

string

No

.

Path to directory to index

force

boolean

No

false

Force re-indexing if index exists

exclude

string[]

No

[]

Additional glob patterns to exclude

concurrency

number

No

4

Parallel file processing workers

Example:

"Index the project at /home/user/myapp with concurrency 8"

Returns:

{
  "filesIndexed": 150,
  "chunksCreated": 892,
  "languages": { "typescript": 500, "javascript": 200, "json": 192 }
}

search_code

Hybrid search with vector similarity, BM25 keyword matching, and RRF fusion.

Parameter

Type

Required

Default

Description

query

string

Yes

—

Natural language search query

directory

string

No

.

Path to indexed directory

limit

number

No

10

Maximum results to return

cursor

string

No

—

Opaque cursor returned by a previous page

max_content_bytes

number

No

20000

UTF-8 byte cap per returned source result

min_confidence

number

No

0

Optional confidence floor; may cause abstention

threshold

number

No

—

Distance threshold (0-2, vector mode only)

mode

enum

No

hybrid

Search mode: hybrid, vector, or fts

vectorWeight

number

No

0.5

Hybrid semantic weight from 0 (keywords) to 1 (vectors)

includeCallContext

boolean

No

true

Include caller/callee information

rerank

enum

No

lexical

none, lexical, or code-aware code ranking

language

string

No

—

Filter by detected language

path_prefix

string

No

—

Filter by project-relative path prefix

symbol_type

string

No

—

Filter by symbol kind such as function or class

include_tests

boolean

No

true

Include test/spec paths

redact_secrets

boolean

No

true

Redact common inline secrets in returned source

neighbor_window

number

No

0

Add up to 3 same-file chunks on each side of each hit

Search Modes:

Mode

Description

Best For

hybrid

Vector + BM25 + RRF fusion

General queries (default)

vector

Semantic similarity only

Conceptual searches

fts

Full-text keyword only

Exact identifiers

Example:

"Search for 'user authentication' with limit 20"

Returns:

{
  "results": [
    {
      "content": "export async function authenticateUser(credentials)...",
      "filePath": "src/auth/login.ts",
      "startLine": 45,
      "endLine": 78,
      "symbolName": "authenticateUser",
      "symbolType": "function",
      "score": 0.0164,
      "confidence": 0.86,
      "parts": {
        "signature": "export async function authenticateUser(credentials)",
        "body": "export async function authenticateUser(credentials)..."
      },
      "callContext": {
        "callers": ["handleLogin"],
        "callees": ["validatePassword"]
      }
    }
  ]
}

Filtered searches retrieve a larger bounded candidate pool before applying the filters. The response reports truncated, the active filters, index metadata, and the source fingerprint represented by the index when available. Retrieval metadata classifies the query as identifier, concept, or mixed, reports duplicate removal and confidence, and explains abstention when no result reaches min_confidence. Each result separates parts.signature, parts.documentation, and parts.body. Use next_cursor with the same query and filters to request a following page.

score is mode-dependent: vector mode returns a distance where lower is better, while FTS and hybrid modes return ranking scores where higher is better. Use the normalized confidence field (0–1) for a mode-independent quality signal.

max_content_bytes bounds each returned source snippet without splitting a multi-byte UTF-8 character. When a snippet is shortened, the result contains content_truncated: true and the response reports content_truncated_count.

Set neighbor_window to 1, 2, or 3 when the matching chunk needs local surrounding context. Neighbor results are marked with is_neighbor, neighbor_of, and neighbor_distance; they inherit the active filters, are score-decayed and confidence-adjusted, and are capped by a bounded seed and result budget. Retrieval metadata reports neighbors_added, neighbor_candidates_considered, and neighbors_truncated. The default 0 keeps the historical result set unchanged.

MCP prompts

The prompt catalog contains src-overview, code-search-workflow, search-tips, project-onboarding, architecture-review, security-review, and refactor-impact. The specialized prompts describe local, read-only tool sequences and explicitly require callers to inspect provenance, freshness, coverage, confidence, truncation, and untrusted-content signals.

MCP resources

SRC publishes JSON resources for discovery and bounded project orientation:

Resource

Purpose

src://server/info

Server identity, version, and description

src://server/capabilities

Active tool profile, enabled tool catalog, annotations, and deterministic catalog revision

src://project/{project}/{view}

Local project template with context, map, status, catalog, or memory views

Project identifiers are derived from the secure local root. The template lists configured SRC_ALLOWED_ROOTS, or the current directory when no allow-list is configured. Resource payloads remain local JSON and use the same bounded, redacted feature implementations as the corresponding tools.

update_index

Incrementally update the index by detecting changed files via SHA-256 hash comparison.

Parameter

Type

Required

Default

Description

directory

string

No

.

Path to indexed directory

dryRun

boolean

No

false

Preview changes without updating

force

boolean

No

false

Force re-index all files

concurrency

number

No

4

Parallel file processing workers

Example:

"Update the index with dry run to see what changed"

Returns:

{
  "added": ["src/new-file.ts"],
  "modified": ["src/auth/login.ts"],
  "removed": ["src/old-file.ts"],
  "unchanged": 148
}

get_index_status

Get status of the embedding index for a directory.

Parameter

Type

Required

Default

Description

directory

string

No

.

Path to directory

Example:

"Get the index status for current directory"

Returns:

{
  "exists": true,
  "indexPath": "/home/user/myapp/.src-index",
  "totalFiles": 150,
  "totalChunks": 892,
  "languages": { "typescript": 500, "javascript": 200 }
}

The status also reports provider compatibility, source/index freshness, storage size, hash-cache and write-lock presence, and corruption indicators when those signals are available.

get_server_info

Get the server identity, version, and description.

Parameter

Type

Required

Default

Description

format

enum

No

text

Output format: text or json

Returns:

{
  "name": "src-mcp",
  "fullName": "SRC (Structured Repo Context)",
  "version": "2.0.0",
  "description": "MCP server for codebase analysis with Treesitter (SCM queries), AST parsing, and embedding-based indexing"
}

parse_ast

Parse Tree-sitter-supported source and return its AST. Provide file_path or content; when using content, also provide language. Optional max_depth limits the returned tree (default 5, maximum 50), max_text_bytes bounds inline node text, max_nodes bounds the returned tree (default 10000), and redact_secrets masks common credentials by default.

query_code

Run a raw Tree-sitter SCM query or one of the presets functions, classes, imports, exports, comments, strings, variables, or types. Provide file_path or content; language is optional, max_matches defaults to 500 (maximum 1000), and redact_secrets defaults to true.

list_symbols

Extract symbols from file_path or direct content. Optional language selects the parser, types filters functions, classes, variables, constants, interfaces, types, enums, methods, or properties, and max_symbols defaults to 1000 (maximum 5000).

analyze_file

Analyze a local file_path through Tree-sitter or configured text fallback. include_ast, include_symbols, include_imports, include_exports, ast_max_depth, ast_max_nodes, include_chunks, and redact_secrets control response detail and bounds.

get_call_graph

Analyze calls under directory (default .), or query a functionName with optional filePath. maxDepth defaults to 2, maxNodes to 200, and maxFiles to 500; exclude accepts additional ignore patterns. Results are static syntactic relationships and may not resolve every dynamic call.

find_symbols

Find definitions, references, imports, or exports across a project. Results include project-relative paths, symbol names, bounded source snippets, and UTF-8 byte offsets for precise follow-up retrieval. max_files, limit, opaque cursor, optional file_path, and redact_secrets keep the response bounded and safe for agent context. mode accepts definitions, references, imports, exports, or all; defaults are definitions, limit: 50, and max_files: 200.

get_dependency_graph

Build a project-relative import/dependency graph with resolved and unresolved edges, cycles, and high-degree hotspots. Relative imports and TypeScript path aliases are resolved when the target stays inside the secure project root. The response also includes a bounded syntax-level type hierarchy with inheritance and implementation edges. max_files, max_edges, max_type_nodes, and max_type_edges independently cap graph expansion (defaults: 200, 2000, 5000, and 10000). include_external defaults to false.

get_code_snippet

Read a bounded source range by exact UTF-8 byte offsets. The response includes the project-relative path, start/end offsets, line/column positions, and a truncation flag. start_offset defaults to 0, end_offset is optional, max_bytes defaults to 12000, and redact_secrets defaults to false so returned offsets continue to describe the original file. It never executes source code.

analyze_impact

Compute direct and transitive dependents for changed project-relative files from the dependency graph. changed_files is required (1–50 paths) and max_files defaults to 200. Unknown files are reported separately.

get_diagnostics

Inspect provider health, index metadata compatibility, path allow-list status, and resource limits for directory (default .) without changing the project.

list_projects

List all safe project roots configured through SRC_ALLOWED_ROOTS, or the current directory when no roots are configured. Each project is indexed independently; the result includes its index status and invalid configured roots so a bad configuration cannot silently widen filesystem access. includeCurrent defaults to true.

get_project_context

Build a bounded local onboarding profile without executing project commands. The result identifies the project name and kind, detected languages and frameworks, package manifests and managers, scripts, workspace patterns, likely entrypoints, test roots/files, configuration and documentation files, TypeScript path aliases, and a fingerprint of the scanned file metadata. Scripts are returned as data only and common inline secrets are redacted by default.

Parameter

Type

Required

Default

Description

directory

string

No

.

Project directory

max_files

number

No

1000

Maximum source files to inspect

max_manifests

number

No

100

Maximum metadata files to inspect

include_scripts

boolean

No

true

Include package scripts without running

redact_secrets

boolean

No

true

Redact common secrets in script commands

The output is read-only, bounded, marked source_is_untrusted, and includes truncated, errors, and profile_fingerprint fields.

semantic_navigation

Navigate a local source position with an allow-listed local language server when one is installed, or use the explicit Tree-sitter fallback. Supported operations are definition, references, implementation, hover, type_hierarchy, and diagnostics. The fallback never pretends to resolve compiler identity: its response marks coverage: "approximate", exposes confidence, and explains the limitation in warnings.

Parameter

Type

Required

Default

Description

directory

string

No

.

Project directory

file_path

string

Yes

—

Source file path relative to the project

line

number

Yes

—

1-based source line

column

number

Yes

—

0-based character column

operation

enum

Yes

—

definition, references, implementation, hover, type_hierarchy, or diagnostics

backend

enum

No

auto

auto, lsp, scip, or treesitter

max_results

number

No

50

Maximum returned locations

max_files

number

No

500

Tree-sitter fallback file bound

include_source

boolean

No

true

Include bounded location snippets

max_source_bytes

number

No

8000

Maximum source bytes included per result

timeout_ms

number

No

5000

Local LSP request timeout

redact_secrets

boolean

No

true

Redact common secrets in returned text

Set SRC_LSP_ENABLED=false to force the safe Tree-sitter fallback. No remote language server is used; external LSP locations are discarded when they fall outside the configured project root.

import_scip_index can import a project-relative SCIP JSON export (or invoke a local scip print --json executable) into .src-index/scip-catalog.json. Explicit lsp/scip requests report unavailable backends as errors; auto degrades with an explicit backend and coverage description.

get_symbol_graph

Build a bounded, local symbol-level architecture graph. It combines modules, definitions, imports, references, calls, inheritance, test discovery, and static route/event/dependency-injection signals. trace_from/trace_to expose bounded paths; focus exposes reverse direct and transitive blast radius. Every inferred relationship carries a confidence score and the response explicitly reports its approximate, syntax/name-based coverage.

Parameter

Type

Required

Default

Description

directory

string

No

.

Project directory

focus

string[]

No

[]

Symbols, paths, or node IDs to prioritize

edge_kinds

enum[]

No

all

Relationship kinds to include

trace_from

string

No

—

Start symbol/path/node for a trace

trace_to

string

No

—

End symbol/path/node for a trace

trace_direction

enum

No

forward

forward, reverse, or both

max_path_length

number

No

8

Maximum edges per trace/blast-radius walk

max_files

number

No

500

Maximum source files

max_nodes

number

No

1000

Maximum returned nodes

max_edges

number

No

5000

Maximum returned edges

include_tests

boolean

No

true

Include test edges and discovery

include_signals

boolean

No

true

Detect static routes/events/DI

redact_secrets

boolean

No

true

Redact evidence snippets

The graph is read-only and never executes project code. Dynamic dispatch, reflection, generated code, and runtime wiring remain explicit limitations.

get_repository_map

Build a compact architecture map before reading many files. Files are ranked with import-graph centrality and optional path/symbol focus, then bounded by a token budget.

Parameter

Type

Required

Default

Description

directory

string

No

.

Project directory

focus

string[]

No

[]

Paths or symbols to prioritize

max_tokens

number

No

2000

Approximate textual map budget

max_files

number

No

500

Maximum files to inspect

redact_secrets

boolean

No

true

Redact evidence snippets

The result includes ranked files, included symbol counts, errors, and an explicit truncated flag.

get_symbol_at_position

Resolve the smallest Tree-sitter symbol containing an editor position. Lines are 1-based, columns are 0-based characters, and returned offsets are UTF-8 byte offsets suitable for get_code_snippet.

Parameter

Type

Required

Default

Description

directory

string

No

.

Project directory

file_path

string

Yes

—

File path relative to the directory

line

number

Yes

—

1-based line

column

number

Yes

—

0-based character column

include_source

boolean

No

true

Include bounded symbol source

max_source_bytes

number

No

20000

Maximum returned source bytes

redact_secrets

boolean

No

true

Redact common secrets in source

assemble_task_context

Assemble a bounded, task-focused agent dossier. In one local call it can combine the project profile, revision-aware memory, relevant documentation, current Git state, a PageRank-style repository map, and code-aware hybrid search. Layers run concurrently and receive a fair share of the token budget, so a large map or search result cannot starve every other source. The response reports per-layer availability, allocation, truncation, warnings, and suggested next actions.

Parameter

Type

Required

Default

Description

directory

string

No

.

Project directory

task

string

Yes

—

Task or question to orient around

depth

enum

No

standard

minimal, standard, or deep evidence

max_tokens

number

No

4000

Approximate total context budget

search_limit

number

No

8

Maximum primary semantic results

include_search

boolean

No

true

Include indexed search results

include_project_context

boolean

No

by depth

Include manifest/framework/entrypoint evidence

include_memory

boolean

No

by depth

Include scoped durable memory

include_artifacts

boolean

No

by depth

Include relevant local documentation

include_git

boolean

No

by depth

Include branch, dirty files, and changed symbols

memory_scope

string

No

project

Project-local memory namespace

memory_min_confidence

number

No

0.4

Ignore low-confidence memory

minimal keeps only map and search, standard enables the complete dossier, and deep increases local evidence and neighboring-code depth. Every mode degrades explicitly when an optional index, Git repository, or context source is unavailable. max_tokens bounds the rendered context field; the machine-readable repository_map and search compatibility fields remain separately bounded by their feature limits and the global MCP response cap.

find_dead_code

Return conservative dead-code candidates using syntax-aware symbol extraction and bounded identifier reference counts. This is a review aid, not a compiler proof: dynamic dispatch, reflection, generated code, entry points, and external consumers can produce false positives.

Parameter

Type

Required

Default

Description

directory

string

No

.

Project directory

limit

number

No

100

Maximum candidates returned

max_files

number

No

500

Maximum source files inspected

include_tests

boolean

No

false

Include candidates from test files

get_changed_symbols

Read the Git working tree relative to HEAD and map changed hunks to current symbols. It includes untracked files, has no shell execution or user-supplied revision argument, and returns explicit bounds/errors.

Parameter

Type

Required

Default

Description

directory

string

No

.

Git repository root

max_files

number

No

300

Maximum changed files to inspect

max_symbols

number

No

1000

Maximum changed symbols to return

get_project_artifacts

Discover and search project documentation without executing or persisting it. Artifacts are classified as readme, architecture, adr, specification, plan, runbook, security, changelog, contributing, or generic documentation.

Parameter

Type

Required

Default

Description

directory

string

No

.

Project directory

query

string

No

""

Terms to search in paths/titles/content

limit

number

No

50

Maximum artifacts returned

max_files

number

No

1000

Maximum documentation files inspected

include_content

boolean

No

false

Include bounded document content

max_content_bytes

number

No

4000

Maximum content bytes per artifact

redact_secrets

boolean

No

true

Redact common inline secrets

The output contains document links, relevance, explicit truncation, and the source_is_untrusted marker. It is a read-only catalog for current files, not a cross-project memory channel.

get_project_memory

Read the opt-in, project-scoped memory stored in .src-index/project-memory.json. Records are typed (decision, constraint, fact, todo, or note), versioned, confidence-scored, expiry-aware, redacted by default, and returned through deterministic opaque cursors. When a record is written in a Git repository, set_project_memory captures the local HEAD by default. Reads compare that provenance with the current local revision and label each record current, stale, or unknown, with an aggregate revision_summary. scope selects a bounded local namespace inside the same project and never merges memory across project roots. search_mode can use weighted field/phrase matching (hybrid) or simple token matching (lexical). set_project_memory is the corresponding explicit upsert/delete operation with optimistic concurrency via expected_updated_at; it never executes or interprets stored text.

Parameter

Type

Required

Default

Description

directory

string

No

.

Project directory

scope

string

No

project

Local namespace inside this project

query

string

No

""

Search titles, bodies, tags and links

search_mode

enum

No

hybrid

Weighted phrase/field or lexical match

kind

enum

No

—

Filter memory kind

tags

string[]

No

[]

Require all tags

include_expired

boolean

No

false

Include expired records

min_confidence

number

No

0

Exclude lower-confidence records

limit / cursor

number / string

No

50 / —

Page bounded records

redact_secrets

boolean

No

true

Redact common inline secrets

For upserts, capture_source_revision defaults to true when no explicit source_revision is supplied. Set it to false only for intentionally revision-independent knowledge. Invalid expires_at values are rejected at the input and persisted-state boundaries instead of becoming silently immortal records. The 500-record store ceiling applies globally across scopes, and a cross-process lock protects optimistic read/check/write updates.

set_project_memory

Parameter

Type

Required

Default

Description

directory

string

No

.

Project directory

scope

string

No

project

Isolated local namespace

operation

enum

Yes

—

upsert or delete

id

string

Yes

—

Stable record identifier

kind

enum

Upsert

—

decision, constraint, fact, todo, note

title / body

string

Upsert

—

Memory title and bounded body

tags / links

arrays

No

[]

Normalized tags and typed relationships

source_revision

string

No

current HEAD

Explicit local Git revision

capture_source_revision

boolean

No

true

Capture local HEAD when no revision is supplied

expires_at

date-time

No

—

Optional expiry

confidence

number

No

0.7

Confidence from 0 to 1

expected_updated_at

string

No

—

Optimistic concurrency guard

redact_secrets

boolean

No (upsert)

true

Redact before persistence

get_project_catalog / refresh_project_catalog

refresh_project_catalog persistently indexes metadata-only documentation artifacts and their typed links. get_project_catalog queries that local catalog with pagination and can opt into bounded, redacted document content. The catalog is isolated per project and carries a deterministic source revision. Both operations accept a bounded local scope (default project); custom scopes use separate .src-index/artifacts-catalog-<scope>.json files and never cross project roots. Catalog search accepts search_mode: "hybrid" for a weighted phrase/field score or "lexical" for the stable token score.

get_project_catalog accepts directory, scope, query, search_mode, an optional artifact kind, limit (default 50), opaque cursor, include_content (default false), max_content_bytes (default 4000), and redact_secrets (default true). refresh_project_catalog accepts directory, scope, and max_files (default and maximum 1000).

get_git_context

Read-only local Git context: status, bounded diff, optional history/blame, CODEOWNERS and changed-symbol mapping. With include_hotspots: true, it also aggregates bounded historical file churn (commits, additions, deletions and binary changes). Supplying both compare_from and compare_to returns a bounded comparison of two local commits or refs, resolved to immutable commit IDs. Paths are project-relative and Git is invoked without a shell; no remote refs, lazy fetches, hooks, builds or project commands are run. Revision ranges and reflog expressions are rejected.

Core controls are files (default []), include_status/include_diff (default true), include_history/include_blame (default false), include_codeowners/include_changed_symbols (default true), max_diff_bytes (50000), max_history (20), max_blame_lines (200), and redact_secrets (true). Hotspot/comparison controls are:

Parameter

Type

Required

Default

Description

include_hotspots

boolean

No

false

Aggregate local file churn across recent commits

max_hotspots

number

No

25

Maximum ranked hotspot files

compare_from / compare_to

string

Together

—

Local revisions to compare; no ranges/remotes

max_compare_files

number

No

100

Maximum files returned by the revision comparison

manage_index_snapshots

Create, list, restore and clean local .src-index-snapshots snapshots. Listing reports validity, and restore verifies every hash before replacement. The required operation is snapshot, list, restore, or cleanup. max_snapshot_bytes defaults to 500 MiB and list_limit to 50; restore also requires snapshot_id and uses backup_current: true; cleanup uses max_snapshots: 10 and max_total_bytes: 500 MiB. Quotas and file counts are enforced, snapshot IDs are validated, and no project code is executed.

maintain_index

Inspect, compact, or migrate the local LanceDB index. inspect reports table versions, fragments, indices, storage bytes, manifest format, and metadata compatibility without creating an index. compact runs the local LanceDB optimizer with an explicit version-retention window and optional removal of unverified fragments. migrate performs the installed LanceDB runtime's idempotent local manifest-path migration when supported. Take a verified manage_index_snapshots snapshot before maintenance that may prune versions; the tool never executes project code.

Parameter

Type

Required

Default

Description

directory

string

No

.

Project directory

operation

enum

No

inspect

inspect, compact, or migrate

cleanup_older_than_days

number

No

7

Version retention window for compact (0–3650)

delete_unverified

boolean

No

false

Remove unverified fragments during compaction

run_static_analysis

Optionally adapt locally installed ast-grep, Semgrep or CodeQL in read-only mode. Set SRC_STATIC_ANALYSIS_ENABLED=true to opt in. Pattern queries remain available, and rule_file accepts an existing project-relative ast-grep or Semgrep rule file, including Semgrep taint rules and ast-grep relational rules. CodeQL uses the existing local database + query_file path and can therefore run local path/data-flow queries when the installed database and query support them. Rule files, databases and queries are never downloaded or executed as project scripts; all subprocess arguments are fixed and non-shell. Missing tools produce a safe availability result rather than an installation or network action.

All variants accept directory, optional project-relative paths, max_results (100), timeout_ms (15000), and redact_secrets (true). Pattern mode requires backend: "ast-grep" | "semgrep", pattern, and language; rules-file mode replaces the latter two with rule_file; CodeQL mode requires backend: "codeql", database, and query_file.

import_scip_index

Import a local index.scip/JSON export or use a locally installed scip CLI to build a bounded navigation catalog. The catalog is content-hashed and stored inside the project index; it is never uploaded. index_file defaults to index.scip, format accepts auto, json, or cli (default auto), and timeout_ms defaults to 15000 with a maximum of 60000.

get_observability

Read bounded, process-local observability without exporting telemetry. The structured JSON form contains tool call counters, recent latency percentiles, runtime memory counters, and the optional secret-free local audit status. Use format: "prometheus" to receive a deterministic Prometheus text exposition in the data.prometheus field; no source text, arguments, tokens, or remote addresses are recorded.

Parameter

Type

Required

Default

Description

directory

string

No

.

Project whose local audit status is read

format

json / prometheus

No

json

Output representation

CLI Reference

Every MCP tool is also a CLI command. You can use SRC from your terminal without any AI assistant.

General Usage

src-mcp <command> [options]
src-mcp --help                  # Show all commands
src-mcp <command> --help        # Show command options

CLI values are validated by the same Zod schema as MCP calls. Numeric options are converted to numbers, enum choices are checked before execution, and array options accept either JSON (recommended when values contain commas) or a comma-separated list:

src-mcp index_codebase --concurrency 8 --exclude '["dist/**","vendor/**"]'
src-mcp set_project_memory --operation upsert --id auth-note --tags auth,bug

Object and tuple options, when exposed by a feature, must be valid JSON. CLI commands use the same execution, audit, output-schema validation, safe-error, and output-size limits as MCP calls. Feature commands write the complete stable result envelope (schema_version, success, meta, and optional data, message, or error) as plain JSON: successes go to stdout, failures to stderr with a non-zero exit code. This keeps output machine-readable and avoids discarding data when a feature also returns a human-readable message.

Or with npx:

npx -y src-mcp <command> [options]

Commands

# Start MCP server (auto-indexes if needed, watches for changes)
src-mcp serve
src-mcp serve --no-watch        # Disable file watcher

# Optional local Streamable HTTP transport
src-mcp serve --transport http --port 3000
# For a remote bind behind a trusted TLS proxy, also set
# MCP_HTTP_BEARER_TOKEN, MCP_HTTP_ALLOWED_HOSTS, SRC_ALLOWED_ROOTS, and
# MCP_HTTP_ALLOW_INSECURE_REMOTE=true.

# Index a codebase manually
src-mcp index_codebase
src-mcp index_codebase --concurrency 8
src-mcp index_codebase --force   # Re-index even if index exists

# Search indexed code
src-mcp search_code --query "authentication"
src-mcp search_code --query "error handling" --limit 20 --mode hybrid
src-mcp search_code --query "UserService" --mode fts  # Exact keyword search

# Update index incrementally
src-mcp update_index
src-mcp update_index --dryRun   # Preview changes only

# Inspect or maintain the local LanceDB index
src-mcp maintain_index --operation inspect
src-mcp maintain_index --operation compact --cleanup_older_than_days 7
src-mcp maintain_index --operation migrate

# Check index status
src-mcp get_index_status

# Server information
src-mcp get_server_info --format json

# Orient and inspect a task
src-mcp get_repository_map --max_tokens 2000
src-mcp assemble_task_context --task "trace authentication failures"
src-mcp get_changed_symbols
src-mcp get_project_artifacts --query "architecture"

Configuration

Environment Variables

All settings can be configured via environment variables:

Variable

Description

Default

OLLAMA_BASE_URL

Loopback-only Ollama API endpoint

http://localhost:11434

EMBEDDING_PROVIDER

ollama or lexical

ollama

EMBEDDING_MODEL

Model for embeddings

nomic-embed-text

EMBEDDING_DIMENSIONS

Vector dimensions (1–16384)

768

CHUNK_SIZE

Characters per chunk (1–100000)

1000

CHUNK_OVERLAP

Overlap, clamped below chunk size

200

EMBEDDING_BATCH_SIZE

Batch size for embedding (1–256)

10

ENRICHMENT_CROSS_FILE

Include resolved cross-file context in embeddings

enabled

ENRICHMENT_MAX_IMPORTS

Maximum imports resolved per enriched file (1–100)

10

ENRICHMENT_MAX_SYMBOLS_PER_IMPORT

Maximum symbols included per resolved import (1–100)

5

SRC_ALLOWED_ROOTS

Allowed project roots separated by ; or ,

unset (required for remote HTTP)

SRC_MAX_FILE_BYTES

Maximum source file size read/indexed (hard max 128 MiB)

10485760

SRC_MAX_RESULT_BYTES

Maximum serialized MCP tool result

2097152

SRC_TOOL_ALLOWLIST

MCP tool names separated by , or ;

unset (all tools)

SRC_TOOL_PROFILE

full, readonly, or minimal

full

SRC_LSP_ENABLED

Enable allow-listed local language-server navigation

enabled

SRC_LSP_SESSION_CACHE

Reuse local LSP sessions between navigation calls

enabled

SRC_LSP_IDLE_MS

Idle TTL for cached LSP sessions (1s–10min)

15000

SRC_STATIC_ANALYSIS_ENABLED

Enable local ast-grep/Semgrep/CodeQL adapters

disabled

SRC_AUDIT_LOG

Persist bounded, secret-free local audit events

disabled

MCP_TASKS

Enable the current Tasks extension

enabled

MCP_TASK_TOOLS

Task-enabled tools separated by , or ;

index/update

MCP_TASK_STORE_DIR

Directory for atomic task state

OS temp directory

MCP_TASK_TTL_MS

Task TTL in milliseconds, or none

86400000

MCP_TASK_POLL_INTERVAL_MS

Suggested task polling interval

1000

MCP_TASK_MAX_ACTIVE

Maximum active asynchronous tasks

8

MCP_TASK_MAX_RESULT_BYTES

Maximum persisted task result size

1048576

LOG_LEVEL

Log verbosity

info

NODE_ENV

Exported development/production runtime flags

unset

HTTP transport variables

HTTP is opt-in; stdio remains the default and the safest local integration.

Variable

Description

Default

MCP_HTTP_HOST

Bind host

127.0.0.1

MCP_HTTP_PORT

Bind port

3000

MCP_HTTP_BEARER_TOKEN

Static bearer token; required for non-loopback

unset

MCP_HTTP_ALLOWED_HOSTS

Hostnames allowed for remote Host/Origin checks

bind host

MCP_HTTP_ALLOW_INSECURE_REMOTE

Explicit opt-in for a non-loopback HTTP listener behind a trusted TLS proxy

false

MCP_HTTP_MAX_BODY_BYTES

Maximum HTTP request body, including chunked data (hard max 16 MiB)

2097152

MCP_HTTP_MAX_CONCURRENT

Maximum concurrent HTTP requests (hard max 256)

16

MCP_HTTP_LEGACY

stateless compatibility or reject modern-only

stateless

MCP_HTTP_RESPONSE_MODE

auto, json, or sse

auto

Example authenticated local client URL:

http://127.0.0.1:3000/mcp
Authorization: Bearer <MCP_HTTP_BEARER_TOKEN>

The server validates localhost Host/Origin headers, refuses unauthenticated remote binds, requires SRC_ALLOWED_ROOTS and explicit TLS termination for any non-loopback bind, caps request size/concurrency, and never logs the bearer token. Every serialized tool response is also bounded by SRC_MAX_RESULT_BYTES (default 2 MiB, hard maximum 16 MiB); oversized or unserializable results fail closed with a safe error instead of returning an unbounded payload. HTTP body limits are capped at 16 MiB and concurrent requests at 256 even when environment variables are misconfigured.

Ollama is used only through its local endpoint by default. The lexical provider is fully in-process and does not require the optional local Ollama service. SRC does not install, fetch, or invoke a remote service as part of indexing or analysis.

Example:

EMBEDDING_PROVIDER=lexical SRC_AUDIT_LOG=1 src-mcp serve

Package API

The package exports a side-effect-free programmatic API. Importing src-mcp does not start stdio or HTTP; use the executable or call an explicit start function instead:

import { createServer, startHttpServer } from "src-mcp";

const server = createServer();
const http = await startHttpServer({ host: "127.0.0.1", port: 3000 });

The src-mcp executable and src-mcp serve remain the supported CLI entry points for Claude Desktop and other MCP clients.

MCP Client Configuration

Claude Desktop (claude_desktop_config.json):

With global installation:

{
  "mcpServers": {
    "src-mcp": {
      "command": "src-mcp",
      "args": ["serve"]
    }
  }
}

With npx:

{
  "mcpServers": {
    "src-mcp": {
      "command": "npx",
      "args": ["-y", "src-mcp", "serve"]
    }
  }
}

With the service-free local lexical provider:

{
  "mcpServers": {
    "src-mcp": {
      "command": "src-mcp",
      "args": ["serve"],
      "env": { "EMBEDDING_PROVIDER": "lexical" }
    }
  }
}

Index Storage

Indexes are stored in .src-index/ directory within each indexed project:

my-project/
├── src/
├── .src-index/              # Created by SRC
│   ├── code_chunks.lance/   # LanceDB table data and manifests
│   ├── call-graph.json      # Call graph cache
│   ├── metadata.json        # Provider/model/dimension/source fingerprint
│   ├── .src-index-hashes.json  # File hash cache
│   ├── project-memory.json   # Optional explicit project memory
│   ├── artifacts-catalog.json # Optional documentation catalog
│   └── scip-catalog.json     # Optional imported local SCIP catalog
├── .src-index-snapshots/     # Local verified index backups
└── ...

Add .src-index/ to your .gitignore:

.src-index/

Supported Languages

Full AST Support (18 languages)

These parser modes use Tree-sitter WASM for AST extraction, symbol-aware chunking, imports, exports, and best-effort static call-graph analysis.

Category

Language

Extensions

Web

JavaScript

.js .jsx .mjs .cjs

TypeScript

.ts .mts .cts

TSX

.tsx

HTML

.html .htm .xhtml

Svelte

.svelte

Systems

C

.c .h

C++

.cpp .hpp .cc .hh .cxx .hxx .c++ .h++

Rust

.rs

Go

.go

Enterprise

Java

.java

C#

.cs .csx

Kotlin

.kt .kts

Scala

.scala .sc

Scripting

Python

.py .pyi .pyw

Ruby

.rb .rake .gemspec

PHP

.php .phtml .php3 .php4 .php5 .phps

Functional

OCaml

.ml .mli

Swift

.swift

Language-aware text fallback (5 modes)

These configured modes use LangChain language-specific separators:

Language

Extensions

Markdown

.md .markdown

LaTeX

.tex .ltx

reStructuredText

.rst

Solidity

.sol

Protocol Buffers

.proto

Generic text fallback (32 modes)

The remaining configured text modes use the generic recursive splitter:

Category

Extensions

Config/data

.json .yaml .yml .toml .ini .cfg .conf .env .xml .csv .txt .log

Shell

.sh .bash .zsh .fish .bat .cmd

Styles

.css .scss .sass .less

Queries/DevOps

.sql .graphql .gql .tf .hcl Dockerfile* Makefile CMakeLists.txt

Languages

.zig .nim .lua .r .dart .ex .exs .erl .hrl .hs .lhs .clj .cljs .cljc .lisp .el .vim .vue

The canonical list is assets/languages.json: currently 99 case-insensitive extensions and 18 exact special filenames. Unknown extensions are not collected for indexing.

Auto-excluded Files

Binary files and generated directories are automatically excluded:

  • Binaries: .exe .dll .so .png .jpg .mp3 .zip .wasm

  • Build outputs: .pyc .class .o dist/ node_modules/

How It Works

Indexing Pipeline

Source Files → Secure Scan → Semantic Chunking → AST Enrichment → Cross-file Context → Embeddings → LanceDB
                    ↓                    ↓                  ↓                 ↓
              Split at symbol      Extract symbols    Resolve imports    nomic-embed-text
              boundaries           and metadata       and aliases        768 dimensions

Steps:

  1. Secure scan — Find supported, non-sensitive files under the project root (respects .gitignore, symlink containment, and file-size caps)

  2. Chunk — Split code at function/class boundaries (1000 chars, 200 overlap)

  3. Enrich — Add AST metadata (symbols, imports, exports)

  4. Resolve — Resolve cross-file imports and TypeScript path aliases

  5. Embed — Generate vectors via Ollama or the local lexical provider

  6. Store — Save to LanceDB with vector, full-text, and versioned metadata

  7. Cache — Atomically store file hashes for incremental updates

Search Pipeline

Query → Embed Query → Vector Search ─┐
                                     ├→ RRF Fusion → Add Call Context → Results
Query → Tokenize ───→ BM25 Search ───┘

Steps:

  1. Embed — Convert query to vector using same model

  2. Vector Search — Find semantically similar chunks (cosine similarity)

  3. BM25 Search — Find keyword matches (term frequency)

  4. RRF Fusion — Combine rankings with Reciprocal Rank Fusion (k=60)

  5. Lexical rerank — Boost exact identifiers, symbols, and path matches

  6. Call Context — Add caller/callee information from call graph

  7. Filter and redact — Apply language/path/symbol/test filters and redact common inline secrets when requested

  8. Return — Ranked, bounded results with index metadata

Technical Specifications

Component

Specification

Embedding Provider

Ollama or deterministic lexical fallback

Embedding Model

nomic-embed-text (137M params, Ollama default)

Vector Dimensions

768

Chunk Size

1000 characters

Chunk Overlap

200 characters

Batch Size

10 embeddings per request

RRF Constant

k=60

Vector Database

LanceDB (embedded)

Reproducible benchmark

Measure the actual index_codebase and search_code implementation, including native LanceDB, FTS, hybrid/vector retrieval, reranking and output formatting:

bun run benchmark:retrieval -- --iterations=3 --k=5 \
  --min-recall-at-k=1 --min-mrr=0.95 --min-ndcg-at-k=0.95

The default is the in-process lexical provider. With an already installed, running local Ollama model, add --provider=ollama --model=nomic-embed-text. Nothing is downloaded. The runner copies the selected corpus to a disposable directory, builds a fresh index and evaluates 24 labelled queries across 12 files (benchmarks/retrieval-engine.json). Each mode reports ranking metrics, warm p50/p95, index time, sampled peak RSS and returned-context cost. Latency excludes MCP transport and call-graph enrichment. Duplicated file chunks consume ranking positions but do not earn repeated relevance credit. A truncated corpus is reported explicitly and labels must refer to files actually included.

This small fixture is a regression gate, not a general quality or large-repository performance claim. Use --directory and --dataset for a representative corpus. CI runs the native engine gate with the lexical provider; Ollama is optional.

Run a bounded, local benchmark for semantic chunking and the deterministic lexical baseline (separate from the native retrieval engine):

bun run benchmark -- --directory=src --iterations=3 --max-files=100

The JSON report contains p50/p95 latency, processed bytes/files/chunks, vector dimensions, resident memory, and a conservative estimated token cost. To compute deterministic file-level precision@k, recall@k, MRR, nDCG, and returned-context cost against a labelled corpus, use:

bun run benchmark -- --directory=src --iterations=3 --max-files=100 \
  --dataset=benchmarks/retrieval.json --k=5

The sample corpus is versioned in benchmarks/retrieval.json; replace it with queries and relative file IDs from your own repositories for meaningful quality tracking. Token counts are estimates (UTF-8 bytes / 4), not claims about a specific tokenizer. A 12-query golden corpus across 12 language/file families is versioned in benchmarks/golden-multilang with its labels in benchmarks/golden-multilang.json. CI runs it with strict precision/recall/MRR/nDCG gates. You can apply the same gates to a local corpus with --min-precision-at-k, --min-recall-at-k, --min-mrr, and --min-ndcg-at-k; a failed gate returns a non-zero exit code while preserving the JSON report.

Release validation

Before publishing, validate the built package from a clean temporary install:

bun run pack:verify
bun run conformance:local

Maintain the CHANGELOG.md Unreleased section while developing. Before merging the release commit, rename it to the package version with its YYYY-MM-DD date and add a fresh Unreleased section. The notes follow the six Keep a Changelog categories (Added, Changed, Deprecated, Removed, Fixed, and Security), are maintained manually with AI assistance, and are reviewed as project documentation. bun run changelog:check and the release workflow validate the structure; neither generates or commits release notes.

conformance:local checks the exact tool/resource/prompt surface and the stdio/HTTP × legacy/modern lifecycle matrix without contacting a remote MCP service or downloading a test runner.

The runtime CI matrix targets Node 22/24 on Windows, macOS and Linux with native storage tests, local MCP conformance, build and clean package installation. Release automation publishes npm before creating its GitHub release and checks each destination independently, so reruns can complete a partial publication.

The dependency-free mutation smoke runs a small, versioned set of pagination security mutants against temporary repository copies:

bun run mutation:smoke

The CI job also runs a bounded official MCP compatibility smoke suite on Linux; the current upstream runner is skipped on Windows because it exits with a libuv teardown assertion after successful checks. Modern 2026-07-28 lifecycle coverage is exercised by the local integration tests. The smoke runner pins the currently validated npm package by default; override MCP_CONFORMANCE_VERSION and MCP_CONFORMANCE_SPEC_VERSION together when a new official runner supports a newer protocol revision.

Test and coverage gates

Run the full local quality gate with:

bun run check
bun run contract:verify
bun run test
bun run test:coverage
bun run build
bun run pack:verify
bun run conformance:local

contract:verify fingerprints the reviewed feature schemas and annotations, MCP tools, CLI commands, prompts, resources, public exports, and default configuration. This makes clean-code refactors fail fast if they accidentally remove or alter a capability. Biome applies the repository formatter and lint rules consistently across source and tooling.

The coverage gate requires at least 80% for lines, statements and functions, and 70% for branches. LSP and ast-grep/Semgrep/CodeQL adapters are optional local subprocess integrations; their executable and protocol failure matrix is kept in integration/safe-degradation tests and excluded from this aggregate unit threshold. This is an explicit measurement boundary, not an assertion that those adapters have exhaustive branch coverage.

Dependency audit

bun.lock is the dependency lockfile of record. CI runs bun audit --production against the installed production dependency graph before build and publication. Keep that check green when updating dependencies; npm audit would require a separate package-lock.json for this Bun-managed workspace.

Comparison

SRC vs Basic Code Search MCPs

Feature

SRC

Basic MCPs

Search Method

Hybrid (Vector + BM25 + RRF)

Keyword only or basic embedding

Call Graph

Static caller/callee context

None

Symbol Navigation

LSP/SCIP definitions, references, implementations, hover, hierarchy, diagnostics, plus safe fallback

Usually absent

Dependency Analysis

Cycles, hotspots, blast radius

Usually absent

Repository Orientation

PageRank-style repo map plus fair-budget, multi-layer agent dossier

Usually absent

Change Analysis

Changed files/symbols and conservative dead code

Usually absent

Cross-file Context

Resolves imports & path aliases

None

Incremental Updates

SHA-256 hash detection

Full re-index required

Local Memory

Scoped atomic memory with confidence, expiry, links, Git provenance, and stale-state detection

Usually absent or plain notes

Local Security

Root containment, secret exclusion, type-aware redaction, limits, injection signals, audit metadata

Varies

AST Languages

18 with Tree-sitter WASM

Few or none

Configured Modes

55 (99 extensions)

Limited

Key Advantages

  1. Hybrid Search — Combines semantic understanding with keyword precision

  2. Call Graph — Understand code relationships, not just content

  3. Cross-file Resolution — Follows resolvable local imports and TypeScript path aliases

  4. Incremental Updates — Only re-index what changed

  5. Semantic Chunking — Splits at symbol boundaries, not arbitrary lines

  6. Production MCP contract — SDK v2, strict structured outputs, pagination, annotations, progress/cancellation, cache hints, resources/prompts, and local stdio by default

Explicit boundaries

SRC is production-hardened, but no static code-intelligence server can promise mathematical perfection. The current boundaries are deliberate:

  • Long operations expose progress and cancellation, and the current MCP Tasks extension provides polling for the configured indexing tools. The TypeScript SDK v2 does not provide the old 2025 TaskStore runtime, so SRC owns a narrowly scoped current-extension store rather than importing removed APIs.

  • Type hierarchy and call/dependency resolution are syntax-aware approximations; dynamic dispatch, generated code, reflection, and compiler-only symbol facts can remain unresolved.

  • Each index is scoped to one secure project root. SRC_ALLOWED_ROOTS supports multiple independently indexed roots; list_projects discovers them, but it is not a single merged cross-project index.

  • An explicit project root further restricts SRC_ALLOWED_ROOTS; a broad allowed parent never authorizes access to a sibling project within a scoped operation.

  • Watcher startup reconciles files changed, added or removed while offline. Shutdown drains queued work and performs a final scan. Search pagination uses a fixed pool of 500 retrieval candidates and invalidates cursors when the LanceDB snapshot or index metadata changes. A reached candidate or neighbor bound sets truncated even when no further cursor is available. Refine the query to explore beyond it.

  • FTS indexes are reused across connections. Its lexical fallback streams the complete corpus and retains only its top-k candidates; scan time still grows with corpus size.

  • Byte snippets reject a start offset inside a UTF-8 character and round the end down to a complete character, with exact returned offsets and truncation.

  • On Windows, allow-listed npm TypeScript/Pyright language servers are launched through Node using their verified package entry point; native .exe binaries remain supported. No shell is invoked.

  • The benchmark reports reproducible latency and memory. Retrieval precision/recall/MRR/nDCG is only meaningful when the labelled corpus matches the repository and ranking configuration under test; token cost is an estimate, not a tokenizer billing figure.

  • LSP, SCIP, ast-grep, Semgrep, CodeQL and Ollama are optional local integrations; SRC never downloads them, executes project code, or silently falls back to a remote provider. The in-process lexical provider is the zero-service mode.

These limits are returned or surfaced through diagnostics instead of being silently presented as stronger guarantees.

Troubleshooting

Ollama Connection Failed

Error: Ollama is not available

Solution:

  1. Ensure Ollama is running: ollama serve

  2. Check the URL: curl http://localhost:11434/api/tags

  3. If Ollama uses another local port, set OLLAMA_BASE_URL to a loopback URL

  4. Or use the no-service fallback: EMBEDDING_PROVIDER=lexical

Model Not Found

Error: model 'nomic-embed-text' not found

Solution:

ollama pull nomic-embed-text

Index Already Exists

Error: Index already exists. Use force=true to re-index.

Solution:

  • Use force: true parameter to re-index

  • Or use update_index for incremental updates

No Results Found

Possible causes:

  1. Query too specific — try broader terms

  2. Wrong directory — check directory parameter

  3. Files excluded — check .gitignore patterns

Slow Indexing

Solutions:

  1. Increase concurrency: --concurrency 8

  2. Exclude large directories: --exclude node_modules --exclude dist

  3. Use faster storage (SSD)

Links

Project

External

License

MIT © 2026 kvnpetit

Ready to supercharge your AI coding experience?

npm install -g src-mcp && src-mcp serve
# or
npx -y src-mcp serve

Report Bug · Request Feature

Available Tools

35 tools
analyze_fileanalyze_fileB
Read-onlyIdempotent

Perform a comprehensive analysis of a source code file. Returns symbols, imports, exports, and code metrics. Optionally includes the full AST.

ParametersJSON Schema
NameRequiredDescriptionDefault
file_pathYesPath to the file to analyze
include_astNoInclude full AST in response (default: false, can be verbose)
ast_max_depthNoMaximum depth for AST if included (default: 5)
ast_max_nodesNoMaximum AST nodes if included (default: 10000)
include_chunksNoInclude text chunks for fallback parsing (default: false)
redact_secretsNoRedact common secrets in structured source fields (default: true)
include_exportsNoInclude export statements (default: true)
include_importsNoInclude import statements (default: true)
include_symbolsNoInclude extracted symbols (default: true)

Output Schema

ParametersJSON Schema
NameRequiredDescription
dataNo
metaYes
errorNo
messageNo
successYes
schema_versionYes

TDQS

B3.4/5.0
Behavior3/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description aligns with them—no contradiction. The description adds the high-level behavioral context that it returns symbols, imports, exports, metrics, and optionally the AST. It does not go further into performance implications or output size warnings, though the schema already warns about AST verbosity. With the safety profile covered by annotations, this is a solid but not exceptional 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?

The description is a single, front-loaded sentence covering the core action, primary outputs, and an optional enhancement. Every clause contributes information; there is no filler, repetition, or unnecessary detail. Extremely efficient and scannable.

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?

Given the rich input schema, output schema, and non-destructive annotations, the description is nearly complete for correct invocation. The main gap is the lack of explicit differentiation from closely related siblings, which is the same weakness as purpose clarity and usage guidelines. Still, the description plus schema and annotations provide enough information for an agent to call analyze_file effectively.

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

Parameters3/5

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

The input schema has 100% parameter description coverage and includes defaults and limits for all nine parameters. The description adds no meaningful parameter details beyond mentioning the optional full AST, which the schema already explains. Baseline 3 applies because the schema carries the semantic weight and the description doesn't need to compensate.

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 specific verb and resource ('Perform a comprehensive analysis of a source code file') and enumerates returned data (symbols, imports, exports, code metrics, optional AST). This makes the main purpose clear. However, it does not distinguish itself from siblings like parse_ast, list_symbols, or run_static_analysis, so an agent could still be uncertain which tool to pick.

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?

There is no guidance about when to use analyze_file versus the many sibling tools. The description only states what the tool does, not when it is preferable to parse_ast or list_symbols, nor any exclusions or alternatives. An agent is left to infer the intended use case from the descriptive language alone.

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

analyze_impactAnalyze change impactA
Read-onlyIdempotent

Read-only blast-radius analysis for changed files using the project dependency graph and reverse transitive closure.

ParametersJSON Schema
NameRequiredDescriptionDefault
directoryNoProject root.
max_filesNoMaximum graph files
changed_filesYesChanged project-relative files

Output Schema

ParametersJSON Schema
NameRequiredDescription
dataNo
metaYes
errorNo
messageNo
successYes
schema_versionYes

TDQS

A4.3/5.0
Behavior4/5

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

Annotations already establish readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful behavioral detail beyond that: it reveals the tool computes blast radius via dependency graph traversal and reverse transitive closure, which helps the agent anticipate the analysis semantics.

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?

A single, front-loaded sentence communicates scope, safety, purpose, and method with no filler. Every part of the description earns its place.

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

Completeness5/5

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

Given the presence of an output schema, fully documented parameters, and strong safety annotations, the description is complete enough for an agent to invoke this tool correctly. It conveys the core concept, input domain, and read-only nature without needing additional explanation.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema fully documents all three parameters. The description reinforces the role of 'changed_files' in the impact analysis, but does not add new parameter-level semantics beyond what the schema already provides.

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 action ('blast-radius analysis'), a well-defined input scope ('changed files'), and the underlying method ('project dependency graph and reverse transitive closure'). This clearly distinguishes it from siblings like get_dependency_graph or analyze_file.

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

Usage Guidelines4/5

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

The phrase 'for changed files' establishes a clear intended context: use this when assessing the impact of modified files. It does not explicitly name sibling alternatives or exclusions, but the context is sufficiently clear from the description.

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

assemble_task_contextAssemble task contextB
Read-onlyIdempotent

Prepare a bounded one-call agent dossier combining project profile, revision-aware memory, relevant artifacts, local Git changes, a PageRank-style repository map, and indexed code search. Each layer degrades independently and receives a fair share of the token budget.

ParametersJSON Schema
NameRequiredDescriptionDefault
taskYesThe development task or question to orient around
depthNoContext breadth: map/search only, normal agent dossier, or deeper evidencestandard
directoryNoProject directory.
max_tokensNoApproximate maximum size of the rendered context bundle
include_gitNo
memory_scopeNoproject
search_limitNoMaximum semantic search results
include_memoryNo
include_searchNo
include_artifactsNo
memory_min_confidenceNoIgnore low-confidence memories in the agent dossier
include_project_contextNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
dataNo
metaYes
errorNo
messageNo
successYes
schema_versionYes

TDQS

B3.4/5.0
Behavior3/5

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is safe and non-mutating. The description adds useful behavioral context: layers degrade independently, each gets a fair share of the token budget, and it is a bounded one-call dossier. However, it doesn't elaborate on what happens when some layers fail (e.g., partial results), or how the token budget is allocated among layers. With annotations covering safety, the description adds moderate context beyond them, justifying a 3 rather than a 2.

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, concise sentence of moderate length that front-loads the core purpose ('Prepare a bounded one-call agent dossier') and immediately enumerates the layers. It then adds the two key behavioral traits (independent degradation and fair token budget) without fluff. While it doesn't use structured lists or paragraphs, the sentence is efficient and every clause adds value. Slightly longer than ideal, but appropriate for the complexity.

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

Completeness3/5

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

Given there is an output schema (not shown) and annotations cover safety, the description does not need to explain return values. However, the tool is complex (12 parameters, 6 without schema descriptions) and the description provides only high-level layer coverage. It leaves out how to use flags like include_memory, include_search, or how to balance depth with max_tokens, despite these being critical for a 'bounded' dossier. The behavior of fair token sharing is mentioned but not how it is enforced. The description is complete enough for basic understanding but lacks operational details that an agent would need to tune the tool effectively, so a 3 is appropriate.

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 only 50%, with 6 of 12 parameters lacking descriptions (include_git, include_memory, include_artifacts, include_project_context, memory_scope, and partially depth). The description only mentions 'project profile, revision-aware memory, relevant artifacts, local Git changes, a PageRank-style repository map, and indexed code search', which maps to the include_* flags and depth, but doesn't explain the syntax or semantics of memory_scope's pattern, nor the defaults and interactions. For example, the description does not clarify what 'memory_scope' does or how 'search_limit' interacts with total token budget. Given the low coverage, the description fails to compensate for the undocumented parameters, scoring below the baseline 3.

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 assembles a bounded one-call agent dossier combining multiple context sources, with a specific verb ('assemble') and resource ('task context'). It distinguishes itself from siblings by emphasizing the combination of project profile, memory, artifacts, Git changes, and code search into a single bundle, whereas siblings like get_project_context or search_code are individual data sources. However, it doesn't explicitly name a sibling it is not, so differentiation is inferred rather than explicit.

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

Usage Guidelines4/5

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

The description implies usage as a one-call entry point for gathering comprehensive context before a task, contrasting with individual retrieval tools among siblings. It doesn't provide explicit when-not-to-use or alternative conditions, nor does it mention when to prefer individual tools over this aggregate. The bounded nature and fair token budget suggest efficiency, but no direct comparison is made. Heavily parameterized, the description could guide when to adjust depth or include flags, but lacks explicit routing.

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

find_dead_codeFind dead codeA
Read-onlyIdempotent

Conservatively identify unexported functions, methods, classes, and types with no visible references. Read-only heuristic analysis with confidence and limitations; never removes code.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum candidates to return
directoryNoProject directory.
max_filesNoMaximum source files to inspect
include_testsNoInclude test/spec files in the analysis (default: false)

Output Schema

ParametersJSON Schema
NameRequiredDescription
dataNo
metaYes
errorNo
messageNo
successYes
schema_versionYes

TDQS

A4.1/5.0
Behavior4/5

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral context: it is a heuristic analysis, conservative, reports confidence and limitations, and never removes code. 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.

Conciseness5/5

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

The description is two tight sentences with no redundancy. It front-loads the core purpose and immediately follows with safety and behavioral caveats, making every sentence earn its place.

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

Completeness5/5

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

With full parameter documentation, a complete output schema, and annotations covering read-only/idempotent/non-destructive behavior, the description adds exactly the missing context: heuristic nature, conservatism, confidence, and the guarantee not to remove code. Nothing essential is missing for an agent to invoke it correctly.

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

Parameters3/5

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

Schema description coverage is 100%, so the four parameters (limit, directory, max_files, include_tests) are already fully documented in the schema. The description adds no additional parameter-level meaning, which is acceptable given the high schema coverage.

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 ('identify'), a clear resource ('unexported functions, methods, classes, and types'), and a precise criterion ('no visible references'). This sharply distinguishes it from siblings like search_code or list_symbols, whose broader scopes are not about dead-code discovery.

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

Usage Guidelines3/5

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

The description implies usage for conservative dead-code analysis and clearly signals a read-only, non-destructive role. However, it does not explicitly state when to prefer this tool over alternatives such as run_static_analysis or analyze_file, nor does it mention any exclusions or prerequisites.

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

find_symbolsFind symbols and referencesA
Read-onlyIdempotent

Read-only code navigation across a project: find symbol definitions, textual references, imports, and exports with precise byte offsets and bounded snippets.

ParametersJSON Schema
NameRequiredDescriptionDefault
modeNoWhat to returndefinitions
limitNoMaximum matches
queryNoSymbol or module text to find; empty lists all definitions
cursorNoOpaque cursor returned by a previous page
directoryNoProject directory to inspect.
file_pathNoOptional file path, relative to directory
max_filesNoMaximum files to parse
redact_secretsNoRedact common secrets in returned snippets (default: true)

Output Schema

ParametersJSON Schema
NameRequiredDescription
dataNo
metaYes
errorNo
messageNo
successYes
schema_versionYes

TDQS

A3.8/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description reinforces this with 'Read-only code navigation' and adds behavior details about returning precise byte offsets and bounded snippets, which is useful operational context 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.

Conciseness5/5

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

A single, well-structured sentence that front-loads the read-only nature and the core actions. No wasted words; every phrase contributes to understanding the tool's purpose.

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?

Given 8 parameters and an existing output schema, the description adequately captures the tool's essence. It does not explain pagination or redaction, but these are fully covered in the schema. The description is complete enough for an agent to grasp the primary function.

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

Parameters3/5

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

Schema description coverage is 100%, so each parameter is already documented. The description adds minimal extra meaning; it hints at the mode via the list of results (definitions, references, etc.) but does not detail parameters like limit or cursor. Baseline 3 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?

The description clearly states the verb (find) and resource (symbol definitions, textual references, imports, and exports) within a project. It also specifies precise byte offsets and bounded snippets, making the tool's scope distinct from generic search. Though it doesn't name siblings, it is sufficiently specific.

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 like search_code or list_symbols. It only states what the tool does, leaving the selection decision to the agent without explicit context or exclusions.

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

get_call_graphget_call_graphB
Read-onlyIdempotent

Analyze function call relationships in a codebase. Query callers/callees for a specific function or get full call graph statistics.

ParametersJSON Schema
NameRequiredDescriptionDefault
excludeNoGlob patterns to exclude from analysis
filePathNoOptional: file path to narrow down function search (used with functionName)
maxDepthNoMaximum depth for call chain traversal (default: 2)
maxFilesNoMaximum number of files to analyze (default: 500)
maxNodesNoMaximum number of relationship nodes returned (default: 200)
directoryNoPath to the directory to analyze.
functionNameNoOptional: specific function name to query callers/callees for

Output Schema

ParametersJSON Schema
NameRequiredDescription
dataNo
metaYes
errorNo
messageNo
successYes
schema_versionYes

TDQS

B3.2/5.0
Behavior3/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is complete. The description adds minor behavioral context by distinguishing between targeted caller/callee queries and full statistics, but it does not disclose cap behavior, traversal limits, or potential cost/scale implications beyond what parameter defaults already imply.

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 only two sentences and is front-loaded with the core purpose. It wastes no words, though 'full call graph statistics' is slightly vague and could be more concrete without bloating the text.

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

Completeness3/5

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

An output schema exists and annotations cover the read-only/idempotent profile, so return values and safety need little explanation. However, the description does not explicitly state how functionName and filePath interact, whether functionName is required for caller/callee queries, or what 'full call graph statistics' means. For a tool with seven optional parameters and two modes, this leaves some ambiguity.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema fully documents all seven parameters. The description adds little beyond naming the two modes, which loosely maps to functionName and directory, but it does not add meaning to exclude, maxDepth, maxFiles, maxNodes, or filePath. A baseline of 3 is appropriate given high schema coverage.

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 specific verb and resource: 'Analyze function call relationships in a codebase' and 'Query callers/callees for a specific function or get full call graph statistics.' It clearly identifies what the tool does, but it does not explicitly differentiate it from sibling tools like get_dependency_graph or get_symbol_graph, so it falls short of the top score.

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 gives some sense of the two modes (specific function lookup vs. full statistics) but provides no guidance on when to choose this tool over alternatives such as get_dependency_graph or semantic_navigation. There are no explicit context conditions, exclusions, or sibling comparisons, leaving the agent to infer appropriate usage.

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

get_changed_symbolsGet changed symbolsA
Read-onlyIdempotent

Read-only Git working-tree analysis that maps changed files and zero-context diff hunks to current source symbols. Includes untracked files, bounded output, and explicit limitations when symbols cannot be resolved.

ParametersJSON Schema
NameRequiredDescriptionDefault
directoryNoGit repository root.
max_filesNoMaximum changed files to inspect
max_symbolsNoMaximum changed symbols to return

Output Schema

ParametersJSON Schema
NameRequiredDescription
dataNo
metaYes
errorNo
messageNo
successYes
schema_versionYes

TDQS

A3.6/5.0
Behavior4/5

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

The description adds real behavioral context beyond the annotations: it is explicitly read-only, includes untracked files, relies on zero-context diff hunks, bounds output, and acknowledges limitations when symbols cannot be resolved. This complements rather than contradicts the readOnlyHint, idempotentHint, and destructiveHint annotations.

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?

The description is a single, tightly packed sentence with no filler. The most important framing (read-only, Git, maps changed files to symbols) is front-loaded, and subsequent clauses add meaningful constraints without redundancy.

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?

Given that the annotations cover safety/idempotence, the schema covers all parameters, and an output schema exists, the description offers sufficient behavioral context: untracked files, bounded output, and symbol-resolution limitations. Slightly more detail about how output bounding manifests could push this higher, but as is it is complete enough for invocation.

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

Parameters3/5

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 directory, max_files, and max_symbols well. The description only gestures at bounded output, which maps loosely to the max_* parameters, but does not need to add more because the schema carries the detailed meaning.

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 what the tool does: it maps changed files and zero-context diff hunks to current source symbols. This is a specific verb and resource, and the read-only Git working-tree framing helps set expectations, though it does not explicitly differentiate from siblings like get_git_context.

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 explains what the operation is, but gives no guidance on when to use it versus sibling tools such as get_git_context, get_index_status, or analyze_impact. No alternative tools or exclusion criteria are mentioned, so an agent gets little help choosing between this and similar Git/analysis tools.

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

get_code_snippetGet code snippetA
Read-onlyIdempotent

Read-only bounded source retrieval by exact UTF-8 byte offsets, with line/column positions and no code execution.

ParametersJSON Schema
NameRequiredDescriptionDefault
directoryNoProject root.
file_pathYesFile path relative to directory
max_bytesNoMaximum returned UTF-8 bytes
end_offsetNoExclusive UTF-8 byte offset
start_offsetNoInclusive UTF-8 byte offset
redact_secretsNoRedact common secrets; offsets remain those of the original file

Output Schema

ParametersJSON Schema
NameRequiredDescription
dataNo
metaYes
errorNo
messageNo
successYes
schema_versionYes

TDQS

A4.2/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds valuable context beyond annotations: retrieval is bounded by byte offsets, returns line/column positions, and guarantees no code execution. This is meaningful behavioral detail for an agent deciding whether to invoke it.

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?

The description is a single, dense, front-loaded sentence that conveys the core mechanism (byte offsets), the output (line/column), and the key safety property (no execution). Every element earns its place; there is no filler.

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?

Given the output schema exists and annotations cover the safety profile, the description needn't explain return values. The byte-offset, bounded-retrieval, no-execution details are enough for an agent to select and invoke it. A small gap is the absence of guidance on non-UTF-8 files or behavior when offsets are invalid, but these are minor given the schema's clarity.

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

Parameters3/5

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

Schema description coverage is 100%, and the schema documents all six parameters including defaults and maximum values. The description adds the 'exact UTF-8 byte offsets' framing, which clarifies the offset semantics, but for the most part the schema already carries the parameter documentation weight. Baseline 3 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?

The description states a specific verb ('retrieval'), precise resource (source code), and unique mechanism (exact UTF-8 byte offsets with line/column positions). It also differentiates itself from read siblings by emphasizing no code execution, which matters for tools like parse_ast or analyze_file.

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

Usage Guidelines4/5

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

The description implies use when you need bounded source retrieval by exact byte offsets, and the read-only/no-execution phrasing distinguishes it from analysis tools. However, it doesn't explicitly state when to prefer alternatives like search_code or get_symbol_at_position, leaving some inference to the agent.

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

get_dependency_graphGet dependency graphA
Read-onlyIdempotent

Read-only project architecture analysis: resolve imports/exports, expose a dependency graph, detect cycles, and rank inbound/outbound hotspots.

ParametersJSON Schema
NameRequiredDescriptionDefault
directoryNoProject directory.
max_edgesNoMaximum import edges to return
max_filesNoMaximum files to analyze
max_type_edgesNoMaximum type-hierarchy edges to return
max_type_nodesNoMaximum type-hierarchy nodes to return
include_externalNoInclude unresolved external imports in the graph

Output Schema

ParametersJSON Schema
NameRequiredDescription
dataNo
metaYes
errorNo
messageNo
successYes
schema_versionYes

TDQS

A4.3/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral detail beyond annotations: it resolves imports/exports, exposes a dependency graph, detects cycles, and ranks inbound/outbound hotspots. There is 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.

Conciseness5/5

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

The description is a single, efficient sentence that front-loads the read-only safety context, then lists the tool's capabilities in a compact colon-separated list. Every phrase carries meaning and there is no filler.

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

Completeness5/5

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

Given the rich input schema, output schema, and read-only annotations, the description is complete enough for an agent to understand the tool's role and select it appropriately. The description covers the high-level capabilities while schema and annotations handle parameter and safety details.

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

Parameters3/5

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

Schema description coverage is 100%, with each of the 6 optional parameters documented including defaults and maximums. The description does not need to repeat parameter details, and it adds no parameter-level information beyond the schema. Baseline 3 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?

The description states a specific verb and resource: 'Read-only project architecture analysis' that resolves imports/exports, exposes a dependency graph, detects cycles, and ranks hotspots. This clearly distinguishes it from siblings like get_call_graph or get_symbol_graph by focusing on import/export dependency structure.

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

Usage Guidelines4/5

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

The description provides clear context: this is for project architecture analysis based on imports/exports and dependency relationships. It does not explicitly name alternatives or exclusions, but the 'read-only project architecture analysis' framing gives sufficient guidance for when to select this tool over obvious siblings.

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

get_diagnosticsGet server diagnosticsA
Read-onlyIdempotent

Inspect embedding provider health, index compatibility, path-security configuration, and resource limits without modifying the project.

ParametersJSON Schema
NameRequiredDescriptionDefault
directoryNoProject directory to diagnose.

Output Schema

ParametersJSON Schema
NameRequiredDescription
dataNo
metaYes
errorNo
messageNo
successYes
schema_versionYes

TDQS

A4.2/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value by specifying exactly what is inspected (embedding provider health, index compatibility, path-security configuration, resource limits) and by explicitly stating the operation is non-modifying, which reinforces the read-only behavior 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.

Conciseness5/5

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

The description is a single, well-structured sentence that front-loads the action and scope, then adds the non-modifying guarantee. Every word earns its place; no filler or redundancy.

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?

Given the tool has one optional parameter, a rich output schema, and strong annotations, the description is nearly complete. It could arguably name a sibling alternative for contrast, but the enumerated diagnostic areas and non-modifying clause give an agent enough to select and invoke it correctly.

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

Parameters3/5

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

Schema description coverage is 100%, so the single parameter 'directory' is already fully documented in the schema. The description does not add parameter-specific detail beyond the schema, but the baseline of 3 is appropriate because the schema carries the full burden.

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 ('Inspect') and a clear resource ('embedding provider health, index compatibility, path-security configuration, and resource limits'), and explicitly notes it does not modify the project. This distinguishes it from sibling tools like get_index_status or get_server_info by enumerating the diagnostic scope.

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

Usage Guidelines4/5

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

The description implies when to use it: when you need diagnostics across the listed areas without modifying the project. It does not explicitly name alternatives or exclusions, but the 'without modifying the project' clause and the enumerated scope provide clear context for selection among the many sibling tools.

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

get_git_contextGet local Git contextB
Read-onlyIdempotent

Inspect bounded local Git status, diff, history, optional churn hotspots, local revision comparisons, blame, CODEOWNERS, and changed-symbol analysis. It uses only fixed non-remote Git commands, rejects arbitrary command arguments, and never executes project scripts.

ParametersJSON Schema
NameRequiredDescriptionDefault
filesNoOptional project-relative paths; no remote refs are accepted
directoryNoLocal Git repository root.
compare_toNoLocal Git revision; ranges, reflogs, and remote fetches are rejected
max_historyNo
compare_fromNoLocal Git revision; ranges, reflogs, and remote fetches are rejected
include_diffNo
max_hotspotsNo
include_blameNo
include_statusNo
max_diff_bytesNo
redact_secretsNo
include_historyNo
max_blame_linesNo
include_hotspotsNoAggregate historical file churn from local commits
max_compare_filesNo
include_codeownersNo
include_changed_symbolsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
dataNo
metaYes
errorNo
messageNo
successYes
schema_versionYes

TDQS

B3.4/5.0
Behavior4/5

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

The description adds valuable constraints beyond the annotations: it states the tool uses only fixed non-remote Git commands, rejects arbitrary command arguments, and never executes project scripts. This is safety-relevant behavior not present in the readOnly/idempotent/non-destructive annotations, and it does not contradict them.

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?

Two concise sentences front-load the purpose and then state key constraints. No filler; every sentence earns its place.

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?

For a tool with 17 parameters and no required ones, the description is too sparse. It doesn't explain parameter semantics for most parameters, doesn't mention when to use this over sibling tools, and doesn't provide usage examples or behavior beyond basic safety. The presence of an output schema covers return values, but the overall description is insufficient for an agent to use it effectively.

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

Parameters3/5

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

Schema coverage is low (29%), with only 3 of 17 parameters having descriptions. The description lists several capabilities (hotspots, comparisons, blame, CODEOWNERS, changed symbols) that map to parameters, providing some semantic context, but it does not explain the many numeric parameters (max_history, max_diff_bytes, etc.) or their defaults. It partially compensates for the schema gaps but not fully.

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's purpose with the verb 'inspect' and lists the specific local Git context it provides (status, diff, history, hotspots, comparisons, blame, CODEOWNERS, changed symbols). It emphasizes 'bounded local' and 'non-remote', which helps distinguish it from remote Git operations, though it does not explicitly name sibling 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 is provided on when to use this tool versus the many sibling tools (get_changed_symbols, get_repository_map, etc.). The description mentions safety constraints but not usage context or alternatives, leaving the agent to infer when this tool is appropriate.

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

get_index_statusget_index_statusA
Read-onlyIdempotent

Check if a codebase is indexed and ready for search. USE THIS to verify index exists before searching. Returns file count, chunk count, and indexed languages.

ParametersJSON Schema
NameRequiredDescriptionDefault
directoryNoPath to the directory to check (defaults to current directory).

Output Schema

ParametersJSON Schema
NameRequiredDescription
dataNo
metaYes
errorNo
messageNo
successYes
schema_versionYes

TDQS

A3.8/5.0
Behavior3/5

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

Annotations already disclose the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=false), so the description's burden is minimal. It adds value by previewing the return payload (file count, chunk count, indexed languages), which goes beyond the annotations 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.

Conciseness5/5

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

Three compact sentences with the core purpose front-loaded, a directive usage hint, and a return-payload note. Every sentence earns its place; there is no fluff or boilerplate.

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 simple 1-optional-parameter tool with rich annotations and an output schema, the description covers purpose, usage timing, and the essence of the return values. Nothing an agent needs to call it correctly is materially missing.

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

Parameters3/5

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

Schema coverage is 100% for the single 'directory' parameter, with its default and purpose already documented in the schema. The description adds no parameter-level syntax or format details beyond what the schema provides, so the baseline of 3 is appropriate.

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 specific verb+resource ('Check if a codebase is indexed and ready for search') and clearly positions the tool as a verification step distinct from mutation siblings like index_codebase, update_index, and maintain_index. It does not explicitly name a sibling, which keeps it from a 5, but the purpose is unambiguous.

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

Usage Guidelines4/5

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

'USE THIS to verify index exists before searching' is an explicit when-to-use directive that routes the agent to this tool ahead of search operations. It lacks an explicit when-not-to-use statement or named alternative (e.g., 'use index_codebase if not indexed'), so it falls short of full guidance.

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

get_observabilityGet local observabilityA
Read-onlyIdempotent

Read bounded local metrics, runtime counters, and secret-free audit status as structured JSON or a Prometheus text export; no telemetry leaves the process.

ParametersJSON Schema
NameRequiredDescriptionDefault
formatNoReturn structured JSON data or a local Prometheus text exportjson
directoryNoProject directory.

Output Schema

ParametersJSON Schema
NameRequiredDescription
dataNo
metaYes
errorNo
messageNo
successYes
schema_versionYes

TDQS

A4.3/5.0
Behavior4/5

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 valuable context beyond those annotations: outputs are bounded, secret-free, and never leave the process. This gives the agent a meaningful behavioral model for safety and privacy 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.

Conciseness5/5

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

The description is a single sentence that front-loads the core purpose, names the output formats, and ends with an important privacy guarantee. Every phrase earns its place, and there is no redundant repetition of the tool name or schema fields.

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

Completeness5/5

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

For a simple read-only tool with two optional parameters, full schema description coverage, annotations, and an output schema, the description is sufficiently complete. It clarifies scope, privacy, security, and output formats, so an agent has enough information to invoke the tool correctly.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already fully documents the format and directory parameters. The description adds a little color by mentioning structured JSON and Prometheus text export, but it does not materially deepen the meaning beyond what the schema already provides. Baseline 3 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?

The description specifies a clear verb ('Read') and resource ('bounded local metrics, runtime counters, and secret-free audit status'), and distinguishes the tool from siblings by emphasizing 'local' and 'no telemetry leaves the process.' This makes it easy for an agent to understand what get_observability does and how it differs from wide-area or server-focused tools.

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

Usage Guidelines4/5

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

The description gives a clear context of use: local observability data without network egress. It does not explicitly name alternatives or state when not to use it, but it strongly implies the boundary between local metrics and other tools. This earns a 4 rather than a 5 because no explicit sibling routing or exclusion is provided.

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

get_project_artifactsGet project artifactsB
Read-onlyIdempotent

Discover and search bounded project documentation such as README files, architecture notes, ADRs, specifications, plans, runbooks, security notes, and changelogs without executing or persisting their content.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum artifacts returned
queryNoOptional words to search in artifact paths, titles, and content
directoryNoProject directory.
max_filesNoMaximum documentation files to inspect
redact_secretsNoRedact common inline secrets in returned content
include_contentNoInclude bounded redacted document content
max_content_bytesNoMaximum content bytes per returned artifact

Output Schema

ParametersJSON Schema
NameRequiredDescription
dataNo
metaYes
errorNo
messageNo
successYes
schema_versionYes

TDQS

B3.4/5.0
Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, covering safety. The description adds a useful behavioral note: 'without executing or persisting their content,' which clarifies that the tool only reads and does not modify state. However, it does not disclose other behaviors like redaction defaults or content limits, which are partially in the schema but not highlighted. With annotations covering the core profile, this is adequate but not rich.

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

Conciseness5/5

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

The description is a single, efficient sentence that front-loads the purpose and provides a concrete list of document types. There is zero wasted wording, and every phrase adds value. This is a model of conciseness.

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?

Given the tool's moderate complexity (7 parameters) and the presence of a complete output schema, the description is sufficient for an agent to call it correctly. It covers the scope ('bounded project documentation'), the non-executing behavior, and the parameter details are in the schema. The only missing piece is usage guidance, but that is captured under usage_guidelines. Overall, it is complete enough for a read-only, well-annotated tool.

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

Parameters3/5

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 all seven parameters. The description does not add any additional meaning beyond the schema—it merely summarizes the tool's purpose. Per the baseline rule, a 3 is appropriate since the schema handles parameter documentation entirely.

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's purpose: discover and search bounded project documentation, listing specific document types. It uses a specific verb ('discover and search') and a clear resource, and it is not a tautology. However, it does not explicitly differentiate from sibling tools like get_project_context or get_project_catalog, which might also deal with project-level information, so it loses one point for not providing sibling differentiation.

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. It does not mention when to prefer this over search_code or get_project_context, nor does it give any exclusions or conditions. The agent must infer usage purely from the purpose statement, which is insufficient for effective tool selection among many siblings.

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

get_project_catalogGet project artifact catalogB
Read-onlyIdempotent

Read the bounded, project-isolated local artifact catalog created by refresh_project_catalog, optionally including redacted live document excerpts.

ParametersJSON Schema
NameRequiredDescriptionDefault
kindNo
limitNo
queryNo
scopeNoLocal catalog namespace isolated inside this projectproject
cursorNo
directoryNoProject directory.
search_modeNoUse weighted phrase/field matching or simple lexical matchinghybrid
redact_secretsNo
include_contentNo
max_content_bytesNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
dataNo
metaYes
errorNo
messageNo
successYes
schema_versionYes

TDQS

B3.4/5.0
Behavior4/5

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds that the catalog is bounded, project-isolated, and may include redacted excerpts, which gives behavioral context beyond the annotation flags. No contradiction.

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?

A single, well-structured sentence that front-loads the core purpose and adds a conditional detail. No wasted words.

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?

Despite the presence of an output schema and annotations, the description is insufficient for a 10-parameter tool with low schema coverage. It does not explain pagination (cursor), filtering (kind, query), or output size controls (limit, max_content_bytes), leaving agents to guess parameter semantics.

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 only 30% (3 of 10 params have descriptions). The description's mention of 'redacted live document excerpts' hints at include_content and redact_secrets, but it does not clarify limit, cursor, kind, query, or max_content_bytes, leaving most parameters unexplained.

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 identifies the action (read), the resource (local artifact catalog), and its key characteristic (project-isolated, created by refresh_project_catalog). This distinguishes it from live-source queries and other catalog tools, though it does not explicitly name an alternative sibling.

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

Usage Guidelines3/5

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

It implies the catalog must first be built by refresh_project_catalog, giving a clear prerequisite. However, it does not state when to use this over related getters like get_project_artifacts or search_code, leaving selection to inference.

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

get_project_contextGet project contextA
Read-onlyIdempotent

Build a bounded local onboarding profile: project type, languages, frameworks, manifests, scripts, workspaces, entrypoints, tests, configuration, documentation, and path aliases. It never executes project commands.

ParametersJSON Schema
NameRequiredDescriptionDefault
directoryNoProject directory.
max_filesNoMaximum source files to inspect
max_manifestsNoMaximum project manifests to inspect
redact_secretsNoRedact common inline secrets in returned commands
include_scriptsNoInclude package scripts, without executing them

Output Schema

ParametersJSON Schema
NameRequiredDescription
dataNo
metaYes
errorNo
messageNo
successYes
schema_versionYes

TDQS

A3.6/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, but the description adds meaningful context beyond those: the scan is bounded and local, and it 'never executes project commands'—a stronger and more specific behavioral guarantee than a generic read-only hint. 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.

Conciseness5/5

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

The description is two sentences with no filler: the first front-loads the core purpose and enumerated scope, and the second adds a critical safety constraint. Every part earns its place.

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?

The tool is moderately complex with five optional parameters, but schema coverage is 100% and an output schema exists, so return values need not be described. The description completes the picture with bounded/local scope and execution safety. The main gap is explicit routing among the many overlapping sibling inspection tools.

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

Parameters3/5

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

All five parameters are fully documented in the input schema, so the baseline is 3. The description's category list loosely maps to some parameters (manifests, scripts, redact_secrets), but it adds no parameter-level meaning beyond what the schema already provides.

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 specific resource and action: build a bounded local onboarding profile covering project type, languages, frameworks, manifests, scripts, workspaces, entrypoints, tests, configuration, documentation, and path aliases. This makes the tool's scope concrete and visibly different from the many sibling query/index tools, though it does not explicitly name an alternative.

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 implies the use case (local onboarding/inspection) and the safety property that it never executes project commands, but it provides no explicit when-to-use or when-not-to-use guidance. None of the numerous sibling tools are mentioned as alternatives or exclusions.

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

get_project_memoryGet project memoryA
Read-onlyIdempotent

Read bounded, project-isolated local memory containing decisions, constraints, facts, todos, and notes. It never calls a remote service and marks all stored content as untrusted data.

ParametersJSON Schema
NameRequiredDescriptionDefault
kindNoFilter by memory kind
tagsNoRequire all of these tags
limitNo
queryNoOptional words to find in titles, notes, tags, or links
scopeNoLocal memory namespace isolated inside this projectproject
cursorNo
directoryNoProject directory.
search_modeNoUse weighted phrase/field matching or simple lexical matchinghybrid
min_confidenceNoExclude memories below this confidence threshold
redact_secretsNoRedact common inline secrets in returned notes
include_expiredNoInclude records whose expiry date has passed

Output Schema

ParametersJSON Schema
NameRequiredDescription
dataNo
metaYes
errorNo
messageNo
successYes
schema_versionYes

TDQS

A3.7/5.0
Behavior4/5

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

Annotations already cover readOnly, idempotent, and non-destructive behavior. The description goes further by explicitly stating that the tool never calls a remote service and treats all stored content as untrusted data, which adds valuable trust and privacy context that the annotations do not convey. This is useful 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.

Conciseness5/5

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

The description is extremely concise: two sentences, both substantive. The opening sentence immediately states the core action and scope, and the second adds relevant behavioral constraints. There is no wasted text, and each sentence carries meaning.

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

Completeness3/5

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

The description adequately frames the tool's existance and trust profile, but it omits meaningful context about pagination and filtering. Likely parameters like 'cursor' and 'limit' are not mentioned in prose, and given 11 optional parameters, an agent is left to inspect the schema without guidance on how the tool's internal bounds apply. It is not grossly incomplete, but there are clear gaps.

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

Parameters3/5

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

With 82% schema coverage, the baseline is 3. The description lists the memory kinds (decision, constraint, fact, todo, note), which mirrors the kind enum already present in the input schema, so it adds little meaning beyond what the schema already provides. It offers no additional insight on filters, pagination, or niche parameters like cursor or limit.

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 identifies the specific verb 'Read' and resource 'bounded, project-isolated local memory,' and lists the memory kinds (decisions, constraints, facts, todos, notes). It distances itself from sibling tools like set_project_memory by emphasizing the read-only nature, but it does not explicitly differentiate this from get_project_context or get_project_artifacts, leaving some boundary ambiguity.

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

Usage Guidelines3/5

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

The description implies the tool is used when an agent needs to retrieve project-local memory, but it gives no explicit 'when to use' or 'when not to use' guidance, and no alternatives are mentioned. Given the presence of several similar siblings (get_project_context, get_project_artifacts, get_project_catalog), the lack of routing guidance is a noticeable gap.

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

get_repository_mapGet repository mapA
Read-onlyIdempotent

Build a bounded, task-focusable repository map of important files and symbols. Ranking uses import-graph centrality plus optional path/symbol focus, so an agent can orient itself before reading source.

ParametersJSON Schema
NameRequiredDescriptionDefault
focusNoOptional paths or symbols to prioritize
directoryNoProject directory.
max_filesNoMaximum files to inspect
max_tokensNoApproximate maximum size of the textual map
redact_secretsNoRedact common secrets in the rendered map (default: true)

Output Schema

ParametersJSON Schema
NameRequiredDescription
dataNo
metaYes
errorNo
messageNo
successYes
schema_versionYes

TDQS

A4/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, covering safety. The description adds behavioral context about ranking (import-graph centrality, optional focus) and the bounded nature (max files/tokens). This goes beyond the annotations and helps the agent understand what the tool does internally. 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.

Conciseness5/5

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

Two sentences with no fluff. The main purpose is front-loaded, and the ranking method and usage context are provided in the second sentence. Every part is useful and directly relevant.

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?

The description explains the purpose, ranking mechanism, and usage context. Since an output schema exists, it does not need to explain return values. It covers the essential behavior an agent needs to decide when to use it, and the bounded nature is mentioned. Minor gaps like the exact format of the map are covered by the output schema.

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

Parameters3/5

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

Schema coverage is 100%, with each parameter having a description. The description mentions 'path/symbol focus' which maps to the focus parameter, but it does not add substantial detail beyond the schema. Baseline 3 is appropriate since the schema already handles parameter documentation and the description adds marginal value.

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 it builds a repository map of important files and symbols, with a specific verb ('build') and resource. It distinguishes itself from siblings by mentioning 'task-focusable' and ranking via centrality/focus, which sets it apart from list_symbols or get_dependency_graph. However, it does not explicitly name an alternative, so it falls just short of a 5.

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

Usage Guidelines4/5

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

The description gives a clear usage context: 'so an agent can orient itself before reading source.' This implies when to use the tool (as a preliminary step) and its purpose. It does not explicitly mention when not to use it or name alternatives, but the context is sufficient for an agent to infer appropriate usage.

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

get_server_infoget_server_infoA
Read-onlyIdempotent

Get SRC server identity, version, and description. Use to verify the MCP server is running correctly.

ParametersJSON Schema
NameRequiredDescriptionDefault
formatNoOutput formattext

Output Schema

ParametersJSON Schema
NameRequiredDescription
dataNo
metaYes
errorNo
messageNo
successYes
schema_versionYes

TDQS

A4.3/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds semantic context that the tool returns server identity, version, and description, which goes beyond the annotations and helps the agent anticipate the content. It does not contradict any annotation, and while it omits details like authentication or rate limits, the simplicity of the operation and the annotation coverage keep the gap minimal.

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?

The description is two short sentences with zero filler. The primary purpose ('Get SRC server identity, version, and description') is front-loaded, followed immediately by the usage context. Every word contributes to the agent's understanding, achieving an ideal balance of brevity and informativeness.

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

Completeness5/5

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

The tool is simple: one optional parameter with full schema documentation and an output schema already defined. The description provides the purpose and a concrete usage scenario, which is all an agent needs to decide when to call it and what to expect. For a read-only informational tool with no side effects, nothing essential is missing.

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

Parameters3/5

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

The input schema provides 100% coverage for the single 'format' parameter, including an enum ('json'/'text'), a default, and a description. The description itself adds no parameter-specific information, but since the schema fully documents the parameter, the baseline of 3 is appropriate. The description's mention of 'identity, version, and description' does not clarify the format parameter's effect, though it is not required to.

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 ('Get'), a clear resource ('SRC server'), and the exact data returned ('identity, version, and description'). It also gives an explicit use case ('verify the MCP server is running correctly'), which makes the tool's purpose unmistakable. No sibling tool overlaps with this informational role, so it is well differentiated.

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

Usage Guidelines4/5

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

The description explicitly says 'Use to verify the MCP server is running correctly,' which gives a clear when-to-use scenario. It does not mention any alternatives or exclusions, but none of the sibling tools serve a similar purpose, so the guidance is sufficient. A perfect score would require explicit when-not conditions, which are not present.

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

get_symbol_at_positionGet symbol at positionA
Read-onlyIdempotent

Resolve the smallest Tree-sitter symbol containing an exact 1-based line and 0-based column. Returns byte-precise ranges and a bounded source body for efficient code navigation.

ParametersJSON Schema
NameRequiredDescriptionDefault
lineYes1-based source line
columnYes0-based character column
directoryNoProject directory.
file_pathYesSource file path relative to directory
include_sourceNoInclude a bounded exact symbol body when found
redact_secretsNoRedact common secrets in returned source (default: true)
max_source_bytesNoMaximum source bytes returned for the symbol

Output Schema

ParametersJSON Schema
NameRequiredDescription
dataNo
metaYes
errorNo
messageNo
successYes
schema_versionYes

TDQS

A4/5.0
Behavior4/5

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

Annotations already establish read-only, idempotent, non-destructive safety, so the bar is lower. The description adds genuinely useful behavior beyond annotations: resolution selects the smallest containing symbol, returns byte-precise ranges, and bounds the source body. 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.

Conciseness5/5

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

Two sentences of about 28 words, front-loaded with the core operation before the return-format detail. Every clause earns its place and nothing redundantly repeats the schema.

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?

With a full output schema, complete parameter coverage, and annotations carrying the safety profile, the description covers the essential contract: coordinate convention, resolution granularity, and output bounding. Minor gaps remain around error behavior when no symbol is found, but nothing an agent needs for a typical correct call is missing.

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

Parameters3/5

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

Schema description coverage is 100%, so the baseline is 3. The description adds modest cross-parameter meaning by tying 'bounded source body' to include_source/max_source_bytes and reinforcing the 1-based/0-based coordinate conventions, but adds no format or syntax details beyond the schema.

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?

States a specific verb ('Resolve') and a specific resource ('the smallest Tree-sitter symbol') with exact coordinate semantics ('exact 1-based line and 0-based column'). This distinguishes it from name-based siblings like find_symbols and query-based search_code without needing to open schemas.

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

Usage Guidelines3/5

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

The phrase 'for efficient code navigation' plus the exact-coordinate framing implies position-based lookup, but no alternative tools are named and there is no when-not-to-use guidance. With close siblings like semantic_navigation, get_code_snippet, and parse_ast available, the agent must infer the selection criteria.

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

get_symbol_graphGet unified symbol graphB
Read-onlyIdempotent

Build a bounded local symbol-level graph combining modules, definitions, imports, references, calls, inheritance, tests, routes, events, and dependency-injection signals, with trace paths and blast-radius analysis.

ParametersJSON Schema
NameRequiredDescriptionDefault
focusNoOptional symbol, path, or node identifiers to prioritize
trace_toNoOptional node, symbol, or path at the end of a trace
directoryNoProject directory.
max_edgesNoMaximum graph edges returned
max_filesNoMaximum source files to inspect
max_nodesNoMaximum graph nodes returned
edge_kindsNoRelationship kinds to include
trace_fromNoOptional node, symbol, or path at the start of a trace
include_testsNoInclude test symbols and test discovery edges
redact_secretsNoRedact common secrets in evidence snippets
include_signalsNoDetect static route, event, and dependency-injection signals
max_path_lengthNoMaximum edges in a returned trace
trace_directionNoDirection used by trace_pathforward

Output Schema

ParametersJSON Schema
NameRequiredDescription
dataNo
metaYes
errorNo
messageNo
successYes
schema_versionYes

TDQS

B3.4/5.0
Behavior3/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful context by noting the graph is 'bounded' and 'local' and mentioning trace paths and blast-radius analysis, but it does not explain how bounds work or what resource costs might be incurred.

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 that leads with the core action and scope. Every clause adds meaningful information about graph contents or capabilities, with no filler or redundancy.

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

Completeness3/5

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

For a tool with 13 parameters and an output schema, the description gives a solid high-level overview of what the graph contains and what analysis is available. However, it does not address how it complements or overlaps with sibling tools like get_call_graph or analyze_impact, and it leaves relationship-selection and trace-direction behavior to the schema.

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

Parameters3/5

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

Schema description coverage is 100%, so every parameter already has a clear description in the schema. The prose references trace paths and edge kinds that map to trace_from/trace_to and edge_kinds, but it does not add semantic detail beyond what the schema already provides.

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 ('Build') and names a clear resource ('bounded local symbol-level graph'), then enumerates the graph's contents: modules, definitions, imports, references, calls, inheritance, tests, routes, events, and DI signals. It is clearly distinct from narrower siblings like get_call_graph and get_dependency_graph, though it does not explicitly name those alternatives.

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

Usage Guidelines3/5

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

There is no explicit when-to-use or when-not-to-use guidance and no sibling routing. The word 'unified' and the large list of edge kinds imply this tool is for broad, cross-cutting symbol-graph and blast-radius exploration, but an agent is left to infer that a call-only or dependency-only graph should go elsewhere.

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

import_scip_indexImport local SCIP indexA
Idempotent

Import a local SCIP JSON export, or ask an installed local scip CLI to print a binary SCIP index as JSON, into the project-isolated catalog used by semantic navigation. No remote service or project script is executed.

ParametersJSON Schema
NameRequiredDescriptionDefault
formatNoRead JSON directly or ask the local scip CLI to print JSONauto
directoryNoProject directory.
index_fileNoExisting project-relative SCIP file or JSON exportindex.scip
timeout_msNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
dataNo
metaYes
errorNo
messageNo
successYes
schema_versionYes

TDQS

A3.8/5.0
Behavior4/5

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

Annotations already declare idempotentHint=true, destructiveHint=false, and readOnlyHint=false. The description adds genuinely useful behavior beyond that: the dual execution modes (read JSON directly vs ask the local scip CLI to print binary SCIP as JSON) and the explicit safety guarantee that no remote service or project script executes. Nothing contradicts 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.

Conciseness5/5

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

Two sentences with zero waste: the first front-loads the purpose and mechanism, the second delivers a security-relevant behavioral guarantee. Every sentence earns its place and the structure is easy to scan.

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?

An output schema exists, so return-value documentation is not the description's burden, and annotations cover idempotence/destructiveness. The description covers input sources, the conversion mode, the target catalog, and a safety safeguard. The main gap is the absence of routing guidance versus index_codebase/update_index, which matters given the tool's two execution modes.

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

Parameters3/5

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

Schema description coverage is 75%, so format, directory, and index_file are already documented in the schema. The description reinforces the format enum by describing the two modes (direct JSON export vs CLI conversion), which is additive but not substantial. It does not cover the undocumented timeout_ms parameter; at 75% coverage the baseline 3 is appropriate.

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 names a specific verb and resource: import a local SCIP JSON export, or convert a binary SCIP index via the local scip CLI, into the project-isolated semantic-navigation catalog. This is enough to distinguish it from search/query/parse siblings, but it does not explicitly contrast the closest sibling, index_codebase, which builds an index from source rather than importing an existing one.

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

Usage Guidelines3/5

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

Usage context is implied: use this when an existing local SCIP file (JSON or binary) must be loaded into the catalog, and the guardrail 'No remote service or project script is executed' communicates a meaningful constraint. However, there is no explicit when-to-use vs alternatives, no when-not-to-use, and index_codebase/update_index are never named.

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

index_codebaseindex_codebaseA
DestructiveIdempotent

Index a codebase for semantic code search. USE THIS FIRST before search_code. Required once per project - creates vector embeddings for 55 configured language modes across 99 extensions. After initial indexing, use update_index for incremental updates.

ParametersJSON Schema
NameRequiredDescriptionDefault
forceNoForce re-indexing even if index exists
excludeNoAdditional glob patterns to exclude
directoryNoPath to the directory to index (defaults to current directory).
concurrencyNoNumber of files to process in parallel (default: 4)

Output Schema

ParametersJSON Schema
NameRequiredDescription
dataNo
metaYes
errorNo
messageNo
successYes
schema_versionYes

TDQS

A4.5/5.0
Behavior4/5

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

The annotations already convey destructive and idempotent behavior; the description adds useful context by explaining that the tool creates vector embeddings across 55 language modes and 99 extensions and that update_index should be used afterward for increments. It does not belabor the destructive nature because the annotation already covers it.

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?

Three sentences with no filler. The first sentence states the core action, the second emphasizes the required ordering, and the third gives the incremental-update alternative; every sentence earns its place.

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

Completeness5/5

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

For an indexing operation with a full output schema, complete parameter documentation, and annotations covering safety/idempotency, the description provides all essential operational context: what it does, when it is required, and what to use afterward. Nothing critical is missing.

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

Parameters3/5

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

Schema description coverage is 100%, so all four parameters (force, exclude, directory, concurrency) are already documented in the schema. The description adds no parameter-level detail, which is acceptable but means the description contributes no extra semantic value here.

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?

States a specific verb and resource ('Index a codebase') plus the purpose ('for semantic code search'), and explicitly tells the agent to use this before search_code. It also distinguishes itself from update_index by framing this as the initial one-time indexing step.

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

Usage Guidelines5/5

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

Provides explicit ordering guidance ('USE THIS FIRST before search_code'), says how often it is needed ('Required once per project'), and names the correct follow-up tool for later changes ('use update_index for incremental updates'). This leaves no ambiguity about when to invoke it.

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

list_projectsList configured projectsA
Read-onlyIdempotent

List the safe project roots available to SRC and each index status. Use this before querying multiple configured repositories; projects remain independently indexed and queried.

ParametersJSON Schema
NameRequiredDescriptionDefault
includeCurrentNoInclude the current directory when no roots are configured

Output Schema

ParametersJSON Schema
NameRequiredDescription
dataNo
metaYes
errorNo
messageNo
successYes
schema_versionYes

TDQS

A4.3/5.0
Behavior4/5

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint, and the description adds meaningful context beyond those: the notion of 'safe' roots, the inclusion of index status, and the independence of projects. No contradiction exists.

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?

Two short sentences with no filler. The first sentence defines scope and output; the second gives usage direction. Both earn their place.

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

Completeness5/5

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

Given the output schema exists, the single optional parameter is fully documented in the schema, and the annotations cover safety/idempotency, the description is complete. An agent has everything needed to call this tool correctly.

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

Parameters3/5

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

The input schema has 100% description coverage, including a clear explanation for includeCurrent. The description itself does not discuss parameters, so the baseline of 3 is appropriate since the schema is already doing the heavy lifting.

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 action ('List') and resource ('safe project roots available to SRC') plus the output detail ('each index status'). This distinguishes it clearly from sibling tools like get_index_status and list_symbols.

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

Usage Guidelines4/5

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

The description gives a concrete when-to-use instruction: 'Use this before querying multiple configured repositories.' It also explains the behavioral context that projects are independently indexed and queried. It does not explicitly name alternatives or when-not-to-use, which would merit a 5.

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

list_symbolslist_symbolsB
Read-onlyIdempotent

Extract all code symbols (functions, classes, variables, etc.) from a file. Returns structured information including name, type, location, and signature for each symbol.

ParametersJSON Schema
NameRequiredDescriptionDefault
typesNoFilter by symbol types: function, class, variable, constant, interface, type, enum, method, property
contentNoCode content to analyze directly (either file_path or content required)
languageNoLanguage name (auto-detected from file path if not provided)
file_pathNoPath to the file to analyze (either file_path or content required)
max_symbolsNoMaximum symbols returned (default: 1000)

Output Schema

ParametersJSON Schema
NameRequiredDescription
dataNo
metaYes
errorNo
messageNo
successYes
schema_versionYes

TDQS

B3.4/5.0
Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds that the result is structured with name, type, location, and signature, but does not mention constraints like max_symbols or the file_path/content requirement. 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.

Conciseness5/5

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

The description is two sentences with no filler. The action and result are front-loaded, and every sentence adds meaningful information.

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?

Given the rich input schema, output schema, and safety annotations, the description is nearly sufficient for calling this read-only tool correctly. The only notable gap is the lack of explicit routing guidance among the many symbol-related sibling tools.

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

Parameters3/5

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 all five parameters. The description only adds generic context about symbol kinds and does not provide additional parameter-level semantics beyond the schema, so the baseline 3 is appropriate.

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 a specific verb ('Extract all code symbols') and a specific resource ('from a file'), and previews the structured output fields. It is not tautological, but it does not explicitly disambiguate itself from sibling tools like find_symbols or parse_ast.

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 gives no guidance on when to prefer this tool over alternatives such as find_symbols, parse_ast, or query_code. It implies a use case—extracting symbols from a file—but provides no explicit context, prerequisites, or exclusion criteria.

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

maintain_indexMaintain the local indexA
Idempotent

Inspect, compact, and migrate the local LanceDB index with bounded, explicit maintenance operations; no project code is executed.

ParametersJSON Schema
NameRequiredDescriptionDefault
directoryNoProject directory.
operationNoInspect the local index, compact its fragments, or migrate local Lance manifestsinspect
delete_unverifiedNoFor compaction, remove unverified fragments after a safe snapshot
cleanup_older_than_daysNoFor compaction, prune table versions older than this many days

Output Schema

ParametersJSON Schema
NameRequiredDescription
dataNo
metaYes
errorNo
messageNo
successYes
schema_versionYes

TDQS

A4.2/5.0
Behavior4/5

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

Beyond the annotations, the description discloses two valuable behavioral traits: operations are bounded/explicit and no project code is executed, which meaningfully limits the blast radius of a mutating tool. Parameter descriptions add that compaction removes fragments only after a safe snapshot and prunes old versions, consistent with destructiveHint=false. No contradiction with the annotations; readOnlyHint=false correctly reflects the mutating operations.

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?

The description is a single well-structured sentence, front-loaded with the three action verbs and closing with the safety qualifier. Every phrase earns its place; there is no filler or repetition of the title.

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?

A fully documented schema, annotations, and an output schema cover most of what an agent needs to choose an operation and supply valid parameters. A minor gap is the absence of prerequisites (e.g., the index must already exist) or an explicit note about what format changes 'migrate' may perform.

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

Parameters3/5

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

Schema description coverage is 100%, with the operation enum and every parameter carrying its own description. The tool description itself adds no parameter-level detail beyond what the schema already provides, which is the baseline-3 scenario.

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 resource (local LanceDB index) and three concrete operations (inspect, compact, migrate) with the qualifier that no project code is executed. This clearly separates it from siblings like index_codebase and update_index, which are about building or refreshing code-derived indexes.

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

Usage Guidelines4/5

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

The phrase 'bounded, explicit maintenance operations; no project code is executed' gives an agent clear context to use this tool for index maintenance rather than code indexing or execution. However, it does not explicitly name alternative tools or state strict when-not conditions, so the selection guidance is implied rather than spelled out.

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

manage_index_snapshotsManage local index snapshotsA
Destructive

Create, verify, restore, list, and clean bounded local snapshots of the semantic index. Snapshots never leave the project, restore uses verified files and a recovery snapshot by default, and no project code is executed.

ParametersJSON Schema
NameRequiredDescriptionDefault
directoryNo
operationYes
list_limitNo
snapshot_idNo
max_snapshotsNo
backup_currentNo
max_total_bytesNo
max_snapshot_bytesNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
dataNo
metaYes
errorNo
messageNo
successYes
schema_versionYes

TDQS

A3.5/5.0
Behavior4/5

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

The description adds valuable behavioral context beyond the annotations: snapshots never leave the project, restore uses verified files and a recovery snapshot by default, and no project code is executed. These safety and operational details are not captured in the annotations (which only indicate destructive intent). However, it doesn't fully disclose all mutation behaviors like what cleanup does or whether restore overwrites the current index, so it's good but not exhaustive.

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

Conciseness5/5

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

The description is two sentences long, front-loaded with the core purpose, and includes key behavioral notes without waste. It is appropriately sized for the tool's complexity and avoids redundancy, making it easy to parse quickly.

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 tool's complexity (8 parameters, mutating, destructive) and the absence of parameter descriptions, the description is notably incomplete. It lacks guidance on how to choose operations, what each parameter does, and what happens during restore or cleanup. While an output schema exists (which may cover return values), the description fails to provide enough operational context for safe and correct invocation, especially for a destructive operation.

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 0% description coverage for parameters, and the tool description provides no information about any of the eight parameters (directory, operation, list_limit, snapshot_id, max_snapshots, backup_current, max_total_bytes, max_snapshot_bytes). An agent would have to rely on parameter names and schema constraints alone, which is insufficient for a tool with this many options and defaults. The description completely fails to compensate for the schema's lack of documentation.

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 creates, verifies, restores, lists, and cleans bounded local snapshots of the semantic index. It specifies the exact resource (snapshots of the index) and distinguishes it from sibling tools like index_codebase or search_code by focusing on snapshot lifecycle management. The verb+resource is specific and unambiguous.

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

Usage Guidelines3/5

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

The description implies when to use the tool (for snapshot management tasks) but provides no explicit guidance on when to prefer it over alternatives or any exclusions. It mentions default restore behavior but doesn't say 'use this when you need to backup or restore the index' or contrast with other index-related tools. This leaves usage context implicit.

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

parse_astparse_astA
Read-onlyIdempotent

Parse code and return the Abstract Syntax Tree (AST). Supports multiple languages including JavaScript, TypeScript, Python, Go, Rust, Java, C, C++, and more.

ParametersJSON Schema
NameRequiredDescriptionDefault
contentNoCode content to parse directly (either file_path or content required)
languageNoLanguage name (auto-detected from file path if not provided)
file_pathNoPath to the file to parse (either file_path or content required)
max_depthNoMaximum depth of AST to return (default: 5)
max_nodesNoMaximum AST nodes materialized in the response (default: 10000)
max_text_bytesNoMaximum UTF-8 text retained per AST node (default: 2000)
redact_secretsNoRedact common secrets in AST text fields (default: true)

Output Schema

ParametersJSON Schema
NameRequiredDescription
dataNo
metaYes
errorNo
messageNo
successYes
schema_versionYes

TDQS

A3.6/5.0
Behavior3/5

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

Annotations already establish readOnly, idempotent, and non-destructive behavior, so the description doesn't need to repeat safety traits. It adds language-scope context but discloses no other runtime behavior (e.g., truncation, redaction defaults) – though those are covered in the schema. No contradiction.

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?

A single, front-loaded sentence states the core function before listing supported languages. 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.

Completeness4/5

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

With a rich schema, full parameter descriptions, output schema, and annotations, the description is mostly sufficient for correct invocation. It does not state the file_path-or-content precondition or usage trade-offs, but these are either in the schema or covered by other dimensions.

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

Parameters3/5

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

Schema description coverage is 100%, and each parameter (content, language, file_path, max_depth, max_nodes, max_text_bytes, redact_secrets) has its own description. The tool description adds no parameter-level meaning beyond the schema, so baseline 3 applies.

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 opens with a specific verb and resource: 'Parse code and return the Abstract Syntax Tree (AST)' – a clear, unambiguous purpose. The language list distinguishes it from sibling search/index/analysis tools, even though it doesn't name them. 'And more' is minor imprecision but doesn't undermine clarity.

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 choose parse_ast over siblings like search_code, analyze_file, or query_code. The description only states capability ('Supports multiple languages') and gives no conditions, exclusions, or alternative routing.

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

query_codequery_codeB
Read-onlyIdempotent

Execute Tree-sitter SCM queries on code to find patterns. Use preset queries (functions, classes, imports, exports, comments, strings, variables, types) or custom SCM query patterns.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryNoSCM query pattern (either query or preset required)
presetNoPreset query name: functions, classes, imports, exports, comments, strings, variables, types
contentNoCode content to query directly (either file_path or content required)
languageNoLanguage name (auto-detected from file path if not provided)
file_pathNoPath to the file to query (either file_path or content required)
max_matchesNoMaximum number of matches to return (default: 500)
redact_secretsNoRedact common secrets in query match text (default: true)

Output Schema

ParametersJSON Schema
NameRequiredDescription
dataNo
metaYes
errorNo
messageNo
successYes
schema_versionYes

TDQS

B3.1/5.0
Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds no additional behavioral context beyond what the schema provides (e.g., redact_secrets default). It does not contradict annotations but also does not enrich them.

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 concise sentence that front-loads the core action. However, it is minimal and does not structure the information (e.g., separating preset vs. custom usage), so it is adequate but not exemplary.

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

Completeness3/5

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

The tool has 7 parameters, an output schema, and full schema coverage. The description covers the main use case but lacks guidance on tool selection, error scenarios, or performance considerations. Given the complexity and sibling context, the description is functional but not fully complete.

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

Parameters3/5

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

Schema description coverage is 100%, so parameters are fully documented there. The description mentions presets and custom patterns, which overlaps with the schema's preset enum and query description, but adds no new meaning beyond the schema. Baseline 3 is appropriate.

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 action ('Execute Tree-sitter SCM queries') and the resource ('code to find patterns'), and mentions both preset and custom queries. It is distinct from sibling tools like search_code or parse_ast, though it does not explicitly name alternatives.

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

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 siblings such as search_code, parse_ast, or list_symbols. The description implies use for pattern detection but does not provide selection criteria or exclusions, which is a gap given the large sibling list.

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

refresh_project_catalogRefresh project artifact catalogA
Idempotent

Scan local project documentation and persist a bounded metadata-only artifact catalog with typed references. It never stores document bodies, contacts remote services, or executes project content.

ParametersJSON Schema
NameRequiredDescriptionDefault
scopeNoLocal catalog namespace isolated inside this projectproject
directoryNoProject directory.
max_filesNoMaximum documentation files to inspect

Output Schema

ParametersJSON Schema
NameRequiredDescription
dataNo
metaYes
errorNo
messageNo
successYes
schema_versionYes

TDQS

A4.1/5.0
Behavior4/5

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

Annotations indicate destructiveHint=false, readOnlyHint=false, and idempotentHint=true, but the description adds valuable context by explicitly stating it never stores document bodies, does not contact remote services, and does not execute project content. This goes beyond the annotations and clearly discloses safety boundaries, which is essential for an agent assessing side effects. The description does not contradict annotations.

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?

The description is a single, compact sentence that front-loads the core action and follows with clear negative constraints. Every phrase adds value; there is no wasted wording or redundancy. The structure is easy to parse and understand at a glance.

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

Completeness5/5

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

The tool has a simple three-parameter schema with full coverage)Skip the description does not need to explain return values because an output schema exists. The description covers key behavioral aspects (metadata-only, no side effects) and the annotations cover idempotency and safety. The tool's complexity is low, so the description is sufficiently complete for an agent to call it correctly.

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

Parameters3/5

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

The schema description coverage is 100%, so the schema already documents each parameter. The description does not add extra meaning beyond what the schema provides for 'scope', 'directory', or 'max_files'. It could have added details like how 'scope' interacts with the catalog namespace or the effect of max_files on truncation, but baseline 3 is appropriate because the schema is fully self-sufficient.

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 verb 'Scan' and the resource 'project documentation', and specifies the outcome: persisting a bounded metadata-only artifact catalog. It distinguishes itself from siblings like 'index_codebase' by emphasizing metadata-only and no remote services, making its purpose unambiguous.

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

Usage Guidelines3/5

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

The description implies when to use it (scanning project docs to persist a catalog) but does not explicitly state when not to use it or mention alternatives. With many sibling tools for indexing and searching, explicit guidance on preferring this over 'index_codebase' or 'update_index' would be helpful. The negative constraints (never stores bodies, no remote calls) hint at boundaries but not direct comparison.

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

run_static_analysisRun local static analysisB
Read-onlyIdempotent

Optionally run an installed local ast-grep, Semgrep, or CodeQL analyzer with fixed non-shell arguments, strict path bounds, timeouts, output caps, and redaction. Disabled by default; no project scripts or remote rules are executed.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathsNo
backendYes
patternNo
databaseNo
languageNo
directoryNo
rule_fileNoExisting project-relative ast-grep or Semgrep rule file
query_fileNo
timeout_msNo
max_resultsNo
redact_secretsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
dataNo
metaYes
errorNo
messageNo
successYes
schema_versionYes

TDQS

B3/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds genuinely useful context beyond that: only installed analyzers run, no project scripts or remote rules execute, and outputs are bounded by strict path limits, timeouts, output caps, and redaction. This is not a contradiction of the annotations because running an installed read-only analyzer on code is consistent with readOnlyHint.

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?

Two sentences, but the first is a dense run-on stringing together constraints with commas. The purpose is front-loaded, and the safety caveat is placed second, which is reasonable. However, the 'Optionally' opening and the overloaded first sentence make it harder to parse than it needs to be.

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?

An output schema exists, so return-value explanation is not required, which helps. However, this is a complex 11-parameter tool with three distinct backends and a 9% schema coverage. The description does not explain backend-specific parameter usage (e.g., codeql requires a database, ast-grep uses a pattern), leaving an agent to guess which of the many undocumented parameters to supply for a given backend.

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 only 9% across 11 parameters, so the description must compensate but does not. It vaguely references constraints ('strict path bounds, timeouts, output caps, and redaction') which map to paths, timeout_ms, max_results, and redact_secrets, but it never explains the meaning of backend, pattern, database, language, rule_file, or query_file, nor which parameters apply to which backend.

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 names a specific verb (run), the resource (installed local static analyzers), and enumerates the three supported backends (ast-grep, Semgrep, CodeQL), which distinguishes it from search/query/parse siblings. The leading 'Optionally' is confusing since it implies the tool might not run, and 'fixed non-shell arguments' is jargon-heavy, but the core purpose is clear.

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

Usage Guidelines2/5

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

No guidance on when to choose this over the many sibling analysis tools (query_code, search_code, parse_ast, analyze_file). The description only states a safety caveat ('Disabled by default; no project scripts or remote rules are executed') without explaining when this tool is appropriate versus alternatives or what conditions make it available.

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

search_codesearch_codeA
Read-onlyIdempotent

Search code semantically using natural language queries, hybrid vector/BM25 retrieval, and deterministic identifier reranking. USE THIS to find code by concept/meaning (e.g., 'authentication logic', 'error handling'). Requires index_codebase first. Returns relevant code chunks with file locations, function names, and call relationships (who calls what).

ParametersJSON Schema
NameRequiredDescriptionDefault
modeNoSearch mode: 'vector' (semantic only), 'fts' (keyword only), 'hybrid' (combined with RRF fusion)hybrid
limitNoMaximum number of results to return
queryYesNatural language search query
cursorNoOpaque cursor returned by a previous search page
rerankNoOptional deterministic reranking: lexical or code-aware symbol/signature ranking without another modellexical
languageNoFilter results to one detected language
directoryNoPath to the indexed directory (defaults to current directory).
thresholdNoMaximum distance threshold for results (lower = more similar)
path_prefixNoFilter results to a project-relative path prefix
symbol_typeNoFilter results to a symbol kind such as function or class
vectorWeightNoHybrid RRF weight for semantic vector results (0 = keyword only, 1 = vector only)
include_testsNoWhether test/spec paths are eligible (default: true)
min_confidenceNoOptional local confidence floor; above it the tool may abstain
redact_secretsNoRedact common inline secrets in returned source (default: true)
neighbor_windowNoOptional bounded same-file context window in chunks on each side of a hit (0 disables it)
max_content_bytesNoMaximum UTF-8 bytes returned for each source result (default: 20000)
includeCallContextNoInclude caller/callee information for each result (uses cached call graph)

Output Schema

ParametersJSON Schema
NameRequiredDescription
dataNo
metaYes
errorNo
messageNo
successYes
schema_versionYes

TDQS

A4.2/5.0
Behavior4/5

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

Annotations already mark the tool as read-only, idempotent, and non-destructiveable. The description adds meaningful behavior beyond this: it requires a prior indexing step, returns code chunks with file locations/function names/call relationships, and uses deterministic reranking rather than an LLM. This gives an agent important operational context 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.

Conciseness5/5

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

Three sentences, front-loaded with the core action and an explicit use case. The directive 'USE THIS' is immediately actionable and every sentence adds value: what it does, when to use it, and what it requires. No filler or redundancy.

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 17-parameter tool with an output schema and rich annotations, the description covers the essential operational context: purpose, usage trigger, prerequisite, and return contents. It doesn't guide parameter selection among the many filters, but the schema descriptions already document those behaviors. A small gap remains around expected latency or result formatting, though the output schema mitigates this.

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

Parameters3/5

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

Schema description coverage is 100% with detailed descriptions for all 17 parameters. The description mentions high-level concepts like hybrid vector/BM25, reranking, and call relationships that map to mode, rerank, and includeCallContext, but it doesn't explain parameter syntax or behavior beyond the schema. Baseline 3 is appropriate since the schema carries the parameter semantics.

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 and resource: 'Search code semantically' using natural language queries accruing hybrid vector/BM25 and reranking. It explicitly contrasts with symbol-based tools by targeting 'concept/meaning' and gives concrete examples like 'authentication logic'. This clearly differentiates it from siblings such as find_symbols or query_code.

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

Usage Guidelines4/5

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

The description provides an explicit usage directive: 'USE THIS to find code by concept/meaning' with examples and a clear prerequisite ('Requires index_codebase first'). It does not name sibling alternatives or specify when to use a different tool, so it stops short of full when/when-not guidance.

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

semantic_navigationSemantic navigationA
Read-onlyIdempotent

Navigate local code with an imported SCIP catalog or allow-listed local language server when available, using definitions, references, implementations, hover, type hierarchies, and diagnostics; otherwise fall back explicitly to bounded Tree-sitter analysis with confidence and coverage metadata.

ParametersJSON Schema
NameRequiredDescriptionDefault
lineYes1-based source line
columnYes0-based character column
backendNoUse a local language server, Tree-sitter fallback, or autoauto
directoryNoProject directory.
file_pathYesSource file path relative to directory
max_filesNoMaximum files used by the Tree-sitter fallback
operationYesSemantic navigation operation to perform
timeout_msNoLocal LSP request timeout
max_resultsNoMaximum locations returned
include_sourceNoInclude bounded source snippets
redact_secretsNoRedact common secrets in returned source and hover text
max_source_bytesNoMaximum source bytes per location or hover result

Output Schema

ParametersJSON Schema
NameRequiredDescription
dataNo
metaYes
errorNo
messageNo
successYes
schema_versionYes

TDQS

A3.7/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, and no destructive side effects, so the burden is lower. The description adds meaningful behavioral context: it uses a SCIP catalog or allow-listed LSP when available, otherwise falls back to a bounded Tree-sitter analysis that returns confidence and coverage metadata. This explains behavior beyond what the annotations contain, with no contradiction.

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 packs multiple facts into one well-organized sentence, front-loading the main action ('Navigate local code') and then the backend strategy and operations. It is dense but efficient, though the long enumeration and the possible alternative string could be split for readability.

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?

Given the complexity of 12 parameters, six operations, and multi-backend behavior, the description provides a useful operational overview and explicitly covers fallback behavior and metadata. The output schema exists, so return formats needn't be spelled out. It omits explicit preconditions like importing a SCIP index or enabling an LSP, but this is handled by sibling tools and can be inferred.

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

Parameters3/5

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

Schema description coverage is 100%, so the baseline is 3. The description does add some semantic context about backend selection (auto/lsp/scip/treesitter) and the meaning of bounded Tree-sitter analysis (confidence/coverage metadata), but it does little to clarify individual parameters like line, column, max_results, or max_source_bytes.

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 specific verb ('Navigate'), a resource ('local code'), and enumerates the exact operations (definitions, references, implementations, hover, type hierarchies, diagnostics). It also clarifies the backend model. However, it doesn't explicitly distinguish itself from overlapping siblings such as get_diagnostics or get_symbol_at_position, so it falls just short of a 5.

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

Usage Guidelines3/5

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

The description implies the use case: semantic navigation over local code, with backend selection and fallback behavior ('when available', 'otherwise fall back explicitly'). However, it gives no explicit direction on when to choose this tool over alternative siblings (e.g., search_code, parse_ast, get_symbol_at_position), and no when-not-to-use guidance.

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

set_project_memorySet project memoryA
DestructiveIdempotent

Create, update, or delete one bounded record in the isolated local project memory. Writes are atomic, optimistic-concurrency aware, secret-redacted by default, and never execute project content.

ParametersJSON Schema
NameRequiredDescriptionDefault
idYes
bodyNo
kindNo
tagsNo
linksNo
scopeNo
titleNo
directoryNo
operationYes
confidenceNo
expires_atNo
redact_secretsNo
source_revisionNo
expected_updated_atNo
capture_source_revisionNoCapture the current local Git HEAD when source_revision is omitted

Output Schema

ParametersJSON Schema
NameRequiredDescription
dataNo
metaYes
errorNo
messageNo
successYes
schema_versionYes

TDQS

A3.7/5.0
Behavior4/5

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

Annotations already cover readOnlyHint=false, destructiveHint=true, and idempotentHint=true. The description goes further by revealing atomicity, optimistic-concurrency awareness, default secret-redaction, and a guarantee never to execute project content, which is genuinely useful beyond the structured data.

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?

Two dense sentences with zero wasted words. The core activity is front-loaded, followed by compact behavioral guarantees; every phrase contributes to a call so the description stays scannable.

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?

For a tool exposing 15 parameters and minimal schema description, the description is far too thin. It does not describe record semantics, scopes, operation behaviors in detail, or how the output is shaped. Although an output schema exists, the very large parameter surface is left to the caller to infer from names and types.

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 only 7%, leaving most of the 15 parameters undefined in the description. The description only loosely hints at parameters (create/update/delete maps to operation, optimistic-concurrency maps to expected_updated_at, secret-redaction maps to redact_secrets) and does not explain id, kind, scope, tags, links, confidence, expires_at, or source_revision.

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 uses a specific verb set ('Create, update, or delete') with a clear resource ('one bounded record in the isolated local project memory'). It clearly distinguishes this write tool from read-only siblings like get_project_memory and get_project_catalog through its action words and resource scoping.

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

Usage Guidelines3/5

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

Usage context is implied but not explicit. The description indicates it handles writes to project memory, which positions it as the counterpart to get_project_memory, but it never states when to use this instead of alternatives or mentions that reads belong to sibling tools.

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

update_indexupdate_indexA
Idempotent

Refresh the search index after code changes. USE THIS instead of re-indexing - it's fast because it only processes changed files (SHA-256 hash detection). Use dryRun=true to preview changes first.

ParametersJSON Schema
NameRequiredDescriptionDefault
forceNoForce re-index of all files (ignore hash cache)
dryRunNoOnly report changes without updating the index
directoryNoPath to the indexed directory.
concurrencyNoNumber of files to process in parallel (default: 4)

Output Schema

ParametersJSON Schema
NameRequiredDescription
dataNo
metaYes
errorNo
messageNo
successYes
schema_versionYes

TDQS

A4.5/5.0
Behavior4/5

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

Annotations already indicate idempotentHint=true and destructiveHint=false, but the description adds real behavioral detail: it only processes changed files via SHA-256 hash detection and supports dry-run preview. This explains the tool's side effects and performance characteristics beyond what the annotations state.

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?

Three short sentences, no filler, and the key purpose is front-loaded. The imperative 'USE THIS' is slightly informal but functionalbrain; every sentence earns its place by adding either scope, rationale, or a safety tip.

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

Completeness5/5

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

Given the output schema exists source and annotations cover safety and idempotence, the description provides what an agent needs to call the tool appropriately: purpose, trigger, differentiation from alternatives, and a safe preview option. Nothing critical is missing.

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

Parameters3/5

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

The schema already documents all four parameters with descriptions and defaults, so the baseline is 3. The description adds a small operational note about dryRun=true, but it does not materially extend the schema's parameter documentation. With 100% coverage, this is acceptable.

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 a specific action ('Refresh the search index') with a clear trigger ('after code changes'), plus a defining characteristic that separates it from a full re-index. The phrase 'USE THIS instead of re-indexing' explicitly distinguishes it from the heavier sibling tools, leaving no ambiguity about its role.

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

Usage Guidelines5/5

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

It gives direct usage direction: use this tool instead of a full re-index when code changes, and use dryRun=true to preview before mutating. This is explicit, actionable guidance with a clear condition and an alternative behavior, which is all that is needed for an agent to select it correctly.

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. 35 tool updatesv2.0.0
    • Addedanalyze_file
    • Addedanalyze_impact
    • Addedassemble_task_context
    • Addedfind_dead_code
    • Addedfind_symbols
    • Addedget_call_graph
    • Addedget_changed_symbols
    • Addedget_code_snippet
    • Addedget_dependency_graph
    • Addedget_diagnostics
    • Addedget_git_context
    • Changedget_index_status2 fields changed
      • changedInput schema / $schema
        Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
      • changedOutput schema / (root)
        Previous value: -nullNew value: +{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "properties": {
+    "data": {
+      "additionalProperties": false,
+      "properties": {
+        "corrupt": {
+          "type": "boolean"
+        },
+        "directory": {
+          "type": "string"
+        },
+        "exists": {
+          "type": "boolean"
+        },
+        "hash_cache_present": {
+          "type": "boolean"
+        },
+        "indexPath": {
+          "type": "string"
+        },
+        "index_freshness": {
+          "enum": [
+            "fresh",
+            "stale",
+            "unknown"
+          ],
+          "type": "string"
+        },
+        "languages": {
+          "additionalProperties": {
+            "maximum": 9007199254740991,
+            "minimum": 0,
+            "type": "integer"
+          },
+          "propertyNames": {
+            "type": "string"
+          },
+          "type": "object"
+        },
+        "lastUpdated": {
+          "type": "string"
+        },
+        "metadata": {
+          "additionalProperties": false,
+          "properties": {
+            "chunkOverlap": {
+              "maximum": 9007199254740991,
+              "minimum": 0,
+              "type": "integer"
+            },
+            "chunkSize": {
+              "exclusiveMinimum": 0,
+              "maximum": 9007199254740991,
+              "type": "integer"
+            },
+            "createdAt": {
+              "type": "string"
+            },
+            "embeddingDimensions": {
+              "exclusiveMinimum": 0,
+              "maximum": 9007199254740991,
+              "type": "integer"
+            },
+            "embeddingModel": {
+              "type": "string"
+            },
+            "embeddingProvider": {
+              "enum": [
+                "ollama",
+                "lexical",
+                "unknown"
+              ],
+              "type": "string"
+            },
+            "legacy": {
+              "type": "boolean"
+            },
+            "schemaVersion": {
+              "maximum": 9007199254740991,
+              "minimum": 0,
+              "type": "integer"
+            },
+            "sourceFingerprint": {
+              "type": "string"
+            },
+            "updatedAt": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "schemaVersion",
+            "embeddingProvider",
+            "embeddingModel",
+            "embeddingDimensions",
+            "createdAt",
+            "updatedAt"
+          ],
+          "type": "object"
+        },
+        "metadataError": {
+          "type": "string"
+        },
+        "storage_bytes": {
+          "maximum": 9007199254740991,
+          "minimum": 0,
+          "type": "integer"
+        },
+        "storage_scan_truncated": {
+          "type": "boolean"
+        },
+        "totalChunks": {
+          "maximum": 9007199254740991,
+          "minimum": 0,
+          "type": "integer"
+        },
+        "totalFiles": {
+          "maximum": 9007199254740991,
+          "minimum": 0,
+          "type": "integer"
+        },
+        "write_lock_present": {
+          "type": "boolean"
+        }
+      },
+      "required": [
+        "directory",
+        "indexPath",
+        "exists",
+        "totalChunks",
+        "totalFiles",
+        "languages"
+      ],
+      "type": "object"
+    },
+    "error": {
+      "type": "string"
+    },
+    "message": {
+      "type": "string"
+    },
+    "meta": {
+      "additionalProperties": false,
+      "properties": {
+        "bounded": {
+          "const": true,
+          "type": "boolean"
+        },
+        "confidence": {
+          "maximum": 1,
+          "minimum": 0,
+          "type": "number"
+        },
+        "coverage": {
+          "enum": [
+            "precise",
+            "approximate",
+            "unknown"
+          ],
+          "type": "string"
+        },
+        "generated_at": {
+          "type": "string"
+        },
+        "index_freshness": {
+          "enum": [
+            "fresh",
+            "stale",
+            "unknown"
+          ],
+          "type": "string"
+        },
+        "instruction_signals": {
+          "additionalProperties": false,
+          "properties": {
+            "count": {
+              "maximum": 9007199254740991,
+              "minimum": 0,
+              "type": "integer"
+            },
+            "detected": {
+              "type": "boolean"
+            },
+            "kinds": {
+              "items": {
+                "enum": [
+                  "instruction_override",
+                  "authority_spoofing",
+                  "tool_execution_request",
+                  "secret_exfiltration_request",
+                  "delimiter_spoofing",
+                  "hidden_unicode",
+                  "encoded_instruction"
+                ],
+                "type": "string"
+              },
+              "type": "array"
+            },
+            "scan_truncated": {
+              "type": "boolean"
+            },
+            "scanned_bytes": {
+              "maximum": 9007199254740991,
+              "minimum": 0,
+              "type": "integer"
+            },
+            "signals": {
+              "items": {
+                "additionalProperties": false,
+                "properties": {
+                  "column": {
+                    "maximum": 9007199254740991,
+                    "minimum": 0,
+                    "type": "integer"
+                  },
+                  "confidence": {
+                    "maximum": 1,
+                    "minimum": 0,
+                    "type": "number"
+                  },
+                  "kind": {
+                    "enum": [
+                      "instruction_override",
+                      "authority_spoofing",
+                      "tool_execution_request",
+                      "secret_exfiltration_request",
+                      "delimiter_spoofing",
+                      "hidden_unicode",
+                      "encoded_instruction"
+                    ],
+                    "type": "string"
+                  },
+                  "line": {
+                    "exclusiveMinimum": 0,
+                    "maximum": 9007199254740991,
+                    "type": "integer"
+                  },
+                  "offset": {
+                    "maximum": 9007199254740991,
+                    "minimum": 0,
+                    "type": "integer"
+                  },
+                  "reason": {
+                    "type": "string"
+                  },
+                  "source": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "kind",
+                  "line",
+                  "column",
+                  "offset",
+                  "confidence",
+                  "reason"
+                ],
+                "type": "object"
+              },
+              "type": "array"
+            }
+          },
+          "required": [
+            "detected",
+            "count",
+            "kinds",
+            "signals",
+            "scanned_bytes",
+            "scan_truncated"
+          ],
+          "type": "object"
+        },
+        "local_only": {
+          "const": true,
+          "type": "boolean"
+        },
+        "provenance": {
+          "enum": [
+            "local-analysis",
+            "local-filesystem",
+            "local-index",
+            "local-lsp"
+          ],
+          "type": "string"
+        },
+        "source_is_untrusted": {
+          "type": "boolean"
+        },
+        "source_revision": {
+          "type": "string"
+        },
+        "truncated": {
+          "type": "boolean"
+        }
+      },
+      "required": [
+        "generated_at",
+        "local_only",
+        "bounded",
+        "provenance"
+      ],
+      "type": "object"
+    },
+    "schema_version": {
+      "const": 1,
+      "type": "number"
+    },
+    "success": {
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "schema_version",
+    "success",
+    "meta"
+  ],
+  "type": "object"
+}
    • Addedget_observability
    • Addedget_project_artifacts
    • Addedget_project_catalog
    • Addedget_project_context
    • Addedget_project_memory
    • Addedget_repository_map
    • Changedget_server_info2 fields changed
      • changedInput schema / $schema
        Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
      • changedOutput schema / (root)
        Previous value: -nullNew value: +{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "properties": {
+    "data": {
+      "additionalProperties": false,
+      "properties": {
+        "description": {
+          "type": "string"
+        },
+        "fullName": {
+          "type": "string"
+        },
+        "name": {
+          "type": "string"
+        },
+        "version": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "name",
+        "fullName",
+        "version"
+      ],
+      "type": "object"
+    },
+    "error": {
+      "type": "string"
+    },
+    "message": {
+      "type": "string"
+    },
+    "meta": {
+      "additionalProperties": false,
+      "properties": {
+        "bounded": {
+          "const": true,
+          "type": "boolean"
+        },
+        "confidence": {
+          "maximum": 1,
+          "minimum": 0,
+          "type": "number"
+        },
+        "coverage": {
+          "enum": [
+            "precise",
+            "approximate",
+            "unknown"
+          ],
+          "type": "string"
+        },
+        "generated_at": {
+          "type": "string"
+        },
+        "index_freshness": {
+          "enum": [
+            "fresh",
+            "stale",
+            "unknown"
+          ],
+          "type": "string"
+        },
+        "instruction_signals": {
+          "additionalProperties": false,
+          "properties": {
+            "count": {
+              "maximum": 9007199254740991,
+              "minimum": 0,
+              "type": "integer"
+            },
+            "detected": {
+              "type": "boolean"
+            },
+            "kinds": {
+              "items": {
+                "enum": [
+                  "instruction_override",
+                  "authority_spoofing",
+                  "tool_execution_request",
+                  "secret_exfiltration_request",
+                  "delimiter_spoofing",
+                  "hidden_unicode",
+                  "encoded_instruction"
+                ],
+                "type": "string"
+              },
+              "type": "array"
+            },
+            "scan_truncated": {
+              "type": "boolean"
+            },
+            "scanned_bytes": {
+              "maximum": 9007199254740991,
+              "minimum": 0,
+              "type": "integer"
+            },
+            "signals": {
+              "items": {
+                "additionalProperties": false,
+                "properties": {
+                  "column": {
+                    "maximum": 9007199254740991,
+                    "minimum": 0,
+                    "type": "integer"
+                  },
+                  "confidence": {
+                    "maximum": 1,
+                    "minimum": 0,
+                    "type": "number"
+                  },
+                  "kind": {
+                    "enum": [
+                      "instruction_override",
+                      "authority_spoofing",
+                      "tool_execution_request",
+                      "secret_exfiltration_request",
+                      "delimiter_spoofing",
+                      "hidden_unicode",
+                      "encoded_instruction"
+                    ],
+                    "type": "string"
+                  },
+                  "line": {
+                    "exclusiveMinimum": 0,
+                    "maximum": 9007199254740991,
+                    "type": "integer"
+                  },
+                  "offset": {
+                    "maximum": 9007199254740991,
+                    "minimum": 0,
+                    "type": "integer"
+                  },
+                  "reason": {
+                    "type": "string"
+                  },
+                  "source": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "kind",
+                  "line",
+                  "column",
+                  "offset",
+                  "confidence",
+                  "reason"
+                ],
+                "type": "object"
+              },
+              "type": "array"
+            }
+          },
+          "required": [
+            "detected",
+            "count",
+            "kinds",
+            "signals",
+            "scanned_bytes",
+            "scan_truncated"
+          ],
+          "type": "object"
+        },
+        "local_only": {
+          "const": true,
+          "type": "boolean"
+        },
+        "provenance": {
+          "enum": [
+            "local-analysis",
+            "local-filesystem",
+            "local-index",
+            "local-lsp"
+          ],
+          "type": "string"
+        },
+        "source_is_untrusted": {
+          "type": "boolean"
+        },
+        "source_revision": {
+          "type": "string"
+        },
+        "truncated": {
+          "type": "boolean"
+        }
+      },
+      "required": [
+        "generated_at",
+        "local_only",
+        "bounded",
+        "provenance"
+      ],
+      "type": "object"
+    },
+    "schema_version": {
+      "const": 1,
+      "type": "number"
+    },
+    "success": {
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "schema_version",
+    "success",
+    "meta"
+  ],
+  "type": "object"
+}
    • Addedget_symbol_at_position
    • Addedget_symbol_graph
    • Addedimport_scip_index
    • Changedindex_codebase3 fields changed
      • changedInput schema / $schema
        Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
      • changedInput schema / properties / concurrency / maximum
        Previous value: -9007199254740991New value: +32
      • changedOutput schema / (root)
        Previous value: -nullNew value: +{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "properties": {
+    "data": {
+      "additionalProperties": false,
+      "properties": {
+        "chunksCreated": {
+          "maximum": 9007199254740991,
+          "minimum": 0,
+          "type": "integer"
+        },
+        "directory": {
+          "type": "string"
+        },
+        "errors": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "filesIndexed": {
+          "maximum": 9007199254740991,
+          "minimum": 0,
+          "type": "integer"
+        },
+        "languages": {
+          "additionalProperties": {
+            "maximum": 9007199254740991,
+            "minimum": 0,
+            "type": "integer"
+          },
+          "propertyNames": {
+            "type": "string"
+          },
+          "type": "object"
+        }
+      },
+      "required": [
+        "directory",
+        "filesIndexed",
+        "chunksCreated",
+        "languages",
+        "errors"
+      ],
+      "type": "object"
+    },
+    "error": {
+      "type": "string"
+    },
+    "message": {
+      "type": "string"
+    },
+    "meta": {
+      "additionalProperties": false,
+      "properties": {
+        "bounded": {
+          "const": true,
+          "type": "boolean"
+        },
+        "confidence": {
+          "maximum": 1,
+          "minimum": 0,
+          "type": "number"
+        },
+        "coverage": {
+          "enum": [
+            "precise",
+            "approximate",
+            "unknown"
+          ],
+          "type": "string"
+        },
+        "generated_at": {
+          "type": "string"
+        },
+        "index_freshness": {
+          "enum": [
+            "fresh",
+            "stale",
+            "unknown"
+          ],
+          "type": "string"
+        },
+        "instruction_signals": {
+          "additionalProperties": false,
+          "properties": {
+            "count": {
+              "maximum": 9007199254740991,
+              "minimum": 0,
+              "type": "integer"
+            },
+            "detected": {
+              "type": "boolean"
+            },
+            "kinds": {
+              "items": {
+                "enum": [
+                  "instruction_override",
+                  "authority_spoofing",
+                  "tool_execution_request",
+                  "secret_exfiltration_request",
+                  "delimiter_spoofing",
+                  "hidden_unicode",
+                  "encoded_instruction"
+                ],
+                "type": "string"
+              },
+              "type": "array"
+            },
+            "scan_truncated": {
+              "type": "boolean"
+            },
+            "scanned_bytes": {
+              "maximum": 9007199254740991,
+              "minimum": 0,
+              "type": "integer"
+            },
+            "signals": {
+              "items": {
+                "additionalProperties": false,
+                "properties": {
+                  "column": {
+                    "maximum": 9007199254740991,
+                    "minimum": 0,
+                    "type": "integer"
+                  },
+                  "confidence": {
+                    "maximum": 1,
+                    "minimum": 0,
+                    "type": "number"
+                  },
+                  "kind": {
+                    "enum": [
+                      "instruction_override",
+                      "authority_spoofing",
+                      "tool_execution_request",
+                      "secret_exfiltration_request",
+                      "delimiter_spoofing",
+                      "hidden_unicode",
+                      "encoded_instruction"
+                    ],
+                    "type": "string"
+                  },
+                  "line": {
+                    "exclusiveMinimum": 0,
+                    "maximum": 9007199254740991,
+                    "type": "integer"
+                  },
+                  "offset": {
+                    "maximum": 9007199254740991,
+                    "minimum": 0,
+                    "type": "integer"
+                  },
+                  "reason": {
+                    "type": "string"
+                  },
+                  "source": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "kind",
+                  "line",
+                  "column",
+                  "offset",
+                  "confidence",
+                  "reason"
+                ],
+                "type": "object"
+              },
+              "type": "array"
+            }
+          },
+          "required": [
+            "detected",
+            "count",
+            "kinds",
+            "signals",
+            "scanned_bytes",
+            "scan_truncated"
+          ],
+          "type": "object"
+        },
+        "local_only": {
+          "const": true,
+          "type": "boolean"
+        },
+        "provenance": {
+          "enum": [
+            "local-analysis",
+            "local-filesystem",
+            "local-index",
+            "local-lsp"
+          ],
+          "type": "string"
+        },
+        "source_is_untrusted": {
+          "type": "boolean"
+        },
+        "source_revision": {
+          "type": "string"
+        },
+        "truncated": {
+          "type": "boolean"
+        }
+      },
+      "required": [
+        "generated_at",
+        "local_only",
+        "bounded",
+        "provenance"
+      ],
+      "type": "object"
+    },
+    "schema_version": {
+      "const": 1,
+      "type": "number"
+    },
+    "success": {
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "schema_version",
+    "success",
+    "meta"
+  ],
+  "type": "object"
+}
    • Addedlist_projects
    • Addedlist_symbols
    • Addedmaintain_index
    • Addedmanage_index_snapshots
    • Addedparse_ast
    • Addedquery_code
    • Addedrefresh_project_catalog
    • Addedrun_static_analysis
    • Changedsearch_code14 fields changed
      • changedInput schema / $schema
        Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
      • addedInput schema / properties / cursor
        Added value: +{
+  "description": "Opaque cursor returned by a previous search page",
+  "maxLength": 1024,
+  "type": "string"
+}
      • addedInput schema / properties / include_tests
        Added value: +{
+  "default": true,
+  "description": "Whether test/spec paths are eligible (default: true)",
+  "type": "boolean"
+}
      • addedInput schema / properties / language
        Added value: +{
+  "description": "Filter results to one detected language",
+  "minLength": 1,
+  "type": "string"
+}
      • changedInput schema / properties / limit / maximum
        Previous value: -9007199254740991New value: +100
      • addedInput schema / properties / max_content_bytes
        Added value: +{
+  "default": 20000,
+  "description": "Maximum UTF-8 bytes returned for each source result (default: 20000)",
+  "exclusiveMinimum": 0,
+  "maximum": 100000,
+  "type": "integer"
+}
      • addedInput schema / properties / min_confidence
        Added value: +{
+  "default": 0,
+  "description": "Optional local confidence floor; above it the tool may abstain",
+  "maximum": 1,
+  "minimum": 0,
+  "type": "number"
+}
      • addedInput schema / properties / neighbor_window
        Added value: +{
+  "default": 0,
+  "description": "Optional bounded same-file context window in chunks on each side of a hit (0 disables it)",
+  "maximum": 3,
+  "minimum": 0,
+  "type": "integer"
+}
      • addedInput schema / properties / path_prefix
        Added value: +{
+  "description": "Filter results to a project-relative path prefix",
+  "minLength": 1,
+  "type": "string"
+}
      • addedInput schema / properties / redact_secrets
        Added value: +{
+  "default": true,
+  "description": "Redact common inline secrets in returned source (default: true)",
+  "type": "boolean"
+}
      • addedInput schema / properties / rerank
        Added value: +{
+  "default": "lexical",
+  "description": "Optional deterministic reranking: lexical or code-aware symbol/signature ranking without another model",
+  "enum": [
+    "none",
+    "lexical",
+    "code"
+  ],
+  "type": "string"
+}
      • addedInput schema / properties / symbol_type
        Added value: +{
+  "description": "Filter results to a symbol kind such as function or class",
+  "minLength": 1,
+  "type": "string"
+}
      • addedInput schema / properties / vectorWeight
        Added value: +{
+  "default": 0.5,
+  "description": "Hybrid RRF weight for semantic vector results (0 = keyword only, 1 = vector only)",
+  "maximum": 1,
+  "minimum": 0,
+  "type": "number"
+}
      • changedOutput schema / (root)
        Previous value: -nullNew value: +{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "properties": {
+    "data": {
+      "additionalProperties": false,
+      "properties": {
+        "cursor_offset": {
+          "maximum": 9007199254740991,
+          "minimum": 0,
+          "type": "integer"
+        },
+        "directory": {
+          "type": "string"
+        },
+        "filters": {
+          "additionalProperties": false,
+          "properties": {
+            "include_tests": {
+              "type": "boolean"
+            },
+            "language": {
+              "type": "string"
+            },
+            "path_prefix": {
+              "type": "string"
+            },
+            "symbol_type": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "include_tests"
+          ],
+          "type": "object"
+        },
+        "index": {
+          "additionalProperties": false,
+          "properties": {
+            "embedding_dimensions": {
+              "maximum": 9007199254740991,
+              "minimum": -9007199254740991,
+              "type": "integer"
+            },
+            "embedding_model": {
+              "type": "string"
+            },
+            "embedding_provider": {
+              "type": "string"
+            },
+            "schema_version": {
+              "maximum": 9007199254740991,
+              "minimum": -9007199254740991,
+              "type": "integer"
+            },
+            "source_fingerprint": {
+              "type": "string"
+            },
+            "updated_at": {
+              "type": "string"
+            }
+          },
+          "type": "object"
+        },
+        "instruction_signals": {
+          "additionalProperties": false,
+          "properties": {
+            "count": {
+              "maximum": 9007199254740991,
+              "minimum": 0,
+              "type": "integer"
+            },
+            "detected": {
+              "type": "boolean"
+            },
+            "kinds": {
+              "items": {
+                "enum": [
+                  "instruction_override",
+                  "authority_spoofing",
+                  "tool_execution_request",
+                  "secret_exfiltration_request",
+                  "delimiter_spoofing",
+                  "hidden_unicode",
+                  "encoded_instruction"
+                ],
+                "type": "string"
+              },
+              "type": "array"
+            },
+            "scan_truncated": {
+              "type": "boolean"
+            },
+            "scanned_bytes": {
+              "maximum": 9007199254740991,
+              "minimum": 0,
+              "type": "integer"
+            },
+            "signals": {
+              "items": {
+                "additionalProperties": false,
+                "properties": {
+                  "column": {
+                    "maximum": 9007199254740991,
+                    "minimum": 0,
+                    "type": "integer"
+                  },
+                  "confidence": {
+                    "maximum": 1,
+                    "minimum": 0,
+                    "type": "number"
+                  },
+                  "kind": {
+                    "enum": [
+                      "instruction_override",
+                      "authority_spoofing",
+                      "tool_execution_request",
+                      "secret_exfiltration_request",
+                      "delimiter_spoofing",
+                      "hidden_unicode",
+                      "encoded_instruction"
+                    ],
+                    "type": "string"
+                  },
+                  "line": {
+                    "exclusiveMinimum": 0,
+                    "maximum": 9007199254740991,
+                    "type": "integer"
+                  },
+                  "offset": {
+                    "maximum": 9007199254740991,
+                    "minimum": 0,
+                    "type": "integer"
+                  },
+                  "reason": {
+                    "type": "string"
+                  },
+                  "source": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "kind",
+                  "line",
+                  "column",
+                  "offset",
+                  "confidence",
+                  "reason"
+                ],
+                "type": "object"
+              },
+              "type": "array"
+            }
+          },
+          "required": [
+            "detected",
+            "count",
+            "kinds",
+            "signals",
+            "scanned_bytes",
+            "scan_truncated"
+          ],
+          "type": "object"
+        },
+        "next_cursor": {
+          "type": "string"
+        },
+        "query": {
+          "type": "string"
+        },
+        "results": {
+          "items": {
+            "additionalProperties": false,
+            "properties": {
+              "callContext": {
+                "additionalProperties": false,
+                "properties": {
+                  "callees": {
+                    "items": {
+                      "type": "string"
+                    },
+                    "type": "array"
+                  },
+                  "callers": {
+                    "items": {
+                      "type": "string"
+                    },
+                    "type": "array"
+                  }
+                },
+                "required": [
+                  "callers",
+                  "callees"
+                ],
+                "type": "object"
+              },
+              "confidence": {
+                "maximum": 1,
+                "minimum": 0,
+                "type": "number"
+              },
+              "content": {
+                "type": "string"
+              },
+              "content_truncated": {
+                "type": "boolean"
+              },
+              "endLine": {
+                "exclusiveMinimum": 0,
+                "maximum": 9007199254740991,
+                "type": "integer"
+              },
+              "filePath": {
+                "type": "string"
+              },
+              "is_neighbor": {
+                "type": "boolean"
+              },
+              "language": {
+                "type": "string"
+              },
+              "neighbor_distance": {
+                "exclusiveMinimum": 0,
+                "maximum": 9007199254740991,
+                "type": "integer"
+              },
+              "neighbor_of": {
+                "type": "string"
+              },
+              "parts": {
+                "additionalProperties": false,
+                "properties": {
+                  "body": {
+                    "type": "string"
+                  },
+                  "documentation": {
+                    "type": "string"
+                  },
+                  "signature": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "body"
+                ],
+                "type": "object"
+              },
+              "score": {
+                "type": "number"
+              },
+              "startLine": {
+                "exclusiveMinimum": 0,
+                "maximum": 9007199254740991,
+                "type": "integer"
+              },
+              "symbolName": {
+                "type": "string"
+              },
+              "symbolType": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "filePath",
+              "language",
+              "startLine",
+              "endLine",
+              "content",
+              "score",
+              "confidence",
+              "parts"
+            ],
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "resultsCount": {
+          "maximum": 9007199254740991,
+          "minimum": 0,
+          "type": "integer"
+        },
+        "retrieval": {
+          "additionalProperties": false,
+          "properties": {
+            "abstained": {
+              "type": "boolean"
+            },
+            "abstention_reason": {
+              "type": "string"
+            },
+            "candidates_considered": {
+              "maximum": 9007199254740991,
+              "minimum": 0,
+              "type": "integer"
+            },
+            "content_limit_bytes": {
+              "exclusiveMinimum": 0,
+              "maximum": 9007199254740991,
+              "type": "integer"
+            },
+            "content_truncated_count": {
+              "maximum": 9007199254740991,
+              "minimum": 0,
+              "type": "integer"
+            },
+            "duplicates_removed": {
+              "maximum": 9007199254740991,
+              "minimum": 0,
+              "type": "integer"
+            },
+            "min_confidence": {
+              "maximum": 1,
+              "minimum": 0,
+              "type": "number"
+            },
+            "neighbor_candidates_considered": {
+              "maximum": 9007199254740991,
+              "minimum": 0,
+              "type": "integer"
+            },
+            "neighbor_window": {
+              "maximum": 3,
+              "minimum": 0,
+              "type": "integer"
+            },
+            "neighbors_added": {
+              "maximum": 9007199254740991,
+              "minimum": 0,
+              "type": "integer"
+            },
+            "neighbors_truncated": {
+              "type": "boolean"
+            },
+            "query_kind": {
+              "enum": [
+                "identifier",
+                "concept",
+                "mixed"
+              ],
+              "type": "string"
+            },
+            "reranker": {
+              "enum": [
+                "none",
+                "lexical",
+                "code"
+              ],
+              "type": "string"
+            }
+          },
+          "required": [
+            "query_kind",
+            "reranker",
+            "candidates_considered",
+            "duplicates_removed",
+            "min_confidence",
+            "abstained",
+            "content_limit_bytes",
+            "content_truncated_count",
+            "neighbor_window",
+            "neighbors_added",
+            "neighbor_candidates_considered",
+            "neighbors_truncated"
+          ],
+          "type": "object"
+        },
+        "secrets_redacted": {
+          "type": "boolean"
+        },
+        "source_is_untrusted": {
+          "const": true,
+          "type": "boolean"
+        },
+        "truncated": {
+          "type": "boolean"
+        }
+      },
+      "required": [
+        "query",
+        "directory",
+        "resultsCount",
+        "truncated",
+        "cursor_offset",
+        "retrieval",
+        "filters",
+        "index",
+        "source_is_untrusted",
+        "secrets_redacted",
+        "instruction_signals",
+        "results"
+      ],
+      "type": "object"
+    },
+    "error": {
+      "type": "string"
+    },
+    "message": {
+      "type": "string"
+    },
+    "meta": {
+      "additionalProperties": false,
+      "properties": {
+        "bounded": {
+          "const": true,
+          "type": "boolean"
+        },
+        "confidence": {
+          "maximum": 1,
+          "minimum": 0,
+          "type": "number"
+        },
+        "coverage": {
+          "enum": [
+            "precise",
+            "approximate",
+            "unknown"
+          ],
+          "type": "string"
+        },
+        "generated_at": {
+          "type": "string"
+        },
+        "index_freshness": {
+          "enum": [
+            "fresh",
+            "stale",
+            "unknown"
+          ],
+          "type": "string"
+        },
+        "instruction_signals": {
+          "additionalProperties": false,
+          "properties": {
+            "count": {
+              "maximum": 9007199254740991,
+              "minimum": 0,
+              "type": "integer"
+            },
+            "detected": {
+              "type": "boolean"
+            },
+            "kinds": {
+              "items": {
+                "enum": [
+                  "instruction_override",
+                  "authority_spoofing",
+                  "tool_execution_request",
+                  "secret_exfiltration_request",
+                  "delimiter_spoofing",
+                  "hidden_unicode",
+                  "encoded_instruction"
+                ],
+                "type": "string"
+              },
+              "type": "array"
+            },
+            "scan_truncated": {
+              "type": "boolean"
+            },
+            "scanned_bytes": {
+              "maximum": 9007199254740991,
+              "minimum": 0,
+              "type": "integer"
+            },
+            "signals": {
+              "items": {
+                "additionalProperties": false,
+                "properties": {
+                  "column": {
+                    "maximum": 9007199254740991,
+                    "minimum": 0,
+                    "type": "integer"
+                  },
+                  "confidence": {
+                    "maximum": 1,
+                    "minimum": 0,
+                    "type": "number"
+                  },
+                  "kind": {
+                    "enum": [
+                      "instruction_override",
+                      "authority_spoofing",
+                      "tool_execution_request",
+                      "secret_exfiltration_request",
+                      "delimiter_spoofing",
+                      "hidden_unicode",
+                      "encoded_instruction"
+                    ],
+                    "type": "string"
+                  },
+                  "line": {
+                    "exclusiveMinimum": 0,
+                    "maximum": 9007199254740991,
+                    "type": "integer"
+                  },
+                  "offset": {
+                    "maximum": 9007199254740991,
+                    "minimum": 0,
+                    "type": "integer"
+                  },
+                  "reason": {
+                    "type": "string"
+                  },
+                  "source": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "kind",
+                  "line",
+                  "column",
+                  "offset",
+                  "confidence",
+                  "reason"
+                ],
+                "type": "object"
+              },
+              "type": "array"
+            }
+          },
+          "required": [
+            "detected",
+            "count",
+            "kinds",
+            "signals",
+            "scanned_bytes",
+            "scan_truncated"
+          ],
+          "type": "object"
+        },
+        "local_only": {
+          "const": true,
+          "type": "boolean"
+        },
+        "provenance": {
+          "enum": [
+            "local-analysis",
+            "local-filesystem",
+            "local-index",
+            "local-lsp"
+          ],
+          "type": "string"
+        },
+        "source_is_untrusted": {
+          "type": "boolean"
+        },
+        "source_revision": {
+          "type": "string"
+        },
+        "truncated": {
+          "type": "boolean"
+        }
+      },
+      "required": [
+        "generated_at",
+        "local_only",
+        "bounded",
+        "provenance"
+      ],
+      "type": "object"
+    },
+    "schema_version": {
+      "const": 1,
+      "type": "number"
+    },
+    "success": {
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "schema_version",
+    "success",
+    "meta"
+  ],
+  "type": "object"
+}
    • Addedsemantic_navigation
    • Addedset_project_memory
    • Changedupdate_index3 fields changed
      • changedInput schema / $schema
        Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
      • addedInput schema / properties / concurrency
        Added value: +{
+  "default": 4,
+  "description": "Number of files to process in parallel (default: 4)",
+  "exclusiveMinimum": 0,
+  "maximum": 32,
+  "type": "integer"
+}
      • changedOutput schema / (root)
        Previous value: -nullNew value: +{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "properties": {
+    "data": {
+      "additionalProperties": false,
+      "properties": {
+        "added": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "directory": {
+          "type": "string"
+        },
+        "dryRun": {
+          "type": "boolean"
+        },
+        "errors": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "modified": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "removed": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "unchanged": {
+          "maximum": 9007199254740991,
+          "minimum": 0,
+          "type": "integer"
+        }
+      },
+      "required": [
+        "directory",
+        "dryRun",
+        "added",
+        "modified",
+        "removed",
+        "unchanged",
+        "errors"
+      ],
+      "type": "object"
+    },
+    "error": {
+      "type": "string"
+    },
+    "message": {
+      "type": "string"
+    },
+    "meta": {
+      "additionalProperties": false,
+      "properties": {
+        "bounded": {
+          "const": true,
+          "type": "boolean"
+        },
+        "confidence": {
+          "maximum": 1,
+          "minimum": 0,
+          "type": "number"
+        },
+        "coverage": {
+          "enum": [
+            "precise",
+            "approximate",
+            "unknown"
+          ],
+          "type": "string"
+        },
+        "generated_at": {
+          "type": "string"
+        },
+        "index_freshness": {
+          "enum": [
+            "fresh",
+            "stale",
+            "unknown"
+          ],
+          "type": "string"
+        },
+        "instruction_signals": {
+          "additionalProperties": false,
+          "properties": {
+            "count": {
+              "maximum": 9007199254740991,
+              "minimum": 0,
+              "type": "integer"
+            },
+            "detected": {
+              "type": "boolean"
+            },
+            "kinds": {
+              "items": {
+                "enum": [
+                  "instruction_override",
+                  "authority_spoofing",
+                  "tool_execution_request",
+                  "secret_exfiltration_request",
+                  "delimiter_spoofing",
+                  "hidden_unicode",
+                  "encoded_instruction"
+                ],
+                "type": "string"
+              },
+              "type": "array"
+            },
+            "scan_truncated": {
+              "type": "boolean"
+            },
+            "scanned_bytes": {
+              "maximum": 9007199254740991,
+              "minimum": 0,
+              "type": "integer"
+            },
+            "signals": {
+              "items": {
+                "additionalProperties": false,
+                "properties": {
+                  "column": {
+                    "maximum": 9007199254740991,
+                    "minimum": 0,
+                    "type": "integer"
+                  },
+                  "confidence": {
+                    "maximum": 1,
+                    "minimum": 0,
+                    "type": "number"
+                  },
+                  "kind": {
+                    "enum": [
+                      "instruction_override",
+                      "authority_spoofing",
+                      "tool_execution_request",
+                      "secret_exfiltration_request",
+                      "delimiter_spoofing",
+                      "hidden_unicode",
+                      "encoded_instruction"
+                    ],
+                    "type": "string"
+                  },
+                  "line": {
+                    "exclusiveMinimum": 0,
+                    "maximum": 9007199254740991,
+                    "type": "integer"
+                  },
+                  "offset": {
+                    "maximum": 9007199254740991,
+                    "minimum": 0,
+                    "type": "integer"
+                  },
+                  "reason": {
+                    "type": "string"
+                  },
+                  "source": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "kind",
+                  "line",
+                  "column",
+                  "offset",
+                  "confidence",
+                  "reason"
+                ],
+                "type": "object"
+              },
+              "type": "array"
+            }
+          },
+          "required": [
+            "detected",
+            "count",
+            "kinds",
+            "signals",
+            "scanned_bytes",
+            "scan_truncated"
+          ],
+          "type": "object"
+        },
+        "local_only": {
+          "const": true,
+          "type": "boolean"
+        },
+        "provenance": {
+          "enum": [
+            "local-analysis",
+            "local-filesystem",
+            "local-index",
+            "local-lsp"
+          ],
+          "type": "string"
+        },
+        "source_is_untrusted": {
+          "type": "boolean"
+        },
+        "source_revision": {
+          "type": "string"
+        },
+        "truncated": {
+          "type": "boolean"
+        }
+      },
+      "required": [
+        "generated_at",
+        "local_only",
+        "bounded",
+        "provenance"
+      ],
+      "type": "object"
+    },
+    "schema_version": {
+      "const": 1,
+      "type": "number"
+    },
+    "success": {
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "schema_version",
+    "success",
+    "meta"
+  ],
+  "type": "object"
+}
  2. 5 tool updatesv1.0.3
    • First observedget_index_status
    • First observedget_server_info
    • First observedindex_codebase
    • First observedsearch_code
    • First observedupdate_index
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

A3.5/5.0

Scored across 35 tools

Disambiguation4/5

Most tools have distinct purposes (search, AST, memory, git, index management). However, some overlap exists: get_symbol_graph vs get_call_graph vs get_dependency_graph, and find_symbols vs list_symbols vs get_symbol_at_position could confuse an agent on which to choose for code navigation. The descriptions help but boundaries are not perfectly crisp.

Naming Consistency4/5

The naming mostly follows a get_/index_/update_/manage_ verb pattern with clear nouns (e.g., get_git_context, refresh_project_catalog, manage_index_snapshots). Minor deviations like 'semantic_navigation' and 'parse_ast' break the strict verb_noun pattern, but the majority are consistent and readable.

Tool Count2/5

35 tools is heavy for a code search/navigation server. While each tool has a specific niche, the set feels overly granular: many tools serve overlapping code-analysis purposes (e.g., get_call_graph, get_symbol_graph, get_dependency_graph, analyze_impact). This count exceeds the typical well-scoped range and increases selection complexity.

Completeness4/5

The server covers the full lifecycle: indexing, searching, navigation, graph analysis, memory, artifacts, git, snapshots, and static analysis. Minor gaps exist: no tool for code editing/writing (but perhaps out of scope) and no explicit tool for clearing/resetting the entire index, but core workflows are well-covered.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Axon.MCP.Server

    ali-kamali
    F
    license
    Not graded
    quality
    D
    maintenance
    An MCP server that transforms codebases into intelligent, queryable knowledge bases, enabling AI assistants to perform semantic search, explore architecture, and analyze code relationships.
    166
    -

  • reposynapse

    Jul879n
    A
    license
    A
    quality
    D
    maintenance
    Universal MCP server that analyzes any codebase and provides structured context to AI assistants. Dynamic, accurate, and token-efficient.
    18
    18 npm
    MIT

  • codeweave

    MdAbdullahAlMahmud
    A
    license
    Not graded
    quality
    D
    maintenance
    A self-hosted MCP server that indexes your codebase and provides AI assistants with deep context including file tree, full-text search, git history, dependencies, and stack detection, all without sending your code to third parties.
    8 npm
    1
    MIT