mirror of
https://github.com/HKUDS/nanobot.git
synced 2026-05-21 17:12:32 +00:00
61 lines
4.0 KiB
Markdown
61 lines
4.0 KiB
Markdown
# Tool Usage Notes
|
|
|
|
Tool signatures are provided automatically via function calling. This section
|
|
documents the general tool contract and non-obvious usage patterns.
|
|
|
|
## General Tool Contract
|
|
|
|
- Use the narrowest structured tool that directly matches the task.
|
|
- Use read-only discovery before writes when state is uncertain.
|
|
- Do not use `exec` as a universal workaround for files, search, web, messages, or schedules.
|
|
- If a tool fails, read the error, refresh the relevant state, and retry with a different approach instead of repeating the same call.
|
|
- After meaningful changes, verify with the smallest reliable check: re-read changed state, run targeted tests, or inspect command output.
|
|
- Respect safety and workspace-boundary errors as real limits, not obstacles to bypass.
|
|
|
|
## Discovery and Reading
|
|
|
|
- Use `find_files` or `list_dir` to locate workspace paths before `read_file` when a path is uncertain.
|
|
- Use `grep` for content search inside the workspace; prefer it over shell grep for ordinary searches.
|
|
- `grep` defaults to `output_mode="files_with_matches"`; use `output_mode="content"` for matching lines with context.
|
|
- Use `fixed_strings=true` for literal keywords containing regex characters.
|
|
- Use `output_mode="count"` to size a broad search before reading full matches.
|
|
- Use `head_limit` and `offset` to page across large result sets.
|
|
- Binary or oversized files may be skipped to keep results readable.
|
|
|
|
## File and Coding Workflows
|
|
|
|
- For code or config changes, the default loop is: locate (`find_files`/`grep`), inspect (`read_file`), edit (`apply_patch`), then verify (`exec` or re-read).
|
|
- Use `apply_patch` as the default code editing tool, especially for multi-file changes, structural edits, generated code, moves, adds, or deletes.
|
|
- Use `apply_patch dry_run=true` when the patch is uncertain and you want validation plus a change summary before writing.
|
|
- Use `edit_file` only for small exact replacements in one file, with `old_text` copied from `read_file`; add `occurrence`, `line_hint`, or `expected_replacements` when ambiguity matters.
|
|
- Use `write_file` for new files or intentional full-file rewrites, not routine partial edits.
|
|
- If `apply_patch` or `edit_file` fails, re-read with `force=true`, narrow the context, and try a smaller patch rather than switching to shell `sed` or `echo`.
|
|
|
|
## Process Execution
|
|
|
|
- Use `exec` for tests, builds, package commands, git commands, and other process execution.
|
|
- Prefer dedicated file/search tools over `cat`, shell `find`, shell `grep`, `sed`, or `echo` for ordinary workspace inspection and edits.
|
|
- Use non-interactive flags such as `-y` or `--yes` when available.
|
|
- Commands have a configurable timeout (default 60s), dangerous commands are blocked, and output is truncated.
|
|
- For long-running or interactive commands, pass `yield_time_ms`; if the process keeps running, continue with `write_stdin`.
|
|
- Use `write_stdin` to poll, provide stdin, close stdin, wait for expected output with `wait_for`, or terminate an existing exec session.
|
|
- Use `list_exec_sessions` to recover active session IDs after context shifts.
|
|
|
|
## Web and External Information
|
|
|
|
- Use web tools when the user asks for current information, a specific URL, or information likely to have changed.
|
|
- Use `web_search` to find sources and `web_fetch` for a specific page or result that needs closer reading.
|
|
- Do not invent freshness-sensitive facts when tools can verify them.
|
|
|
|
## Messaging and Media
|
|
|
|
- Use `message` to send content or local media to the user/channel.
|
|
- `read_file` only reads content for your analysis; it does not deliver a file to the user.
|
|
- When sending an existing local file, attach it through the message/media mechanism instead of pasting file contents unless the user asked for text.
|
|
|
|
## Scheduling and Background Work
|
|
|
|
- Use `cron` for scheduled reminders or recurring jobs; do not run `nanobot cron` through `exec`.
|
|
- For heartbeat tasks, update `HEARTBEAT.md` according to the agent instructions.
|
|
- Do not write reminders only to memory files when the user expects an actual notification.
|