# Sprint 10a Research: Agent Efficiency & Quality Assurance

## Codebase Research Findings

### A) Feedback Loop: What Does Agent Get Back?

**build_scene response:**
```python
{"created": int, "errors": [...], "total_requested": int, "parent": str, "truncated": bool}
```
**Problem**: Bare summary. Agent knows *how many* nodes succeeded but NOT what they are, where they ended up, or whether Godot actually instantiated them correctly. No confirmation that scene references resolved or hierarchies are correct.

**node_ops response:**
```python
{"results": [{"status": "ok"|"error", "op": str, "node": str, ...}], "scene_modified": bool, "undo_available": bool, "validation": [...]}
```
**Problem**: Individual `add_child` operations return minimal info (just status). No confirmation of where nodes were placed, no post-operation state snapshot.

**Missing feedback across all bridge tools:**
- No post-operation node tree snapshot
- No collision/overlap detection after placement
- No scene reload confirmation
- No editor state (which scene is open, game running, errors)

### B) Godot Error Capture: Does Agent See Red Console Errors?

**YES but LIMITED.** The debugger.gd captures `godotiq:error` messages from the running game via `EngineDebugger.send_message()`. These are push events.

**Limitations:**
1. Only game-side errors (from running game that explicitly sends them)
2. No editor-side error capture (when node_ops/build_scene cause Godot internal errors)
3. No parsing of Godot console output stream
4. Script compilation errors ARE caught in exec_editor, but general runtime issues are not
5. No "show me the last N editor console lines" tool

### C) Editor Awareness: Must Agent Poll?

**Every bridge tool response is isolated.** No auto-inclusion of editor context. After `build_scene()` succeeds, response is ONLY `{"created": 5, ...}` — no open scene, no game state, no errors.

Agent must explicitly call `godotiq_editor_context()` to know which scene is open, if game is running, project path, etc. This forces extra round trips on every workflow step.

### D) Time Bottlenecks

1. **Missing ambient editor state (HIGH)**: Extra round trips for editor_context
2. **Screenshot ops (HIGH)**: 30-second timeout, 3 retries, 50K+ chars base64
3. **Repeated file parsing (MEDIUM)**: scene_map reads .tscn from disk, scene_tree reads live state — similar data, separate calls
4. **Build scene truncation (MEDIUM)**: Max 256 nodes, large grids need multiple calls
5. **Scene tree traversal (MEDIUM)**: Full tree walk on large scenes

### E) Creation Workflow Clarity

The prompt has a well-structured 6-phase creation workflow with code examples and "ask user" checkpoints.

**Weaknesses:**
1. "ASK USER to verify" is vague — what should user look for?
2. No error recovery guidance
3. Grid override coordinate system not explained
4. Placement tool usage has no code example

### F) Quality Control / Auto-QA

**What exists:**
- `spatial_validator.py`: Pre-operation validation (wall proximity, overlap, outliers)
- Build scene: Max 256 node cap with truncation
- Script compilation error catch in exec

**What's missing:**
- No post-build validation (tile connectivity, scene refs, hierarchy)
- No post-op state verification (confirm transform matches request)
- No scene integrity check (orphan signals, broken refs)
- No grid path connectivity validation

---

## Web Research Findings

### MCP Tool Response Design Patterns (2025)

**Key insights from MCP spec 2025-06-18:**
- Tools should return both `content` (human-readable) and `structuredContent` (machine-parseable)
- Content supports `annotations.audience` — separate agent-facing data from user-facing summaries
- Tool errors should use `isError: true` with actionable messages, not protocol-level errors
- Tool descriptions are critical: 89.8% of MCP tools suffer from "Unstated Limitations"

**Recommendations for GodotIQ:**
- Include ambient project state in every response to eliminate follow-up calls
- Return actionable error messages ("No scene open. Call godotiq_exec to open one.")
- Define outputSchema for strict validation

### Agent Efficiency in Tool-Use Workflows (2025)

**Key patterns:**
- **Ambient context**: Embed relevant state in every response — eliminates "get state" calls
- **Batch operations**: Accept arrays of items, not just single items
- **Pre-flight validation**: Tools should auto-validate preconditions (MCP spec requires it)
- **Sensible defaults**: Reduce decision overhead for agents
- **Token budgeting**: Stay within 25K token response limits

**Context-Aware MCP (CA-MCP)** offloads execution logic to specialized servers with shared context, reducing execution time by 67-74%.

### GDScript Editor Plugin Error Capture

**Two approaches by Godot version:**

1. **EditorDebuggerPlugin (Godot 4.0+)**: Captures messages from running game via debugger protocol. Use `_has_capture("error")` to intercept error messages. Data includes file, line, function, message, warning flag, callstack.

2. **Logger class (Godot 4.5+)**: Intercepts ALL engine log messages. Override `_log_error()` and `_log_message()`. Most comprehensive solution.

**For GodotIQ (targeting Godot 4.0-4.4):**
- Use EditorDebuggerPlugin with `_has_capture("error")` for runtime errors
- Store recent errors in a ring buffer on the server
- Return last N errors in tool responses via `_editor_state.recent_errors`

**Error data format from engine:**
- source_file, source_func, source_line, error, error_descr, warning, callstack

---

## Testing Setup

**Existing test infrastructure:**
- pytest with pytest-asyncio (asyncio_mode = "auto")
- Fixtures in tests/fixtures/
- Tests organized by tool category in tests/test_tools/
- Bridge tests in tests/test_bridge/
- No live Godot integration tests (all mocked)

**For this sprint:**
- New tests for grid connectivity validation (unit tests, no Godot needed)
- Test that _editor_state structure is correct
- Test pre-flight check error messages
- All tests should be pure Python with mocked bridge responses
