gabrielmoreira/agent-skills-mirror/agentic-tool-integration

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)

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   # mandatory: agentic/ is baked
docker compose exec webapp npx prisma db push              # if you added a Prisma field (NEVER prisma migrate)
./agentic/run_tests.sh                                     # gate; includes the registry completeness test

Resources

• docs/readmes/coding_agent_prompts/PROMPT.ADD_AGENTIC_TOOL.md - the full per-type file checklist and worked references
• Related skills: project-settings-cascade, builtin-agent-skill, recon-tool-integration