Move integration tool descriptions out of Go and into YAML

.agents/skills/add-integration/SKILL.md

@@ -115,7 +115,17 @@ that your tools surface for natural-language queries users would actually type.
 
 Add an OAuth flow when the API supports it *and* you want guided credential setup in the Web UI. Get basic token auth working first. Grant type depends on the API: Device Flow for headless, PKCE for browser-redirect. Add a corresponding setup page in `web/templates/pages/`.
 
-## 3. Implementation
+## 3. Tool Definition Authoring (YAML-first)
+
+Tool definitions live in `integrations/<name>/tools.yaml`. See [`docs/tool-yaml.md`](../../../docs/tool-yaml.md) for schema, wiring, and strict-key rules.
+
+When adding a new adapter:
+- Author `tools.yaml` directly — no inline `[]mcp.ToolDefinition{...}` literals.
+- Skip the `//go:build parity` test pattern — it exists only for adapters being *migrated* from inline Go literals; a new adapter writing one would be testing nothing.
+
+The strict-mode loader (`KnownFields(true)`) panics at startup on key typos like `descripton:` instead of silently producing blank prose. Prose-only YAML edits also avoid Go-review noise.
+
+## 4. Implementation
 
 Reference `AGENTS.md > Adding a New Integration` for the 7-step mechanical checklist.
 Focus here on judgment calls:

.agents/skills/optimize-integration/SKILL.md

@@ -72,6 +72,17 @@ Focus on parameters where the wrong value is a common mistake:
 - Parameters that are mutually exclusive with another parameter
 - Parameters where a prerequisite tool provides the needed information
 
+### Editing tool descriptions (YAML-first)
+
+Tool descriptions live in `integrations/<name>/tools.yaml`, not in Go source. To refine a description:
+
+1. Edit `tools.yaml` directly — no Go code changes needed for prose-only updates.
+2. Run `go test ./integrations/<name>/...` to confirm the YAML parses without error.
+3. Run the benchmark (see `/mcp-benchmark` or `/search-benchmark`) to measure the improvement.
+4. Commit the YAML change alone — prose updates don't need a Go code review.
+
+The embed rebuild happens automatically at compile time via `//go:embed`. No separate codegen step.
+
 ### Verification
 
 - `make ci` passes (descriptions are data, not logic)
@@ -205,5 +216,4 @@ Use `"-*_url"` to exclude all fields matching a glob pattern. Valid in exclusion
 | Adding every field "just in case" | Every field costs tokens x N items — unjustified fields compound across pagination | Justify each field by the query it enables |
 | Enriching Tier 4 tools that are already clear | Description churn with no routing improvement | Don't touch what doesn't need touching |
 | Broad glob exclusions like `-*_url` | Silently excludes future upstream API fields that match the glob | Use targeted exclusions when field set is small and stable |
-| Aliasing `ToolDefinition.Parameters` map in search | Progressive silent corruption — `extractSharedParameters` deletes from shared map | Always deep-copy the Parameters map when building `searchToolInfo` |
 | Mutation handler hardcodes one parent type when API has polymorphic parents | 400/silent failure for other parent types (e.g., `listAfter` on a collection ID in Notion) | Branch on parent type at the op-building layer; verify API uses the same write mechanism for all parent types |

AGENTS.md

@@ -27,6 +27,10 @@
 5. **MCP smoke test** — `TestSmoke_SearchResponseShape` in `server/server_test.go` validates the full response contract
 6. **Go files must be `gofmt`'d** — run `make fmt` or `gofmt -w <file>` after editing `.go` files
 
+## Testing Against the Live Server
+
+Before benchmarking or running tool-call tests against a running switchboard, verify the binary you're hitting matches the build you intend to test. Check `serverInfo.version` in the MCP `initialize` response (or `./dist/switchboard -version`) and compare against `git rev-parse --short HEAD`. Silent results from an old running binary look identical to results from the fresh build, so an unverified test pass means nothing (May 2026: a 30-minute benchmark ran against a stale `e94882e` binary from another branch before the mismatch was caught).
+
 ## Git Workflow
 
 - Branch from `main` for all changes