Token-Efficient Workflows

Input tokens are 85-95% of AI coding bills. NestWeaver’s graph-based retrieval is designed to minimize token spend — but how you query matters. This guide covers the strategies that make the biggest difference.

The core principle

NestWeaver gives your agent precomputed answers instead of raw files. But even within NestWeaver, there’s a spectrum from “broad and expensive” to “narrow and cheap.”

Rule of thumb: Filter early, use concise format for scanning, and switch to detailed only for the results you need to read deeply.

1. 1 Name the seed A symbol, file, or project. Not the whole tree.
2. 2 Filter Repo, path, or kind, before the ranking.
3. 3 Scan concise Signatures and neighbors only.
4. 4 Open one Detailed, or the source span, for what you will change.

In a subagent or a script, run the same steps with the CLI. The answer is the same, without the MCP tool schemas.

MCP vs CLI: choose by context

NestWeaver offers two query interfaces. They return the same data, but their token costs differ significantly.

Interface	When to use	Token overhead
MCP tools	Main conversation loop, interactive work	~18K tokens for tool schemas (loaded once per session)
CLI via Bash	Subagents, batch scripts, hooks	Zero schema overhead — precomputed answers only

Use CLI in subagents for ~40-60% fewer tokens per query. The CLI returns the same data without loading tool schemas into context. Always pass --json for machine-readable output.

# In a subagent or script — CLI is cheaper
nestweaver context "UserService" --token-budget 2000 --json

# In the main conversation loop — MCP is natural
# (tool schemas are already loaded)

Filter for precision

Every context query accepts filters that narrow results before ranking. Unfiltered queries return broader but less focused results — more tokens for less signal.

Filter	Effect	Example
repos	Limit to specific repositories	repos: ["my-backend"]
tags	Filter by tag	tags: ["project/auth"]
path_prefix	Limit to a directory	path_prefix: "src/services/"
kinds	Symbol, Note, or Section only	kinds: ["Symbol"]
exclude_tags	Remove unwanted categories	exclude_tags: ["archived"]

Use response_format wisely

Every context and search tool supports response_format:

• "concise" — Titles, kinds, and UIDs only. Use for scanning many results. ~60% fewer tokens than detailed.
• "detailed" — Adds text excerpts, scores, and full metadata. Use when you need to read the content.

Pattern: Query with concise first to find the right nodes, then use read_symbols or note_get on the specific items you need.

Control the token budget

brain_context defaults token_budget to 2000. Pass a symbol name. A phrase such as “payment processing” is a question for nestweaver investigate.

nestweaver context processPayment --token-budget 1000
nestweaver context processPayment --token-budget 2000
nestweaver investigate "payment processing"

Choose the right tool

Need	Tool	Why
Structural context around a topic	brain_context	PPR-ranked, token-budget-aware
Keyword search	brain_search	BM25, fast lookup
Read a specific symbol’s source	read_symbols	Cheapest — returns only the span you need
Project-wide overview	project_context	Pre-scoped to a project’s subgraph
Check before changing code	blast_radius	Shows downstream dependents

Summary

1. Use CLI in subagents — 40-60% fewer tokens vs MCP
2. Filter with repos/tags/path_prefix — narrow before ranking
3. Use concise format for scanning — switch to detailed only when needed
4. Set explicit token budgets — don’t accept the default if you need less
5. Use read_symbols for specific lookups — cheapest way to read source