tzero-mcp

search_codebase_semantic

Find functions, classes, or logic snippets by concept using local BM25 + TF-IDF semantic search over AST tokens, headers, and docstrings without external embedding APIs.

Instructions

100% Private, local hybrid BM25 + TF-IDF semantic code search across workspace AST tokens, function headers, and docstrings without sending code to third-party embedding APIs.

Behavior:

Read-only: In-memory inverted index query; does not modify files.
Idempotent: Deterministic search ranking for identical query and code states.
100% Offline & Private: Never sends code or embeddings to external APIs; $0 cost and zero data leakage.

Usage Guidelines:

When to use: Find functions, classes, or logic snippets using conceptual natural language queries (e.g. 'authentication jwt token verify', 'rate limit algorithm').
Sibling Routing: For exact string or regex matches, use IDE grep or ripgrep. For finding unused code, use 'find_dead_code'.

Returns: Ranked Markdown list of matching code snippets with file locations, match scores, and surrounding context.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`query`	Yes	Natural language or technical keyword query describing the desired code logic.
`top_k`	No	Maximum number of top-matching code snippets to return (default: 5).
`project_root`	No	Workspace root directory to index and search (default: current directory).	.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv0.1.1Oct 16, 2026

addedInput schema / properties / project_root / description

Added value: +"Workspace root directory to index and search (default: current directory)."

addedInput schema / properties / query / description

Added value: +"Natural language or technical keyword query describing the desired code logic."

addedInput schema / properties / top_k / description

Added value: +"Maximum number of top-matching code snippets to return (default: 5)."

First observedv0.1.0Oct 15, 2026

TDQS

A4.3/5.0

Behavior4/5

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

With no annotations, the description carries the full burden and does well: it discloses read-only (in-memory query, no file modification), idempotent/deterministic ranking, and privacy ($0 cost, no external embedding APIs). It does not address latency or indexing cost on large workspaces, a minor gap for a search tool.

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?

Well-structured with front-loaded purpose and clear Behavior/Usage/Returns sections with bullets. It is slightly verbose (the Returns section overlaps the output schema), but every section is scannable and earns most of 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?

Given no annotations but an existing output schema, the description covers behavior, usage, and safety/privacy adequately. The Returns description is partly redundant with the output schema, and no latency/scale caveat is given, but an agent has enough 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?

Schema coverage is 100%, so all three parameters are already documented in the schema. The description adds value only by clarifying the query is natural-language/conceptual with examples; top_k and project_root receive no added meaning beyond the schema. 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 states a specific verb (search) and resource (codebase) with precise scope: hybrid BM25 + TF-IDF semantic search across AST tokens, function headers, and docstrings. It clearly distinguishes itself from siblings by naming grep/ripgrep and find_dead_code as different tools.

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 explicitly states when to use the tool ('conceptual natural language queries') with concrete examples, and provides explicit sibling routing: exact/regex matches go to grep/ripgrep, unused-code detection goes to find_dead_code. Nothing is left to inference.

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