# Troubleshooting Tool-Index.md Showing 'Yes' but AI Cannot Call Tool: A Complete Guide

> Fix AI tool calling errors when tool-index.md shows 'yes'. Understand why a green checkmark isn't enough and learn how to troubleshoot AI sandbox execution for your tools.

- Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill)
- Tags: how-to-guide
- Published: 2026-08-16

---

**A green checkmark in [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) only confirms binary presence, not whether the AI's sandbox environment can actually execute the tool.**

When using `zhaoxuya520/reverse-skill`, developers often encounter a frustrating scenario: [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) displays a **✓** (yes) for a required tool, yet the AI agent reports it cannot invoke it. This guide explains why this mismatch occurs and provides concrete steps to resolve it based on the repository's routing architecture.

## Understanding the Reverse-Skill Architecture

The `reverse-skill` platform operates as a neutral router that separates **decision-making** from **execution verification**. Before any tool invocation, the system checks whether required tooling exists on the host through a carefully orchestrated pipeline:

| Component | Purpose | File Path |
|---|---|---|
| [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) | Global routing rules; single source of truth for skill selection | [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) |
| [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) | Machine-readable matrix derived from [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) | [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) |
| [`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md) | Auto-generated list of available binaries with ✅/❌ flags | [`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md) |
| `skills/scripts/refresh-tool-index.*` | Host scanner that regenerates the index | `skills/scripts/refresh-tool-index.ps1` (Windows) / [`skills/scripts/refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/refresh-tool-index.sh) (Linux/macOS) |
| [`README_AI.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/README_AI.md) | AI agent instructions prohibiting path guessing | [`README_AI.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/README_AI.md) |
| Routing scripts (`master-route.ps1`, `smoke.ps1`) | Execute pipeline and enforce "auth-status = granted" gates | `skills/scripts/master-route.ps1` |

According to the repository's design, skills read [`../tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/../tool-index.md) before attempting tool invocation. A **✓** entry indicates the binary exists at the recorded absolute path—but this is where the confusion begins.

## Why Tool-Index.md Shows "Yes" While AI Fails to Call the Tool

The index records **presence only**; it does **not** verify that the current AI execution environment can launch the binary. In `skills/scripts/refresh-tool-index.ps1` and [`skills/scripts/refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/refresh-tool-index.sh), the scanning logic tests for file existence and basic path resolution, not sandbox permissions or runtime compatibility.

Common causes of this mismatch include:

- **Stale Index** — Generated before tool reinstallation, leaving recorded paths invalid
- **Permission/Sandbox Constraints** — The AI client runs inside a sandbox without execute permissions on host binaries
- **Platform Mismatch** — Index entries from a different OS (e.g., Windows-only tool listed on Linux)
- **Missing Runtime Dependencies** — Auxiliary libraries absent despite main binary presence (e.g., Java for `jadx`)

## Step-by-Step Troubleshooting Procedure

Follow this sequence to isolate and resolve the issue:

### 1. Refresh the Tool Index

Run the platform-appropriate script to rebuild [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) with current system state:

**Windows:**

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/refresh-tool-index.ps1

```

**Linux/macOS:**

```bash
bash skills/scripts/refresh-tool-index.sh

```

These scripts scan the host PATH, locate compatible binaries, and rewrite both [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) and the accompanying JSON metadata.

### 2. Validate Recorded Paths Manually

Open [`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md) and locate the problematic entry. Copy the absolute path and test directly:

```bash

# Example: verifying frida after refresh

# Entry shows: ✅ frida → /usr/local/bin/frida (v15.2.2)

/usr/local/bin/frida --version

```

If this fails, the index entry is corrupted or points to a moved/removed binary.

### 3. Check AI Sandbox Permissions

Confirm your AI client is permitted to execute external binaries. According to [`README_AI.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/README_AI.md), AI agents must *never* guess tool paths—but even with correct paths, hosted LLM services may completely disallow external process invocation. This is an environment policy issue, not a `reverse-skill` configuration problem.

### 4. Verify Platform Compatibility

Cross-reference the tool's platform requirements with your host OS. The routing matrix in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) may contain platform-specific entries that don't apply to your current environment.

### 5. Inspect Auxiliary Dependencies

For JVM-based tools like `jadx`, ensure `JAVA_HOME` is properly set. For Python tools, verify the virtual environment is active. These dependencies are outside the scope of [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) detection.

## Synchronizing Router and Index with Smoke Tests

If all manual checks pass but the AI still cannot invoke the tool, the routing logic in `skills/scripts/master-route.ps1` may be rejecting calls due to stale cached data. The smoke test regenerates both the routing matrix and tool index:

**Windows:**

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/smoke.ps1

```

**Linux/macOS:**

```bash
bash skills/scripts/smoke.sh

```

The smoke test performs an end-to-end sanity check, ensuring [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) and [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) remain in sync.

## How Skills Actually Use the Index

Skills implement tool discovery through direct index parsing. While this pattern is illustrative, it demonstrates the dependency chain:

```powershell

# Inside a skill PowerShell script

$toolIndex = Get-Content "$PSScriptRoot\..\tool-index.md" |
    ConvertFrom-StringData   # parses lines like "frida = C:\tools\frida\frida.exe"

$fridaPath = $toolIndex['frida']
if (-not $fridaPath) {
    Write-Error "Frida not found in tool‑index – aborting."
} else {
    & $fridaPath -V   # invoke the tool

}

```

The AI agent's failure typically occurs at the final invocation line—after the index check has already succeeded.

## Summary

- **Refresh first**: Always run `refresh-tool-index.ps1` or [`refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/refresh-tool-index.sh) when tools change
- **Test manually**: Verify absolute paths outside the AI environment
- **Check sandbox constraints**: Many hosted AI services prohibit external binary execution regardless of index status
- **Run smoke tests**: Use `smoke.ps1` or [`smoke.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/smoke.sh) to force synchronization between router and index
- **Remember the limitation**: [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) confirms **presence**, not **executable permission**

## Frequently Asked Questions

### How often should I regenerate tool-index.md?

Regenerate whenever you install, upgrade, or relocate tools. The index does not auto-update. As implemented in `zhaoxuya520/reverse-skill`, the `refresh-tool-index.*` scripts must be triggered manually or through CI/CD pipelines.

### Can I edit tool-index.md manually?

Manual edits are overwritten on the next refresh. The file is generated output, not configuration. Modify the scan logic in `skills/scripts/refresh-tool-index.ps1` or [`skills/scripts/refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/refresh-tool-index.sh) if you need custom detection behavior.

### Why does the same tool work for me but not the AI?

Your user account typically has broader permissions than sandboxed AI processes. The index check runs under your context during refresh, while AI invocation occurs under restricted service accounts. This permission gap is the most common root cause of "yes in index, no in practice" scenarios.

### What does the smoke test actually verify?

The smoke test in `skills/scripts/smoke.ps1` validates that [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) matches [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) and that all gated skills have their required tools available. It catches drift between the routing matrix and actual host capabilities.