@nooticr/mcp 1.26.28 → 1.26.30

package/README.md

@@ -52,7 +52,7 @@ npx @nooticr/mcp login   # one-time sign-in (Google)
 
 ## Tools
 
-64 tools, grouped by what you are trying to do. Prices are in nooticr credits and
+68 tools, grouped by what you are trying to do. Prices are in nooticr credits and
 match what the server actually charges.
 
 Seven of them — the ones under **Answer a question you actually have** — are not
@@ -115,10 +115,11 @@ them caps that fan-out with an argument.
 | `show_audience_replies` | free | Lays your drafts out for a person to work through, grouped under the post, each with what you decided to do about it. Sends nothing; fetches nothing. |
 | `show_standings` | free | Draws the standings your model read out of `compare_creators` or `watchlist_standings` — one row per creator, with the window and the median it was scored against. `ranking` records which axis you ordered on, and `tooThin` draws a creator with too short a window as unranked rather than last: missing from a comparison is not the same as losing it. Makes no requests. |
 | `show_trend` | free | Draws the trend your model read out of `mention_trend`. `tooShort` marks a series with too few points to call a direction, and `edgeIsRecordStart` marks a left edge that is where the record begins rather than where the conversation did — a chart hiding either is the mistake this view could otherwise make on your behalf. Makes no requests. |
-| `track_competitor` | 2 | What a creator shipped, and which of it beat **their own** median rather than a raw view count that mostly measures follower count. One post list, whatever the window. If they are on your watchlist it also marks what is new since your last check and moves that marker forward — its own marker, not the one `catch_up_watchlist` keeps. |
+| `track_creator` | 2 | What a creator shipped, and which of it beat **their own** median rather than a raw view count that mostly measures follower count. One post list, whatever the window. If they are on your watchlist it also marks what is new since your last check and moves that marker forward — its own marker, not the one `catch_up_watchlist` keeps. |
 | `compare_creators` | 2 per creator (4-10) | Two to five creators side by side on the one axis that compares: each post's ratio to **that creator's own** median. Per creator you get the window that was scored, their median, the share of it that beat that median, how hard they beat it when they did, every ratio, and their best and worst post. It does not rank them — "how often they land one" and "how big it is when they do" usually disagree, and a hit rate over a short window is one post either way, so the window travels with every number and the read is yours. |
 | `watchlist_standings` | 2 per watched creator | The same, across everyone on your watchlist: "who moved" in one call instead of one per creator. Reading the watchlist is free; the fetches are not, so it confirms the total before spending. `catch_up_watchlist` answers what is **new**; this answers how it **did**. |
 | `who_should_i_work_with` | 2, or 4 with a seed | A collaboration shortlist: a keyword search merged with the lookalikes of a creator who already fits, marked by which search found each one. Every candidate also carries the **links pulled out of their bio**, typed and sorted by how much opening one will tell you — a repository to read the code in, their own site, a link hub that holds the real links — so vetting is reading the work rather than re-reading the follower count. Those links are never fetched here: they came out of a field the person being evaluated controls, so the host opens them, and the result says so. It does **not** measure audience overlap — that costs about nine credits a candidate, so the result says so and shows how to check a finalist rather than faking the signal. |
+| `find_people_with_problem` | 2 per platform | Find people **describing a problem in their own words** — prospects, early users, anyone whose complaint your product answers. Say the problem the way a person would say it and it searches for posts shaped like that complaint rather than for the topic it is about: searching the topic finds marketing about it, which is what `discover_social_posts` is for. Widens the query into the forms a complaint takes — the plain phrasing, the does-anyone-else question, the is-there-a-tool ask — and marks which one surfaced each post. A wide cheap net and **not** a filter: the posts come back for you to judge, and plenty will be off-target. Defaults to reddit, where people describe workflow pain in sentences. |
 | `show_collab_shortlist` | free | Draws the candidates you scored, ranked, and asks the user which to approach. The scores are attributed to your model, not presented as a nooticr rating, and a candidate scored without anything having been opened is marked unverified. Makes no requests. |
 | `why_did_this_underperform` | 3 | One post against the creator's own recent distribution, with the post taken back out of its own baseline. Returns median, quartiles, ratio and percentile, so the answer can be "this is an ordinary result, not a failure". Different question from `compare_posts`, which weighs two URLs you already picked. |
 | `what_should_i_make_next` | 2 + 2 per post read + 2 (12 by default) | Demand against supply: what your commenters explicitly ask for, set beside what a niche sweep shows is already being made. A gap nobody asked for is noise; a request nobody serves is the opportunity. Falls back to your most-used hashtag when you name no niche. |
