A few related documentation/entry-point fixes, grouped because they are all small and touch how users (and AI agents) first find their way into the tool. From a review of how well AI agents can use the tool: the docs themselves proved good once found (an agent answered a "what's wasteful in this bundle" question writing every query straight from analyzer.md), but the entry points have gaps.
1. Version-pin the documentation URL in --help
Program.cs hardcodes blob/main/Documentation/unitydatatool.md. Someone running an old binary gets docs describing a newer tool. Derive the tag from the assembly version for release builds (e.g. blob/v2.1.0/...), falling back to main for dev builds.
2. Add a "using UnityDataTool with an AI agent" guide, replacing the dated section in analyze-examples.md
The "Using AI tools to help write queries" section of analyze-examples.md predates AI agents (it describes pasting the schema into a chat). Replace it with a compact guide page covering the canonical loop and the facts that experiments showed agents trip on:
- the loop:
analyze -> open the .db with any SQLite client (sqlite3 CLI, or Python stdlib sqlite3 as the no-install fallback) -> start from object_view / view_breakdown_by_type -> drill down with dump / serialized-file / archive -> trace with find-refs
id (database row) vs object_id (what dump -i takes)- one build per database (the duplicate-archive-name rule)
- TypeTrees required; what "Files without TypeTrees" means for Player builds
- the
refs table columns (object, referenced_object) — an agent guessed these wrong and burned queries
- one canonical worked example: "diagnose a bundle" combining
object_view ORDER BY size DESC, texture_view, mesh_view R/W flags, and view_potential_duplicates (today that recipe spans analyzer.md and analyze-examples.md)
Deliberately agent-agnostic — this is just a good usage playbook, and if a skill file for a specific agent ecosystem ever proves worthwhile, this page is its content.
3. Fix the README "Downloads" section
It still directs people to the Actions tab. Proper GitHub Releases with attached zips have existed since v1.3.x. Point to Releases (keep Actions as the bleeding-edge option), and mention what's in the zip plus the add-to-PATH step.
4. Route tool users out of AGENTS.md
AGENTS.md is (correctly) contributor-oriented, but an agent landing in a clone to use the tool starts there. Add a short pointer at the top: "Using the tool rather than working on it? See <the guide from item 2>."
A few related documentation/entry-point fixes, grouped because they are all small and touch how users (and AI agents) first find their way into the tool. From a review of how well AI agents can use the tool: the docs themselves proved good once found (an agent answered a "what's wasteful in this bundle" question writing every query straight from analyzer.md), but the entry points have gaps.
1. Version-pin the documentation URL in
--helpProgram.cshardcodesblob/main/Documentation/unitydatatool.md. Someone running an old binary gets docs describing a newer tool. Derive the tag from the assembly version for release builds (e.g.blob/v2.1.0/...), falling back tomainfor dev builds.2. Add a "using UnityDataTool with an AI agent" guide, replacing the dated section in analyze-examples.md
The "Using AI tools to help write queries" section of
analyze-examples.mdpredates AI agents (it describes pasting the schema into a chat). Replace it with a compact guide page covering the canonical loop and the facts that experiments showed agents trip on:analyze-> open the.dbwith any SQLite client (sqlite3 CLI, or Python stdlibsqlite3as the no-install fallback) -> start fromobject_view/view_breakdown_by_type-> drill down withdump/serialized-file/archive-> trace withfind-refsid(database row) vsobject_id(whatdump -itakes)refstable columns (object,referenced_object) — an agent guessed these wrong and burned queriesobject_view ORDER BY size DESC,texture_view,mesh_viewR/W flags, andview_potential_duplicates(today that recipe spans analyzer.md and analyze-examples.md)Deliberately agent-agnostic — this is just a good usage playbook, and if a skill file for a specific agent ecosystem ever proves worthwhile, this page is its content.
3. Fix the README "Downloads" section
It still directs people to the Actions tab. Proper GitHub Releases with attached zips have existed since v1.3.x. Point to Releases (keep Actions as the bleeding-edge option), and mention what's in the zip plus the add-to-PATH step.
4. Route tool users out of AGENTS.md
AGENTS.md is (correctly) contributor-oriented, but an agent landing in a clone to use the tool starts there. Add a short pointer at the top: "Using the tool rather than working on it? See <the guide from item 2>."