Tool Notes & Best Practices

Applies to: 4.0.8.1+

This page covers additional engineering guidance.

1) Output contract

• use next_action + execution_commands[] in new code
• keep todo_suggestion in every command
• avoid using legacy fields (for example tool_commands) as primary schema

2) Safety boundaries

• for high-risk tools (Cmd, DB writes, external side effects), enforce:
  • parameter validation
  • allowlists (command prefixes, directories, resource scopes)
• avoid raw model-generated dangerous command strings

3) Concurrency and timeout

• start conservative: max_rounds=3~5, concurrency=1~3
• configure tool.loop.timeout for slow external tools
• increase concurrency only after dependency capacity is verified

4) Observability and debugging

• enable runtime.show_tool_logs
• inspect extra.tool_logs first
• focus on per-record success/error/result

5) Testing

• add focused tests for both plan and execution handlers
• cover:
  • next_action=response short-circuit
  • record integrity under concurrency
  • error recording on failed tools

6) Migration notes

• must_call() / async_must_call() are soft-compat only; use generate_tool_command() in new code
• during migration, stabilize decision schema before replacing executor logic

7) With search -> browse flows

For search+browse loops:

1. require URL-backed evidence in planning prompt
2. treat browse output as evidence, not final answer
3. include citations in final response for auditability