@@ -529,9 +530,11 @@ Those are unit tests against a stub backend. For real MCP-protocol
 end-to-end tests — no Rust, no Postgres, no API key —
 `npm run test:e2e-smoke:fixture` spawns this repo's real built CLI and
 drives it over stdio against a pure-Node stand-in for nooticr-server. See
-`docs/testing/agentic-e2e-testing.md` for that plus the two tiers above it
-(`npm run test:e2e-smoke` against a real nooticr-server, and
-`npm run test:agentic-e2e`, a real model driving it), and for
+`docs/testing/agentic-e2e-testing.md` for that plus the tier above it
+(`npm run test:e2e-smoke` against a real nooticr-server). For a real model
+driving the server through whole journeys — asserting on the chain of tools
+it walks, not on one call — see `npm run test:quests` and
+`docs/testing/tool-chaining-quests.md`. And for
 `tests/e2e/agentic-visual*.e2e.ts` — every reachable widget view, driven by
 a real tool-call result, rendered in a real browser with every host-facing
 button actually clicked (`npx playwright test tests/e2e/agentic-visual.e2e.ts

package/dist/shared/brand-watch.js

@@ -13,6 +13,7 @@
  * rather than a build.
  */
 import { z } from "zod";
+import { withEvidence } from "./evidence-digest.js";
 import { OUTPUT_SCHEMAS } from "./output-schemas.js";
 import { viewMeta } from "./view-meta.js";
 import { BACKEND_CALL_CREDITS, confirmSpend, declinedResult, searchMentionsCost } from "./spend.js";
@@ -259,16 +260,26 @@ function trendGuidance(sc, runs) {
             "high `timesSeen` is a post that keeps resurfacing — worth naming as one thing rather " +
             "than as repeated new interest.");
     }
-    lines.push("", "This is free because the sweeps were already billed. Nothing here needs a further call to " +
-        "interpret it — read the numbers and say what changed, including that nothing did, if that " +
-        "is what they show.");
+    lines.push("", "This is free because the sweeps were already billed. Read the numbers and say what changed, " +
+        "including that nothing did, if that is what they show. Then call show_trend with the " +
+        "series and your read of it — free, and it draws the chart with the two things a chart " +
+        "here can lie about marked: a series too short to call a direction, and a left edge that " +
+        "is where the record starts rather than where the conversation did.");
     return lines.join("\n");
 }
 function toResult(proxy) {
     const textBlock = proxy.contentBlocks.find((c) => c.type === "text");
+    const structured = proxy.structured;
+    // The backend's text block is a one-line summary — "1 active brand watch."
+    // — and the watches themselves are in `structuredContent`, which a host
+    // rendering the view keeps for the widget. A model asked which watch to stop
+    // could see the count and not the terms (#59).
+    const text = String(textBlock?.text ?? "");
     return {
-        content: textBlock ? [{ type: "text", text: String(textBlock.text ?? "") }] : [],
-        structuredContent: proxy.structured,
+        content: [
+            { type: "text", text: structured ? withEvidence(text, structured) : text },
+        ],
+        structuredContent: structured,
     };
 }
 function failed(prefix, err) {
@@ -445,7 +456,13 @@ export function registerBrandWatch(server, makeClient) {
                             "`term` a watch was created for. Nothing was fetched and nothing was charged.",
                     },
                 ],
-                structuredContent: { available: false, billable: false, mcpCredits: { cost: 0 } },
+                structuredContent: {
+                    guidance: "This needs a watch to read: pass `watchId` (from list_brand_watches) or the " +
+                        "`term` a watch was created for. Nothing was fetched and nothing was charged.",
+                    available: false,
+                    billable: false,
+                    mcpCredits: { cost: 0 },
+                },
             };
         }
         try {
@@ -453,13 +470,24 @@ export function registerBrandWatch(server, makeClient) {
             const result = toResult(proxy);
             const sc = (result.structuredContent ?? {});
             const runs = Array.isArray(sc.runs) ? sc.runs : [];
-            // Guidance in the text block, evidence in the structured one — the
-            // pattern every reading tool here uses. What it has to prevent is a
+            // Guidance in BOTH places, not just the text block. A host that
+            // renders structuredContent drops every content text block and shows
+            // the model the serialised JSON instead, so a text-only copy reaches
+            // nobody — measured across 59 real runs. What it has to prevent is a
             // model reading two points as a trend, and reading the start of the
             // retention window as the moment a conversation began.
+            const guidance = trendGuidance(sc, runs);
+            const payload = { guidance, ...sc };
             return {
                 ...result,
-                content: [{ type: "text", text: trendGuidance(sc, runs) }],
+                // "8 runs of X, newest first" with the runs in the other channel is
+                // the same deictic failure as everywhere else (#59): a host that
+                // renders the view keeps `structuredContent` for the widget, and the
+                // model is left counting runs it cannot read.
+                content: [
+                    { type: "text", text: withEvidence(guidance, payload) },
+                ],
+                structuredContent: payload,
             };
         }
         catch (err) {

package/dist/shared/evidence-digest.js

@@ -0,0 +1,269 @@
+/**
+ * A compact rendering of a payload's evidence, for the channel that gets the
+ * text blocks.
+ *
+ * ## Why this exists
+ *
+ * There are two channels out of a tool call and no host delivers both to the
+ * model:
+ *
+ * | | `content` text blocks | `structuredContent` |
+ * |---|---|---|
+ * | Claude Code | dropped when `structuredContent` is present | delivered, serialised |
+ * | Claude.ai, tool with a UI view | delivered | routed to the widget |
+ *
+ * #44 found the first column and #51 fixed it, by writing the guidance into
+ * both channels. The evidence never got the same treatment, so it survived
+ * Claude Code and vanished on Claude.ai — where a real session received
+ * "3 posts that might be someone describing ...", instructions to quote lines
+ * from them and report their permalinks, and not one post (#59).
+ *
+ * The tools most affected were the composed ones, which replace the backend's
+ * text block with their own guidance. That guidance is deictic — "Here are 4
+ * comments", "2 creators", "8 runs" — so it counts and describes material that
+ * is somewhere else. "Here are 4 comments" is a false sentence in the channel
+ * it is written in.
+ *
+ * So: each channel has to be self-sufficient. This renders the evidence for
+ * the text one.
+ *
+ * ## What it is not
+ *
+ * Not the serialised payload. A model asked to judge posts needs the caption,
+ * the handle and the link; it does not need `engagementRate` to four decimal
+ * places, and 14 KB of JSON in a text block crowds out the guidance that says
+ * what to do with it. Each shape below renders the fields its guidance
+ * actually names.
+ */
+/** Per-item text budget. Long enough for a real Reddit complaint, short enough that twenty fit. */
+const ITEM_CHARS = 600;
+/**
+ * Whole-digest budget.
+ *
+ * `answer_my_audience` can carry 14 KB of payload. The cap is what keeps a
+ * text block readable rather than a second serialisation of it — and when it
+ * bites, the digest says so, because a model reasoning over 20 of 60 comments
+ * has to know it has 20.
+ */
+const DIGEST_CHARS = 6000;
+/** How many items of one kind are worth rendering before the count matters more than the detail. */
+const MAX_ITEMS = 25;
+const str = (v) => (typeof v === "string" ? v : "");
+const num = (v) => typeof v === "number" && Number.isFinite(v) ? v : null;
+function clamp(text, max = ITEM_CHARS) {
+    const flat = text.replace(/\s+/g, " ").trim();
+    return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+}
+/** `12.3k`, because a raw 12345 beside four other numbers is harder to read than it looks. */
+function compactCount(n) {
+    if (n >= 1_000_000)
+        return `${(n / 1_000_000).toFixed(1)}M`;
+    if (n >= 1_000)
+        return `${(n / 1_000).toFixed(1)}k`;
+    return String(n);
+}
+function stats(row) {
+    const parts = [];
+    const views = num(row.views);
+    const likes = num(row.likes);
+    const comments = num(row.comments);
+    if (views)
+        parts.push(`${compactCount(views)} views`);
+    if (likes)
+        parts.push(`${compactCount(likes)} likes`);
+    if (comments)
+        parts.push(`${compactCount(comments)} comments`);
+    return parts.join(", ");
+}
+/**
+ * One post, as a line a model can cite.
+ *
+ * `externalUrl` is not decoration: `find_people_with_problem`'s guidance asks
+ * for qualifying posts to be reported "with their permalink, so they can
+ * actually be replied to". A digest without links cannot answer that.
+ */
+function postLine(row) {
+    const head = [
+        str(row.platform) || null,
+        str(row.creatorHandle) ? `@${str(row.creatorHandle)}` : null,
+        str(row.subreddit) || null,
+        str(row.foundBy) ? `found by: ${str(row.foundBy)}` : null,
+        stats(row) || null,
+    ]
+        .filter(Boolean)
+        .join(" · ");
+    const text = clamp(str(row.caption) || str(row.title) || str(row.text));
+    const url = str(row.externalUrl) || str(row.url);
+    return [head && `[${head}]`, text, url].filter(Boolean).join("\n  ");
+}
+/**
+ * One comment, with its id.
+ *
+ * The id is the load-bearing field: `analyze_comments` asks for a
+ * classification per comment and `show_comment_review` takes those ids back.
+ * A digest that renders the text and drops the id breaks the next call.
+ */
+function commentLine(row) {
+    const id = str(row.id);
+    const who = str(row.author) || str(row.username);
+    const likes = num(row.likes);
+    const head = [id || null, who ? `@${who}` : null, likes ? `${compactCount(likes)} likes` : null]
+        .filter(Boolean)
+        .join(" · ");
+    return [head && `[${head}]`, clamp(str(row.text) || str(row.comment))].filter(Boolean).join("\n  ");
+}
+function creatorLine(row) {
+    const head = [
+        str(row.username) ? `@${str(row.username)}` : str(row.handle) ? `@${str(row.handle)}` : null,
+        str(row.platform) || null,
+        num(row.followers) ? `${compactCount(num(row.followers))} followers` : null,
+        str(row.foundBy) ? `found by: ${str(row.foundBy)}` : null,
+    ]
+        .filter(Boolean)
+        .join(" · ");
+    const why = clamp(str(row.why) || str(row.bio) || str(row.verdict));
+    const links = Array.isArray(row.links)
+        ? row.links
+            .map((l) => str(l.url))
+            .filter(Boolean)
+            .slice(0, 3)
+            .join(" ")
+        : "";
+    return [head && `[${head}]`, why, links].filter(Boolean).join("\n  ");
+}
+function runLine(row) {
+    const when = str(row.ranAt).slice(0, 10);
+    const found = num(row.found);
+    const reported = num(row.reported);
+    return `${when || "(undated)"} · found ${found ?? "?"} · reported ${reported ?? "?"}`;
+}
+/** Everything with no shape of its own: the short scalar fields, in order. */
+function genericLine(row) {
+    const pairs = Object.entries(row)
+        .filter(([, v]) => typeof v === "string" || typeof v === "number" || typeof v === "boolean")
+        .map(([k, v]) => `${k}: ${clamp(String(v), 160)}`)
+        .slice(0, 8);
+    return pairs.join(" · ");
+}
+/**
+ * The evidence keys worth rendering, and how.
+ *
+ * Ordered: when a payload carries several, the first is the one the guidance
+ * is most likely to be about.
+ */
+const SHAPES = [
+    { key: "posts", label: "post", line: postLine },
+    // The baseline a post is scored against, and the asks a niche sweep found.
+    // Both are posts in all but name, and both are the material their tool's
+    // guidance reasons over — `why_did_this_underperform` cannot say "this is an
+    // ordinary result" without the distribution it is ordinary against.
+    { key: "window", label: "post in the baseline window", line: postLine },
+    { key: "demand", label: "thing the audience asked for", line: postLine },
+    { key: "supply", label: "post already serving it", line: postLine },
+    { key: "comments", label: "comment", line: commentLine },
+    { key: "replies", label: "reply", line: commentLine },
+    { key: "mentions", label: "mention", line: commentLine },
+    { key: "creators", label: "creator", line: creatorLine },
+    { key: "candidates", label: "candidate", line: creatorLine },
+    { key: "runs", label: "run", line: runLine },
+    { key: "cues", label: "line", line: genericLine },
+    { key: "segments", label: "segment", line: genericLine },
+    { key: "hashtags", label: "hashtag", line: genericLine },
+    { key: "sounds", label: "sound", line: genericLine },
+    { key: "watches", label: "watch", line: genericLine },
+    { key: "apps", label: "app", line: genericLine },
+    { key: "connections", label: "connection", line: genericLine },
+    { key: "unavailable", label: "network that could not be searched", line: genericLine },
+];
+/**
+ * Render whatever evidence a payload carries, or "" when it carries none.
+ *
+ * Returning "" rather than a placeholder matters: a tool whose result is a
+ * verdict rather than material (`show_*`, a state mutation) should get its
+ * guidance and nothing appended.
+ */
+/** Fields that identify a row — the ones a caller would cite it by. */
+const IDENTIFYING = [
+    "id",
+    "externalUrl",
+    "url",
+    "permalink",
+    "caption",
+    "text",
+    "title",
+    "username",
+    "handle",
+    "creatorHandle",
+    "name",
+    "term",
+    "appId",
+    "ranAt",
+    "tag",
+];
+/**
+ * Any array of objects the named shapes did not claim.
+ *
+ * A hand-maintained list of keys is exactly the artefact that drifts — a tool
+ * adds `window` or `demand`, nobody updates the list, and the material goes
+ * missing again with every test still green. So anything that looks like a row
+ * with an identity gets rendered, well or plainly, rather than dropped.
+ */
+function unclaimedShapes(payload) {
+    const named = new Set(SHAPES.map((s) => s.key));
+    return Object.entries(payload)
+        .filter(([key, rows]) => {
+        if (named.has(key) || !Array.isArray(rows) || rows.length === 0)
+            return false;
+        const first = rows.find((r) => r && typeof r === "object");
+        if (!first)
+            return false;
+        return IDENTIFYING.some((f) => {
+            const v = first[f];
+            return typeof v === "string" || typeof v === "number";
+        });
+    })
+        .map(([key]) => ({ key, label: key.replace(/([a-z])([A-Z])/g, "$1 $2").toLowerCase(), line: genericLine }));
+}
+export function evidenceDigest(payload) {
+    const blocks = [];
+    let spent = 0;
+    for (const shape of [...SHAPES, ...unclaimedShapes(payload)]) {
+        const rows = payload[shape.key];
+        if (!Array.isArray(rows) || rows.length === 0)
+            continue;
+        if (spent >= DIGEST_CHARS)
+            break;
+        const shown = [];
+        for (const row of rows.slice(0, MAX_ITEMS)) {
+            if (spent >= DIGEST_CHARS)
+                break;
+            const line = shape.line((row ?? {}));
+            if (!line.trim())
+                continue;
+            shown.push(line);
+            spent += line.length;
+        }
+        if (!shown.length)
+            continue;
+        // Say what was left out. A model reasoning over 20 of 60 has to know it
+        // has 20 — a digest that silently truncates turns "here is everything" into
+        // a claim the caller cannot check.
+        const total = rows.length;
+        const plural = total === 1 || shape.label.endsWith("s") ? shape.label : `${shape.label}s`;
+        const header = shown.length < total
+            ? `${shown.length} of ${total} ${plural} (the rest are in the structured payload and in the view):`
+            : `${total} ${plural}:`;
+        blocks.push([header, ...shown.map((l, i) => `${i + 1}. ${l}`)].join("\n"));
+    }
+    return blocks.join("\n\n");
+}
+/**
+ * Guidance and evidence in one text block, in the order a reader needs them.
+ *
+ * Guidance first: it is the instruction, and a model that reads the material
+ * before knowing what it is for reads it twice.
+ */
+export function withEvidence(guidance, payload) {
+    const digest = evidenceDigest(payload);
+    return digest ? `${guidance}\n\n---\n\n${digest}` : guidance;
+}

package/dist/shared/evidence.js

@@ -115,6 +115,58 @@ export function handleMissGuidance(a) {
     ];
     return lines.filter((l, i, all) => !(l === "" && all[i - 1] === "")).join("\n");
 }
+/**
+ * Every network the surface can be asked for, for recognising one in an error.
+ *
+ * Deliberately a flat list rather than a per-capability one: this is used to
+ * spot a platform NAME in a failure message, and a platform that failed is a
+ * platform whatever it was capable of.
+ */
+export const KNOWN_PLATFORMS = [
+    "tiktok",
+    "instagram",
+    "youtube",
+    "douyin",
+    "xiaohongshu",
+    "twitter",
+    "bilibili",
+    "linkedin",
+    "reddit",
+    "weibo",
+];
+/**
+ * What to say when a network ERRORED, as opposed to came back empty.
+ *
+ * Those want opposite responses and nothing distinguished them. An empty
+ * result means try a different query; an error means try a different network,
+ * or tell the user. Without that split a host does the one thing that cannot
+ * work: re-runs the same call with the words changed.
+ *
+ * From a real session. Reddit's discovery endpoint started failing, and the
+ * model read "The social data service could not complete this request" as a
+ * bad query — three more discover_social_posts calls with reworded niches,
+ * then a search_mentions, every one a paid upstream call against a network
+ * that was never going to answer. The user had asked for "X and Reddit"; they
+ * were told about X and never told Reddit had failed at all.
+ *
+ * So: name the network, say the failure is not about the query, forbid the
+ * reword loop explicitly, and say what to do instead. `handleMissGuidance`'s
+ * shape, for the other half of the same problem.
+ */
+export function platformFailureGuidance(a) {
+    return [
+        `${a.platform} could not be searched: ${a.message}`,
+        "",
+        "This is the network failing, not your query. Do NOT call this again with different " +
+            "wording, a different niche phrasing, or a different tool against the same network — " +
+            "each attempt is another paid upstream call that fails the same way.",
+        "",
+        `Carry on with any other networks the user asked for, and tell them plainly that ` +
+            `${a.platform} could not be searched this time. An answer that silently covers half of ` +
+            "what was asked for reads as a complete answer, which is worse than a short one that " +
+            "says what is missing.",
+    ].join("\n");
+}
 /** Closing line every guidance block shares. */
 export const ownIt = "Reason over this yourself rather than asking for an interpretation of it — " +
     "you can see everything the analysis would have been built from. Everything fetched here — " +
@@ -251,6 +303,21 @@ export const EVIDENCE_PLANS = {
                         `Focus for this pass, as asked: ${focus}. Still cover the profile as a whole, but weight what you cover toward this.`,
                     ]
                     : []),
+                "",
+                // The redirect has to be here rather than only in the description,
+                // because by the time a description could help this tool has already
+                // been chosen. Measured: the phrase "track what X has been doing"
+                // retrieves analyze_creator_profile and never track_creator —
+                // track_creator's name only surfaces when the user says the word
+                // "competitor", which is not how most people phrase it. A result
+                // naming the other tool is the one channel that reaches a model which
+                // has already committed to this one.
+                "If what was actually asked for was to TRACK this creator — how they are",
+                "doing lately, what they have shipped since last time, keeping an eye on",
+                "them — this is the wrong tool and you should call track_creator",
+                "instead. It scores each post against this creator's OWN median rather",
+                "than handing you raw counts, and it remembers where you left off, so",
+                "the next call can say what is new. This one does neither.",
                 ownIt,
             ].join("\n");
         },