# Usage Guide — Sprint 8a: Token Optimization

## Quick Start

All GodotIQ MCP tools now accept a `detail` parameter controlling output verbosity:

```python
# Brief — minimal output for quick checks (~2,000 char limit)
result = await godotiq_scene_map(scene="res://main.tscn", detail="brief")

# Normal — standard output (default, ~8,000 char limit)
result = await godotiq_scene_map(scene="res://main.tscn")

# Full — everything, no limits
result = await godotiq_scene_map(scene="res://main.tscn", detail="full")
```

## Detail Levels

| Level | Max Chars | Use When |
|-------|-----------|----------|
| `brief` | 2,000 | Quick status checks, scanning many tools |
| `normal` | 8,000 | Default — most operations |
| `full` | Unlimited | Deep investigation, debugging |

## What Changed

### New in output_limit.py
- `truncate_output(text, detail)` — Truncate raw text strings
- `apply_output_limit()` now validates unknown detail values (normalizes to "normal")

### Tools Updated (Sections 02-05)
- **suggest_scale** — `detail` param added, output limited
- **impact_check** — Renamed `detail` data field to `change_description`, added `detail` verbosity param
- **placement** — `detail` param added
- **12 bridge tools** — `detail` param added to screenshot, run, editor_context, node_ops, script_ops, file_ops, input, exec, undo_history, save_scene, camera + ping
- **6 high-output bridge tools** — file_ops, node_ops, editor_context, input, watch, undo_history now call `apply_output_limit()` after sub-module response

### Special: file_ops read
Large file content from `op="read"` is string-truncated before list truncation:
```python
# Returns truncated content with metadata:
{"content": "first 1800 chars...", "content_truncated": true, "content_original_chars": 50000}
```

## Example: Token-Efficient Workflow

```python
# 1. Get project overview (brief)
summary = await godotiq_project_summary(detail="brief")

# 2. Check scene layout (normal)
scene = await godotiq_scene_map(scene="res://main.tscn", detail="normal")

# 3. Quick asset check (brief)
assets = await godotiq_asset_registry(detail="brief")

# Combined output: ~5,000 chars instead of ~30,000+
```

## Running Tests

```bash
# Full suite (944 tests)
uv run pytest -v

# Token optimization tests only
uv run pytest tests/test_tools/test_truncate_output.py tests/test_tools/test_detail_levels.py tests/test_tools/test_token_budget.py -v
```
