**`utils/`** - Pure utility functions:

**`utils/`** - Utility functions (helpers):
- Reusable helpers called by tools, CLI, or other utils

- Pure Go functions (input → output, minimal side effects)
- Can have database dependency for utility queries (e.g., `EntityExists()`)
- Reusable across tools, CLI, and other packages
- Examples: `ValidateXxx()`, `ParseFilename()`, `ComputeHash()`, `EntityExists()`
**`tools/`** - MCP tool implementations:
- MCP-specific types (`DatasetInput`, `ClusterOutput`, etc.)
- Business logic layer between CLI/MCP and database
- Orchestrates validation, database operations, and response formatting
- One file per MCP tool (e.g., `dataset.go`, `cluster.go`)
- Imports `utils/` for validation and helpers
**Decision checklist:**
1. Does it define MCP tool types? → `tools/`
2. Is it a reusable helper function? → `utils/`
3. Does multiple tools/CLI need it? → `utils/`
4. Is it specific to one MCP tool's logic? → `tools/`

- Examples: `ValidateXxx()`, `ParseFilename()`, `EntityExists()`, `ImportCluster()`

**Examples:**
| Function | Package | Reason |
|----------|---------|--------|
| `ValidateShortID()` | `utils/` | Pure validation, reusable |
| `EntityExists()` | `utils/` | Database helper, reusable |
| `CreateOrUpdateDataset()` | `tools/` | MCP tool implementation |
| `ImportCluster()` | `utils/` | Reusable import logic |
| `DatasetInput` struct | `tools/` | MCP-specific type |

**`tools/`** - MCP/CLI tools (the actual tools):
- One file per tool, called directly by CLI commands and MCP adapters
- Defines tool input/output types (`DatasetInput`, `ClusterOutput`, etc.)
- Examples: `dataset.go`, `cluster.go`, `import_files.go`

**Key insight:** The package boundary is about **reuse and MCP coupling**, not database dependency. `utils/` can use the database for utility queries, but it should never define MCP tool types.

**Simple rule:** If it's called by `cmd/` or `cmd/mcp.go`, it goes in `tools/`. If it's called by `tools/`, it goes in `utils/`.

- **Core logic** (`tools/`): Pure Go functions with no MCP dependency. Input/output via plain structs.
- **MCP adapters** (`cmd/mcp.go`): Thin wrappers bridging MCP types to core functions. Only file importing `mcp` SDK.
- **CLI commands** (`cmd/`): Parse flags, call core functions, print results. Power-user interface.

- **Tools** (`tools/`): MCP/CLI tool implementations. Each file = one tool. Defines input/output types.
- **Utils** (`utils/`): Reusable helper functions. Called by tools, never by CLI/MCP directly.
- **MCP adapters** (`cmd/mcp.go`): Thin wrappers bridging MCP types to tool functions.
- **CLI commands** (`cmd/`): Parse flags, call tool functions, print JSON results.