# AI Tool Routing

Use tools by evidence domain. Do not choose tools by convenience when another
tool owns the relevant fact.

## RepoKey Vivado MCP

Use for local Vivado/PL state:

- Vivado sessions and project state.
- BD/IP/OOC/run health.
- bitstream/LTX and Hardware Manager.
- ILA/VIO inventory, trigger planning, capture/export.
- timing/utilization/implementation evidence from the live Vivado project.

## PL QoR MCP

Use for QoR evidence records and AI decision artifacts:

- `pl_qor_probe`
- `pl_qor_collect_baseline`
- `pl_qor_decide`
- `pl_qor_compare`
- `pl_qor_make_experiment`

This MCP does not execute optimization experiments. It can generate reviewed
Tcl/manifest files for later human-authorized execution.

## PL-PS Handoff

Use for customer-visible PL-to-PS delivery artifacts:

- Generate `control_handoff.xlsx/json/md`.
- Generate `ps_delivery.xlsx`.
- Generate `evidence.md` and `ai_reading_guide.md`.
- Compare legacy Excel register/control sheets against current PL evidence.
- Import PL engineer review decisions.
- Apply AI/engineer feedback patches without overwriting hard facts.

Primary CLI:

```powershell
{{REPOKEY_ROOT}}\repokey-client.cmd handoff pl2ps {{PROJECT_ROOT}} --output {{PROJECT_ROOT}}\pl_ps_handoff --summary-json
```

Use Handoff when the question is "what should PS know about this PL design?"
Use PL QoR MCP when the question is "is implementation timing/fanout/QoR safe?"

## Vitis MCP

Use for PS/Vitis/XSCT state:

- Static PS context: interrupt consumers, AXI register consumers, and driver
  entry points written to `.vivado_ai_mcp/ps_context`.
- Vitis status/build/run through project-local helpers.
- PS `test_mode` read/write.
- `debug_status`.
- RF front-end source/runtime configuration reports.
- PS-side RepoKey handoff consumption checks.
- ILA CSV analysis from the PS project perspective.

Use PS context before broad PS source reading when the user asks how PS consumes
PL interrupts, AXI registers, or driver entry points. Use live Vitis/XSCT tools
only when runtime state or hardware behavior is required.

## AMD Doc MCP

Use for official AMD/Xilinx documentation semantics:

- XDC timing exception semantics.
- Vivado strategy and command behavior.
- Vitis/XSCT behavior.
- Vitis HLS pragma/interface semantics.
- clock/reset/CDC/RDC official guidance.
- AMD/Xilinx IP parameter meaning.

Endpoint:

```text
https://vivado.amd.com/mcp/doc-search
```

AMD Doc MCP is not local project evidence. Pair it with RepoKey/Vitis evidence
before making an engineering decision.

## Vivado Debug MCP (Optional)

The bundled `vivado_debug_mcp` package is a low-token hardware debug evidence
layer. Use it for ILA/VIO inventory parsing, probe search, trigger-plan
templates, capture summary/compare, live batch capture, and XSCT PL register
probe generation:

- CLI (`vivado-debug`): `inventory`, `probe-search`, `trigger-plan-template`,
  `capture-summary`, `ila-csv-summary`, `capture-compare`, `write-session`,
  `live-inventory`, `capture-tcl`, `live-capture`, `xsct-reg-read`,
  `xsct-reg-write`.
- MCP server (`vivado-debug-mcp`): same tools over stdio. Built into the
  RepoKey client (`repokey-client.cmd debug serve`); register with
  `install\register_debug_mcp.ps1` or the `MCP_REGISTRATION_TEMPLATE.json` entry.

It complements RepoKey Vivado MCP (live project/session state) by keeping
compact, reusable debug evidence under `.vivado_ai_mcp/debug`.

## Vivado Context MCP (Optional)

The bundled `vivado_context_mcp` package is a low-token project context layer.
Use it before broad project scanning when the question is about what the Vivado
project contains:

- CLI (`vivado-context`): `index`, `summarize`, `hierarchy`, `constraints`,
  `bd-summary`, `bd-connections`, `clock-reset`, `entry-points`,
  `cache-status`, `relevant`, `report`, `tokens`.
- MCP server (`vivado-context-mcp`): same tools over stdio. Register manually
  from `MCP_REGISTRATION_TEMPLATE.json` (the server also needs the `mcp`
  Python package).

It writes compact context under `.vivado_ai_mcp/context/` (project_summary.json,
agent_summary.md) and exposes handoff-facing facts (PS interrupts/AXI from the
BD) that the PL-PS Handoff layer consumes.

## Decision Order

1. Gather local evidence with RepoKey Vivado MCP, PL QoR MCP, or Vitis MCP.
2. For PL-to-PS delivery, generate or read PL-PS Handoff artifacts.
3. Read local context and prior evidence.
4. Query AMD Doc MCP only when official tool semantics matter.
5. Classify risk and decide whether action is automatic, reviewed, or blocked.
6. Record before/after evidence and the decision rationale.

## Red Lines

Do not automatically execute:

- PL optimization experiments.
- false path or multicycle constraints.
- latency-changing pipeline edits.
- AXI/stream protocol changes.
- RF front-end data alignment changes.
- PS/PL handoff semantic changes.
- clock/reset/CDC/RDC architecture changes.
