TOOLS.md

# TOOLS.md - Local Notes

Skills define _how_ tools work. This file is for _your_ specifics — the stuff that's unique to your setup.

## Research Tools

Your primary tools for research:
- `web_search` — find sources
- `web_fetch` — retrieve and verify sources
- `sessions_spawn` — spawn sub-agents for heavy research

### Key Parameters

**web_fetch:**
- Max characters per fetch: 50,000 (system hard limit)
- Workaround for long articles: fetch in sections using anchors or fetch multiple related pages
- Always verify the fetched content matches what you expected

**web_search:**
- No hard limit on number of queries
- Use varied phrasing to combat selection bias
- Search for "X criticism" or "X controversy" to find dissenting views
- Include recency in queries: "X 2025" to find latest developments

**sessions_spawn (sub-agents):**
- Use for heavy research tasks requiring many searches/fetches
- Configure with `--thinking high` for complex synthesis
- Can use cheaper model via `--model` to control costs
- Default max depth: 1 (you can spawn sub-agents but they cannot spawn further unless configured)
- Sub-agents inherit your tool permissions (but not session tools)

## What Goes Here

Things like:
- Current research project notes
- Preferred search query patterns
- Any custom verification steps
- Notes on sources that have been particularly reliable or problematic

## Examples

```markdown
### Research Notes (Current Projects)

**Project: AI Safety Standards 2025**
- Started: 2025-03-17
- Status: In progress
- Key queries: ["AI safety framework 2025", "AI governance latest", "AI ethics criticism"]
- Sources to prioritize: peer-reviewed papers, official standards bodies (ISO, IEEE), government policy docs
- Gaps so far: Non-English perspectives limited
- Sub-agent spawned: yes (session ID: abc123) — awaiting results

### Source Reliability Notes

- **Highly reliable:** .gov, .edu, .org (established orgs), peer-reviewed journals
- **Use with caution:** News outlets (check for original sources), industry blogs (conflict of interest likely)
- **Verify carefully:** Social media claims, Reddit posts, anonymous "expert" quotes
- **Avoid:** Unverified PDFs from unknown domains, content farms

### Query Bank

For bias mitigation, keep a list of alternative framings:
- Primary: "quantum computing advantages"
- Alternative 1: "quantum computing limitations"
- Alternative 2: "quantum computing criticism"
- Alternative 3: "quantum computing challenges"
```

## Why Separate?

Skills are shared. Your setup is yours. Keeping them apart means you can update skills without losing your notes, and share skills without leaking your infrastructure.

---

Add whatever helps you conduct rigorous research. This is your research notebook.