Rust CLI · MCP Server · Agent Skill

ToolScout is a tool-first gate.

AI agents often write throwaway code when a mature local tool would solve the job better. ToolScout checks installed tools, registered candidates and verified tool memory before an agent reinvents a commodity operation.

Quick install ↓View architecture Latest v1.0.1 ↗

# Before writing incidental code, ask ToolScout
toolscout advise \
  --task 'extract text from a docx file' \
  --intent avoid_custom_code \
  --category document \
  --json

# Result: prefer mature tools such as pandoc or textutil;
# write custom code only when no suitable tool fits.

01 / Why

It does not add process for its own sake. It removes unnecessary code.

pre-code gate

Triggered before code

Use it only when an agent is about to reimplement a commodity local operation such as document conversion, image work, JSON extraction, archives or search.

tool first

Mature tools first

Query the registry, then detect whether tools such as pandoc, jq, ffmpeg, magick or rg already exist locally.

memory last

Experience without authority drift

tool-memory stores verified tool experience. It is not an enterprise knowledge base and must not become high-authority memory.

02 / Architecture

Three layers: rules, runtime and shared tool-memory.

What ToolScout includes

SKILL.md: the canonical rule source for when agents should and should not invoke ToolScout.
Rust runtime core: CLI, MCP server, registry query, tool detection and diagnostics.
shared tool-memory: stored by default at ~/.config/toolscout/tool-memory for verified tool experience.

What ToolScout does not do

It does not execute dangerous commands for the agent.
It does not auto-install software.
It does not modify user business files.
It does not maintain a second high-authority rule copy.
It does not treat tool-memory as Vault or enterprise knowledge authority.

03 / Flow

Agent workflow: decide first, then act.

ToolScout workflow and architecture diagram

04 / Decisions

The output is not “always use a tool”. It is a concrete action recommendation.

use_existing_tool

A mature local tool is available. Use it before writing incidental code.

verify_recalled_recipe

A remembered command may be reusable. Re-detect the tool and verify that the recipe still works.

tool_known_but_missing

A suitable tool exists but is missing locally. Use a fallback, or ask before installing.

write_code_allowed

Write code only when no mature tool fits, or when the task genuinely requires custom logic.

05 / Install

Quick install on macOS; build from source on Linux.

curl -sL https://github.com/licat233/toolscout/releases/download/v1.0.1/toolscout-universal-apple-darwin.tar.gz | tar xz
mv toolscout-universal /usr/local/bin/toolscout

toolscout memory init --json
toolscout doctor

toolscout advise --task 'extract text from a docx file' --intent avoid_custom_code --category document --json

06 / Agents

One tool-first rule for Codex, Claude Code and Hermes Agent.

Important boundary: do not invoke ToolScout at task start. Invoke it only when the agent is about to write incidental code for a commodity local operation, or before installing a dependency for that operation. Ordinary chat, planning, code reading, code review, repository inspection and normal software development should not trigger ToolScout.

GitHub

Help agents reuse mature tools instead of reinventing them.

Source code, installation guidance, MCP integration examples and the full canonical rule live in the GitHub repository.

Open repository ↗