feat(tools): Add search files tool, enable read file snippet

LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Alex Mackay
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

Makefile

@@ -39,7 +39,7 @@ install: build
 	mv $(BIN) $(GOBIN)
 
 run: build
-	@./$(BUILD_FOLDER)/agent-cli run documentor --repo https://github.com/ATMackay/agent.git
+	@./$(BUILD_FOLDER)/agent-cli run documentor --repo https://github.com/ATMackay/agent
 
 test: 
 	@mkdir -p $(COVERAGE_BUILD_FOLDER)

agents/documentor/documentor.go

@@ -3,10 +3,10 @@ package documentor
 import (
 	"context"
 
+	"github.com/ATMackay/agent/tools"
 	"google.golang.org/adk/agent"
 	"google.golang.org/adk/agent/llmagent"
 	"google.golang.org/adk/model"
-	"google.golang.org/adk/tool"
 )
 
 type Documentor struct {
@@ -15,18 +15,16 @@ type Documentor struct {
 
 // NewDocumentor returns a Documentor agent.
 func NewDocumentor(ctx context.Context, cfg *Config, model model.LLM) (*Documentor, error) {
-	// Configure documentor agent tools
-	fetchRepoTreeTool, err := NewFetchRepoTreeTool(cfg)
-	if err != nil {
-		return nil, err
-	}
-
-	readRepoFileTool, err := NewReadRepoFileTool(cfg)
-	if err != nil {
-		return nil, err
-	}
-
-	writeOutputTool, err := NewWriteOutputTool(cfg)
+	// Configure documentor agent tools and dependencies.
+	deps := tools.Deps{}
+	deps.AddConfig(tools.FetchRepoTree, tools.FetchRepoTreeConfig{WorkDir: cfg.WorkDir})
+
+	functionTools, err := tools.GetTools([]tools.Kind{
+		tools.FetchRepoTree, // Fetch repository tree to understand the structure of the codebase.
+		tools.ReadFile,      // Read specific files to understand code details and extract relevant information for documentation.
+		tools.SearchRepo,    // Search the repository to find relevant code snippets or information.
+		tools.WriteFile,     // Write documentation or other output files.
+	}, &deps)
 	if err != nil {
 		return nil, err
 	}
@@ -37,12 +35,8 @@ func NewDocumentor(ctx context.Context, cfg *Config, model model.LLM) (*Document
 		Model:       model,
 		Description: "Retrieves code from a GitHub repository and writes high-quality markdown documentation.",
 		Instruction: buildInstruction(),
-		Tools: []tool.Tool{
-			fetchRepoTreeTool, // Fetch Git Repository files
-			readRepoFileTool,  // Read files tool
-			writeOutputTool,   // Write output to file tool
-		},
-		OutputKey: StateDocumentation,
+		Tools:       functionTools,
+		OutputKey:   tools.StateDocumentation,
 	})
 	if err != nil {
 		return nil, err

agents/documentor/prompt.go

@@ -10,16 +10,41 @@ Sub-path filter: {sub_path?}
 Output path: {output_path}
 Max files to read: {max_files?}
 
+Your goal is to produce high-quality maintainer documentation while minimizing token usage and avoiding unnecessary file reads.
+
 Workflow:
 1. Call fetch_repo_tree first using the repository_url, ref, and sub_path from state.
-2. Inspect the manifest and identify the most relevant files for architecture and code-level documentation.
-3. Prefer entry points, cmd/, internal/, pkg/, config, and core domain files.
-4. Skip tests, generated files, vendor, binaries, and irrelevant assets unless they are central.
-5. Do not read more than max_files files.
-6. Use resources efficiently. Reading files can be expensive so inspect them in the order that gets highest insight, you may reach the max_files limit before all files can be read.
-6. Call read_repo_file for each selected file.
-7. Write detailed maintainers' documentation in markdown.
-8. Call write_output_file with the completed markdown and output_path.
+2. Inspect the manifest and identify the most likely entry points, core packages, configuration files, and important domain files.
+3. Use search_repo before reading files whenever possible. Search for package entry points, main flows, key types, interfaces, constructors, config structures, and important symbols.
+4. Prefer targeted investigation over broad exploration.
+5. Only call read_repo_file when you have a specific reason to inspect a file.
+6. Prefer snippet reads over full-file reads whenever possible.
+7. Only read full files when the whole file is required to understand behavior.
+8. Do not repeatedly read files unless necessary.
+9. Do not read more than max_files files.
+10. After gathering enough evidence, write the documentation and call write_output_file with the completed markdown and output_path.
+
+Reading Strategy:
+- Search first, read second.
+- Use search_repo to locate relevant symbols, functions, types, config keys, and control flow before reading files.
+- Use read_repo_file with targeted line ranges or snippets whenever possible.
+- Avoid reading large files in full unless absolutely necessary.
+- Do not read files “just in case”.
+- Do not read files that are likely irrelevant to architecture or maintainer understanding.
+- If a search result is sufficient to identify relevance, only then read the necessary snippet.
+- Stop reading once you have enough information to document the system accurately.
+
+File Selection Priorities:
+- Entry points such as main packages, CLI commands, server startup, and initialization code.
+- Core domain packages and orchestration flows.
+- Important configuration, options, and dependency wiring.
+- Public interfaces, constructors, and extension points.
+- Files that define important types, state transitions, or external integrations.
+
+Avoid reading unless clearly necessary:
+- Tests, mocks, fixtures, examples, generated files, vendor, binaries, lockfiles, assets, and migration blobs.
+- Large utility files unless they are central to understanding system behavior.
+- Multiple similar files when one or two representative files are enough.
 
 Requirements:
 - Explain architecture and package responsibilities.
@@ -28,5 +53,19 @@ Requirements:
 - Mention important file paths and symbol names.
 - Do not invent behavior beyond the code retrieved.
 - If repository coverage is partial, say so explicitly.
+- If documentation is based on selected representative files rather than exhaustive review, say so explicitly.
+
+Important Constraints:
+- Always call fetch_repo_tree first.
+- Prefer search_repo before read_repo_file.
+- Prefer snippet reads before full-file reads.
+- Read the fewest files necessary to produce accurate documentation.
+- Do not exceed max_files files.
+- Avoid token overload by minimizing broad or redundant reads.
+- Write clear, concise, and accurate documentation based only on retrieved evidence.
+
+Decision Rule:
+Before each file read, ask: “What specific question am I trying to answer from this file?”
+If that question is not specific, search first instead of reading.
 `
 }

cmd/documentor.go

@@ -8,6 +8,7 @@ import (
 
 	"github.com/ATMackay/agent/agents/documentor"
 	"github.com/ATMackay/agent/model"
+	"github.com/ATMackay/agent/tools"
 	"github.com/spf13/cobra"
 	"github.com/spf13/viper"
 	agentpkg "google.golang.org/adk/agent"
@@ -101,13 +102,13 @@ func NewDocumentorCmd() *cobra.Command {
 			}
 
 			initState := map[string]any{
-				documentor.StateRepoURL:    repoURL,
-				documentor.StateRepoRef:    ref,
-				documentor.StateOutputPath: output,
-				documentor.StateMaxFiles:   maxFiles,
+				tools.StateRepoURL:    repoURL,
+				tools.StateRepoRef:    ref,
+				tools.StateOutputPath: output,
+				tools.StateMaxFiles:   maxFiles,
 			}
 			if pathPrefix != "" {
-				initState[documentor.StateSubPath] = pathPrefix
+				initState[tools.StateSubPath] = pathPrefix
 			}
 
 			resp, err := sessService.Create(ctx, &session.CreateRequest{