# Debugui Tools > --- name: debugui-tools description: Catalogue of the SIXTEEN granted `mcp__debugui__*` tools - exact names, parameter names/types/defaults, return shapes, and the error string each one emits. Read when you need a fact out of the COMPILED STATIC SCHEDULE (which tiles exist; a tile's role, kernel and channel<->kernel-argument map; a flow's hops and stream-switch pairs; per-flow supply/demand; BD lengths; where a symbol occurs) or out of WHAT THE USER HAS ON SCREEN (`get_ui_state` is how "this tile" / "that flow" resolves to real coords; `get_pane` returns one UI pane verbatim; `list_apps` / `current_app` answer "which app is loaded, and what else could be"; `app_sources` lists that app's own source files so an explanation can cite code instead of stopping at the schedule), when the user has run a live overlay scan in the AIE Debug pane (`get_live_scan` returns the latest DMA/Cores/Events/Switch summary — pair with the `live-scan-results` skill), and when a debugui call returned something you must interpret: "daemon not reachable" from the daemon-backed tools, `_load_view()`'s tried-paths error, or a `kinds=` filter that is never validated and so silently matches nothing on a typo. Most of the sixteen touch only static schedule or disk logs; `get_live_scan` reads the last `/grid` overlay the user ran (still not a substitute for `get_backend_status` session gating). `select_app` is registered in debug_ui_mcp.py but deliberately NOT granted - never call it; ask the user to switch apps in the UI. Also documents the get_applog FRESH/STALE/UNVERIFIED banner and the get_ipc_log CSV columns. A tool catalogue, not a procedure: symptom triage is dma-stall-triage's, scan interpretation is live-scan-results's, an on-disk file's absolute path is app-layout's, what a banner lets you claim is session-provenance's. --- # debugui MCP tools — the cheap static-schedule and UI-state layer Source of truth: `src/tool/debug/debug_ui_mcp.py`. The list is `_llm_spawn()`'s `--allowedTools` in `schedule_debug_server.py`. Note that `--allowedTools` is a *permission* allowlist, not an availability filter, and the spawn also sets `--permission-mode bypassPermissions` — so a tool the server exposes is callable whether or not it is listed. Withholding one requires `--disallowedTools`, which the spawn uses for exactly one tool (below). **Sixteen** `mcp__debugui__*` tools are granted, in three groups: - **Schedule-view tools** (9) — `get_design_overview`, `tile_list`, `tile_info`, `get_flow_detail`, `symbol_search`, `get_backend_status`, `get_applog`, `get_sim_log`, `get_ipc_log`. These read the **static compiled schedule** (`schedule_view.json`, the same blob that renders `host_schedule.html`) or a log file on disk. - **Live scan tool** (1) — `get_live_scan`. Returns the latest **overlay scan** the user ran from the AIE Debug pane (DMA / Cores / Events / Switch). Does not touch the board itself; it reads `backend_status.json > last_scan` or `GET /live_scan`. Interpret with the `live-scan-results` skill; gate with `get_backend_status` / `session-provenance`. - **App / UI tools** (6) — `list_apps`, `current_app`, `app_sources`, `get_ui_state`, `list_panes`, `get_pane`. See the second section below. None reads `schedule_view.json` except `get_pane`, and they fail differently: `list_apps` / `current_app` / `get_ui_state` are **daemon-backed** (HTTP), `app_sources` reads `backend_status.json` off disk, and `list_panes` is a static table. Fifteen of the sixteen do not issue fresh hardware reads during the tool call itself. `get_live_scan` surfaces a scan the user (or live overlay) already triggered via `/grid`. None are gated by the session-authorization check that `mcp__aiegdb__aie_exec` enforces, none write hardware, and none can fail a run. Use them freely. `debug_ui_mcp.py` registers a seventeenth tool, `select_app(app_id)`, which the spawn explicitly **denies** via `--disallowedTools mcp__debugui__select_app` — switching the app reconfigures the whole server (board IPs, PDIs, ELF paths) and belongs to the user. Calling it will be refused; if the user needs a different app, tell them to pick it in the UI. **Coordinates.** `col`/`row` everywhere here are the *logical* grid coords shown in the UI (row 0 = shim, rows >= 3 = core). They are the same coords `aie_exec("target tile C R")` takes — `aiegdb` adds `startcol` itself (`phys_col = col + startcol`, `aiegdb.py:449`). Do not pre-add `startcol`. ## Data resolution (why a tool may say "not found") `_load_view()` tries, in order: the current app's `/schedule_view.json` (asked of the daemon via `/apps`), `$DEBUGUI_JSON_DIR/schedule_view.json`, `$AIEMCP_JSON_DIR/schedule_view.json`, `./aout/worklocal/schedule_view.json`, `./worklocal/schedule_view.json`. The error message lists exactly the paths it tried — quote it rather than guessing. It is cached per resolved path. --- ## The schedule-view tools ### `mcp__debugui__get_design_overview()` → str No parameters. **Call this first in a new session.** Three sections: `=== Grid geometry ===` (`cols`, `rows`, `startcol`, `shim rows`, `core rows`), `=== Communication flows (N) ===` one line per comm_path (`f → tile(c,r)`), and `=== Supply/demand balance ===` one line per flow: either `f balanced pattern=

