diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 30d171543b..78c608c73a 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -106,6 +106,11 @@ hermes chat -q "Hello"
 ### Run tests
 
 ```bash
+# Preferred — matches CI (hermetic env, 4 xdist workers); see AGENTS.md
+scripts/run_tests.sh
+
+# Alternative (activate the venv first). The wrapper is still recommended
+# for parity with GitHub Actions before you open a PR:
 pytest tests/ -v
 ```
 
@@ -286,16 +291,18 @@ registry.register(
 )
 ```
 
-Then add the import to `model_tools.py` in the `_modules` list:
+**Wire into a toolset (required):** Built-in tools are auto-discovered: any
+`tools/*.py` file that contains a top-level `registry.register(...)` call is
+imported by `discover_builtin_tools()` in `tools/registry.py` when `model_tools`
+loads. There is **no** manual import list in `model_tools.py` to maintain.
 
-```python
-_modules = [
-    # ... existing modules ...
-    "tools.my_tool",
-]
-```
+You must still add the tool name to the appropriate list in `toolsets.py`
+(for example `_HERMES_CORE_TOOLS` or a dedicated toolset); otherwise the tool
+registers but is never exposed to the agent. If you introduce a new toolset,
+add it in `toolsets.py` and wire it into the relevant platform presets.
 
-If it's a new toolset, add it to `toolsets.py` and to the relevant platform presets.
+See `AGENTS.md` (section **Adding New Tools**) for profile-aware paths and
+plugin vs core guidance.
 
 ---
 
@@ -595,7 +602,7 @@ refactor/description   # Code restructuring
 
 ### Before submitting
 
-1. **Run tests**: `pytest tests/ -v`
+1. **Run tests**: `scripts/run_tests.sh` (recommended; same as CI) or `pytest tests/ -v` with the project venv activated
 2. **Test manually**: Run `hermes` and exercise the code path you changed
 3. **Check cross-platform impact**: If you touch file I/O, process management, or terminal handling, consider macOS, Linux, and WSL2
 4. **Keep PRs focused**: One logical change per PR. Don't mix a bug fix with a refactor with a new feature.