tzero-mcp

search_codebase

Read-onlyIdempotent

Locate functions, classes, and docstrings across a local repository using hybrid keyword and semantic search, returning ranked code snippets with file paths and line ranges.

Instructions

Executes private local hybrid search combining BM25 keyword matching and TF-IDF semantic scoring across repository functions, classes, and docstrings, distinguishing from 'query_memory_store' and 'build_project_context' by indexing source code identifiers and docstrings rather than querying agent episodic memory or generating context trees.

Parameters:

query (str, required): Search term or natural language description of the code to locate.
project_root (str, optional, default='.'): Root directory of the repository to search (default: current directory).
top_k (int, optional, default=5): Maximum number of ranked results to return (default: 5).

Behavior:

Read-only: Queries local code files without writing to disk or modifying indices.
Idempotent: Deterministic ranked results for identical queries on the same codebase.
100% Offline: Executes entirely on CPU; no OpenAI/cloud embeddings, zero network egress.
Auth & Rate Limits: Zero authentication or credentials required; sub-millisecond query latency.
Error Handling: Returns empty match report with query suggestions if no relevant tokens are found.

Usage Guidelines:

When to use: Locate relevant functions, classes, or code implementations across the repository using natural language or code identifier queries.
When NOT to use: Do not use for querying persistent semantic knowledge graphs or agent memory triples (use 'query_memory_store' instead); do not use for generating full project context trees (use 'build_project_context' instead).

Returns: Ranked list of matching code snippets with file paths, line ranges, relevance scores, and matched symbol definitions.

Input Schema

Name	Required	Description	Default
`query`	Yes	Search term or natural language description of the code to locate.
`top_k`	No	Maximum number of ranked results to return (default: 5).
`project_root`	No	Root directory of the repository to search (default: current directory).	.

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Addedv7.3.2Oct 24, 2026
Removedv7.0.1Oct 24, 2026
Addedv7.0.0Oct 23, 2026

TDQS

A4.4/5.0

Behavior4/5

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

Annotations already declare readOnly, idempotent, and non-destructive, so the description's restatement of those traits adds little. However, it goes beyond annotations with genuinely new context: fully offline/CPU-only execution, zero network egress, zero auth, sub-millisecond latency, and an explicit error-handling path returning an empty report with suggestions.

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 front-loaded with the core purpose first, then structured sections for parameters, behavior, usage, and returns. Slightly verbose where it repeats annotation-backed traits (read-only, idempotent) and the return shape already covered by the output schema.

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 search tool with an output schema and full annotation coverage, the definition is complete: purpose, retrieval mechanism, alternatives, failure mode, and performance profile are all present. An agent has everything needed to select and 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 description coverage is 100% and the description's parameter list restates the schema text near-verbatim, adding no syntax, format, or behavioral nuance beyond what the schema already provides. Baseline 3 is appropriate when the schema does 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?

States a specific verb (hybrid search combining BM25 + TF-IDF) and resource (repository functions, classes, docstrings), and immediately distinguishes itself from 'query_memory_store' and 'build_project_context' by what it indexes. An agent can identify it without opening the schema.

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 'When to use' and 'When NOT to use' sections, naming the exact alternatives (query_memory_store, build_project_context) and the conditions that select them. 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.

Deploy Server