@skill-graph/cli 0.5.6

package/marketplace/skills/tool-call-flow/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: tool-call-flow
+description: "Use when reasoning about the protocol-level cycle by which a language model uses external tools: the four phases (declaration, request, execution, continuation), the message-history state model that ties them together, the structural differences between vendor protocols (Anthropic tool-use, OpenAI function-calling, MCP) and how they compose, parallel vs sequential tool calls, error handling and retries inside the cycle, and the separation between the model (which produces structured intent) and the runtime (which executes the intent and routes results back). Do NOT use for the decision of when and how many tool calls to make (use tool-call-strategy), agent-system architecture and coordination patterns (use agent-engineering), prompt wording (use prompt-craft), or the design of evals for tool-use behavior (use agent-eval-design)."
+license: MIT
+allowed-tools: Read Grep
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"agent\",\"domain\":\"agent/protocol\",\"scope\":\"reference\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-15\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-15\\\\\\\"}\",\"eval_artifacts\":\"planned\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"comprehension_state\":\"present\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"tool call\\\\\\\",\\\\\\\"tool use\\\\\\\",\\\\\\\"function calling\\\\\\\",\\\\\\\"MCP\\\\\\\",\\\\\\\"Model Context Protocol\\\\\\\",\\\\\\\"tool result\\\\\\\",\\\\\\\"parallel tool calls\\\\\\\",\\\\\\\"tool schema\\\\\\\",\\\\\\\"JSON Schema\\\\\\\",\\\\\\\"assistant turn\\\\\\\",\\\\\\\"tool runtime\\\\\\\",\\\\\\\"tool router\\\\\\\",\\\\\\\"tool definitions\\\\\\\",\\\\\\\"agent calling tools\\\\\\\"]\",\"triggers\":\"[\\\\\\\"how does tool calling actually work\\\\\\\",\\\\\\\"what's the message shape for a tool result\\\\\\\",\\\\\\\"MCP vs function calling vs Anthropic tools\\\\\\\",\\\\\\\"can the model call tools in parallel\\\\\\\",\\\\\\\"where do tool errors live in the message history\\\\\\\"]\",\"examples\":\"[\\\\\\\"design the message-shape contract between a model and a tool runtime\\\\\\\",\\\\\\\"explain why a tool result must be appended to the message history before the next assistant turn\\\\\\\",\\\\\\\"decide whether to expose a capability as a tool, an MCP server, or an inline API\\\\\\\",\\\\\\\"diagnose why a model keeps re-calling the same tool with the same arguments\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"decide whether to call a tool or write a script (use tool-call-strategy)\\\\\\\",\\\\\\\"choose a multi-agent coordination pattern (use agent-engineering)\\\\\\\",\\\\\\\"design an eval suite that tests tool-call correctness (use agent-eval-design)\\\\\\\"]\",\"relations\":\"{\\\\\\\"related\\\\\\\":[\\\\\\\"tool-call-strategy\\\\\\\",\\\\\\\"agent-engineering\\\\\\\",\\\\\\\"api-design\\\\\\\",\\\\\\\"type-safety\\\\\\\",\\\\\\\"client-server-boundary\\\\\\\"],\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"tool-call-strategy\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"tool-call-strategy owns the decision of when, how many, and which tools to call (token cost, redundancy, parallelization, decision gate). tool-call-flow owns the protocol-level cycle that makes any call possible. The two compose: strategy decides what to do; flow describes the mechanism that carries it out.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"agent-engineering\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"agent-engineering owns multi-agent and multi-step system architecture (orchestrator/worker, consensus, sequential chains). tool-call-flow is one cycle inside a single agent — the protocol for a single model-to-runtime interaction.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"api-design\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"api-design owns the external API surface that tools may wrap. tool-call-flow owns the model-facing contract: how the tool is declared to the model, how the result is encoded back to it, and how the cycle is structured.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"client-server-boundary\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"client-server-boundary owns the serialization frontier between server and client code. tool-call-flow is an analogous frontier between a language model (which produces structured intent) and a runtime (which executes the intent) — the trust direction is different but the discipline of explicit serialization is identical.\\\\\\\"}],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"tool-call-strategy\\\\\\\",\\\\\\\"agent-eval-design\\\\\\\"]}\",\"mental_model\":\"|\",\"purpose\":\"|\",\"boundary\":\"|\",\"analogy\":\"A tool-call flow is to a language model what a procurement system is to an executive — the executive does not personally drive to the supplier; they sign a typed purchase order, the procurement department validates the order, executes it, and returns the receipt with whatever was delivered or with a documented reason it could not be. The executive's signature is intent; the department's stamp is authorization; the receipt is the only state of the cycle that survives, and the next decision is made against that record.\",\"misconception\":\"|\",\"concept\":\"{\\\\\\\"definition\\\\\\\":\\\\\\\"A tool-call flow is the multi-turn protocol by which a language model uses external capabilities. It has four phases — declaration (the runtime tells the model which tools exist and their parameter schemas), request (the model emits a structured tool-call message specifying tool name and arguments), execution (the runtime invokes the underlying capability and produces a result), continuation (the runtime appends the result to the message history and re-prompts the model, which either continues with another tool call or produces a final answer). The state of the cycle lives in the message history; the model is stateless across calls.\\\\\\\",\\\\\\\"mental_model\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"purpose\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"boundary\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"taxonomy\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"analogy\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"misconception\\\\\\\":\\\\\\\"|\\\\\\\"}\",\"skill_graph_source_repo\":\"https://github.com/jacob-balslev/skill-graph\",\"skill_graph_protocol\":\"Skill Metadata Protocol v5\",\"skill_graph_project\":\"Skill Graph\",\"skill_graph_canonical_skill\":\"skills/tool-call-flow/SKILL.md\"}"
+  skill_graph_source_repo: "https://github.com/jacob-balslev/skill-graph"
+  skill_graph_protocol: Skill Metadata Protocol v4
+  skill_graph_project: Skill Graph
+  skill_graph_canonical_skill: skills/tool-call-flow/SKILL.md
+---
+
+# Tool-Call Flow
+
+## Coverage
+
+The protocol-level cycle by which a language model uses external capabilities. Covers the four phases (declaration, request, execution, continuation), the message-history state model that ties them together, the structural differences between vendor protocols (Anthropic tool-use, OpenAI function-calling, Model Context Protocol, Gemini function calling), parallel tool calls, streaming tool calls, the runtime's role as orchestrator, error encoding inside the cycle, and the boundary between model-side intent and runtime-side execution.
+
+## Philosophy
+
+A tool-call flow is the smallest unit of agentic capability. Strip away orchestration patterns, multi-agent coordination, evaluation harnesses — what remains is a single language model alternating turns with a runtime that executes capabilities on its behalf. Understanding this cycle precisely is the foundation for understanding everything that builds on it.
+
+The cycle's defining property is the separation of planning from execution. The model produces structured intent; the runtime carries it out. This separation is not a workaround for current model capabilities; it is a deliberate design choice that makes the system auditable, composable, and recoverable. A system that fuses the two — by letting the model execute code directly, or by letting the runtime make decisions — gains expressiveness and loses every benefit the separation provides.
+
+The four-phase structure is identical across every current vendor protocol. The names differ, the message shapes differ, the encoding of parallelism differs, but the cycle — declare, request, execute, continue — is the same. A practitioner who understands the cycle can move between Anthropic, OpenAI, MCP, and Gemini at the cost of a translation layer; a practitioner who understands only one vendor's encoding cannot.
+
+## The Four Phases
+
+| Phase | Who acts | Output | Becomes |
+|---|---|---|---|
+| 1. Declaration | Runtime | List of tools with name, description, JSON-Schema parameter spec | Part of the request to the model |
+| 2. Request | Model | Assistant message with one or more tool-call blocks (or a final-answer message — ending the cycle) | Appended to message history |
+| 3. Execution | Runtime | Result of invoking the named tool with the supplied arguments | A tool-result message |
+| 4. Continuation | Runtime | Tool-result message paired with the request by ID | Appended to message history; cycle repeats |
+
+The cycle ends when the model emits an assistant message *without* any tool-call blocks. The final message's content is the final answer.
+
+## Vendor Protocol Comparison
+
+The cycle is the same; the encoding differs. The table below shows the same single-call cycle in three protocols.
+
+### Anthropic tool-use (Messages API)
+
+```jsonc
+// Request to model (turn 1)
+{
+  "model": "claude-opus-4-7",
+  "tools": [{
+    "name": "get_weather",
+    "description": "Returns current weather for a city.",
+    "input_schema": {
+      "type": "object",
+      "properties": { "location": { "type": "string" } },
+      "required": ["location"]
+    }
+  }],
+  "messages": [
+    { "role": "user", "content": "What's the weather in Paris?" }
+  ]
+}
+
+// Model response (turn 1 → 2)
+{
+  "role": "assistant",
+  "content": [
+    { "type": "text", "text": "I'll check the current weather." },
+    { "type": "tool_use", "id": "toolu_01A", "name": "get_weather",
+      "input": { "location": "Paris" } }
+  ]
+}
+
+// Runtime executes get_weather("Paris") → { "temp_c": 18, "conditions": "cloudy" }
+
+// Request to model (turn 2, includes appended tool result)
+{
+  "messages": [
+    { "role": "user", "content": "What's the weather in Paris?" },
+    { "role": "assistant", "content": [...] },  // turn 1 above
+    { "role": "user", "content": [
+        { "type": "tool_result", "tool_use_id": "toolu_01A",
+          "content": "{\"temp_c\":18,\"conditions\":\"cloudy\"}" }
+    ]}
+  ]
+}
+
+// Model response (final)
+{ "role": "assistant", "content": [
+  { "type": "text", "text": "It's 18°C and cloudy in Paris." }
+]}
+```
+
+### OpenAI function-calling (Chat Completions)
+
+```jsonc
+// Same flow with different encoding:
+// - Tool calls live in `tool_calls` adjacent to `content`, not inside `content`.
+// - Tool results live in messages with `role: "tool"` (not inside a user-role message).
+// - IDs pair via `tool_call_id`.
+{
+  "role": "assistant",
+  "content": null,
+  "tool_calls": [{
+    "id": "call_abc", "type": "function",
+    "function": { "name": "get_weather",
+                   "arguments": "{\"location\":\"Paris\"}" }
+  }]
+}
+{
+  "role": "tool",
+  "tool_call_id": "call_abc",
+  "content": "{\"temp_c\":18,\"conditions\":\"cloudy\"}"
+}
+```
+
+### Model Context Protocol (MCP)
+
+```jsonc
+// MCP externalizes the declaration phase. Tools live on an MCP server.
+// The model client discovers them at runtime via the MCP transport
+// (typically JSON-RPC over stdio or SSE), then inlines them into the
+// per-call request to the underlying model API (Anthropic, OpenAI, etc.).
+
+// 1. Client → MCP server: tools/list
+// 2. MCP server → client: list of tool declarations
+// 3. Client embeds those declarations in the model request (in whatever
+//    vendor's encoding the underlying model uses)
+// 4. Model emits a tool-call message
+// 5. Client → MCP server: tools/call { name, arguments }
+// 6. MCP server → client: result
+// 7. Client appends the result and re-prompts the model
+```
+
+MCP's contribution is dynamic discovery and provider neutrality at the catalog level, not a different cycle shape.
+
+## Parallel Tool Calls
+
+Modern protocols allow the model to emit multiple tool-call blocks in a single assistant message. The runtime executes them concurrently and appends all results to the history before re-prompting.
+
+```jsonc
+// Anthropic — single assistant message with two tool_use blocks
+{
+  "role": "assistant",
+  "content": [
+    { "type": "tool_use", "id": "toolu_01A", "name": "get_weather",
+      "input": { "location": "Paris" } },
+    { "type": "tool_use", "id": "toolu_01B", "name": "get_weather",
+      "input": { "location": "Tokyo" } }
+  ]
+}
+// Runtime executes both concurrently
+// Next user-role message contains both tool_result blocks
+```
+
+Parallel calls reduce wall-clock latency for independent operations but add coordination complexity for dependent ones: the model cannot use the result of one parallel call to inform another in the same turn (they all execute against the same pre-result state). Dependent calls must be sequential.
+
+## Streaming Tool Calls
+
+Streaming protocols emit the assistant message token-by-token. A complete tool-call block can be reconstructed before the full message finishes streaming, allowing the runtime to begin execution speculatively:
+
+1. Streamed tokens form a complete tool_use block.
+2. Runtime parses the complete block and begins executing the tool.
+3. Streaming continues; if a second tool-call block arrives, it also begins executing.
+4. When the streamed message completes, the runtime has the full set of calls; some are already done.
+
+Streaming is an optimization, not a different cycle. The correctness contract is the same: results must be appended in their assigned positions; the model sees the same history regardless of timing.
+
+## Failure Encoding
+
+All failures are tool-result messages — never out-of-band exceptions that break the cycle.
+
+| Failure | Encoding |
+|---|---|
+| Schema validation failed | Result with error: "arguments did not match schema: missing required field 'location'" |
+| Tool execution threw | Result with error: "OpenWeatherMap returned 503 Service Unavailable" |
+| Timeout | Result with error: "tool execution exceeded 10s timeout" |
+| Permission denied | Result with error: "this tool requires admin permission" |
+| Unknown tool | Result with error: "no tool named 'get_wether' (did you mean 'get_weather'?)" |
+
+The model sees the error in its next turn and can choose: retry with corrected arguments, try a different tool, abandon the goal, or surface the failure to the user with context. The runtime's job is to encode the failure faithfully; the model's job is to handle it.
+
+## The Runtime's Responsibilities
+
+The runtime is the orchestrator. Specifically, it owns:
+
+- **Tool catalog management** — declare which tools exist and their schemas (or, with MCP, discover them).
+- **Schema validation** — verify the model's tool-call arguments match the declared schema before invocation.
+- **Dispatch** — route the validated call to the underlying implementation (local, network, MCP, subagent, human).
+- **Execution policy** — timeouts, retries, rate limits, parallelism limits, side-effect gating.
+- **Result encoding** — format the execution output as a tool-result message paired by ID.
+- **Loop control** — re-prompt the model; cap the maximum number of turns; detect runaway loops.
+- **Audit and persistence** — store the message history; make runs replayable.
+
+The model owns only the planning: which tool, which arguments, when to stop.
+
+## Verification
+
+After applying this skill, verify:
+- [ ] Every tool declaration has a precise description naming when the tool should be used and what the arguments mean (the description is a prompt, not documentation).
+- [ ] Every tool has a JSON Schema for its parameters with `required` fields and constrained types — the model's arguments are validated against this schema before execution.
+- [ ] Tool-call and tool-result messages are paired by ID — the pairing is checked, not assumed.
+- [ ] Errors are encoded into tool-result messages with diagnostic content the model can read — they do not break the loop.
+- [ ] The cycle has a maximum-turns cap on the runtime side — a model that keeps tool-calling never exits without intervention.
+- [ ] Side-effecting tools have explicit gating (confirmation, dry-run mode, allow-list) — the model does not enforce side-effect discipline.
+- [ ] Parallel tool calls are used only for independent operations — dependent calls remain sequential.
+- [ ] The message history is the only state — no hidden runtime memory the model cannot see.
+- [ ] Logs include the full message history (or a structured trace) per cycle — runs are replayable.
+
+## Do NOT Use When
+
+| Instead of this skill | Use | Why |
+|---|---|---|
+| Deciding when to call a tool versus when to write a script | `tool-call-strategy` | tool-call-strategy owns the decision; tool-call-flow owns the mechanism that carries the decision out |
+| Choosing a multi-agent coordination pattern | `agent-engineering` | agent-engineering owns system-level architecture; tool-call-flow is one cycle inside one agent |
+| Writing the natural-language description that goes into a tool declaration | `prompt-craft` | prompt-craft owns wording; this skill owns the shape of what wording goes where |
+| Designing the JSON shape of an external API a tool wraps | `api-design` | api-design owns the external surface; tool-call-flow owns the model-facing contract |
+| Designing evals for tool-use correctness | `agent-eval-design` | agent-eval-design owns eval structure; tool-call-flow describes what is being evaluated |
+| Debugging a tool that returns wrong results in production | `debugging` | debugging owns the diagnostic activity |
+
+## Key Sources
+
+- Anthropic. [Tool use overview](https://docs.anthropic.com/en/docs/build-with-claude/tool-use). Canonical reference for the Anthropic Messages API tool-use protocol — the tool_use / tool_result block structure, ID pairing, parallel calls.
+- OpenAI. [Function calling guide](https://platform.openai.com/docs/guides/function-calling). Canonical reference for the OpenAI Chat Completions and Responses APIs' function-calling protocol — tool_calls / tool messages, tool_call_id pairing.
+- Anthropic. [Model Context Protocol specification](https://modelcontextprotocol.io/specification). The open specification for MCP — transport, tool discovery, the tools/list and tools/call methods.
+- JSON Schema. [Draft 2020-12 specification](https://json-schema.org/draft/2020-12/json-schema-core). The schema language used for parameter declarations across all vendor protocols.
+- Google. [Gemini function calling documentation](https://ai.google.dev/gemini-api/docs/function-calling). The function_call / function_response message-part structure — same four-phase cycle, third encoding.
+- Yao, S., Zhao, J., Yu, D., Du, N., Shafran, I., Narasimhan, K., & Cao, Y. (2022). ["ReAct: Synergizing Reasoning and Acting in Language Models"](https://arxiv.org/abs/2210.03629). The Thought-Action-Observation loop that prefigured the structured tool-call protocols.
+- Schick, T., Dwivedi-Yu, J., Dessì, R., Raileanu, R., Lomeli, M., Zettlemoyer, L., Cancedda, N., & Scialom, T. (2023). ["Toolformer: Language Models Can Teach Themselves to Use Tools"](https://arxiv.org/abs/2302.04761). Meta's foundational paper on training models to invoke tools — the research thread that motivates the protocol design choices.
+- LangChain. [Tool calling concepts](https://python.langchain.com/docs/concepts/tool_calling/). Framework-agnostic description of the cycle structure, useful as a third-party reference outside any single vendor.

package/marketplace/skills/tool-call-strategy/SKILL.md

@@ -0,0 +1,292 @@
+---
+name: tool-call-strategy
+description: "Use when an agent is making too many tool calls, when context is filling from verbose tool outputs, when the same operation could be a script instead of N individual calls, or when designing a tool-use protocol for a new agent or harness. Covers the three costs of every call (token, latency, context pollution), the script-vs-call decision gate, tool-selection decision trees (file-search vs content-search vs targeted-read vs full-read), call batching and parallelization, redundancy avoidance, the poka-yoke principle, subagent delegation for context protection, and cost-benchmark heuristics by task type. Do NOT use for prompt wording (use `prompt-craft`), broader context stack design across the five layers (use `context-engineering`), runtime tool failures or production debugging (use `debugging`), or behaviour-preserving refactor mechanics (use `refactor`)."
+license: MIT
+compatibility: "Provider-agnostic; abstract tool capabilities map to concrete tools across Claude Code, Cursor, Copilot, OpenCode, Aider, Continue. Specific tool names in this skill (read_file, grep_search, run_in_terminal, apply_patch) are concrete examples — substitute the equivalent in your harness."
+allowed-tools: Read Grep Bash Edit
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"engineering\",\"domain\":\"ai-engineering/tool-use\",\"scope\":\"portable\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-06\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-06\\\\\\\"}\",\"eval_artifacts\":\"planned\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"tool call optimization\\\\\\\",\\\\\\\"reduce tool calls\\\\\\\",\\\\\\\"too many tool calls\\\\\\\",\\\\\\\"script vs tool call\\\\\\\",\\\\\\\"batching tool calls\\\\\\\",\\\\\\\"parallel tool calls\\\\\\\",\\\\\\\"parallelize calls\\\\\\\",\\\\\\\"independent calls\\\\\\\",\\\\\\\"redundant reads\\\\\\\",\\\\\\\"re-reading file\\\\\\\",\\\\\\\"tool selection\\\\\\\",\\\\\\\"which tool to use\\\\\\\",\\\\\\\"grep before read\\\\\\\",\\\\\\\"file search before grep\\\\\\\",\\\\\\\"bulk edit script\\\\\\\",\\\\\\\"poka-yoke tool design\\\\\\\",\\\\\\\"subagent delegation for tool efficiency\\\\\\\",\\\\\\\"context-efficient tool use\\\\\\\",\\\\\\\"cost per tool call\\\\\\\",\\\\\\\"tool call benchmark\\\\\\\",\\\\\\\"agent efficiency\\\\\\\",\\\\\\\"token efficiency per call\\\\\\\"]\",\"examples\":\"[\\\\\\\"the agent made 17 read_file calls when 3 greps would have done — what should it have done?\\\\\\\",\\\\\\\"we're renaming a variable across 40 files — script or tool calls?\\\\\\\",\\\\\\\"the agent re-reads the same file three times in one task — fix the policy\\\\\\\",\\\\\\\"should I batch these reads into one message or wait for each result?\\\\\\\",\\\\\\\"design a tool-use protocol for our new agent harness — what rules matter?\\\\\\\",\\\\\\\"the context window is filling with verbose terminal output — how do I cut it?\\\\\\\",\\\\\\\"is it worth delegating this exploratory search to a subagent?\\\\\\\",\\\\\\\"what's a reasonable tool-call budget for a single-file bug fix?\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"improve this prompt's wording to get better outputs\\\\\\\",\\\\\\\"design what skills get loaded for which prompts\\\\\\\",\\\\\\\"the test suite is failing after my change — find the cause\\\\\\\",\\\\\\\"extract this repeated string-concat into a helper function\\\\\\\",\\\\\\\"scaffold a new SKILL.md for our team's tool-use rules\\\\\\\",\\\\\\\"review this AI-generated PR for correctness\\\\\\\"]\",\"relations\":\"{\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"context-engineering\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"context-engineering designs the entire information stack reaching the model; tool-call-strategy owns the per-call efficiency decisions inside that stack\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"prompt-craft\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"prompt-craft writes the wording of one instruction; tool-call-strategy decides which external operations the agent should invoke around that instruction\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"debugging\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"debugging chases a specific runtime failure; tool-call-strategy is about the efficiency profile of healthy tool use\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"refactor\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"refactor owns behaviour-preserving code transformations as the deliverable; tool-call-strategy decides whether to deliver that transformation through 50 tool calls or one script\\\\\\\"}],\\\\\\\"related\\\\\\\":[\\\\\\\"context-engineering\\\\\\\",\\\\\\\"refactor\\\\\\\",\\\\\\\"prompt-craft\\\\\\\"],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"code-review\\\\\\\"]}\",\"portability\":\"{\\\\\\\"readiness\\\\\\\":\\\\\\\"scripted\\\\\\\",\\\\\\\"targets\\\\\\\":[\\\\\\\"skill-md\\\\\\\"]}\",\"lifecycle\":\"{\\\\\\\"stale_after_days\\\\\\\":90,\\\\\\\"review_cadence\\\\\\\":\\\\\\\"quarterly\\\\\\\"}\",\"skill_graph_source_repo\":\"https://github.com/jacob-balslev/skill-graph\",\"skill_graph_protocol\":\"Skill Metadata Protocol v5\",\"skill_graph_project\":\"Skill Graph\",\"skill_graph_canonical_skill\":\"skills/tool-call-strategy/SKILL.md\"}"
+  skill_graph_source_repo: "https://github.com/jacob-balslev/skill-graph"
+  skill_graph_protocol: Skill Metadata Protocol v4
+  skill_graph_project: Skill Graph
+  skill_graph_canonical_skill: skills/tool-call-strategy/SKILL.md
+---
+
+# Tool Call Strategy
+
+## Coverage
+
+- The three costs of every tool call: token cost (schema overhead and result size), latency cost (round-trip and decision time), context pollution (results persist in attention window)
+- The script-vs-call decision gate: deterministic bulk work belongs in a script; reasoning-dependent work belongs in individual tool calls with the agent in the loop
+- Tool selection decision tree: file-search vs content-search vs targeted-read vs full-read, the dedicated-tool-over-shell rule, and the harness-agnostic capability map
+- Batching independent calls in a single message vs sequential round-trips, and the dependency-detection heuristic
+- Redundancy avoidance: the conversation-as-cache mental model, recognising re-reads, re-searches, and re-runs
+- Context-efficient patterns: targeted line ranges, summarised verification output, dedicated-tool defaults
+- Subagent delegation for context protection: when exploration belongs in a disposable subagent context vs the main session
+- The poka-yoke principle: design tool usage to prevent mistakes, not just optimise speed
+- Cost benchmark heuristics: rough call-count ranges per task type and the "stop and reconsider" red flag
+
+## Philosophy
+
+Every tool call has three simultaneous costs: tokens (schema overhead plus result), latency (network round-trip plus decision time), and context pollution (results persist in the attention window and degrade subsequent reasoning). Agents that issue 12 calls where 3 would suffice are not merely slower — they are measurably less accurate, because noise accumulated in the context window pushes useful signal further from the attention window.
+
+The optimal strategy is not "minimise calls." Under-calling causes hallucination and skipped verification. The objective is **information gained per unit cost**: a single well-targeted grep that returns five matching lines is worth more than reading three entire files to find the same information. A script that processes fifty files in one shell call is worth more than fifty individual edit calls. The conversation history acts as a cache; information already retrieved does not need to be retrieved again.
+
+> A tool call is like a SQL query against a slow, expensive, noisy database — plan it before you run it, do not re-run queries whose results are already in the result set, and reach for set-based operations (scripts) when you catch yourself doing the same row-level work N times.
+
+## The Three Costs of Every Tool Call
+
+| Cost | Mechanism | Magnitude |
+|---|---|---|
+| **Token cost** | Tool schemas sent with every request (~500 tokens per declared tool). Each result adds to conversation. Ten available tools = ~5,000 tokens of overhead before any user input. | Scales with number of available tools and result size |
+| **Latency cost** | Network round-trip, tool execution time, model decision time per call | ~200–2000 ms per call; compounds for sequential calls |
+| **Context pollution** | Every result stays in conversation history. Failed attempts, verbose outputs, and redundant reads all persist | Degrades reasoning quality as context fills |
+
+**The compound effect:** five unnecessary reads do not just cost five times the tokens — they push useful context further from the attention window, degrading the quality of subsequent reasoning. Context is not just a budget; it is a signal-to-noise ratio.
+
+## Harness-Agnostic Tool Capability Map
+
+Every modern coding-agent harness exposes the same five abstract tool capabilities under different concrete names. Substitute your harness's equivalents when applying this skill.
+
+| Abstract capability | Claude Code | Cursor / Copilot / Continue | OpenCode | Shell-only fallback |
+|---|---|---|---|---|
+| File-pattern search (find files by name/path glob) | `Glob` | `file_search` | `glob` | `find` |
+| Content search (find text inside files) | `Grep` | `grep_search` | `grep` | `grep -r`, `rg` |
+| Targeted read (read specific lines of a file) | `Read` (with `offset`/`limit`) | `read_file` (with line range) | `read` | `sed -n 'A,Bp'` |
+| Diff-based edit (modify part of a file) | `Edit` / `MultiEdit` | `replace_string_in_file` / `apply_patch` | `edit` | `sed -i` (avoid) |
+| Shell execution (run an arbitrary command) | `Bash` | `run_in_terminal` | `bash` | direct shell |
+
+The principles in this skill apply uniformly across all of them. Examples below use the Cursor/Copilot names because they are the most descriptive; the same advice applies to whichever set of names your harness exposes.
+
+## The Script-vs-Call Decision Gate
+
+The single most impactful optimisation: use scripts for deterministic work, tool calls for reasoning-dependent work.
+
+```
+Is the operation deterministic (known input → known output)?
+  YES → Can it be expressed as a shell command or script?
+          YES → Write a script, run once via a shell-execution tool
+          NO  → Single tool call with structured output
+  NO  → Does the operation require reasoning about intermediate results?
+          YES → Individual tool calls with the agent in the loop
+          NO  → Batch into a script that returns structured data the agent can reason about
+```
+
+### When scripts beat tool calls
+
+| Scenario | Tool-call approach | Script approach | Savings |
+|---|---|---|---|
+| Rename a variable across 20 files | 20 diff-based edit calls | One project-owned script via shell execution | 19 fewer calls |
+| Check which files import a module | 10 targeted-read calls | One content-search call | 9 fewer calls |
+| Run lint + typecheck + test | 3 sequential shell calls | `pnpm lint && pnpm typecheck && pnpm test` | 2 fewer calls |
+| Create 5 similar test files | 5 file-creation calls | Script that generates all 5 | 4 fewer calls |
+| Collect metrics from multiple sources | N targeted-read calls | Script that aggregates and returns JSON | N−1 fewer calls |
+
+### When tool calls beat scripts
+
+| Scenario | Why a script fails |
+|---|---|
+| Edit depends on understanding the code around it | The agent needs to read, reason, then decide what to change |
+| Search result determines next action | The search path cannot be predicted in advance |
+| Error in one step changes the approach for the next | Scripts cannot reason about failures mid-flight |
+| Output needs human or agent review before proceeding | Scripts execute blindly |
+
+## Tool Selection Decision Tree
+
+Choose the right tool for the information need. Wrong tool choice is the largest single source of wasted calls.
+
+```
+Need to find files by name or path pattern?
+  → file-pattern search (NOT shell `find`, NOT shell `ls`)
+
+Need to find content inside files?
+  → Need the matching lines themselves?
+        YES → content search with matching lines (returns content)
+        NO  → Just need file paths? content search or file-pattern search
+
+Need to read file contents?
+  → Know which lines you need?
+        YES → targeted read with line range
+        NO  → Need the whole file?
+                YES → full read (default)
+                NO  → content search for the specific function or class first, then targeted read of the section
+
+Need to modify a file?
+  → Targeted change to existing content?
+        YES → diff-based edit (sends only the diff; fails if the old string does not match)
+        NO  → Complete rewrite or new file?
+                YES → file-creation tool
+                NO  → diff-based edit
+
+Need to run a command?
+  → Is there a dedicated tool for this? (read tool instead of `cat`/`head`/`tail`, content search instead of `grep`)
+        YES → use the dedicated tool
+        NO  → shell execution
+```
+
+### Critical rules
+
+| Rule | Why |
+|---|---|
+| Never use shell execution to read files with `cat`, `head`, `tail` | The dedicated read tool is purpose-built, shows line numbers, handles images/PDFs |
+| Never use shell execution for `grep` or `rg` file searches | The dedicated content search has optimised permissions and structured output |
+| Never use shell execution for `find` to discover files | The file-pattern search (glob) is faster and returns sorted results |
+| Never default to inline `sed` or `awk` edits in shell | Prefer diff-based edits for reviewable changes; reserve raw `sed` for cases where a script would be disproportionate |
+| Content search before full read | Content search returns only matching lines; full read returns the entire file |
+| File-pattern search before content search | If you know the file pattern, narrow the search space first |
+
+## Batching and Parallelization
+
+### Independent calls: batch in a single message
+
+If two or more tool calls do not depend on each other's output, make them all in the same message.
+
+**Sequential (bad):**
+```
+Message 1: read file A         → wait for result
+Message 2: read file B         → wait for result
+Message 3: search for pattern  → wait for result
+Total: 3 round-trips
+```
+
+**Parallel (good):**
+```
+Message 1: read file A + read file B + search for pattern
+Total: 1 round-trip (wall-clock = max of individual calls)
+```
+
+### Dependency detection
+
+| Calls are independent when | Calls are dependent when |
+|---|---|
+| Different files, no shared state | Second call uses first call's output |
+| Read-only operations | First call creates or modifies what second reads |
+| Verification checks (lint, type, test) | Error in first determines whether to run second |
+
+### Batching heuristic
+
+Before making a tool call, ask: *"Is there another call I need to make that does not depend on this one's result?"* If yes, batch them.
+
+## Avoiding Redundant Operations
+
+### The information-cache mental model
+
+Treat the conversation context as a cache. Information already retrieved does not need to be retrieved again.
+
+| Redundancy type | Example | Fix |
+|---|---|---|
+| Re-reading a file | Read file A, make an edit, re-read file A to verify | The edit tool confirms what changed; trust it |
+| Re-searching for the same pattern | Two identical content searches in one conversation | Reference the earlier result |
+| Reading a file just written | Create file, then read it to confirm contents | File creation confirms success; trust it |
+| Running the same verification twice | `pnpm typecheck` after edit, then again before commit | Once is enough if no other changes were made |
+| Exploring broadly then narrowly | Search all files, then search the same pattern in a subdirectory | Start narrow; widen only if needed |
+
+### The "Do I already know this?" check
+
+Before every tool call, answer: *"Is this information already in my context from a previous call?"* If yes, reference it instead of re-fetching.
+
+## Context-Efficient Patterns
+
+### For file reading
+
+| Need | Efficient pattern | Wasteful pattern |
+|---|---|---|
+| Find a specific function | Content search for the function name, then targeted read of the 30-line section | Full read of the entire 2000-line file |
+| Check if a pattern exists | Content search (returns match count) | Full read of the entire file and search manually |
+| Read multiple small sections | Multiple targeted reads with explicit line ranges | One full read that includes irrelevant code |
+| Compare two files | Targeted reads of both with relevant line ranges | Full reads of both |
+
+### For file modification
+
+| Need | Efficient pattern | Wasteful pattern |
+|---|---|---|
+| Change one line | Diff-based edit with minimal old/new string | Full file rewrite |
+| Change N similar lines | Diff-based edits batched in one message | N separate sequential edit calls |
+| Change across many files | Project-owned script (Node, Python) — see note below | N separate edit calls |
+| Create a new file | File-creation tool | Diff-based edit (cannot edit what does not exist) |
+
+> **Bulk-edit note:** for "change across many files", prefer a project-owned script (Node, Python) that produces a reviewable diff rather than inline `sed -i` or `awk` in a shell call. Inline `sed -i` bypasses agent review and is hard to audit. Reserve raw `sed` for cases where a proper script would be disproportionate overhead.
+
+### For verification
+
+| Need | Efficient pattern | Wasteful pattern |
+|---|---|---|
+| Check if tests pass | `pnpm test 2>&1 \| tail -20` | Full unbounded test output in context |
+| Check if a server is running | `curl -sf URL > /dev/null && echo up \|\| echo down` | Full curl output with headers and body |
+| Check types | `pnpm typecheck 2>&1 \| head -30` | Unbounded typecheck output |
+| Run multiple checks | `pnpm lint && pnpm typecheck && pnpm test` (one call) | Three separate shell calls |
+
+## Subagent Delegation for Context Protection
+
+Subagents run in separate contexts. Use them to prevent context pollution from exploratory work.
+
+### When to use subagents
+
+| Scenario | Why subagent |
+|---|---|
+| Exploring an unfamiliar part of the codebase | Exploration reads many files; main context stays clean |
+| Running a broad search that may return many results | Results stay in subagent context; only the summary returns |
+| Reviewing code (writer/reviewer pattern) | Reviewer has fresh context without implementation bias |
+| Parallel independent investigations | Each runs in its own context without cross-contamination |
+
+### When NOT to use subagents
+
+| Scenario | Why direct |
+|---|---|
+| Single targeted read or content search | Subagent overhead exceeds the call itself |
+| Work that requires multiple back-and-forth decisions | Subagent cannot ask clarifying questions mid-task |
+| Simple file edits | Direct is faster |
+
+### Subagent context-efficiency rule
+
+Brief subagents with the minimum context they need. Include: what to find, where to look, what format to report back in. Do not include: full conversation history, unrelated background, or "figure out what I need."
+
+## The Poka-Yoke Principle
+
+Design tool usage to prevent mistakes, not just optimise speed. *Poka-yoke* (Japanese: "mistake-proofing") is the lean-manufacturing principle of designing the work so the wrong action is hard or impossible.
+
+| Poka-yoke | Why it prevents errors |
+|---|---|
+| Use absolute file paths | Relative paths break when working directory changes |
+| Prefer diff-based edit over full-file rewrite for existing files | Diff-based edit fails if the old string does not match; full rewrite silently overwrites |
+| Run a content search before a full read | Confirms the file exists and contains the pattern before reading the full content |
+| Run verification *after* edits, not before | Pre-edit verification is wasted if the edit changes the result |
+| Pipe long outputs through `tail` or `head` | Prevents context overflow from verbose commands |
+
+## Cost Benchmark Heuristics
+
+Rough guideline ranges for different task types. These are heuristic targets, not empirically calibrated thresholds — actual counts vary by task complexity, codebase familiarity, and how much context is already in the session. Treat them as "should I stop and reconsider?" thresholds, not hard limits.
+
+| Task type | Guideline range | Typical tools |
+|---|---|---|
+| Simple bug fix (1 file) | 3–5 calls | Content search, targeted read, diff-based edit, verify |
+| Feature addition (2–3 files) | 5–10 calls | Read existing patterns, write new code, verify |
+| Refactor (many files) | 3–8 calls | Content search to find all sites, script to batch-edit, verify |
+| Investigation / exploration | 5–15 calls | Multiple content searches and targeted reads |
+| Complex multi-file feature | 10–20 calls | Plan, read patterns, implement, verify |
+
+**Red flag:** if a task is taking more than 20 tool calls, stop and ask: *"Am I using the right approach?"* Consider scripting, subagent delegation, or a different strategy. The fact that 20 calls feels like a lot is itself a useful signal — listen to it.
+
+## Verification
+
+After applying this skill, verify:
+
+- [ ] Content search ran before targeted read when looking for specific content
+- [ ] Independent tool calls were batched in the same message
+- [ ] Scripts replaced N+1 individual calls for deterministic bulk operations
+- [ ] No re-reads or re-searches for information already in context
+- [ ] Targeted reads with explicit line ranges were used for large files
+- [ ] Verbose command outputs were piped through `head` or `tail`
+- [ ] Total tool calls fall within the benchmark range for this task type, or there is a documented reason they exceed it
+- [ ] Subagents were used for context-heavy exploration, not for trivial single calls
+
+## Do NOT Use When
+
+| Use instead | When |
+|---|---|
+| `prompt-craft` | The fix is in the wording of one instruction (clarity, format, few-shot examples), not how the surrounding tool calls are sequenced |
+| `context-engineering` | The question is about the entire information stack (system prompt, memory, rules, skills) reaching the model, not per-call efficiency |
+| `debugging` | A tool is returning errors at runtime — that is a bug, not an efficiency problem |
+| `refactor` | The deliverable is a behaviour-preserving code transformation; the tool-call efficiency of getting there is a means, not the end |
+| `skill-router` | Deciding which *skill* should activate for a query, not which *tool call* the activated skill should make next |
+| `documentation` | Writing prose for a human reader explaining how the agent's tool usage works |