## MCP Tool Usage Guidelines

Use Distill MCP tools for token-efficient operations:

### Rule 1: Smart File Reading

When reading source code files for **exploration or understanding**:

\`\`\`
mcp__distill__smart_file_read filePath="path/to/file.ts"
\`\`\`

**When to use native Read instead:**
- Before editing a file (Edit requires Read first)
- Configuration files: `.json`, `.yaml`, `.toml`, `.md`, `.env`

### Rule 2: Compress Large Outputs

After Bash commands that produce large output (>500 chars):

\`\`\`
mcp__distill__auto_optimize content="<paste the large output>"
\`\`\`

### Rule 3: Register Model at Session Start

\`\`\`
mcp__distill__register_model model="claude-opus-4-5-20251101"
\`\`\`

### Rule 4: Code Execution SDK for Complex Operations

For multi-step operations, use `code_execute` instead of multiple tool calls (**98% token savings**):

\`\`\`
mcp__distill__code_execute code="<typescript code>"
\`\`\`

**SDK API (`ctx`):**
- `ctx.compress.auto(content, hint?)` - Auto-detect and compress
- `ctx.compress.logs(logs)` - Summarize log output
- `ctx.compress.diff(diff)` - Compress git diff
- `ctx.compress.semantic(content, ratio?)` - TF-IDF compression
- `ctx.code.parse(content, lang)` - Parse to AST structure
- `ctx.code.extract(content, lang, {type, name})` - Extract element
- `ctx.code.skeleton(content, lang)` - Get signatures only
- `ctx.files.read(path)` - Read file content
- `ctx.files.exists(path)` - Check if file exists
- `ctx.files.glob(pattern)` - Find files by pattern
- `ctx.utils.countTokens(text)` - Count tokens
- `ctx.utils.detectType(content)` - Detect content type
- `ctx.utils.detectLanguage(path)` - Detect language from path

**Examples:**

\`\`\`typescript
// Get skeletons of all TypeScript files
const files = ctx.files.glob("src/**/*.ts").slice(0, 5);
return files.map(f => ({
  file: f,
  skeleton: ctx.code.skeleton(ctx.files.read(f), "typescript")
}));

// Compress and analyze logs
const logs = ctx.files.read("server.log");
return ctx.compress.logs(logs);

// Extract a specific function
const content = ctx.files.read("src/api.ts");
return ctx.code.extract(content, "typescript", { type: "function", name: "handleRequest" });
\`\`\`

### Quick Reference

| Action | Use |
|--------|-----|
| Read code for exploration | `mcp__distill__smart_file_read filePath="file.ts"` |
| Get function/class | `mcp__distill__smart_file_read filePath="file.ts" target={"type":"function","name":"myFunc"}` |
| Compress build errors | `mcp__distill__auto_optimize content="..."` |
| Summarize logs | `mcp__distill__summarize_logs logs="..."` |
| Multi-step operations | `mcp__distill__code_execute code="return ctx.files.glob('src/**/*.ts')"` |
| Before editing | Use native `Read` tool |

## MCP Tools

Use Distill for token optimization:
- Code exploration: `mcp__distill__smart_file_read filePath="file.ts"`
- Large outputs: `mcp__distill__auto_optimize content="..."`
- Multi-step ops: `mcp__distill__code_execute code="return ctx.files.glob('**/*.ts')"`
- Before editing: Use native `Read` tool

distill-mcp setup --hooks

Show my session stats