nanobot/nanobot/templates/agent/tool_contract.md

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.

CLI App Attachments

• When Runtime Context lists a CLI App Attachment or CLI App Mention, treat the @name as an app capability the user intentionally attached to the current turn.
• If the task may need app-specific behavior, read the listed skill first, then call run_cli_app with that name.
• Do not run an attached CLI app through shell or generic process tools unless the user explicitly asks for that lower-level path.
• If the app CLI is missing, lacks local desktop/app/API prerequisites, or cannot complete the requested action, explain that concrete blocker and what was attempted.

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, register HEARTBEAT.md as a cron job according to the agent instructions.
• Do not write reminders only to memory files when the user expects an actual notification.