Token Reduction Benchmark

One-line summary: on Unity 2022.3.62f2, the v0.0.43 connector change turns the biggest observed discovery hotspot, list --compact, from ~1844 estimated tokens into ~93 estimated tokens, and adds explicit low-token projections for find_gameobjects.

• Measured on: 2026-06-22
• CLI: hera-agent-unity v0.0.29
• Connector under test: AgentConnector/package.json 0.0.43 as a local UPM package
• Unity: 2022.3.62f2
• Project: %UNITY_PROJECT% (Test2022.3.62f2 fixture)
• Scene: Assets/HeraSmoke/Scenes/Smoke_2022_3.unity
• Token estimate: UTF-8 output bytes divided by 4, rounded up

This benchmark measures the CLI output payload that comes back into an agent context. It does not include the outer tool-call framing overhead of a specific AI client.

---

0. TL;DR

Command / scenario	Before	After	Change
list --compact	~1844 T	93 T	~95% less
find_gameobjects --name Pickup --limit 20 vs legacy verbose shape	~714 T	253 T	~65% less
find_gameobjects --name Pickup --limit 20 --ids	N/A	54 T	new lowest-token handoff path
find_gameobjects --name Pickup --limit 20 --names	N/A	103 T	new names-only projection

The important design change is:

• default discovery stays cheap;
• verbose data is still available;
• callers must opt in to expensive fields with --fields.

---

1. What Changed

list --compact

Before v0.0.43, list --compact did not change the list tool's payload. It returned the same name + description catalogue as default list, so the smoke test measured it at about 1844 estimated tokens.

In v0.0.43, list --compact is an alias for list --names.

Use:

hera-agent-unity list --compact
hera-agent-unity list --names

Only use plain list when one-line descriptions are actually needed. Use list --tool <name> when a full parameter schema is needed for one tool.

find_gameobjects

Before v0.0.43, every result entry included:

{ "instance_id": -123, "name": "Pickup", "path": "/Root/Pickup", "scene": "Main", "active": true }

In v0.0.43, default output is:

{ "instance_id": -123, "name": "Pickup" }

Projection controls:

Flag	Use when
--ids	You will pass matches into manage_gameobject, manage_components, manage_prefab, or another command that accepts instance_id.
--names	You only need a human-readable object list.
--fields instance_id,name,path	You need hierarchy paths for disambiguation.
--fields all	You need the legacy verbose shape: instance_id, name, path, scene, active.

---

2. Measurement Method

Each command was executed against the same running Unity Editor. Output bytes were measured from combined stdout/stderr text, then estimated as ceil(bytes / 4).

PowerShell sketch:

$out = & hera-agent-unity find_gameobjects --name Pickup --limit 20 --ids --compact-json 2>&1
$text = ($out | Out-String).TrimEnd("`r", "`n")
$bytes = [Text.Encoding]::UTF8.GetByteCount($text)
$tokens = [Math]::Ceiling($bytes / 4)

The smoke scene contained a realistic small gameplay setup:

• root hierarchy for gameplay objects;
• ground, player capsule, camera, and light;
• 10 spawn points;
• 20 pickup objects plus prefab instances;
• HUD canvas with health, inventory, and objective text.

This matters because empty-scene tests understate the cost of discovery commands. The goal is to approximate what an AI agent asks during real Unity game-development work.

---

3. Results

Discovery Catalogue

Case	Exit	Bytes	Est. tokens	Notes
list --names --compact-json	0	370	93	flat tool-name array
list --compact --compact-json	0	370	93	now identical to --names
list --compact before v0.0.43	0	~7376	~1844	previous smoke measurement
list --compact-json	0	7425	1857	default list still includes descriptions

Interpretation:

• list --compact is now safe for bootstrap and repeated discovery.
• plain list remains intentionally descriptive and should not be the default bootstrap path.

GameObject Search

All rows use:

hera-agent-unity find_gameobjects --name Pickup --limit 20

with the projection shown in the table.

Projection	Bytes	Est. tokens	Relative use
default {instance_id,name}	1009	253	normal agent search
--ids	216	54	cheapest follow-up handoff
--names	409	103	readable list
--fields instance_id,name,path	2114	529	path disambiguation
--fields all	2854	714	legacy verbose shape

Interpretation:

• --ids is the preferred path when the next step is object mutation.
• default search is still readable and much smaller than the legacy verbose shape.
• path/scene/active are now paid for only when explicitly requested.

Error Path

Invalid projection combinations are compact and branchable:

hera-agent-unity find_gameobjects --name Pickup --ids --fields name --compact-json

Result:

Case	Exit	Bytes	Est. tokens	Code
invalid projection	1	139	35	INVALID_PROJECTION

This preserves the stable code-based error contract while keeping the error payload small.

---

4. Verification

Static verification:

go clean -testcache
golangci-lint run ./...
golangci-lint fmt --diff
go test ./...
git diff --check

Result:

• golangci-lint run ./...: 0 issues
• golangci-lint fmt --diff: clean
• go test ./...: passed
• git diff --check: clean

Unity verification:

hera-agent-unity manage_packages add "file:%HERA_REPO%/AgentConnector"
hera-agent-unity editor refresh --compile --wait --timeout 180000 --compact-json
hera-agent-unity console --type error --lines 50 --compact-json
hera-agent-unity list --tool find_gameobjects --compact-json

Observed:

• Unity resolved com.notnull92.hera-agent-unity as local package version 0.0.43.
• Unity 2022.3.62f2 returned to ready.
• Console error query returned matched: 0.
• list --tool find_gameobjects exposed the new parameters: fields, ids, names.

Unity EditMode tests:

hera-agent-unity test --mode EditMode --filter HeraAgent --timeout 180000 --compact-json

Result:

• total: 0, failed: 0
• The test project did not discover HeraAgent EditMode tests, so the functional gate for this change was the live command surface above.

---

5. Conclusion

On Unity 2022.3.62f2, v0.0.43 succeeds at the targeted token reduction:

• the repeated discovery hotspot list --compact is now effectively as cheap as list --names;
• find_gameobjects no longer pays for hierarchy path, scene name, and active state by default;
• agents get a new 54-token object-ID handoff path for realistic follow-up edits;
• verbose information remains available through explicit projection flags.

This keeps hera-agent-unity aligned with its main product constraint: if a workflow uses many more tokens than a direct MCP-style interface, the CLI has lost its reason to exist. The v0.0.43 changes keep the common Unity-agent loop on the low-token path by default.