# Token Savings

> Less context burned, more context for reasoning.

AI coding agents operate within fixed context windows. Every token spent on loading instructions, reading documentation, or fetching task details is a token not available for reasoning and writing code. Orbitmap is designed from the ground up to minimize token overhead - so your agents spend their context budget on what matters.

---

## How Much Does Orbitmap MCP Cost?

Orbitmap connects to your agent via MCP (Model Context Protocol). Here's the actual token cost per conversation:

| What loads | Tokens | When |
|------------|--------|------|
| Server instructions + tool names | ~2,500 | Every conversation start |
| Each tool schema (on first use) | ~300–500 | Only when the agent calls that tool |
| Typical session (5–8 tools used) | ~4,500–6,000 | After active work |

That's **less than 3% of a 200K context window** even during intensive use.

### Deferred Tool Loading

Orbitmap doesn't dump all 26 tool definitions into your agent's context at once. Instead, it registers only tool **names** on startup (~225 tokens). Full schemas are loaded on-demand when the agent actually needs a specific tool.

This means:

- **Start of conversation**: ~2,500 tokens (instructions + names only)
- **After using 3 tools**: ~3,500 tokens (instructions + 3 schemas)
- **After context compression**: back to ~2,500 tokens (schemas are evicted, re-fetched if needed)

The agent never pays for tools it doesn't use.

### Lite Profile for Sub-Agents

For lightweight agent setups, Orbitmap offers a **Lite profile** with only 13 essential tools. The startup cost drops to just **~820 tokens** - three times lighter than the full profile.

| Profile | Tools | Startup cost | % of 200K context |
|---------|-------|-------------|-----------------|
| **Full** | 26 | ~2,500 tok | 1.25% |
| **Lite** | 13 | ~820 tok | 0.41% |
| **Manager** | 22 | ~1,070 tok | 0.54% |

## Task Context: Read Only What You Need

Without a project management tool, an agent picking up previous work has to re-explore the codebase - reading files, grepping for patterns, trying to reconstruct what happened. That costs thousands of tokens every time.

With Orbitmap, a single `get_tasks()` call returns the task's work logs, decisions, and status. The agent gets exactly the context it needs to resume work:

```terminal
~/my-project

> Resume work on the auth middleware.

Agent: Loading task context...
> get_tasks(task_id='TS-r2d2x1')

Work logs (4 entries):
1. [code_change] Created SupabaseAuth
   middleware with JWT validation
2. [decision] Used firebase/php-jwt
   instead of Sanctum
3. [decision] Chose Redis session driver
4. [note] All auth tests pass

Got it. Resuming from where I left off -
the middleware uses firebase/php-jwt for
JWT validation with Redis sessions.
```

Instead of spending **5,000+ tokens** re-exploring the codebase, the agent spends **~800 tokens** loading structured task context. That's an **80%+ reduction** - and the context is more accurate because it includes decisions and reasoning, not just code.

## Document Access: Three-Tier Reading

Traditional approach: agent reads the entire document to find what it needs. A typical project spec is 5,000–10,000 tokens. Multiply by several documents per session, and you've burned half your context window on documentation alone.

Orbitmap uses a **three-tier reading flow** that minimizes token consumption at every step:

### Tier 1: Context Field (~50 tokens)

Every document has a short **context** description visible in document listings. The agent reads this to decide if the document is even relevant - without opening it.

```terminal
~/my-project

> How does our auth middleware validate
  tokens?

Agent: Let me find the right document...
> get_project_docs()

8 documents found. Checking context fields:
- "Architecture Guide": Covers auth,
  middleware, DB schema...
- "API Reference": REST endpoints and
  response formats...

"Architecture Guide" is the one I need.
```

### Tier 2: Table of Contents (~200 tokens)

Once the right document is identified, the agent fetches only the **table of contents** - not the full content. From the TOC, it pinpoints the exact section.

```terminal
> get_document('arch-guide')

TOC: 14 sections
  ## Project Overview
  ## Authentication Flow    <-- this one
  ## Database Schema
  ## API Design
  ...
```

### Tier 3: Single Section (~500 tokens)

The agent fetches **just the section it needs**. The full 5,000-token document is never loaded.

```terminal
> get_document('arch-guide',
    section='## Authentication Flow')

480 tokens loaded (not 5,200).

The SupabaseAuth middleware validates JWT
tokens using firebase/php-jwt...
```

### The Math

| Approach | Tokens consumed |
|----------|----------------|
| Read entire document | ~5,000 |
| Orbitmap three-tier flow | ~750 |
| **Savings** | **~85%** |

This scales with project size. Whether your project has 3 documents or 30, the per-lookup cost stays roughly the same - because the agent only ever reads the section it needs.

## Section-Based Editing

The same efficiency applies to **editing documents**. Agents can patch a single section without downloading or re-uploading the entire document:

```terminal
> edit_document('arch-guide',
    mode='patch',
    operations=[{
      op: 'replace_section',
      heading: '## Authentication Flow',
      content: '..updated content..'
    }])
```

No need to load 5,000 tokens just to change one paragraph.

## Context Window Efficiency in Practice

Here's a typical session comparison:

| Action | Without Orbitmap | With Orbitmap |
|--------|-----------------|---------------|
| Resume previous task | ~5,000 tok (re-explore code) | ~800 tok (read task logs) |
| Find info in docs | ~5,000 tok (read full doc) | ~750 tok (context + TOC + section) |
| Check project status | ~3,000 tok (read files, git log) | ~400 tok (get_tasks) |
| MCP overhead | 0 | ~2,500 tok (one-time startup) |
| **Total per session** | **~13,000+ tok** | **~4,450 tok** |

The MCP startup cost pays for itself after a single task lookup or document read. Over a full working session with multiple lookups, the savings compound significantly.

### Why This Matters

- **More room for reasoning** - agents preserve their context window for code analysis, not for re-reading documentation
- **Faster responses** - less data to process means quicker agent output
- **Longer productive sessions** - with less context wasted, agents can work longer before hitting context limits
- **Scales with project size** - token cost per lookup stays constant regardless of how many documents or tasks your project has