loopctl-mcp-server 2.74.0 → 2.75.0

package/index.js

@@ -4665,7 +4665,12 @@ const TOOLS = [
       "trustworthy answer plus its provenance rather than a ranked list to triage yourself; " +
       "use knowledge_search when you want to browse/enumerate matches. Additive — existing " +
       "knowledge tools are unchanged. If semantic ranking is unavailable it degrades to " +
-      "keyword-only (meta.fallback/fallback_reason), same as knowledge_search.",
+      "keyword-only (meta.fallback/fallback_reason), same as knowledge_search.\n\n" +
+      "TODAY THE CURATED BRANCH IS UNREACHABLE ON THIS DEPLOYMENT: a source counts as " +
+      "curated only if its article has curated_at set, and no article does — so every " +
+      "call returns provenance 'retrieved' and a null curated_article_id. Read a " +
+      "'retrieved' verdict as the normal case, not as evidence that a curated answer " +
+      "was considered and rejected. This line comes out when something actually curates.",
     inputSchema: {
       type: "object",
       properties: {
@@ -6493,7 +6498,40 @@ const TOOLS = [
       "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).",
+      "preceding one (UP when an agent refines and re-searches).\n\n" +
+      "Exact attribution (unit: READS — not surfaced results, not calls): attributed_opens " +
+      "/ cross_key_opens / direct_opens count READ rows by how their originating search was " +
+      "established, resolved server-side at write time and never accepted from a caller. " +
+      "Not comparable with followed_through, which counts SURFACED RESULTS later opened. " +
+      "cross_key_opens is the population followed_through cannot see: it correlates on " +
+      "api_key_id, and the injected recall hook searches under a different key from the " +
+      "session that reads, so that channel scores a structural ZERO there — meaning " +
+      "UNMEASURABLE, not unread. Cross-key attribution is circumstantial (two agents in one " +
+      "tenant can reach one article independently), hence labelled rather than folded in. " +
+      "direct_opens is the agent going straight to an article by link or cited id, which " +
+      "used to look identical to 'surfaced and ignored' — close to its opposite.\n\n" +
+      "Disposition (unit: SEARCH CALLS): searches_scored_with_follow_through, " +
+      "searches_reformulated and searches_quiet PARTITION searches_scored — NOT searches. " +
+      "Treating every not-opened search as a failure is wrong — an agent answered by the " +
+      "result snippet correctly opens nothing, and that is a success. A reformulation (the " +
+      "SAME SESSION issuing a later search call with a DIFFERENT QUERY in-window, nothing " +
+      "opened) is the closest thing to an unambiguous failure, so it is split out; what " +
+      "remains is `quiet` and is STILL a mixture of 'snippet sufficed' and 'rows ignored'. " +
+      "This surface does not separate them — do not read quiet as either.\n\n" +
+      "searches_scored is SMALLER than searches and the gap is NOT quiet traffic. A search " +
+      "is scoreable only if it carries a session identity (stamped forward-looking, so a " +
+      "pre-migration row reports searches_scored: 0) and comes from a channel that can " +
+      "react to a result at all — the recall hook and the session-start auto-query emit one " +
+      "distilled query per prompt and never see what came back, so they cannot reformulate " +
+      "by construction. They stay in every other denominator here, precision included. " +
+      "Read searches - searches_scored as n/a, never as zero.\n\n" +
+      "COMPARE ROWS ONLY WITHIN A metric_version. Every row carries the version of the " +
+      "definition set that produced it. Three changes have already altered what a figure here " +
+      "MEANS — searched went from search calls to surfaced results, infrastructure traffic " +
+      "began being excluded, and the disposition trio was rescoped — each forward-looking and " +
+      "each previously leaving no mark on the row, so a series read across one of those " +
+      "boundaries compares definitions rather than days. 0 means the row predates the stamp " +
+      "and its definitions are unknown.",
     inputSchema: {
       type: "object",
       properties: {
@@ -6515,8 +6553,15 @@ const TOOLS = [
   {
     name: "knowledge_analytics_top",
     description:
-      "Return the top accessed knowledge articles for the tenant. " +
-      "Use to identify which articles agents actually read. Requires orchestrator role.",
+      "Return the top READ knowledge articles for the tenant — articles whose body was " +
+      "actually delivered (get/context/drill). Requires orchestrator role.\n\n" +
+      "access_type DEFAULTS TO READS, not to every event. `search` and `index` rows are " +
+      "IMPRESSIONS the ranker produced — one per surfaced result — and they outnumber reads " +
+      "roughly 50:1, so the old unfiltered default ranked ranker output while claiming to " +
+      "show what agents read. Pass access_type:'all' if you genuinely want impressions " +
+      "counted, or a single type to select one. unique_keys counts distinct API KEYS, not " +
+      "agents: v2 mints one ephemeral key per dispatch, so one agent dispatched N times is " +
+      "N keys.",
     inputSchema: {
       type: "object",
       properties: {
@@ -6549,8 +6594,12 @@ const TOOLS = [
   {
     name: "knowledge_article_stats",
     description:
-      "Return per-article usage statistics: total accesses, unique agents, " +
-      "by-type breakdown, and the 10 most recent events. Requires orchestrator role.",
+      "Return per-article usage statistics: total_events (impressions included), " +
+      "total_reads (bodies actually delivered — get/context/drill), unique_keys, a by-type " +
+      "breakdown, and the 10 most recent events. Requires orchestrator role.\n\n" +
+      "Read total_reads, not total_events, when you want usage: impressions outnumber reads " +
+      "roughly 50:1. unique_keys counts distinct API KEYS rather than agents — v2 mints one " +
+      "ephemeral key per dispatch.",
     inputSchema: {
       type: "object",
       properties: {
@@ -6565,7 +6614,8 @@ const TOOLS = [
   {
     name: "knowledge_agent_usage",
     description:
-      "Return knowledge usage for an agent: total reads, unique articles, top read articles. " +
+      "Return knowledge usage for an agent: total_reads (bodies actually delivered), " +
+      "total_events (impressions included), unique articles, top read articles. " +
       "Pass api_key_id (api_keys.id credential) OR agent_id (agents.id logical identity) — not both. " +
       "Requires orchestrator role.",
     inputSchema: {
@@ -6600,8 +6650,11 @@ const TOOLS = [
   {
     name: "knowledge_unused_articles",
     description:
-      "Return published articles that have not been accessed in the configured " +
-      "time window. Use to identify dead-weight knowledge. Requires orchestrator role.",
+      "Return published articles that have not been READ in the configured time window. " +
+      "Use to identify dead-weight knowledge. Requires orchestrator role.\n\n" +
+      "\"Not read\" means no get/context/drill. It deliberately does NOT mean \"no event\": " +
+      "on that definition an article the ranker surfaces constantly and nobody ever opens " +
+      "counted as USED, which made this blind to the largest class of dead weight there is.",
     inputSchema: {
       type: "object",
       properties: {

package/package.json

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