tool-use

Files (1)

• SKILL.md

SKILL.md (first lines)

<!-- 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.

From xoai/sage, MIT.

More from xoai/sage