| name | agentic-tool-integration |
| description | Wiring a new tool the AI agent can call (not the recon pipeline): the tool registry, the phase map, the hardcoded dispatch chokepoint, and the duplicated execution paths that make a tool work in single mode but silently break in parallel plans. Trigger: adding or editing a tool the agent invokes; editing agentic/prompts/tool_registry.py, PhaseAwareToolExecutor in agentic/tools.py, agentic/orchestrator_helpers/nodes/execute_tool_node.py or execute_plan_node.py, TOOL_PHASE_MAP / DANGEROUS_TOOLS in agentic/project_settings.py, or a new MCP server in mcp/servers/.
|
| license | MIT |
| metadata | {"author":"redamon","version":"1.0.0","scope":["agentic"],"auto_invoke":["Adding a tool the agent can call","Editing the agent tool registry, phase map, or PhaseAwareToolExecutor dispatch","Adding or editing an MCP server the agent uses"]} |
When to Use
- Adding any tool the agent uses during a chat session (CLI wrapper, MCP tool, or API tool).
For a recon-pipeline tool (runs during a scan, writes the graph), use
recon-tool-integration instead. For the
per-setting/default multi-layer wiring, use
project-settings-cascade. For a whole
new attack skill (not a tool), use builtin-agent-skill.
Critical Rules
- NEVER
import a package not already in the agent image. agentic/ is
baked into the redamon-agent image; a missing import crash-loops the
container. Confirm it is in agentic/requirements.txt
or the Dockerfile first.
- NEVER add a tool without a
TOOL_REGISTRY entry in
agentic/prompts/tool_registry.py. The
registry is the single source of truth the LLM reads; an unregistered tool is
invisible to the agent. All four fields (purpose, when_to_use,
args_format, description) are required, and the description must clear the
100-char minimum in agentic/tests/test_tool_registry_completeness.py,
which fails on any unregistered or stub entry.
- NEVER forget the dispatch branch for a non-MCP / API tool.
PhaseAwareToolExecutor.execute() at agentic/tools.py:2070
has hardcoded if/elif dispatch. A Type D (API) tool or an MCP tool needing
key injection MUST add an elif; without it the tool is registered but never
dispatched. MCP tools with no key injection go through the else branch automatically.
- NEVER edit
execute_tool_node.py without mirroring it in execute_plan_node.py.
execute_tool_node.py
(single tool) and execute_plan_node.py
(parallel plans) duplicate long-running detection and session/listener
handlers. Update one only and the tool works interactively but silently
misbehaves in parallel plan execution.
- NEVER rely on the Prisma default to reach existing projects. The
agentToolPhaseMap default applies to NEW projects only. Existing projects
need a jsonb UPDATE or the agent never sees the tool there. See
project-settings-cascade.
- ALWAYS add the tool to
TOOL_PHASE_MAP in agentic/project_settings.py.
If it sends attack traffic: also add it to DANGEROUS_TOOLS (frozenset,
project_settings.py:22), a per-tool
section in agentic/prompts/stealth_rules.py,
and the right list in CATEGORY_TOOL_MAP (_check_roe_blocked,
execute_plan_node.py:47).
Pick the integration type (simplest that fits)
| Type | Use when | Core files beyond the registry |
|---|
| A kali_shell | tool is in Kali, 300s timeout OK, no parsing | Dockerfile + kali_shell description only (no registry entry) |
| B MCP tool on existing server | CLI tool, custom timeout/parsing, fire-and-forget | @mcp.tool() in an existing mcp/servers/*.py (auto-discovered) |
| C new MCP server | stateful/interactive, own port | new mcp/servers/*_server.py + SERVERS in run_servers.py + URL in MCPToolsManager |
| D API/HTTP tool | external API, key-gated | ToolManager class + elif dispatch in tools.py + orchestrator key hot-reload |
Naming is uniform across every layer: MCP fn / registry key / phase-map key =
execute_<tool>; Prisma field camelCase; Python setting SCREAMING_SNAKE; DB
column snake_case via @map().
Commands
docker compose build agent && docker compose up -d agent
docker compose exec webapp npx prisma db push
./agentic/run_tests.sh
Resources
