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

A green checkmark in 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 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	Global routing rules; single source of truth for skill selection	RULES.md
skills/config/routing.json	Machine-readable matrix derived from RULES.md	skills/config/routing.json
skills/tool-index.md	Auto-generated list of available binaries with ✅/❌ flags	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 (Linux/macOS)
README_AI.md	AI agent instructions prohibiting path guessing	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 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, 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 with current system state:

Windows:

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

Linux/macOS:

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

These scripts scan the host PATH, locate compatible binaries, and rewrite both tool-index.md and the accompanying JSON metadata.

2. Validate Recorded Paths Manually

Open skills/tool-index.md and locate the problematic entry. Copy the absolute path and test directly:

# 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, 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 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 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 -NoProfile -ExecutionPolicy Bypass -File skills/scripts/smoke.ps1

Linux/macOS:

bash skills/scripts/smoke.sh

The smoke test performs an end-to-end sanity check, ensuring routing.json and 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:

# 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 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 to force synchronization between router and index
• Remember the limitation: 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 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 matches tool-index.md and that all gated skills have their required tools available. It catches drift between the routing matrix and actual host capabilities.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}