` or `f OVER-SUPPLY|UNDER-SUPPLY supply=B demand=B [note]`. Answers: *what is this design, how many flows, is anything unbalanced?* ### `mcp__debugui__tile_list()` → str No parameters. One line per tile: `(col,row) `. Answers: *which tiles exist and which are shim / core / compute?* Cheapest way to get valid coords before `tile_info`. ### `mcp__debugui__tile_info(col: int, row: int, section: str = "all")` → str `section` ∈ `"hi" | "mid" | "lo" | "all"` (case-insensitive; anything else returns an error string). Exactly what the human sees when clicking a tile: - `hi` — role, kernel, `supply / demand:` per-flow verdict lines (`flow (): balanced|OVER-SUPPLY|UNDER-SUPPLY supply=..B/round demand=..B/round (delta ..B) [note]`), `transfers:`, `contracts:`, and the `channel <-> kernel argument (by BD buffer address)` map (`S2MM0 -> window arg [bd 0x.. = ] via `). - `mid` — the tile's `dfschedule` IR slice, preceded by `file: ` and rows tagged `: `. - `lo` — attributed `host.cc` lines: `file: `, then `host.cc lines -:`, then rows tagged `host.cc: `. Unknown tile → error listing every available `(col,row)`. Answers: *what is this tile supposed to be doing, and which source line configured it?* ### `mcp__debugui__get_flow_detail(flow_index: int)` → str The net-detail panel for one flow. Per stage: `[producer|consumer] tile(c,r) gmio=… contract=…` then `hop: → [/]`; then `[stream-switch connections]` as `(c,r) / → /` for `circuit_connect` entries; then `[supply/demand]` with `pattern / supply_per_round / demand_per_round / balanced / note` and one `participants` line per endpoint: `(c,r) ch bd_len= fires= [shim]`. Bad index → error listing available indices. Answers: *how does data actually get from the shim to this tile, and who over/under-supplies?* The `participants` block is the table to reason over for a data-mismatch question. ### `mcp__debugui__symbol_search(query: str, kinds: str = "")` → str Case-insensitive substring search, mirroring the UI search bar. `kinds` is a comma-separated filter, empty = all. Valid kinds: `kernel`, `window`, `buffer`, `contract`, `bd_len`, `net`, `flow`, `gmio`, `port`. Output: a count header then ` (col,row) f

' needs col and row` / `needs flow` / `needs query`. Unknown tile → `error: no tile (c,r) in the current app`. An empty pane returns `(pane

is empty for tile (c,r) in this app)`, which is information, not a failure. Nothing here is unique to `get_pane`: `tile.kernel` and `tile.supply` are the kernel-match and supply/demand blocks that `tile_info(col,row,"hi")` already includes, and `grid`, `search`, `net.flow`, `tile.hi/mid/lo` delegate to `tile_list`, `symbol_search`, `get_flow_detail` and `tile_info`. Reach for `get_pane` when the user is pointing at something on screen and you want *just* that pane (pair it with `get_ui_state`); use `tile_info` / `get_flow_detail` when you are driving the investigation yourself. --- ## Which tool first | User asks | Order | |---|---| | anything, cold start | `current_app()` → `get_design_overview()` → `get_backend_status()` | | "what am I looking at?" / "this tile", "that flow" | `get_ui_state()` → `get_pane(...)` on what it reports | | "what's in the Info / Run / Tools pane?" | `list_panes()` for the layout, then the tool that pane maps to | | "which app is loaded?" / "what else can I load?" | `current_app()` / `list_apps()` | | "what does this kernel actually do?" / "where is this in my code?" | `app_sources()` → Read the file it names → cite `:` | | "what's on tile (0,3)?" | `tile_list()` → `tile_info(0,3,"hi")` → `"mid"`/`"lo"` only if pressed | | "why is the output wrong / zero?" | `get_design_overview()` (find the unbalanced flow) → `get_flow_detail()` (participants table) → `tile_info` on the offending endpoint | | "where is ``?" | `symbol_search("")` → `tile_info(col,row)` | | "how is f3 routed?" | `get_flow_detail(3)` | | "did the run pass?" | `get_applog(80)` — and state the provenance banner | | sim hangs / no output | `get_backend_status()` → `get_sim_log(100)` → `get_ipc_log(120,"both")` | | "is the DMA actually stuck?" | static first (`get_flow_detail`, `tile_info`) to know what *should* happen, `get_backend_status()` to confirm a live read is allowed, **`get_live_scan()` if the user scanned**, only then `aie_exec("target tile C R")` / `aie_exec("dma status")` / `aie_exec("bd")` | | coloured tiles / switch mismatch / "what did scan show?" | `get_live_scan()` → **`live-scan-results`** skill → `get_flow_detail` / `tile_info` on named tiles | **Rule:** never open with a hardware read. A live `dma status` is only interpretable once you know from `get_flow_detail`/`tile_info` which channel, BD id and length that tile was compiled to use — and `get_backend_status()` is what tells you the read will not simply be refused. **Do not** try to read `schedule_view.json` with the Read tool to answer these questions — it is a large blob and every field above is already rendered for you. **These tools return names and summaries, not file contents.** `tile_info` gives you the kernel's *name*; `app_sources()` maps that name to the file and line defining it. For any other on-disk artifact — the `.bcf` address map, `aie_control_config.json`, a per-tile wrapper — switch to the **app-layout** skill for the absolute paths (anchored on the `path` from `current_app()`) and open the file. **When** to open source rather than stop at the schedule, and how to cite it, is **source-grounding** — the short version is that an answer which never leaves the register dump is not finished.