tzero-mcp

Build Persistent AST Context Snapshot Cache

build_ast_snapshot

Idempotent

Precomputes and caches AST symbols, module dependency graphs, and token metrics into a persistent local index so multi-turn sessions retrieve codebase context quickly without recalculating full ASTs.

Instructions

Pre-computes and caches high-speed AST symbols, module dependency graphs, and token metrics into a persistent '.tzero/snapshot.json' index, distinguishing from 'build_project_context' and 'search_codebase' by enabling sub-8ms instant context retrieval across multi-turn sessions rather than recalculating full AST representations on every invocation.

Parameters:

workspace_dir (str, optional, default='.'): Target repository root directory containing source code to index.
force_refresh (bool, optional, default=False): When True, invalidates existing snapshot and rebuilds fresh AST cache from disk.

Behavior:

Mutability: Writes cached index to '.tzero/snapshot.json'; does not modify repository source code files.
Idempotency: Deterministic index generation for identical repository state.
Performance & Latency: Sub-8ms cache retrieval on hit; <600ms initial scan across 100+ files.
Resources: Consumes <45MB RAM; thread-safe local file operations.
Privacy: 100% offline local processing; zero external network transmission.
Auth & Limits: Zero external credentials or API keys required; zero rate limits.
Error Handling: Skips unparseable or binary files gracefully and continues indexing.

Usage Guidelines:

When to use: Use when caching or fast-loading complete codebase AST symbols and token metrics in <8ms across multi-turn sessions or large workspaces (10,000+ files).
When NOT to use: Do not use for real-time live symbol editing or single file pruning (use 'prune_code_snippet' instead); do not use for ad-hoc semantic keyword searching (use 'search_codebase' instead).

Returns: Formatted Markdown report detailing snapshot status, file count, load time, and token economics (-95%).

Input Schema

Name	Required	Description	Default
`force_refresh`	No	Whether to force rebuild the cache even if valid (default: False).
`workspace_dir`	No	Target repository root directory (default: current directory).	.

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Addedv10.6.0Nov 6, 2026

TDQS

A4.5/5.0

Behavior5/5

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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, but the description goes well past that: it names the write target ('.tzero/snapshot.json'), clarifies source files are not modified, states determinism, gives latency and memory envelopes, confirms offline/no-credential operation, and specifies graceful skipping of binary/unparseable files. Auth, limits, side effects and error behavior are all covered.

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?

Purpose is front-loaded and the sectioned layout is scannable, but the text is padded with promotional claims ('high-speed', 'sub-8ms' repeated in both the preamble and usage section, '-95% token economics'). Several behavioral bullets restate annotation-provided traits such as idempotency, so not every line 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 a two-parameter caching tool, the description leaves nothing an agent needs unanswered: scope, side effects, performance cost, resource footprint, failure modes and invocation conditions are all present. Because an output schema exists, the dedicated Returns line is supplementary rather than load-bearing.

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 both parameters and their defaults are already documented. The description largely restates them, adding only marginal meaning for 'force_refresh' (that the existing snapshot is invalidated and rebuilt from disk) beyond the schema's 'even if valid' phrasing.

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 opening sentence names a specific verb ('Pre-computes and caches') and three concrete resources (AST symbols, module dependency graphs, token metrics), plus the artifact it produces ('.tzero/snapshot.json'). It then explicitly distinguishes itself from 'build_project_context' and 'search_codebase' by citing the retrieval-latency benefit, so an agent can select 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?

The description has dedicated 'When to use' and 'When NOT to use' sections that name the exact alternatives to pick instead ('prune_code_snippet' for single-file pruning, 'search_codebase' for semantic keyword search). Exclusion conditions are stated rather than inferred, which is the strongest form of routing guidance.

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