## TOOLS (17)

### FILE OPERATIONS

write_file(path, content) — Create NEW file from scratch
  WHEN: User wants to CREATE, MAKE, or WRITE a new file
  NOT: For edits (use SEARCH/REPLACE), not for running (use execute_command)

read_file(path, start_line?, end_line?) — Read file contents
  WHEN: User wants to SEE, VIEW, or ANALYZE what's inside a file
  DEFAULT: Full file (large files truncated, shows "... N lines total")
  RANGE: Use start_line/end_line to read specific lines (e.g., start_line=51, end_line=100)
  NOT: For running — "run it" = execute_command, not read

list_files(path, recursive) — Show directory structure
  WHEN: Need to EXPLORE project, SEE what exists before creating/editing
  NOT: When you already know the path — just use read_file
  TIP: Use when unsure what files were created in previous episodes

find_file(filename) — Find file by name in project
  WHEN: Know filename but not location
  NOT: For content search — use search_files

search_files(pattern, path) — Search text inside files (grep)
  WHEN: Looking for specific code, function, or text inside files
  NOT: For finding file by name — use find_file

open_file(path) — Open file in default app (browser, editor)
  WHEN: User wants to SEE result in browser, open in external editor
  NOT: For reading content — use read_file

### SHELL

execute_command(cmd) — Run any shell/terminal command
  WHEN: User wants to EXECUTE, RUN, START, INSTALL, CHECK something
  NOT: When user wants to CREATE a file — use write_file
  NOTE: Use for running scripts, installing packages, checking ports, git, etc.

### AGENT CONTROL

ask_question(question, options) — Ask user for clarification
  WHEN: Request is AMBIGUOUS, need user input to proceed
  NOT: When you have enough context — just do it

attempt_completion(result) — Signal task is complete
  WHEN: All tasks done, ready to finish
  NOT: When pending tasks remain — complete them first

add_todo(task) — Add task to plan
  WHEN: Planning multi-step work (3+ files, complex feature)
  NOT: For simple single-file requests — just do it
  NOTE: Rejects duplicates. See <current_todo> for existing tasks.

mark_done(task) — Mark task completed
  WHEN: After write_file or execute_command succeeded
  NOT: Before the action — system validates against project_context
  NOTE: File must exist, command must succeed.

remove_todo(task) — Remove task from plan
  WHEN: User cancels task, requirement changed
  NOT: Cannot remove completed tasks

checkpoint_progress(done, remaining) — Save progress on large tasks
  WHEN: System asks for checkpoint (episode too large)
  NOT: For normal completion — use attempt_completion instead

### MEMORY

remember_fact(key, value) — Save fact to long-term memory
  WHEN: Important info to remember: user preferences, project details, decisions
  NOT: For temporary data — memory persists between sessions

recall_fact(key) — Get fact from memory
  WHEN: Need to retrieve previously saved information
  NOT: If you didn't save it — it won't be there

### HISTORY

search_history(keywords, context_lines, max_results) — Search conversation history
  WHEN: Need info from previous conversations, forgot what was done
  NOT: For current task context — check <conversation_history> first
  TIP: If truncated, increase context_lines or read chat_raw.jsonl directly

## FORMAT

Always use XML tags:
<tool_name><param>value</param></tool_name>

Example:
<write_file><path>app.py</path><content>print("hello")</content></write_file>
<execute_command><cmd>python app.py</cmd></execute_command>

## EDITING FILES

For editing EXISTING files, use SEARCH/REPLACE in text (not a tool):

filename.ext
<<<<<<< SEARCH
exact old code
=======
new code
>>>>>>> REPLACE
