tool-guardian
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| TG_LOOP_GUARD | No | Set to 0 to disable the loop guard that warns on the 3rd identical call and refuses it on the 5th. | |
| TG_VALIDATE_ARGS | No | Set to 0 to disable argument validation (silent fixes of near-miss types, and refusal of invalid calls with an example). | |
| TOOL_GUARDIAN_ENV | No | Explicit path to a .env file to load. Otherwise a .env is looked for by an upward search starting at the config file's directory (or the cwd) and walking up to 5 parent directories. | |
| TOOL_GUARDIAN_STATE | No | Path to state.json, where activated groups are remembered across sessions. Empty disables it. Default ~/.tool-guardian/state.json. | |
| TOOL_GUARDIAN_CONFIG | No | Path to the mcp.json config file. Config is searched in order: --config PATH, $TOOL_GUARDIAN_CONFIG, ./mcp.json, ./.mcp.json, ~/.tool-guardian/mcp.json. | |
| TOOL_GUARDIAN_LADDER | No | Set to 0 to turn off the output ladder (result shaping) applied to call_tool results. | |
| TOOL_GUARDIAN_PRESET | No | Set to 'small' for 8k-context local models. It sets TOOL_GUARDIAN_CATALOGUE_CHARS=1500 and TOOL_GUARDIAN_DESC_WORDS=6. | |
| TOOL_GUARDIAN_PYTHON | No | Python interpreter for the DSH bundle to use. Otherwise a .venv beside the package, then python/python3 on PATH (3.9+). | |
| TOOL_GUARDIAN_SKILLS | No | One or more folders containing SKILL.md files, separated by ':' on Linux/macOS and ';' on Windows. Enables the list_skills and read_skill tools. | |
| TOOL_GUARDIAN_CALL_LOG | No | Path to the call log where every router call is appended (argument values never are). Default ~/.tool-guardian/calls.jsonl. | |
| TOOL_GUARDIAN_HOOK_MODE | No | Set to 'deny' to make the Claude Code PreToolUse hook block a shell call that does a router tool's job and tell Claude which call_tool(...) to use. | |
| TOOL_GUARDIAN_PROVE_KEY | No | Bearer token for the OpenAI-compatible endpoint used by 'tool-guardian --prove'. | |
| TOOL_GUARDIAN_PROVE_URL | No | Base URL of an OpenAI-compatible chat endpoint (e.g. http://127.0.0.1:11434/v1) used by 'tool-guardian --prove' to test whether the model drives the router. | |
| GUARDIAN_NO_UPDATE_CHECK | No | Set to 1 to disable the once-a-day update check. | |
| TOOL_GUARDIAN_DESC_WORDS | No | Words of a tool, server or skill description shown in catalogue and search lines. Default 12; 6 with TOOL_GUARDIAN_PRESET=small. | |
| TOOL_GUARDIAN_PROVE_MODEL | No | Model id used by 'tool-guardian --prove'. Default: the first id from GET <url>/models. | |
| TOOL_GUARDIAN_CALL_TIMEOUT | No | Milliseconds/seconds timeout before a call gets no reply; the router stops the backend and restarts it before the next call. A second failure within 60 s marks the backend DOWN. | |
| TOOL_GUARDIAN_CATALOGUE_CHARS | No | Each server's block in list_capabilities is cut at this many characters, with a '[+N more tools not shown ...]' line pointing at search_capabilities. Default 0 (no cap); 1500 with TOOL_GUARDIAN_PRESET=small. | |
| TOOL_GUARDIAN_DESCRIBE_DETAIL | No | Set to 'full' to make describe_tool return the whole tool definition by default instead of the compact form. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
This server publishes no instructions, or was last inspected before Glama recorded them.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| list_capabilitiesA | List the tools on the connected MCP servers. No server is reachable yet; this says why. With a keyword, search_capabilities is cheaper. Read-only. Returns a line per tool, else per server with any error. |
| describe_toolA | Get the arguments of ONE backend tool, before call_tool. |
| call_toolA | Invoke a tool on a connected server. THIS IS THE STEP THAT ANSWERS THE USER -- list_capabilities only finds the name. |
| search_capabilitiesA | Find a tool by keyword on every connected server; cheaper than list_capabilities when you know roughly what you want. Read-only. Returns a line per match, best first, with args. |
| list_groups_with_costsA | Tool GROUPS with the context-token cost of loading each; to find a tool use list_capabilities. Read-only. Returns a line per group and the totals. |
| retrieve_spillA | Read back the FULL original of a result call_tool shortened, by the id in its notice; an unknown or pruned id fails saying so. Read-only. Returns a text window, or grep's lines. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 6 tools
Each tool maps to a distinct step in the discovery-invoke pipeline: list vs search vs describe vs call vs retrieve are separable, and descriptions explicitly cross-reference ("to find a tool use list_capabilities"). The main friction is list_capabilities / search_capabilities / list_groups_with_costs, three read-only listing tools that are similar in spirit and could be briefly confused, though the descriptions steer correctly.
Every tool is snake_case verb_noun: list_capabilities, search_capabilities, describe_tool, call_tool, list_groups_with_costs, retrieve_spill. Naming is predictable and immediately readable, with the object of each verb clearly identifiable.
Six tools is well-scoped for a gateway whose job is discover, inspect, invoke, and recover output. No tool feels redundant or padded, and each covers a real stage of the proxy workflow.
The surface covers discovery, argument inspection, invocation, and spill recovery — the core lifecycle for a tool-proxy server. Minor gaps exist around connection/session management (connecting or refreshing servers) and reading backend resources/prompts, but agents can work around these.