Skip to main content
Glama

Build Hierarchical AST Codebase Context Tree

build_project_context
Read-onlyIdempotent

Generates read-only repository architecture, symbol maps, or focus-file skeletons with AST pruning to cut context tokens by up to 95% at session start or during refactors.

Instructions

Returns repository-wide context or a selected context view without persisting an index; distinguishing from 'build_ast_snapshot' which writes a cache and 'generate_architectural_passport' which analyzes one Python file.

Parameters:

  • project_root: File system directory path; accepts relative or absolute paths, resolving symlinks and automatically skipping .git, node_modules, venv, and binary artifacts.

  • context_type: Structural format selector: 'tree' emits full 4-tier AST architecture; 'repo_map' builds compact PageRank-ranked symbol table; 'skeleton' outputs target file implementation with 1st-degree callers/callees; 'zero_waste_prompt' formats prompt-ready AST prefix; 'incremental_diff' isolates git diff context.

  • focus_file: Relative or absolute file path to anchor 1st-degree dependency skeletons when context_type is 'skeleton' or 'incremental_diff'; ignored when context_type is 'tree'.

  • reduction_mode: AST pruning depth: 'ultra' preserves type signatures, classes, methods, and docstrings while removing function bodies (80-95% compression); 'balanced' retains control-flow branch headers; 'none' includes raw source code without pruning.

  • max_tokens: Soft token ceiling (1,000 to 128,000); tree generation prioritizes core architectural layers and truncates leaf utility modules first if budget binds.

  • include_file_contents: Set True to append AST-pruned source bodies; set False for pure directory and class hierarchy outlines with lowest token footprint.

Behavior:

  • Mutability: Strictly read-only; reads filesystem AST without modifying files, caches, or disk state.

  • Idempotency: Deterministic; identical workspace revisions yield bit-for-bit identical context payloads.

  • Privacy & Network: 100% offline local processing; zero cloud API calls, telemetry, or external network egress.

  • Performance & Resources: Executes in <500ms for 500 files consuming <50MB RAM; thread-safe with zero rate limits.

  • Auth: Zero authentication, API keys, or cloud credentials required.

  • Return Structure: Emits complete Markdown document with '# Repository Architecture', '# Module Dependencies', and token telemetry; no pagination required.

  • Error Handling: Returns non-crashing warning document with troubleshooting steps if path is empty or contains no supported language source files.

Usage Guidelines:

  • When to use: Ingest codebase architecture, symbol tables, focus file skeletons, or zero-waste prompt context at the start of an agent session or major refactor to save 80-95% context tokens.

  • When NOT to use: Do not use for stripping implementation bodies from an in-memory code string or diff patch (use 'prune_code_snippet' instead); do not use for targeted keyword or semantic identifier lookup across code (use 'search_codebase' instead).

Returns: Structured Markdown document featuring '# Repository Architecture (T-1)', '# Module Dependencies (T-2)', '# AST Signatures (T-3)', '# Architectural Rules (T-4)', and quantitative token savings metrics.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "build_project_context"
  }
}

Input Schema

NameRequiredDescriptionDefault
focus_fileNoOptional path to a focus file when context_type is 'skeleton' or 'incremental_diff'.
max_tokensNoUpper token budget threshold for returned context.
context_typeNoContext generation mode: 'tree' for hierarchical multi-tier AST tree, 'repo_map' for compact symbol index, 'skeleton' for focus-file implementation with 1st-degree caller/callee skeletons, 'zero_waste_prompt' for agent prompt prefix with pruned AST, 'incremental_diff' for git diff context.tree
project_rootNoTarget repository root path to scan (default: current working directory)..
reduction_modeNoAST reduction level: 'ultra' for signatures & docstrings (80-95% reduction), 'balanced' for signatures + control headers, 'none' for verbatim source.ultra
include_file_contentsNoWhen True, includes AST-reduced file bodies; when False, emits directory hierarchy only.

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv7.3.2
  2. Removedv7.0.1
  3. Addedv7.0.0

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, yet the description still adds non-redundant behavior: no disk or cache persistence, deterministic bit-for-bit output per revision, offline-only processing with no telemetry, and a defined failure mode (non-crashing warning document when the path is empty or has no supported sources). Performance, auth, and thread-safety characteristics are all disclosed, which is well beyond the annotation bar.

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?

Front-loads the one-line differentiator, then groups detail under labeled Parameters, Behavior, and Usage Guidelines blocks, so an agent can jump to the needed section. It loses a point for redundancy: the return payload (the T-1 through T-4 Markdown sections) is described twice, once under 'Return Structure' and again under 'Returns'.

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 six-parameter, read-only analysis tool with full annotation coverage and an output schema, everything an agent needs before calling is present: mode selection, budget behavior, path edge cases, error behavior, and prerequisites (none). Nothing material is deferred to inference.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3; the description earns above that by adding real semantics the schema lacks — path symlink resolution plus automatic skipping of .git/node_modules/venv/binaries, the fact that focus_file is ignored when context_type is 'tree', and the truncation policy where leaf utility modules are dropped first when the token budget binds. It stops short of 5 because the per-mode 'context_type' and 'reduction_mode' text largely restates the enum descriptions already present in 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?

Opens with a specific verb+resource and scope ('Returns repository-wide context or a selected context view without persisting an index'), then immediately contrasts itself with 'build_ast_snapshot' (writes a cache) and 'generate_architectural_passport' (single Python file). An agent can distinguish it from the near-miss siblings without opening any 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?

Has explicit 'When to use' (session start, major refactor, token savings) and 'When NOT to use' clauses that name the correct alternatives for each exclusion case ('prune_code_snippet' for in-memory strings/diffs, 'search_codebase' for keyword/symbol lookup). Both the positive and negative routing conditions are stated, not inferred.

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