# Max Tool-Calling Iteration Limit: Recovery Guide ## What Happens When an agent repeatedly polls an empty directory in a cron job, it may hit the **maximum number of tool-calling iterations allowed**. The session is then forcibly terminated with a message like: ``` You've reached the maximum number of tool-calling iterations allowed. Please provide a final response summarizing what you've found and accomplished so far. ``` This is a hard stop. The agent cannot continue checking and must produce a final summary. ## Why It Happens The agent falls into an infinite polling loop, checking the same empty directory over and over. Each `terminal` call to `ls` or `find` counts as one tool iteration. Even though the directory is empty, the agent keeps checking, hoping a command file will appear. This is a variant of the polling anti-pattern documented in `references/cron-polling-anti-patterns.md`. ## Real-World Example ``` # Session log excerpt: > su -c "ls -la /sdcard/VisualAgent/commands/" → "total 0" > su -c "ls -la /sdcard/VisualAgent/commands/" → "total 0" > su -c "ls -la /sdcard/VisualAgent/commands/" → "total 0" # ... 100+ identical checks later ... > You've reached the maximum number of tool-calling iterations allowed. ``` ## Recovery: When You Hit the Limit 1. **Stop immediately** — Do not try to make any more tool calls. The system has forced a final response. 2. **Summarize what you found** — Report the directory state, any commands processed, and any results written. 3. **If nothing was done, respond `[SILENT]`** — If the directory was empty and no commands were processed, the correct response is `[SILENT]` (nothing to report). 4. **Do NOT apologize for the loop** — The user configured the cron job; hitting the limit is a system safeguard, not a user-facing error. Just report the state. ## Prevention: How to Avoid Hitting the Limit ### Single Check Pattern ```bash # ONE check, then decide FILES=$(su -c "find /sdcard/VisualAgent/commands/ -name '*.json' -type f 2>/dev/null") if [ -z "$FILES" ]; then echo "[SILENT]" exit 0 fi # Process all found files for f in $FILES; do # ... execute ... done ``` ### Never Loop Without Progress If you must poll (e.g., waiting for a command to complete), ensure each iteration makes progress: - Check a different condition each time - Have a maximum retry count - Include a timeout ```bash MAX_RETRIES=3 for i in $(seq 1 $MAX_RETRIES); do RESULT=$(su -c "cat /sdcard/VisualAgent/results/expected_result.json 2>/dev/null") if [ -n "$RESULT" ]; then break fi sleep 1 done ``` ### Use `find` Instead of `ls` `find` with a file pattern tells you everything you need in one call: ```bash # Lists all .json files, or empty if none su -c "find /sdcard/VisualAgent/commands/ -name '*.json' -type f" ``` No need to `ls` the directory and then `find` the files separately. ## Summary | Scenario | Action | |----------|--------| | Directory empty after first check | Respond `[SILENT]`, stop | | Hit iteration limit | Produce final summary, no more tools | | Need to wait for file | Use `find` with max retries, not infinite `ls` | | Multiple files to process | List all with `find`, process in batch |