loopctl-mcp-server 2.67.0 → 2.68.0

package/README.md

@@ -326,7 +326,7 @@ it is enforced server-side and a no-op for a non-superadmin key — see below.)
 | `knowledge_agent_usage` | Per-agent knowledge usage: total reads, unique articles, top read articles. Required: exactly one of `api_key_id` (credential) or `agent_id` (logical identity). Optional: `limit`, `since_days`. See Wiki Attribution section. |
 | `knowledge_unused_articles` | Published articles with zero accesses in the window. Optional: `days_unused` (default 30), `limit` (default 50, max 200). |
 | `knowledge_curation_log` | Concise human-readable log of KB CURATION adjustments — novelty-gate decisions (`gate_duplicate`/`gate_draft`/`gate_skip`) and conflict resolutions (`supersede`/`merge`/`dismiss`) — for analyzing the agents'-KB rollout, distinct from the verbose audit log. Each entry: `{at, kind, summary, refs, actor, confidence}`. **RECORDED ONLY when `settings.kb_curation_log` is on** (PATCH `/api/v1/admin/tenants/:id` with `settings:{kb_curation_log:true}`); off by default = no rows. Most recent first. Requires orchestrator role. Optional: `kind`, `since` (ISO8601), `limit` (default 50, max 500), `offset`. |
-| `knowledge_retrieval_metrics` | Daily retrieval-PRECISION time series: for each day, the share of search results the agent then opened (search → get/context within a window). A proxy for whether retrieval is improving as the corpus is de-duplicated, better navigated (MOCs), and conflict-resolved. Most recent day first. Requires orchestrator role. Optional: `limit` (default 30, max 365), `offset`. |
+| `knowledge_retrieval_metrics` | Daily retrieval-PRECISION time series: for each day, the share of RECORDED surfaced search RESULTS the agent then opened (search → get/context within a window). A proxy for whether retrieval is improving as the corpus is de-duplicated, better navigated (MOCs), and conflict-resolved. **Denominators (#582):** `precision` = `followed_through`/`searched`, where `searched` counts RECORDED surfaced RESULTS — one row per result put in front of the agent, capped at the first 20 per call (cap enforced by `Loopctl.Knowledge.Analytics.max_recorded_search_results/0`) — not search calls (`results_recorded` is the same number named for its unit). That cap makes `precision` precision@20: a call returning more contributes only 20, and an open of a result ranked beyond the cap is in neither term. The per-CALL rate is the separate `search_follow_through` = `searches_with_follow_through`/`searches` (distinct QUERY-BEARING calls — query-less `list`/`list_keyset` enumeration pages are excluded). `results_returned` is the true un-truncated count for those same calls. The four call-level fields are filtered per ROW, not per day, so a day mixing pre-#582 or enumeration rows with real searches reports a PARTIAL figure rather than 0 — and `results_returned` is NOT comparable to `searched`. Zero-result and keyless searches are unrecordable, so both ratios are upper bounds — and both rise when a search returns FEWER results, so never optimise them without the absolute `followed_through`; `search_follow_through` is additionally biased DOWN by the recording cap (opens beyond rank 20 are invisible) and UP by crediting every search in the window that surfaced the opened article. Most recent day first. Requires orchestrator role. Optional: `limit` (default 30, max 365), `offset`. |
 
 ### Egress / Privacy Tools (US-41.4)
 

package/index.js

@@ -6042,10 +6042,36 @@ const TOOLS = [
     name: "knowledge_retrieval_metrics",
     description:
       "Return the daily retrieval-PRECISION time series (agents' KB #3): for each day, the " +
-      "share of search results the agent then opened (search → get/context within a window). " +
-      "A proxy for whether retrieval is improving — watch it trend up as the corpus is " +
-      "de-duplicated, better navigated (MOCs), and conflict-resolved. Most recent day first. " +
-      "Requires orchestrator role.",
+      "share of RECORDED surfaced search RESULTS the agent then opened (search → get/context " +
+      "within a window). A proxy for whether retrieval is improving — watch it trend up as " +
+      "the corpus is de-duplicated, better navigated (MOCs), and conflict-resolved. Most " +
+      "recent day first. Requires orchestrator role.\n\n" +
+      // The cap is enforced by Loopctl.Knowledge.Analytics.max_recorded_search_results/0
+      // (Elixir); this JS string cannot interpolate it, so change both together.
+      "Denominators (#582): precision = followed_through / searched, and `searched` counts " +
+      "RECORDED surfaced RESULTS — one row per result put in front of the agent, capped at " +
+      "the first 20 per call — not search calls (`results_recorded` is the same number, " +
+      "named for its unit). Because of that cap precision is precision@20: a call returning " +
+      "more results contributes only 20 to `searched`, and an open of a result ranked beyond " +
+      "the cap is in neither term. The per-CALL rate is separate: `search_follow_through` = " +
+      "searches_with_follow_through / searches — the share of QUERY-BEARING SEARCHES that " +
+      "led to an open. `results_returned` is the true un-truncated result count for those " +
+      "same calls, so it exceeds the rows those calls wrote whenever a page hit the cap.\n\n" +
+      "Call-level population: the four call-level fields are filtered per ROW, not per day " +
+      "— a row counts only if it carries a search identity (nothing recorded before #582 " +
+      "does) and is not a query-less enumeration page (list / list_keyset; browsing is not " +
+      "searching). A day that mixes qualifying and non-qualifying rows reports a PARTIAL " +
+      "searches / results_returned, not 0. Do NOT compare results_returned against " +
+      "searched: different row populations, so results_returned < searched is normal on a " +
+      "legacy-heavy or browse-heavy day.\n\n" +
+      "Caveats: zero-result searches and keyless searches are structurally unrecordable and " +
+      "sit in NO denominator, so both ratios are upper bounds; and both rise if a search " +
+      "simply returns FEWER results, with no better retrieval. Never optimise either alone — " +
+      "read them with the absolute followed_through and the volume fields. " +
+      "search_follow_through carries two further biases pointing OPPOSITE ways: the 20-row " +
+      "recording cap hides opens of results ranked beyond it (DOWN on large pages), while " +
+      "one open credits EVERY search in the window that surfaced that article, not just the " +
+      "preceding one (UP when an agent refines and re-searches).",
     inputSchema: {
       type: "object",
       properties: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loopctl-mcp-server",
-  "version": "2.67.0",
+  "version": "2.68.0",
   "description": "MCP server for loopctl \u2014 structural trust for AI development loops",
   "type": "module",
   "main": "index.js",