Skip to content
Skills Library
AI & agents · Analysis

tool-use

/tool-use

Guides tool selection across three layers: local scripts (zero context cost), MCP proxy (minimal context), and subagent dispatch (isolated context). Ensures the agent uses the cheapest effective layer and never pollutes the main context window with raw tool output. Use when the agent needs external information, current documentation, database access, or multi-step research.

Author
xoai ↗
Repository
sage ↗
Licence
MIT
Last repository change
28.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
1
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 28.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • SKILL.md zawiera komentarze HTML (1). Nie widać ich w podglądzie Markdown, a model je czyta.

What it does and when to use it

Guides tool selection across three layers: local scripts (zero context cost), MCP proxy (minimal context), and subagent dispatch (isolated context). Ensures the agent uses the cheapest effective layer and never pollutes the main context window with raw tool output. Use when the agent needs external information, current documentation, database access, or multi-step research.

Original author description

Guides tool selection across three layers: local scripts (zero context cost), MCP proxy (minimal context), and subagent dispatch (isolated context). Ensures the agent uses the cheapest effective layer and never pollutes the main context window with raw tool output. Use when the agent needs external information, current documentation, database access, or multi-step research.

How it works

  1. When to Use
  2. The Three Layers
  3. Tool Selection Rules
  4. Context Budget Awareness
  5. When NOT to Use Tools
  6. Failure Modes
Original SKILL.md headings · 165 lines, 1,003 words
SKILL.md preview
---
name: tool-use
description: >
  Guides tool selection across three layers: local scripts (zero context cost),
  MCP proxy (minimal context), and subagent dispatch (isolated context). Ensures
  the agent uses the cheapest effective layer and never pollutes the main context
  window with raw tool output. Use when the agent needs external information,
  current documentation, database access, or multi-step research.
version: "1.0.0"
modes: [fix, build, architect]
---

<!-- sage-metadata
cost-tier: sonnet
activation: auto
tags: [tools, mcp, context, efficiency]
inputs: [task-context, mcp-manifest]
outputs: [tool-results]
requires: []
-->

# Tool Use

Pick the right tool at the right cost. Every token matters.

## When to Use

When the agent needs information that isn't in its context window: current
documentation, database queries, external APIs, file system operations, or
multi-step research. Also when the agent needs to verify information (check
if an import exists, test an API endpoint) rather than relying on memory.

**Core Principle:** The main context window is shared between your instructions
(CLAUDE.md), the conversation, the task, and any tool output. A 2000-token MCP
response is 2000 tokens of pack guidance or conversation history that gets pushed
out. Use the cheapest layer that answers the question. Escalate only when needed.

## The Three Layers

### Layer 1 — Local Tools (Zero Context Cost)

Bash scripts that run and return a result. The output is small and deterministic.
Use for anything that can be answered by running a command.

```bash
# Run tests
bash .sage/gates/scripts/sage-verify.sh .

# Check for hallucinated imports
bash .sage/gates/scripts/sage-hallucination-check.sh src/ .

# Capture screenshots
bash .sage/tools/sage-screenshot.sh http://localhost:3000 --output .sage/screenshots --full-page

# Check build
npm run build

# Check types
npx tsc --noEmit
```

**When:** Tests, builds, type checks, linting, screenshots, file operations.
**Cost:** Only the exit code or small output enters context.

### Layer 2 — MCP Proxy (Minimal Context Cost)

Calls an external MCP tool through the proxy script. The proxy connects to the
MCP server, executes the tool, and returns the extracted content — not the raw
protocol response.

```bash
# Get current framework documentation
npx tsx sage/runtime/mcp/mcp-client.ts call-tool context7 query-docs \
  --params '{"libraryId":"/nextjs/nextjs","topic":"server components caching"}'

# Resolve a library name to Context7 ID
npx tsx sage/runtime/mcp/mcp-client.ts call-tool context7 resolve-library-id \
  --params '{"libraryName":"supabase"}'
```

**When:** You need a SPECIFIC fact from current documentation. "What's the
exact API for `revalidatePath` in Next.js 16?" "What are the parameters for
Supabase's `createClient`?" Single-question, single-answer lookups.

**Cost:** ~200-500 tokens per call. The proxy extracts the relevant text.

**Decision test:** Can you state the exact question in one sentence? → Layer 2.
Do you need to browse, synthesize, or follow up? → Layer 3.

### Layer 3 — Subagent Dispatch (Isolated Context)

Spawn a subagent (on Tier 1 platforms like Claude Code) with a focused task.
The subagent has its own context window, can make multiple MCP calls, search
the web, and synthesize results. It returns a compressed summary.

**When:**
- Research requiring multiple sources or steps
- Category benchmarking (analyze 3-5 competitor approaches)
- Complex debugging requiring cross-referencing (Sentry errors + codebase + docs)
- Any task where you'd need 3+ Layer 2 calls to answer

