debugging-tool-loops
Loads when a session shows many tool calls (often the same name repeated) with no terminal text, no `complete` call, and either hits `stopWhen: stepCountIs(...)` (default 10) OR exhausts max output tokens. The LLM is in a tool loop without producing a final message. Distinguish from `debugging-empty-output` — that's about contract exits being absent; this is about the LLM never deciding to stop. Required: the agent prompt needs an explicit termination criterion.
Profile →npx skills add friday-platform/friday-studio --skill debugging-tool-loops --agent claude-code
Same command for any agent — swap --agent for codex, cursor, copilot.
Weekly change comes from our own snapshots, not the repository page — it measures attention, not adoption.
# Debugging tool loops Symptom: agent makes 8+ tool calls (often repeating searches with slight variations), eventually hits `stepCountIs(10)` cap or runs out of output tokens, ends with `output: {response: ""}` or empty `complete` args. ## Diagnostic checklist ### 1. Confirm the loop signature ``` describe_session(sessionId) → session.agentBlocks[].toolCalls ``` Look for: - 6+ tool calls in a single agent block. - Repeated calls to similar tools (`search_issues` × 3, `search_pull_requests` × 3, then more search variations). - No `complete` or `failStep` toolName in the list. - Final assistant text is empty. If the agent IS calling `complete` but with empty args, that's `@friday/debugging-empty-output` step 2, not this skill. ### 2. Check the agent prompt's termination criterion A loop usually means the agent doesn't know when to stop searching. Look for prompts like: ``` "Search for all stale issues across all repos." ``` The LLM keeps searching because "all" is open-ended. Add an explicit stop condition: ``` "Search exactly these 6 queries (3 issue queries × 3 PR queries). After all 6 return, stop and call `complete` with the report. Do not search again." ``` ### 3. Check whether
- Diagnostic checklist
- 1. Confirm the loop signature
- 2. Check the agent prompt's termination criterion
- 3. Check whether the agent has the right terminal tool
- 4. Bump maxsteps only as a last resort
- What NOT to do
- Cross-references
What does the debugging-tool-loops skill do?
Loads when a session shows many tool calls (often the same name repeated) with no terminal text, no `complete` call, and either hits `stopWhen: stepCountIs(...)` (default 10) OR exhausts max output tokens. The LLM is in a tool loop without producing a final message. Distinguish from `debugging-empty-output` — that's about contract exits being absent; this is about the LLM never deciding to stop. Required: the agent prompt needs an explicit termination criterion.
How do I install it?
Run `npx skills add friday-platform/friday-studio --skill debugging-tool-loops --agent claude-code` — it drops the skill into your project so the agent can pick it up. Swap the --agent value for codex, cursor or copilot if you use one of those.
Where does this skill come from?
From friday-platform/friday-studio, a repository with 98 stars. We read it straight from the repository tree rather than a submitted listing, so what you see here is what is actually published.
Is a popular skill a good skill?
Not necessarily. Stars measure attention, not adoption — a repository can trend for a week and be abandoned. That is why we show the weekly change from our own snapshots next to the total, instead of a single flattering number.