@nooticr/mcp 1.26.27 → 1.26.29

package/dist/shared/loading-plans.js

@@ -243,12 +243,39 @@ export const LOADING_PLANS = {
             },
         ],
     },
-    track_competitor: {
+    track_creator: {
         label: "Reading what they shipped",
         kind: "strip",
         n: 3,
         steps: [step("get_user_posts")],
     },
+    find_people_with_problem: {
+        label: "Looking for people with this problem",
+        kind: "list",
+        n: 6,
+        // Three query shapes per platform, so the step repeats rather than
+        // representing one search — the wait is proportional to platforms asked
+        // for, and a single-step plan would under-report it badly.
+        steps: [step("discover_social_posts")],
+    },
+    // Both fan out one post-list fetch per creator, so the price is the size of
+    // the list and the wait is drawn per unit — same shape as catch_up_watchlist.
+    compare_creators: {
+        label: "Scoring each against their own median",
+        kind: "list",
+        n: 3,
+        steps: [],
+        perUnit: [CREATOR_UNIT],
+        note: "Priced per creator compared.",
+    },
+    watchlist_standings: {
+        label: "Reading the whole watchlist",
+        kind: "list",
+        n: 5,
+        steps: [],
+        perUnit: [CREATOR_UNIT],
+        note: "Priced per creator on the watchlist.",
+    },
     who_should_i_work_with: {
         label: "Building a shortlist",
         kind: "list",
@@ -299,6 +326,7 @@ export const LOADING_PLANS = {
     show_variants: { label: "Laying out the variants", kind: "list", n: 4, steps: [], free: true },
     show_repurposed_post: { label: "Laying out the rewrites", kind: "text", n: 1, steps: [], free: true },
     show_collab_shortlist: { label: "Drawing the shortlist", kind: "list", n: 5, steps: [], free: true },
+    show_standings: { label: "Drawing the standings", kind: "list", n: 4, steps: [], free: true },
     show_trend: { label: "Drawing the trend", kind: "text", n: 1, steps: [], free: true },
     // Reads stored aggregates the sweeps already paid for. Free, and no
     // upstream step to wait on — the wait is a database read.

package/dist/shared/output-schemas.js

@@ -198,7 +198,19 @@ const analysis = open({
  * marker, what it fetched, and where it came from. Optional throughout,
  * because the shape of the material itself differs per tool.
  */
+/**
+ * What to do with the material, carried where a host will actually deliver it.
+ *
+ * Every tool that returns guidance puts the same string in a `content` text
+ * block too. That block is the one the MCP spec points at and the one hosts
+ * drop: a host rendering `structuredContent` replaces the text blocks with the
+ * serialised JSON, so the text copy reaches no model. Declared here rather than
+ * left to `passthrough()` because a host reading the schema should be able to
+ * see that the field exists.
+ */
+const guidance = scalar().describe("What to do with this payload, in prose. Read it: it is the instruction, not a summary.");
 const evidence = {
+    guidance,
     mode: scalar().describe('Always "evidence": this payload is material you have still to read.'),
     tool: scalar(),
     evidenceFrom: listOf(z.string()).describe("The cheap calls this was assembled from."),
@@ -311,6 +323,7 @@ export const OUTPUT_SCHEMAS = {
      * one should not find the key gone.
      */
     analyze_comments: open({
+        guidance,
         summary: scalar(),
         themes: anyList(),
         commentsAnalyzed: scalar(),
@@ -516,7 +529,7 @@ export const OUTPUT_SCHEMAS = {
         threads: anyList().describe("Shaped like search_mentions so one view renders both."),
         mcpCredits,
     }),
-    track_competitor: open({
+    track_creator: open({
         ...evidence,
         username: scalar(),
         platform: scalar(),
@@ -525,7 +538,7 @@ export const OUTPUT_SCHEMAS = {
         since: scalar(),
         sinceApplied: scalar(),
         tracked: scalar().describe("True when this creator is on the watchlist, which is what makes a diff possible."),
-        lastCheckedAt: scalar().describe("When track_competitor last looked, or null on a first look."),
+        lastCheckedAt: scalar().describe("When track_creator last looked, or null on a first look."),
         newSincePreviousCheck: scalar().describe("Posts not seen at the last check; null when there was none."),
         baseline: open({
             count: scalar(),
@@ -549,6 +562,21 @@ export const OUTPUT_SCHEMAS = {
         creditsCharged: scalar(),
         mcpCredits,
     }),
+    /**
+     * Prospect discovery. The unit is a POST that might be someone describing a
+     * problem — `posts` rather than a bespoke key, because the gallery view
+     * already draws that shape and a wide net does not need a view of its own.
+     */
+    find_people_with_problem: open({
+        ...evidence,
+        problem: scalar(),
+        platforms: listOf(z.string()),
+        posts: listOf(post),
+        searchedShapes: listOf(z.string()).describe("Which complaint phrasings were searched: plain, shared, asking."),
+        unavailable: anyList().describe("Searches that errored, by platform and shape."),
+        creditsCharged: scalar(),
+        mcpCredits,
+    }),
     who_should_i_work_with: open({
         ...evidence,
         niche: scalar(),
@@ -726,6 +754,84 @@ export const OUTPUT_SCHEMAS = {
         days: scalar(),
         mcpCredits,
     }),
+    /**
+     * One row per creator, on the axis every creator shares. `window` sits
+     * beside every derived number on purpose — a hit rate whose denominator is
+     * invisible cannot be told apart from a hit rate that means something.
+     */
+    compare_creators: open({
+        creators: listOf(open({
+            handle: scalar(),
+            platform: scalar(),
+            window: scalar().describe("Posts scored — the denominator of hitRate and the baseline."),
+            baseline: open({
+                count: scalar(),
+                median: scalar(),
+                min: scalar(),
+                max: scalar(),
+                p25: scalar(),
+                p75: scalar(),
+            }).nullish(),
+            hitRate: scalar().describe("Share of the window at or above aboveRatio x their own median."),
+            medianWinRatio: scalar().describe("How hard they beat their median when they did."),
+            ratios: listOf(z.number()).describe("Every post's ratio to their own median, ascending."),
+            best: post.nullish(),
+            worst: post.nullish(),
+            unavailable: scalar().describe("Set when this creator could not be scored, and why."),
+        })).optional(),
+        platform: scalar(),
+        platformDefaulted: scalar(),
+        metric: scalar(),
+        thinWindow: scalar().describe("Below this many posts, a hit rate is one post either way."),
+        aboveRatio: scalar().describe("The ratio hitRate counts from."),
+        billable: scalar(),
+        mode: scalar(),
+        tool: scalar(),
+        evidenceFrom: listOf(z.string()),
+        creditsCharged: scalar(),
+        mcpCredits,
+    }),
+    show_standings: open({
+        creators: listOf(anyObject()),
+        metric: scalar(),
+        ranking: scalar().describe("Which axis the order is on — 'how often' and 'how big' disagree."),
+        verdict: scalar(),
+        tooThin: listOf(z.string()).describe("Handles drawn unranked rather than bottom."),
+        // The discriminator the view keys on, since `creators` alone is ambiguous
+        // with the two fetching tools' payloads.
+        standings: scalar(),
+    }),
+    watchlist_standings: open({
+        creators: listOf(open({
+            handle: scalar(),
+            platform: scalar(),
+            window: scalar(),
+            baseline: open({
+                count: scalar(),
+                median: scalar(),
+                min: scalar(),
+                max: scalar(),
+                p25: scalar(),
+                p75: scalar(),
+            }).nullish(),
+            hitRate: scalar(),
+            medianWinRatio: scalar(),
+            ratios: listOf(z.number()),
+            best: post.nullish(),
+            worst: post.nullish(),
+            unavailable: scalar(),
+        })).optional(),
+        watching: scalar().describe("How many creators are on the watchlist."),
+        metric: scalar(),
+        thinWindow: scalar(),
+        aboveRatio: scalar(),
+        billable: scalar(),
+        mode: scalar(),
+        tool: scalar(),
+        evidenceFrom: listOf(z.string()),
+        creditsCharged: scalar(),
+        mcpCredits,
+    }),
     discover_sounds: open({
         sounds: listOf(open({
             title: scalar(),
@@ -766,6 +872,7 @@ export const OUTPUT_SCHEMAS = {
      * documenting a field that never arrives is worse than omitting it.
      */
     score_draft: open({
+        guidance,
         draft: scalar(),
         platform: scalar(),
         mcpCredits,
@@ -858,6 +965,7 @@ export const OUTPUT_SCHEMAS = {
         trend: scalar().describe("The discriminator the view keys on."),
     }),
     mention_trend: open({
+        guidance,
         runs: listOf(open({
             ranAt: scalar(),
             found: scalar().describe("Everything that sweep saw."),

package/dist/shared/prompts.js

@@ -298,7 +298,7 @@ export function registerPrompts(server) {
         `over- and under-performs, who the audience is. 2 credits.\n` +
         `4. watch_creator to add them to your watchlist — free, stores the handle only, fetches ` +
         `nothing.\n` +
-        `5. track_competitor on the same handle — what they have shipped recently and which of it ` +
+        `5. track_creator on the same handle — what they have shipped recently and which of it ` +
         `beat THEIR OWN median, not a raw view count that mostly measures follower count. 2 credits, ` +
         `whatever the window. Because they are now on your watchlist, this also sets its own "since I ` +
         `last checked" marker — a different one from catch_up_watchlist's.\n` +

package/dist/shared/standings.js

@@ -0,0 +1,146 @@
+/**
+ * Putting two creators side by side (issue #30).
+ *
+ * The surface had a strong and correct stance on baselines, applied in one
+ * direction only. `track_creator` scores each post against the median of
+ * that creator's own window, "because a raw view count mostly measures
+ * follower count — outperformance against themselves is the signal".
+ * `why_did_this_underperform` does the same for a single post.
+ *
+ * Both were right, and both then discarded the comparison. A ratio to one's
+ * own median is *exactly* the quantity that IS comparable across creators of
+ * different sizes — a 300k-follower account beating its median by 2.1× and a
+ * 4k-follower account doing the same are the same event — and no tool ever
+ * placed two of them next to each other. So "is their hit rate better than
+ * mine?" was unanswerable at any price, while every ingredient was computed on
+ * every call and thrown away.
+ *
+ * The comparison itself stays the model's job, as everywhere else here. This
+ * module normalises each creator to the same axis and reports how much window
+ * it had to do it with; ranking them server-side would hide exactly the thing
+ * that decides whether a ranking means anything.
+ */
+import { ABOVE_RATIO, BREAKOUT_RATIO, distributionOf, MIN_BASELINE_POSTS, numberOf, standing, } from "./performance.js";
+/** Median of an already-sorted list. */
+function mid(sorted) {
+    if (!sorted.length)
+        return null;
+    const i = Math.floor(sorted.length / 2);
+    return sorted.length % 2 ? sorted[i] : (sorted[i - 1] + sorted[i]) / 2;
+}
+const round2 = (n) => Math.round(n * 100) / 100;
+/**
+ * One creator, reduced to the axis every creator shares.
+ *
+ * `hitRate` is a share of a window and not a rate — over six posts it is one
+ * post either way — which is why `window` travels beside it everywhere rather
+ * than being folded into a score. A caller that cannot see the denominator
+ * cannot know the number is noise, and the guidance below leans on it.
+ */
+export function creatorStanding(handle, platform, posts, metric, pick) {
+    const values = posts.map(pick);
+    const baseline = distributionOf(values);
+    const empty = {
+        handle,
+        platform,
+        window: posts.length,
+        baseline,
+        hitRate: null,
+        medianWinRatio: null,
+        ratios: [],
+        best: null,
+        worst: null,
+    };
+    if (!posts.length) {
+        return { ...empty, unavailable: "no posts came back for this handle" };
+    }
+    if (!baseline) {
+        // Fewer than MIN_BASELINE_POSTS is not a baseline, and inventing one would
+        // put a confident ratio on an account nobody has enough of. The same
+        // refusal `distributionOf` already makes for a single post.
+        return {
+            ...empty,
+            unavailable: `only ${posts.length} post${posts.length === 1 ? "" : "s"} in the window — ` +
+                `${MIN_BASELINE_POSTS} is the fewest that make a baseline`,
+        };
+    }
+    const scored = posts.map((post) => ({ post, standing: standing(pick(post), values) }));
+    const ratios = scored.map((s) => numberOf(s.standing.ratio)).filter((r) => Number.isFinite(r));
+    const winners = ratios.filter((r) => r >= ABOVE_RATIO);
+    const byRatio = [...scored].sort((a, b) => numberOf(b.standing.ratio) - numberOf(a.standing.ratio));
+    return {
+        handle,
+        platform,
+        window: posts.length,
+        baseline,
+        hitRate: round2(winners.length / posts.length),
+        medianWinRatio: winners.length ? round2(mid([...winners].sort((a, b) => a - b)) ?? 0) : null,
+        ratios: [...ratios].sort((a, b) => a - b).map(round2),
+        best: { ...byRatio[0].post, standing: byRatio[0].standing, metric },
+        worst: { ...byRatio[byRatio.length - 1].post, standing: byRatio[byRatio.length - 1].standing, metric },
+        unavailable: null,
+    };
+}
+/**
+ * The window below which a hit rate should not be quoted as one.
+ *
+ * Not a hard floor — the row is still returned, because "we only have 5 posts"
+ * is itself the answer to "who is accelerating?" and hiding it would leave the
+ * model guessing. It is the number the guidance names so the model says "too
+ * few posts to call this" instead of ranking confidently, the same discipline
+ * `find_hook_pattern` applies with "a template that fits one post is not a
+ * pattern".
+ */
+export const THIN_WINDOW = 8;
+/**
+ * What to do with a set of standings.
+ *
+ * Written to be read by the model that just received them, in the voice
+ * `evidence.ts` sets: say what the material is, what is comparable about it,
+ * and what would be a mistake to conclude.
+ */
+export function standingsGuidance(a) {
+    const scored = a.rows.filter((r) => !r.unavailable);
+    const thin = scored.filter((r) => r.window < THIN_WINDOW);
+    const lines = [];
+    lines.push(`${a.rows.length} creator${a.rows.length === 1 ? "" : "s"}` +
+        (a.source === "watchlist" ? " from your watchlist" : "") +
+        `, each scored against their OWN recent median ${a.metric} — never against each other's raw ` +
+        "numbers, because a raw count mostly measures follower count. The ratio is what compares: " +
+        "a large account beating its median by 2× and a small one doing the same have done the same " +
+        "thing.");
+    if (!scored.length) {
+        lines.push("", "None of them could be scored — see `unavailable` on each row. That is a gap in what came " +
+            "back, not a finding about the creators, so say which ones and why rather than reporting " +
+            "an empty comparison.");
+        return lines.join("\n");
+    }
+    lines.push("", "Per creator: `window` is how many posts were scored, `baseline.median` is the middle of " +
+        `their own window, \`hitRate\` is the share of it at or above ${ABOVE_RATIO}× that median, ` +
+        "`medianWinRatio` is how hard they beat it when they did, and `ratios` is every post's " +
+        "ratio ascending so the spread is visible. `best` and `worst` carry the posts themselves.", "", "Two different questions live in those numbers and they usually disagree: how OFTEN someone " +
+        "lands one (`hitRate`) and how BIG it is when they do (`medianWinRatio`). A creator with a " +
+        "low hit rate and a high win ratio is swinging; the reverse is consistent and capped. Say " +
+        "which of the two you are ranking on, because 'who is doing better' has no single answer.");
+    if (thin.length) {
+        lines.push("", `Do not rank ${thin.map((r) => `@${r.handle} (${r.window} posts)`).join(", ")} confidently. ` +
+            `A hit rate over fewer than ${THIN_WINDOW} posts is one post either way, and a median over ` +
+            "a window that small moves with the window. Say the sample is too thin to call rather " +
+            "than putting them in an order.");
+    }
+    const unavailable = a.rows.filter((r) => r.unavailable);
+    if (unavailable.length) {
+        lines.push("", `Not scored: ${unavailable.map((r) => `@${r.handle} — ${r.unavailable}`).join("; ")}. ` +
+            "Missing from the comparison is not the same as bottom of it.");
+    }
+    lines.push("", `Every ratio here is against a window measured now. It cannot tell you whether anyone's ` +
+        "baseline is itself moving — that needs a second point in time, which nothing stores yet " +
+        "(issue #28). So do not read a high hit rate as 'improving'; it is 'consistent within this " +
+        "window' and nothing more.", "", "When you have decided what the numbers say, call show_standings with the rows and the axis " +
+        "you ranked on. Free, and it is the one place the ranking is attributed to you rather than " +
+        "presented as a nooticr score — it also draws a creator with too thin a window as unranked " +
+        "rather than last, which is the mistake a plain table makes on your behalf.");
+    return lines.join("\n");
+}
+/** Threshold re-exported so the tools and the view agree on the badge. */
+export { ABOVE_RATIO, BREAKOUT_RATIO };

package/dist/shared/tools-def.js

@@ -349,11 +349,29 @@ export const TOOL_DEFINITIONS = [
         inputSchema: z.object({ username: z.string().describe("Whose audience this is, with or without @."), summary: z.string().optional(), replies: z.array(z.object({ id: z.string(), comment: z.string(), author: z.string().optional(), likes: z.number().optional(), postUrl: z.string().optional(), postTitle: z.string().optional(), postedAt: z.string().optional(), draft: z.string().optional(), kind: z.string().optional(), why: z.string().optional() })), themes: z.array(z.string()).optional(), nextSteps: z.array(z.string()).optional() }).strict(),
     },
     {
-        name: "track_competitor",
+        name: "track_creator",
         title: "Track Competitor",
-        description: "What a creator shipped recently, and which of it beat their own baseline. Scores every post in the window against the median of that same window, because a raw view count mostly measures follower count \u2014 outperformance against themselves is the signal worth reporting. If they are on your watchlist it also marks which posts are new since your last track_competitor call and moves that marker forward. Use for a rival you follow over time. Consumes 2 nooticr credits, whatever the window size.",
+        description: "What a creator shipped recently, and which of it beat their own baseline. Scores every post in the window against the median of that same window, because a raw view count mostly measures follower count \u2014 outperformance against themselves is the signal worth reporting. If they are on your watchlist it also marks which posts are new since your last track_creator call and moves that marker forward. Use for a rival you follow over time. Consumes 2 nooticr credits, whatever the window size.",
         inputSchema: z.object({ username: z.string().describe("Creator handle, with or without @."), platform: z.string().optional().describe("Platform (default tiktok)."), limit: z.number().int().optional().describe("Posts in the window (default 12, max 30)."), metric: z.enum(["views", "likes", "comments", "shares", "engagementRate"]).optional().describe("Which stat to rank on (default views)."), since: z.string().optional().describe("Only posts published on or after this date, as YYYY-MM-DD.") }).strict(),
     },
+    {
+        name: "compare_creators",
+        title: "Compare Creators",
+        description: "Two to five creators side by side, each scored against THEIR OWN recent median rather than against each other's raw numbers — which is the only way the comparison means anything, because a raw view count mostly measures follower count. Returns per creator: how many posts were scored, their own median, the share of the window that beat it, how hard they beat it when they did, every post's ratio, and their best and worst post. The ranking is yours to make: 'how often' and 'how big' usually disagree, and a hit rate over a short window is one post either way, so the window size travels with every number. Fetches one post list per creator: 2 nooticr credits each, 4-10 in total. Use for 'is their hit rate better than mine'; track_creator is one creator alone.",
+        inputSchema: z.object({ usernames: z.array(z.string()).min(2).max(5), platform: z.string().optional(), limit: z.number().int().optional(), metric: z.string().optional() }).strict(),
+    },
+    {
+        name: "watchlist_standings",
+        title: "Watchlist Standings",
+        description: "The same comparison across everyone on your watchlist, answering 'who moved' in one call instead of one per creator. Each is scored against their own recent median, so the numbers are comparable between accounts of different sizes; the window size travels with each so a short one is not ranked as if it were a season. Reads the watchlist itself for free and fetches one post list per creator on it: 2 nooticr credits each, so the price is the size of your watchlist — it confirms before spending. Use for the weekly 'who is accelerating'; catch_up_watchlist is what is NEW rather than how it did.",
+        inputSchema: z.object({ limit: z.number().int().optional(), metric: z.string().optional() }).strict(),
+    },
+    {
+        name: "show_standings",
+        title: "Show Standings",
+        description: "Draw the standings you read out of compare_creators or watchlist_standings. Free, and makes no requests — it only renders what you pass it: one row per creator with their window, their own median, how often they beat it and how hard, and the post that did best. Pass `ranking` to say which axis you ordered on, and `tooThin` for the creators whose window was too short to rank — a table that hides that is the one mistake this view can make on your behalf. Call this after you have decided what the numbers mean, not instead of deciding.",
+        inputSchema: z.object({ creators: z.array(z.object({}).passthrough()).min(1).max(25), metric: z.string().optional(), ranking: z.string().optional(), verdict: z.string().optional(), tooThin: z.array(z.string()).optional() }).strict(),
+    },
     {
         name: "who_should_i_work_with",
         title: "Who Should I Work With",
@@ -372,6 +390,12 @@ export const TOOL_DEFINITIONS = [
         description: "Demand and supply in one result. Reads the comments on a creator's own recent posts for what their audience explicitly asks for, sweeps the niche for what is already being made, and returns both with ids so an idea can be traced back to the comment that asked for it \u2014 a gap nobody asked for is noise, a request nobody serves is the opportunity. Names the niche from the creator's most-used hashtag when you do not give one. Use to decide what to film; niche_report covers the supply half alone. Consumes 2 nooticr credits for the post list, 2 per post read, and 2 for the sweep \u2014 12 at the default of 4 posts.",
         inputSchema: z.object({ username: z.string().describe("Your handle, with or without @."), platform: z.string().optional().describe("Platform (default tiktok)."), niche: z.string().optional().describe("Niche for the supply sweep. Defaults to your most frequent hashtag."), limit: z.number().int().optional().describe("Your posts to read comments on (default 4, max 8). This is the price."), commentsPerPost: z.number().int().optional().describe("Comments per post (default 25, max 50)."), supplyLimit: z.number().int().optional().describe("Posts in the niche sweep (default 12, max 30).") }).strict(),
     },
+    {
+        name: "find_people_with_problem",
+        title: "Find People With A Problem",
+        description: "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 (\"I spend hours checking competitors by hand\") and this searches for posts shaped like that complaint, not for the topic it is about. That difference is the point: 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 merges what each returns. It is a wide cheap net and NOT a filter: the posts come back for you to judge, and many will be off-target. Consumes 2 nooticr credits per platform searched. Defaults to reddit, where people describe workflow pain in sentences; add twitter for volume.",
+        inputSchema: z.object({ problem: z.string().describe("The problem in a person's own words, not a topic. \"I waste an hour a day checking what competitors posted\" finds people; \"competitor analysis\" finds marketing about competitor analysis."), platforms: z.array(z.enum(["reddit", "twitter", "youtube", "tiktok", "instagram", "linkedin"])).optional().describe("Where to look (default reddit). Each one is a separate paid search."), limit: z.number().int().optional().describe("Posts per query shape (default 6, max 15).") }).strict(),
+    },
     {
         name: "search_spoken_mentions",
         title: "Search Spoken Mentions",