Built-in Tools
Relevant source files
The following files were used as context for generating this wiki page:
M31 Autonomous (M31A) utilizes a suite of 18 built-in tools to interact with the filesystem, execute shell commands, and perform external research. These tools are the primary mechanism through which the AI agent implements code changes, verifies work, and gathers context during the Execute Phase.
The tool system is governed by a central dispatcher that manages permissions, rate limiting, and concurrency. Tools are designed to be deterministic and require a "read-before-write" mental model, ensuring the agent understands the codebase before making modifications.
Sources: README.md:120-130, internal/engine/workflow/prompts/tool-use.md:144-148, CONTRIBUTING.md:46-48
Tool Architecture and Dispatching
Tools in M31A are implemented as discrete Go modules within the internal/tools/ directory and registered via a DefaultDispatcher. The execution flow involves a topological sort of tasks (Kahn's algorithm) followed by parallel tool execution with bounded concurrency.
The diagram shows the lifecycle of a tool call from detection in the LLM's response to the final filesystem state and git commit.
Sources: internal/engine/workflow/execute.go:271-330, README.md:140-150
Permission and Safety Layers
Every tool execution is subject to a multi-layered security model to prevent unauthorized or destructive actions:
- Permission Modal: Gated by user choices (Allow/Always/Deny).
- Rate Limiting: Token-bucket implementation with different rates for standard (10 sustained) vs. dangerous (2 sustained) tools.
- Concurrency Control: Maximum of 8 concurrent tool executions via semaphore.
- SSRF Protection:
WebFetchblocks private and loopback IP addresses.
Sources: README.md:250-270, scripts/validate-release.sh:372-390
Core Tool Categories
The 18 tools are categorized by their function: Filesystem Operations, Search & Analysis, Shell Execution, and Utility.
Filesystem Operations
These tools are the primary means of modifying the project. M31A enforces a strict rule to prefer Edit over FileWrite for modifications to preserve existing file structure.
| Tool | Purpose | Key Constraint |
|---|---|---|
| FileRead | Read file contents (max 5MB). | Must read target and all imports before writing. |
| FileWrite | Create new files or full rewrites. | Atomic writes via temp files and rename. |
| Edit | Targeted string or line-range replacement. | Preferred for changes < 80% of file size. |
| FileDelete | Safely remove files. | Automatic backup before removal. |
| FileMove | Rename or move files. | Creates parent directories automatically. |
| FileList | List directory contents with metadata. | Returns sizes and types. |
| Sources: internal/engine/workflow/prompts/tool-use.md:8-90, scripts/validate-release.sh:267-285 |
Search and Intelligence
Tools designed to help the agent discover patterns and navigate large codebases.
- Glob: Finds files by pattern using
**recursive matching. - Grep: Regular expression search across file contents with a pure Go fallback if
ripgrepis missing. - CodeMap: Generates a map of project symbols and relationships.
- CodeComplexity: Classifies codebase complexity (Simple/Moderate/Complex) to inform model selection.
Sources: internal/engine/workflow/prompts/tool-use.md:92-109, README.md:126-128
Execution and External Research
- Bash: Runs shell commands for building, testing, and git operations. Restricted by a 30-minute timeout and 50,000 character output limit.
- WebFetch: Fetches documentation or API references from URLs (text/markdown only).
- WebSearch: Performs external searches via search engines (requires configuration).
Sources: internal/engine/workflow/prompts/tool-use.md:3-6, internal/engine/workflow/prompts/tool-use.md:111-115
Session and State Management
Tools used to track progress and interact with the user during the workflow.
- TodoWrite / TodoRead: Manages a structured TODO list (
pending,in_progress,completed). - AskUserQuestion: Pauses execution to clarify requirements (interactive sessions only).
- DevServer / HTTPCheck: Manages development server lifecycles and performs smoke tests.
Sources: internal/engine/workflow/prompts/tool-use.md:117-133, README.md:130-132
Execution Logic and Loop Detection
During the Execute phase, the engine tracks tool calls to detect infinite loops or redundant operations. If a tool call repeats within a configured window (default 3), a ExecuteLoopDetectMsg is emitted.
The sequence diagram illustrates the internal check performed before tool dispatch to prevent runaway agent behavior.
Sources: internal/engine/workflow/execute.go:275-300, README.md:131-133
Summary of Usage Rules
The effectiveness of these tools relies on the Read-Before-Write Rule:
- Analyze: Use
Glob,Grep, andFileReadto build a mental model. - Context: Read the target file AND its imports, types, and callers.
- Action: Use
EditorFileWrite. - Verification: Always follow with
Bashto run tests or build commands.
Sources: internal/engine/workflow/prompts/autonomous.md:18-35, internal/engine/workflow/prompts/tool-use.md:144-150
M31A's toolset provides a high-fidelity interface for the agent to act as a software architect, ensuring that every modification is grounded in the existing codebase context.