Give AI Agents the Map First

•3 min read
aicontext-managementclaudemcp

Give AI Agents the Map First

AI agents navigate codebases and file systems best when they can see the full structure before diving into details. Give them the complete map upfront, let them reason about what they need, and they're more likely to select the right tools based on those descriptions.

TL;DR

Run tree or similar commands to provide directory structure upfront. The LLM identifies exactly what it needs without reading massive files that bury the signal in noise. This pattern—progressive disclosure—reduces context consumption while improving precision. Works for filesystems, MCP servers, Obsidian vaults, database schemas, and any structured information.

Map, Reason, Request

LLMs excel at navigating structured data when you give them the overview first:

bash
# Without map: read the whole file
cat src/utils.py
# Returns: 10,000 lines of mixed utilities
 
# With map: see structure first
tree src/
# Shows:
# src/
# ├── utils/
# │   ├── strings.py
# │   ├── dates.py
# │   └── validators.py
 
# Then request exactly what you need
cat src/utils/strings.py
# Returns: 50 focused lines

The pattern: Map (run tree to get full structure), Reason (LLM sees what exists), Request (targeted tool calls for specific files).

Obsidian Vaults

Generate a tree structure with frontmatter and tags. Claude sees all notes, locations, and metadata. Claude makes precise requests: "show me all notes tagged #productivity in the /projects folder."

The agent navigates intelligently because it has the complete map.

MCP Servers as Code

Present MCP servers as code APIs rather than tool calls. The agent discovers tools by exploring the filesystem, then writes code:

python
from mcp.figma import (
    get_designs,
    update_layer
)
 
designs = get_designs(
    project_id="abc"
)
 
for design in designs.filter(
    status="review"
):
    update_layer(
        design.id,
        layer="background",
        color="#fff"
    )

This enables agents to use context efficiently by loading tools on demand, filtering data before it reaches the model, and executing complex logic in a single step.

Implementation

Provide filesystem structure:

bash
tree -L 3 -F --dirsfirst

For knowledge bases with metadata:

bash
find vault/ -name "*.md" \
  -exec head -20 {} \; \
  | grep -E "(^#|^tags:|^date:)"

For MCP servers, document APIs as importable modules. Let the agent explore via filesystem, then write code.

Why This Scales

Maps are compact—a tree with 1000 files might be 50KB of text. Reading those 1000 files might be 50MB. Given the map, agents typically need 5-10 files, not all 1000.

The context window becomes a workspace for reasoning and targeted retrieval.

References