| 1 | # Agent Tools DOX |
| 2 | |
| 3 | ## Purpose |
| 4 | |
| 5 | - Own core agent tool implementations available to Agent Zero agents. |
| 6 | - Keep tool execution contracts, progress logging, intervention handling, and tool-result formatting stable. |
| 7 | |
| 8 | ## Ownership |
| 9 | |
| 10 | - Tool modules in this directory are discovered by the framework and should define `Tool` subclasses. |
| 11 | - Shared tool base classes and response contracts live in `helpers/tool.py`. |
| 12 | - Plugin-specific tools belong in plugin `tools/` directories. |
| 13 | |
| 14 | ## Local Contracts |
| 15 | |
| 16 | - Tools must derive from `helpers.tool.Tool` and implement `async def execute(...)`. |
| 17 | - Return `helpers.tool.Response(message=..., break_loop=...)`. |
| 18 | - Use `await self.agent.handle_intervention(...)` when a long-running or external result should respect pause/intervention flow. |
| 19 | - Sanitize or mask secrets before logging, returning, or storing tool outputs. |
| 20 | - Do not perform destructive filesystem or network actions without the tool contract making that behavior explicit. |
| 21 | - This directory is a file-documented DOX profile: every direct `*.py` tool module must have a same-directory `*.py.dox.md` file named by appending `.dox.md` to the full Python filename. |
| 22 | - The `*.py.dox.md` file owns tool purpose, tool arguments/concepts, output and `break_loop` behavior, side effects, important helper dependencies, prompt-contract notes, and verification guidance. |
| 23 | - When a tool module is added, removed, renamed, or behaviorally changed, update its matching `*.py.dox.md` in the same change. |
| 24 | - Do not leave stale file-level DOX after tool deletion or rename. |
| 25 | |
| 26 | ## Work Guidance |
| 27 | |
| 28 | - Keep tool output concise enough for message history while preserving actionable detail. |
| 29 | - Put reusable parsing, provider, filesystem, or network logic in `helpers/`. |
| 30 | - Update prompt tool instructions when changing tool names, arguments, or behavior. |
| 31 | - During the DOX pass, verify that every direct `*.py` file has a matching `*.py.dox.md` and that changed tool behavior is described there. |
| 32 | |
| 33 | ## Verification |
| 34 | |
| 35 | - Run targeted tool tests after changing a tool or its prompt contract. |
| 36 | - Run prompt/snapshot tests when tool instructions or output shape changes. |
| 37 | - Check file-level documentation coverage with a script or shell loop that verifies each `tools/*.py` has a matching `tools/*.py.dox.md`. |
| 38 | |
| 39 | ## Child DOX Index |
| 40 | |
| 41 | No child DOX files. |