# Section 2: Add `detail` to Assets Tools

**Status: IMPLEMENTED**

## Deviations from Plan
- None. Implementation matches plan exactly.

## Overview

This section adds the `detail` parameter to the `suggest_scale` tool in `src/godotiq/tools/assets/__init__.py`. This is a small, focused change. The `suggest_scale` tool currently produces bounded, small output (single scale recommendation dicts), so the `detail` parameter is primarily for API consistency with the rest of the tool suite. However, for `brief` mode, the output is trimmed to return only the essential recommendation fields.

The `asset_registry` tool in the same file already has full `detail` support and does not need changes in this section.

**Depends on:** Section 1 (output_limit.py enhancements — specifically the input validation for unknown `detail` values in `apply_output_limit()`).

## File to Modify

`/Users/salvatorefarruggio/Desktop/godotiq/src/godotiq/tools/assets/__init__.py`

## Tests (Write First)

All tests go in `/Users/salvatorefarruggio/Desktop/godotiq/tests/test_tools/test_detail_levels.py`. This file is shared across sections 2-6 — each section adds its own test class(es). This section adds the `suggest_scale` tests.

The file needs the standard imports and the `session` fixture from `tests/test_tools/conftest.py` (which creates a `GodotIQSession` loaded from `tests/fixtures/sample_project`).

### Test stubs for suggest_scale detail

```python
import inspect
import json

from godotiq.session import GodotIQSession
from godotiq.tools.assets import _build_suggest_scale


class TestSuggestScaleDetail:
    """Tests for suggest_scale detail parameter support."""

    def test_suggest_scale_accepts_detail_parameter(self) -> None:
        """suggest_scale function signature includes detail parameter."""
        sig = inspect.signature(_build_suggest_scale)
        assert "detail" in sig.parameters

    def test_suggest_scale_default_returns_dict(self, session: GodotIQSession) -> None:
        """suggest_scale with no detail kwarg returns a dict result."""
        # Call with intended_use (reference mode) since no model needed
        result = _build_suggest_scale(session, scene="res://main.tscn", intended_use="printer")
        assert isinstance(result, dict)

    def test_suggest_scale_brief_output_under_3000_chars(self, session: GodotIQSession) -> None:
        """suggest_scale(detail='brief') output < 3000 chars."""
        result = _build_suggest_scale(
            session, scene="res://main.tscn", intended_use="printer", detail="brief"
        )
        serialized = json.dumps(result, default=str)
        assert len(serialized) < 3000

    def test_suggest_scale_normal_output_under_10000_chars(self, session: GodotIQSession) -> None:
        """suggest_scale(detail='normal') output < 10000 chars."""
        result = _build_suggest_scale(
            session, scene="res://main.tscn", intended_use="printer", detail="normal"
        )
        serialized = json.dumps(result, default=str)
        assert len(serialized) < 10000
```

**Key points about these tests:**

- They import `_build_suggest_scale` directly (the internal function), not the MCP-decorated async wrapper, to avoid needing MCP context.
- They use the `session` fixture from `tests/test_tools/conftest.py`.
- The scene path and intended_use values reference objects in the `tests/fixtures/sample_project` fixture (which contains a `main.tscn` and printer models).
- The 3000/10000 char thresholds include buffer for metadata overhead from `apply_output_limit()` (the raw limits are 2000/8000, but serialization + truncation metadata can add a few hundred characters).

## Implementation Details

### Changes to `_build_suggest_scale()`

Add `detail: str = "normal"` parameter to the function signature.

**Updated signature:**

```python
def _build_suggest_scale(
    session: GodotIQSession,
    scene: str,
    model: str | None = None,
    near_node: str | None = None,
    intended_use: str = "",
    detail: str = "normal",
) -> dict:
```

**Filtering behavior by detail level:**

For `brief` mode, return only the essential recommendation. Before the final `return result` (both in the model mode path and the reference mode path via `_reference_mode()`), apply filtering:

- **`brief`**: Strip the result dict to only include: `recommended_scale`, `match_tier` (or `matches_found` in reference mode), `scene`, and `mode`. Remove verbose fields like `reference_models`, `references`, `scale_range`, `reasoning`, `note`, `suggestion`, `position_suggestion`. Then call `apply_output_limit(result, detail)`.
- **`normal`** and **`full`**: Return the current full result unchanged. Still call `apply_output_limit(result, detail)` for safety, but output will be well within limits since suggest_scale results are inherently small.

The implementation approach is:

1. Build the result dict exactly as today (no changes to existing logic).
2. Before returning, if `detail == "brief"`, create a slimmed-down version keeping only the essential keys.
3. Call `apply_output_limit(result, detail, list_keys=["reference_models"])` (or `["references"]` for reference mode) on the result before returning.

The `_reference_mode()` function (called when `model is None`) also needs the detail parameter threaded through. The simpler approach is to apply filtering in `_build_suggest_scale()` after the result is constructed, regardless of which code path produced it. This avoids modifying `_reference_mode()`.

### Changes to `godotiq_suggest_scale()` (MCP wrapper)

Add `detail: str = "normal"` to the async MCP wrapper function signature and pass it through to `_build_suggest_scale()`.

**Updated signature:**

```python
async def godotiq_suggest_scale(
    scene: str,
    model: str | None = None,
    near_node: str | None = None,
    intended_use: str = "",
    detail: str = "normal",
    ctx: Context = None,
) -> dict:
```

**Updated docstring** — add one line for the detail parameter:

```
detail: Output verbosity — "brief" (summary), "normal" (default), or "full" (everything).
```

### Brief-mode key filtering logic

After the result dict is built (in `_build_suggest_scale()`), apply this filtering before return:

```python
# At the end of _build_suggest_scale, before returning result:
if detail == "brief":
    brief_keys = {"scene", "mode", "recommended_scale", "match_tier", "matches_found", "error"}
    result = {k: v for k, v in result.items() if k in brief_keys}

return apply_output_limit(result, detail, list_keys=["reference_models", "references"])
```

### What NOT to change

- Do not modify `_build_asset_registry()` or `godotiq_asset_registry()` — they already have full `detail` support.
- Do not modify `_reference_mode()` — filtering happens in the caller.
- Do not modify any existing test files.

## Summary of Changes

| Location | Change |
|----------|--------|
| `_build_suggest_scale()` signature | Add `detail: str = "normal"` parameter |
| `_build_suggest_scale()` return path | Add brief-mode key filtering + `apply_output_limit()` call |
| `godotiq_suggest_scale()` signature | Add `detail: str = "normal"` parameter |
| `godotiq_suggest_scale()` docstring | Add one-line detail description |
| `godotiq_suggest_scale()` call | Pass `detail=detail` to `_build_suggest_scale()` |
| `tests/test_tools/test_detail_levels.py` | Add `TestSuggestScaleDetail` class with 4 tests |