**How to dispatch:**
```
Subagent task: "Research how Next.js 16 changed the caching model compared to
Next.js 15. Focus on: what's different for Server Components, what migration
steps are needed, and what the nextjs pack should update."

Context to include: nextjs pack rules (caching section only)
Return: 3-5 bullet summary of key changes + specific migration steps
```

**Cost:** Only the returned summary enters the main context (~100-300 tokens).
The subagent's full research stays in its isolated window.

## Tool Selection Rules

**MUST (violation = wasted context or missed information):**

- MUST check `.sage/mcp-manifest.json` before attempting MCP calls. If no
  manifest exists, run `bash sage/runtime/mcp/discover.sh .` first.
- MUST use Layer 1 for all verification tasks (tests, build, type check,
  screenshots). Never use MCP or subagents for things bash can do.
- MUST NOT paste raw MCP responses into the conversation. Extract the
  relevant fact and state it concisely.

**SHOULD (violation = inefficient but functional):**

- SHOULD prefer pack guidance over MCP lookups when the pack covers the topic.
  Packs contain judgment ("use server components for data fetching"). MCP
  contains knowledge ("here's the API for server components"). Judgment first,
  then knowledge if you need specific syntax.
- SHOULD batch related MCP calls. If you need 3 facts from the same library's
  docs, make one call with a broader topic rather than 3 narrow calls.
- SHOULD use Layer 3 for any task requiring 3+ MCP calls. The subagent
  handles the multi-step work; you get a summary.

**MAY (context-dependent):**

- MAY skip Layer 2 and go directly to Layer 3 for research-heavy tasks
  (category benchmarking, architecture research, migration planning).
- MAY use Layer 2 for a quick fact-check even if the pack likely covers it,
  when accuracy for a specific API detail is critical (version-specific syntax).

## Context Budget Awareness

Monitor your context usage. As conversation grows:

- **Early in conversation (< 30% context used):** Layers 2 and 3 freely.
  You have room for tool output.
- **Mid conversation (30-60%):** Prefer Layer 1 and Layer 3 (isolated).
  Avoid Layer 2 calls that return large text blocks.
- **Late in conversation (> 60%):** Layer 1 only. If you need MCP information,
  use Layer 3 with a tight summary requirement. Re-read `.sage/decisions.md`
  to avoid losing your place.

## When NOT to Use Tools

- **The pack already answers the question.** "Should I use server components?"
  → Pack says yes. Don't query Context7 to confirm what the pack already states.
- **Your training data is sufficient.** "What does `useState` do?" → You know
  this. Don't waste a tool call.
- **The user already provided the answer.** If the user told you the API format,
  don't verify it with MCP. Trust the user over tools.

## Failure Modes

- **MCP server not responding:** Fall back to training data + web search.
  Note in your response: "Context7 was unreachable; using training data for
  this API reference — verify the syntax is current."
- **Tool returns irrelevant content:** Don't paste it into context. State:
  "MCP returned unrelated results for [query]. Falling back to [alternative]."
- **No MCP manifest exists:** Run discovery: `bash sage/runtime/mcp/discover.sh .`
  If no MCP config exists at all, tools are Layer 1 only — that's fine.
- **Subagent not available (Tier 2 platform):** Use Layer 2 with multiple
  focused calls. Summarize results yourself instead of delegating to a subagent.

Versions

The database has no other skills named tool-use.

Database snapshot: 13.11.2026 · package version a4eeeb4eae95 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 91context-architect
    Context engineering tool for building AI agent systems. Use when developers need to design agent context strategies — system prompts, tool sets, examples, and runtime context management. Guides through modular design with built-in patterns and dynamic research.
  • 100tool-budget-audit
    Audit how much context an agent's tools consume, through tool definitions and tool results, and decide whether to trim the catalog, add tool search, or add programmatic tool calling. Use when an agent has many tools or MCP servers, picks the wrong tools, or burns context on tool output.
  • 100subagent-dispatch
    When delegating work to a subagent — implementation, review, research, or exploration. Use when a task benefits from a fresh context window, parallel execution, or isolated scope.
  • 100domain-agentic-context
    Specialized agentic and context engineering prompt methodology for Claude. Use when designing AI agents — system prompts, tool definitions, context window architectures, failure mode planning, multi-agent coordination, agent evaluation. Trigger on: "design an agent," "build a…
  • 95agent-tool-routing
    Tool registry, capability discovery, schema-first routing, router policies and fallbacks. Use when an agent has more than ~15 tools, multiple MCP servers, or needs dynamic tool selection based on context.
  • 100context-compress-audit
    Audit a repository, plugin setup, or agent session for raw Bash, Read, WebFetch, and MCP outputs that should be routed through context-compress instead. Use when asked to find context waste, raw tool output waste, missing plugin routing, or places where large command/file/web…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.