@nooticr/mcp 1.26.79 → 1.26.81

package/dist/shared/jobs.js

@@ -675,7 +675,7 @@ export function registerJobTools(server, makeClient, store) {
             "Costs 2 nooticr credits for the post list plus 2 per post opened — 14 credits at the " +
             "default of 6 posts. Use when the job is to answer people; search_mentions is for what " +
             "strangers say elsewhere.",
-        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: true },
         outputSchema: OUTPUT_SCHEMAS.answer_my_audience,
         inputSchema: z
             .object({
@@ -861,15 +861,14 @@ export function registerJobTools(server, makeClient, store) {
     server.registerTool("track_creator", {
         title: "Track Competitor",
         _meta: viewMeta("track_creator"),
-        description: "Track a competitor, keep an eye on a rival, see how someone is doing lately, catch what " +
-            "they shipped since you last looked — this is the tool for all of those. What a creator " +
-            "shipped recently and which of it beat THEIR OWN baseline: fetches their recent posts " +
+        description: "What a creator shipped recently and which of it beat THEIR OWN baseline: fetches their recent posts " +
             "once and scores each against the median of that same window, because a raw view count " +
             "mostly measures follower count — outperformance against themselves is the signal. If " +
             "they are on your watchlist it also marks what is new since your last track_creator " +
             "call and moves that marker forward. " +
-            "Consumes 2 nooticr credits — one post list, whatever the window size. Use for a rival " +
-            "you follow; analyze_creator_profile is the full teardown of one you do not.",
+            "Consumes 2 nooticr credits — one post list, whatever the window size. Use to track a " +
+            "competitor, keep an eye on a rival, see how someone is doing lately, or catch what they " +
+            "shipped since you last looked; analyze_creator_profile is for a one-off profile teardown.",
         annotations: {
             readOnlyHint: false,
             destructiveHint: true,
@@ -1059,15 +1058,15 @@ export function registerJobTools(server, makeClient, store) {
         title: "Compare Creators",
         _meta: viewMeta("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: " +
+            "than against each other's raw numbers, 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 " +
+            "hard they beat it when they did, every post's ratio, and their highest and lowest 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.",
-        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+            "Use to compare hit rates between two to five creators, yourself included; track_creator covers one creator.",
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: true },
         outputSchema: OUTPUT_SCHEMAS.compare_creators,
         inputSchema: z
             .object({
@@ -1131,13 +1130,13 @@ export function registerJobTools(server, makeClient, store) {
         title: "Watchlist Standings",
         _meta: viewMeta("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 " +
+            "call. 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.",
-        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+            "weekly 'who is accelerating'; catch_up_watchlist lists what is new since the last check.",
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: true },
         outputSchema: OUTPUT_SCHEMAS.watchlist_standings,
         inputSchema: z
             .object({
@@ -1215,7 +1214,7 @@ export function registerJobTools(server, makeClient, store) {
             "per candidate, so the result says so and tells you how to check a finalist yourself. " +
             "Consumes 2 nooticr credits, or 4 with a seed creator. Use to build a list to vet; " +
             "get_similar_creators is the raw lookalike call.",
-        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: true },
         outputSchema: OUTPUT_SCHEMAS.who_should_i_work_with,
         inputSchema: z
             .object({
@@ -1364,7 +1363,7 @@ export function registerJobTools(server, makeClient, store) {
             "quartiles, ratio and percentile — so the answer can be 'this is a normal result, not a " +
             "failure'. Consumes 3 nooticr credits (1 for the post, 2 for the window). Use when you " +
             "have one post and no comparison; compare_social_posts is for two URLs you already picked.",
-        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: true },
         outputSchema: OUTPUT_SCHEMAS.why_did_this_underperform,
         inputSchema: z
             .object({
@@ -1485,7 +1484,7 @@ export function registerJobTools(server, makeClient, store) {
             "Consumes 2 nooticr credits for the post list, 2 per post read for comments, and 2 for the " +
             "niche sweep — 12 at the default of 4 posts. Use to decide what to film; niche_report " +
             "covers the supply half alone.",
-        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: true },
         outputSchema: OUTPUT_SCHEMAS.what_should_i_make_next,
         inputSchema: z
             .object({
@@ -1669,8 +1668,7 @@ export function registerJobTools(server, makeClient, store) {
             "anything: each row is a draft, and a reply is posted only after the creator confirms its " +
             "exact text. Each comment shows with what you decided to do " +
             "about it and your draft underneath, grouped under its post, so they can work through " +
-            "them one at a time and skip the rest. Call this after you have drafted the replies, not " +
-            "instead of drafting them.",
+            "them one at a time and skip the rest. Call this after you have drafted the replies.",
         annotations: {
             readOnlyHint: true,
             destructiveHint: false,
@@ -1810,14 +1808,14 @@ export function registerJobTools(server, makeClient, store) {
         title: "Search Spoken Mentions",
         _meta: viewMeta("search_spoken_mentions"),
         description: "Brand mentions people SAY but never type. search_mentions reads captions, post bodies " +
-            "and comments — text — so a video that names a brand only out loud is invisible to it. " +
+            "and comments — text — so it does not see a brand named only out loud in a video. " +
             "This reads the words actually spoken, from the platform's own caption track (not our own " +
             "speech recognition — see get_post_transcript), and searches them for a term. Narrows to " +
             "candidate posts first (a niche/keyword sweep, named creator handles, and/or your " +
             "watchlist), transcribes only the most-viewed survivors up to a hard ceiling you set, and " +
             "returns the matched line with surrounding context so tone can be judged. TikTok, YouTube " +
-            "and Douyin — the networks whose post detail already carries a caption track, which is " +
-            "what makes a transcript one cheap read rather than a wait. Every other network's audio " +
+            "and Douyin — the networks whose post detail already carries a caption track, so a " +
+            "transcript is read directly rather than waited for. Every other network's audio " +
             "can be transcribed too, at the same price, but not yet from here: see " +
             "get_post_transcript for that route. Even on these three a video whose creator disabled " +
             "captions is invisible to this tool; coverage is real but " +
@@ -1828,7 +1826,7 @@ export function registerJobTools(server, makeClient, store) {
             "count. Above 6 credits worst-case it asks first, like search_mentions. Use when a term " +
             "might be spoken on camera but not written anywhere; search_mentions is for what people " +
             "typed.",
-        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: true },
         outputSchema: OUTPUT_SCHEMAS.search_spoken_mentions,
         inputSchema: z
             .object({
@@ -2130,14 +2128,14 @@ export function registerJobTools(server, makeClient, store) {
         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. " +
+            "that complaint, not for the topic it is about. Searching the TOPIC returns marketing " +
+            "about it; discover_social_posts covers that. " +
             "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 " +
+            "It is a broad search and NOT a filter: the posts come back for you to judge, and " +
             "many will be off-target. Consumes 2 nooticr credits per search, and each platform is searched once per query shape — three by default, so 6 credits per platform. Defaults to " +
-            "reddit, where people describe workflow pain in sentences; add twitter for volume. Not searchable here: linkedin.",
-        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+            "reddit, where people describe workflow pain in sentences; add twitter for volume. Not searchable here: linkedin. Use to find prospects or early users by the way they describe a problem.",
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: true },
         outputSchema: OUTPUT_SCHEMAS.find_people_with_problem,
         inputSchema: z
             .object({

package/dist/shared/loading-plans.js

@@ -503,6 +503,11 @@ export const LOADING_PLANS = {
     list_employees: { label: "Reading your employees", kind: "list", n: 3, steps: [], free: true },
     pause_employee: { label: "Updating the employee", kind: "text", n: 1, steps: [], free: true },
     fire_employee: { label: "Letting the employee go", kind: "text", n: 1, steps: [], free: true },
+    // Creator CRM (crm.ts): free, and none of it fetches.
+    crm_upsert_creator: { label: "Saving the creator", kind: "text", n: 1, steps: [], free: true },
+    crm_list_creators: { label: "Reading your creator pipeline", kind: "list", n: 3, steps: [], free: true },
+    crm_update_status: { label: "Updating the creator's status", kind: "text", n: 1, steps: [], free: true },
+    crm_log_interaction: { label: "Logging the interaction", kind: "text", n: 1, steps: [], free: true },
     list_pending_actions: { label: "Reading what awaits approval", kind: "list", n: 3, steps: [], free: true },
     get_employee_audit: { label: "Reading the audit trail", kind: "list", n: 3, steps: [], free: true },
     approve_action: { label: "Approving the action", kind: "text", n: 1, steps: [], free: true },

package/dist/shared/marketplace.js

@@ -274,7 +274,7 @@ export function registerMarketplaceTools(server, makeClient) {
             "repeating until the scan is done. Never conclude, or end your turn, on an incomplete " +
             "scan: a read of 4 of 10 listings presented as the category is wrong. " +
             "For Amazon specifically, scan_amazon_category returns the same shape plus Amazon's own " +
-            "review-aspect counts.",
+            "review-aspect counts. Use for a category or a competitive set on one of these marketplaces; get_marketplace_product reads one product.",
         annotations: {
             readOnlyHint: false,
             destructiveHint: false,
@@ -407,7 +407,7 @@ export function registerMarketplaceTools(server, makeClient) {
             "of the same marketplace and `query`, so it fetches nothing and never re-scans — run " +
             "scan_marketplace_category first, and again later, to have two runs to compare. `new` and " +
             "`gone` mean entered or left the results, not listed or delisted. A category scanned only " +
-            "once has no earlier run and says so. Free.",
+            "once has no earlier run and says so. Free. Use when the user asks what changed in a category since an earlier scan.",
         annotations: {
             readOnlyHint: true,
             destructiveHint: false,
@@ -442,7 +442,7 @@ export function registerMarketplaceTools(server, makeClient) {
     server.registerTool("get_price_history", {
         title: "Get Price History",
         description: "One product's price over time — or its rating, review count or availability with `metric` — " +
-            "from the observations stored each time the product was scanned. `marketplace` and `id` name " +
+            "from the observations stored each time the product was scanned. Use when someone asks how a product's price, rating, review count or stock moved over time. `marketplace` and `id` name " +
             "the product the same way get_marketplace_product does; `from` and `to` take dates (default: " +
             "the last 30 days). Returns the points oldest first with min, max, first, last and the " +
             "percentage change from first to last. A point is stored only when something changed, so the " +
@@ -498,7 +498,7 @@ export function registerMarketplaceTools(server, makeClient) {
         annotations: {
             readOnlyHint: true,
             destructiveHint: false,
-            idempotentHint: true,
+            idempotentHint: false,
             openWorldHint: true,
         },
         outputSchema: OUTPUT_SCHEMAS.get_marketplace_product,
@@ -549,7 +549,7 @@ export function registerMarketplaceTools(server, makeClient) {
             "cite that the scan does not contain is flagged. Without a scanId, listings you pass are " +
             "drawn marked as not checked against a scan. Free. Your read is attributed to you, never " +
             "presented as a nooticr rating of anyone's product. For Amazon scans use " +
-            "show_amazon_category_insights. Call this after you have read the reviews, not instead of reading them.",
+            "show_amazon_category_insights. Call this after you have read the reviews and written the read.",
         annotations: {
             readOnlyHint: true,
             destructiveHint: false,

package/dist/shared/output-schemas.js

@@ -1785,6 +1785,11 @@ export const OUTPUT_SCHEMAS = {
         action: anyObject().nullish(),
     }),
     reject_action: open({ rejected: scalar(), action: anyObject().nullish() }),
+    // Creator CRM (nooticr-server E1): the creator/interaction views are the server's own shapes.
+    crm_upsert_creator: open({ creator: anyObject().nullish() }),
+    crm_list_creators: open({ creators: listOf(open({ id: scalar(), platform: scalar(), handle: scalar(), status: scalar() })) }),
+    crm_update_status: open({ creator: anyObject().nullish() }),
+    crm_log_interaction: open({ interaction: anyObject().nullish() }),
     list_employees: open({ employees: listOf(open({ id: scalar(), name: scalar(), status: scalar() })) }),
     list_pending_actions: open({ actions: listOf(open({ id: scalar(), employeeId: scalar() })) }),
     // AU1 (nooticr-server employees/mcp.rs get_employee_audit; event shape from employee_audit_view::event_view).

package/dist/shared/own-account.js

@@ -154,7 +154,7 @@ export function registerOwnAccountTools(server, makeClient) {
         description: "Patch your own product's fields — omitted arguments leave their column unchanged. Takes " +
             "appId (optional when your workspace has only one product); every other field is " +
             "snake_case, the same names create_product takes and for the same reason — the backend " +
-            "reads them by exact key. Free — no AI call, just a row.",
+            "reads them by exact key. Free — no AI call, just a row. Use when the user wants to change details of a product that already exists.",
         annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
         inputSchema: z
             .object({
@@ -191,7 +191,7 @@ export function registerOwnAccountTools(server, makeClient) {
         title: "Get Scheduled Posts",
         description: "Your own scheduled and draft posts in the content pipeline — title, status, scheduled " +
             "time, approval status. What is queued to publish, not what already has (see " +
-            "get_post_performance for that). Does not publish or change anything. No cost to call.",
+            "get_post_performance for that). Does not publish or change anything. No cost to call. Use when the user asks what is queued or drafted in their content pipeline.",
         _meta: viewMeta("get_scheduled_posts"),
         annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
         inputSchema: z
@@ -218,7 +218,7 @@ export function registerOwnAccountTools(server, makeClient) {
         title: "Get Post Performance",
         description: "Your own already-published posts with their engagement counters — views, likes, " +
             "comments, shares, platform, post date. This is the raw performance history, not an " +
-            "interpretation of it; pair with growth_brief for that. No cost to call.",
+            "interpretation of it; pair with growth_brief for that. No cost to call. Use when the user asks how their own published posts performed.",
         _meta: viewMeta("get_post_performance"),
         annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
         inputSchema: z
@@ -245,7 +245,7 @@ export function registerOwnAccountTools(server, makeClient) {
         title: "Get Video Stats",
         description: "Your own most recently synced video performance stats across every connected creator — " +
             "views, likes, comments, shares, plus a running total. Reads the last sync; does not " +
-            "trigger a new one. No cost to call.",
+            "trigger a new one. No cost to call. Use when the user asks for their own synced video numbers.",
         _meta: viewMeta("get_video_stats"),
         annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
         inputSchema: z
@@ -285,7 +285,7 @@ export function registerOwnAccountTools(server, makeClient) {
         title: "Get Content Plan",
         description: "The saved weekly content plan for your own product, if one has been generated (see " +
             "generate_content_plan). Read-only and free even when a plan exists — generating a new " +
-            "one is the paid step. Returns plan: null when none has been made yet. No cost to call.",
+            "one is the paid step. Returns plan: null when none has been made yet. No cost to call. Use when the user asks to see the content plan already generated for their product.",
         _meta: viewMeta("get_content_plan"),
         annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
         inputSchema: z
@@ -316,7 +316,7 @@ export function registerOwnAccountTools(server, makeClient) {
         description: "Your own product's brand playbook — name, description and the playbook text — if one has " +
             "been configured, in the dashboard or by a previous analyze_product run. Read-only: never " +
             "creates or edits a playbook itself. Returns available: false when none exists yet. Takes " +
-            "appId (optional when your workspace has only one product). No cost to call.",
+            "appId (optional when your workspace has only one product). No cost to call. Use when a task needs the product's stored brand voice or positioning.",
         _meta: viewMeta("get_brand_playbook"),
         annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
         inputSchema: z
@@ -388,7 +388,8 @@ export function registerOwnAccountTools(server, makeClient) {
         "themselves (installs, opens, purchases, revenue) feed get_post_performance and growth_brief " +
         "rather than being repeated here. Returns a message rather than an error when nothing has " +
         "ever been synced; connect GA4 in API Connections first. Takes appId (optional when your " +
-        "workspace has only one product). No cost to call.");
+        "workspace has only one product). No cost to call. Use to check whether GA4 data is synced " +
+        "and for which dates.");
     connectorRead("get_search_console_data", "search_console", "Get Search Console Data", "Your own product's Google Search Console data — total clicks and impressions and the top " +
         "search queries — as of its last sync into nooticr, not a live Search Console call. Use it " +
         "to see whether people search for what your social content is about. Returns a message " +
@@ -411,7 +412,7 @@ export function registerOwnAccountTools(server, makeClient) {
             "background: returns a jobId immediately rather than the finished analysis — poll it with " +
             "analyze_product_status. Billed like the dashboard's own analyze job: 10 of your " +
             "workspace's plan AI credits (first analysis free per workspace), a different balance from " +
-            "your personal MCP credits and not tracked by check_nooticr_credits.",
+            "your personal MCP credits and not tracked by check_nooticr_credits. Use when the user wants a brand playbook generated or refreshed for their product.",
         // Not view-less for lack of trying: the immediate reply is only a
         // jobId and state: "pending", nothing to draw yet. analyze_product_status,
         // which returns the finished playbook, is where the view belongs — see
@@ -440,7 +441,7 @@ export function registerOwnAccountTools(server, makeClient) {
         title: "Analyze Product Status",
         description: "Poll a job started by analyze_product. Takes jobId. Returns state (pending, thinking, " +
             "done, error) and, once done, the generated analysis/brand playbook. Free to poll — the " +
-            "cost was already charged when analyze_product started the job.",
+            "cost was already charged when analyze_product started the job. Use after analyze_product, until the job reports done or error.",
         _meta: viewMeta("analyze_product_status"),
         annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
         inputSchema: z
@@ -467,13 +468,13 @@ export function registerOwnAccountTools(server, makeClient) {
             "appId plus the draft fields to review something that only exists as arguments. Nothing is " +
             "published. If the AI reviewer is unavailable the result carries degraded: true and a " +
             "warning — treat those scores as generic placeholders, never as real feedback. Free — " +
-            "nothing is billed for this, same as the dashboard's own pre-publish review.",
+            "nothing is billed for this, same as the dashboard's own pre-publish review. Use when the user wants feedback on a post before publishing it.",
         _meta: viewMeta("review_post"),
         // Not read-only: given a postId the backend saves the review and score
         // onto that scheduled post (`save_ai_review`), overwriting whatever was
         // there. Free, which is not the same thing — a host that auto-approves
         // read-only tools would let this rewrite pipeline data unattended.
-        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
         inputSchema: z
             .object({
             postId: z.number().int().optional().describe("A post already in your pipeline. Alternative to appId + draft fields."),
@@ -505,9 +506,9 @@ export function registerOwnAccountTools(server, makeClient) {
             "schedule anything — this only returns the draft text for you to present, refine, or hand " +
             "to a tool that persists it. Billed like the dashboard's own Draft Post button: consumes " +
             "your workspace's plan AI credits, a different balance from your personal MCP credits and " +
-            "not tracked by check_nooticr_credits.",
+            "not tracked by check_nooticr_credits. Use when the user asks for a post written for their own product.",
         _meta: viewMeta("draft_post"),
-        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: false },
         inputSchema: z
             .object({
             appId: z
@@ -537,13 +538,13 @@ export function registerOwnAccountTools(server, makeClient) {
             "plus whatever analytics (GA4, Search Console, PostHog) and fleet analysis you have " +
             "synced. It changes nothing of yours, but it is not free: billed like the dashboard's own " +
             "Growth Brief button, from your workspace's plan AI credits rather than your personal " +
-            "MCP credits.",
+            "MCP credits. Use when the user asks how their product's social presence is doing and what to do next.",
         _meta: viewMeta("growth_brief"),
         // Spending the workspace's plan AI credits (`CREDIT_GROWTH_BRIEF`) is
         // what puts this outside read-only, by the same rule that already
         // covers draft_post and generate_content_plan. It writes no content of
         // the user's, which is why the description says so in those words.
-        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: false },
         inputSchema: z
             .object({
             appId: z
@@ -569,7 +570,7 @@ export function registerOwnAccountTools(server, makeClient) {
             "a hook, caption, hashtags and a full production script for each, grounded in what already " +
             "worked in your post history. Saves the generated plan (fetch it later with the free " +
             "get_content_plan) but does not schedule or publish any post. Billed like the dashboard's " +
-            "own Content Plan button: your workspace's plan AI credits, not your personal MCP credits.",
+            "own Content Plan button: your workspace's plan AI credits, not your personal MCP credits. Use when the user asks for a week of planned posts for their product.",
         _meta: viewMeta("generate_content_plan"),
         annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
         inputSchema: z
@@ -601,11 +602,11 @@ export function registerOwnAccountTools(server, makeClient) {
         description: "Generate timed on-screen caption cues for a video on your own product — a transcript " +
             "plus start/end-timed lines. Does not burn captions onto any video or touch stored media; " +
             "only returns the cue data. If no AI provider is configured the result carries " +
-            "provider: \"mock\" placeholder captions instead of failing — check that field before " +
+            "provider: \"mock\" placeholder captions rather than an error — check that field before " +
             "treating the captions as real. Billed like the dashboard's own Generate Captions button: " +
-            "your workspace's plan AI credits, not your personal MCP credits.",
+            "your workspace's plan AI credits, not your personal MCP credits. Use when the user needs timed on-screen captions for one of their videos.",
         _meta: viewMeta("generate_captions"),
-        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: false },
         inputSchema: z
             .object({
             appId: z

package/dist/shared/replies.js

@@ -35,7 +35,7 @@ export function registerReplyTools(server, makeClient) {
             "connected with capabilities: [\"manage_comments\"] (see connect_social_account); networks " +
             "that cannot be answered come back under `unsupported` with the reason. Optional platform, " +
             "influencerId, postId, sinceDays (1-30, default 7), limit (1-100, default 30), " +
-            "includeAnswered. Read-only: it sends nothing. No cost to call.",
+            "includeAnswered. Read-only: it sends nothing. No cost to call. Use when the user wants to reply to comments on their own connected account.",
         annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
         outputSchema: OUTPUT_SCHEMAS.list_comments_to_answer,
         inputSchema: z
@@ -64,7 +64,7 @@ export function registerReplyTools(server, makeClient) {
             "posted. Pass `text` to use the user's own wording (no cost), or omit it and nooticr " +
             "writes one (costs 1 nooticr credit); `guidance` steers the writing. Replies may not contain links, " +
             "emails, phone numbers or @-mentions of anyone but the commenter. Returns a draftId and a " +
-            "confirmationToken: show the reply to the user first, then post it with post_comment_reply.",
+            "confirmationToken: show the reply to the user first, then post it with post_comment_reply. Use when the user wants to answer one comment from list_comments_to_answer.",
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
         outputSchema: OUTPUT_SCHEMAS.draft_comment_reply,
         inputSchema: z
@@ -93,7 +93,7 @@ export function registerReplyTools(server, makeClient) {
             "has seen and agreed to the exact text: pass the draftId, confirm: true and the " +
             "confirmationToken from draft_comment_reply. Each comment is answered at most once and " +
             "daily limits apply. It writes to a third-party network and cannot be undone from here. " +
-            "No cost to call.",
+            "No cost to call. Use only once the user has approved a draft's exact text.",
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
         outputSchema: OUTPUT_SCHEMAS.post_comment_reply,
         inputSchema: z

package/dist/shared/sheets.js

@@ -29,6 +29,8 @@ const cell = z
 const rows = z.array(z.array(cell));
 const READ = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true };
 const WRITE = { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true };
+// Overwriting a range replaces whatever the cells held, which append and add-sheet never do.
+const OVERWRITE = { ...WRITE, destructiveHint: true };
 export function registerSheetsTools(server, makeClient) {
     const passthrough = (name) => async (args, extra) => {
         const client = await makeClient({ ...extra, arguments: args });
@@ -43,7 +45,7 @@ export function registerSheetsTools(server, makeClient) {
         title: "Create Spreadsheet",
         description: "Create a Google spreadsheet in the connected Google account, with the named sheets and a header row on each. " +
             "Returns its id and URL; Nooticr owns the file, so later writes need no approval. " +
-            "Requires the product's Google Sheets connection. Free.",
+            "Requires the product's Google Sheets connection. Free. Use when the user wants results written to a new Google spreadsheet.",
         annotations: WRITE,
         inputSchema: z
             .object({
@@ -60,7 +62,7 @@ export function registerSheetsTools(server, makeClient) {
     server.registerTool("sheets_list", {
         title: "List Spreadsheets",
         description: "List the spreadsheets this connection can see: the ones Nooticr created and the ones the customer picked. " +
-            "Each says whether it was created or picked and whether the employee may edit it without approval. Free.",
+            "Each says whether it was created or picked and whether the employee may edit it without approval. Free. Use to find a spreadsheet's id before reading or writing it.",
         annotations: READ,
         inputSchema: z.object({ appId, limit: z.number().int().min(1).max(100).optional() }).strict(),
         outputSchema: OUTPUT_SCHEMAS.sheets_list,
@@ -72,7 +74,7 @@ export function registerSheetsTools(server, makeClient) {
             'and a range open at the bottom ("A:F", "Ledger!$A:$F") or longer than the cap is cut to the rows that fit, ' +
             "with truncated=true when more may remain: read further down with a range that starts after the last row. " +
             'A bare name without quotes ("Expenses") is passed to Google as written, since it may be a named range, ' +
-            'so name a tab as "Ledger!A:F" or "\'My Tab\'" to have it bounded. Free.',
+            'so name a tab as "Ledger!A:F" or "\'My Tab\'" to have it bounded. Free. Use when the user asks about data held in one of their connected spreadsheets.',
         annotations: READ,
         inputSchema: z.object({ appId, id: spreadsheetId, range: z.string() }).strict(),
         outputSchema: OUTPUT_SCHEMAS.sheets_read,
@@ -81,7 +83,7 @@ export function registerSheetsTools(server, makeClient) {
         title: "Append Spreadsheet Rows",
         description: "Append rows after the last row of a sheet (tab). Values are typed: numbers stay numbers and ISO dates become sheet dates. " +
             "At most 10000 cells per call. Free on a file Nooticr created or one the customer allowed you to edit; " +
-            "on any other file the customer picked it waits for their approval.",
+            "on any other file the customer picked it waits for their approval. Use to add new rows below the existing data in a sheet.",
         annotations: WRITE,
         inputSchema: z.object({ appId, id: spreadsheetId, sheet: z.string().describe("Tab name."), rows }).strict(),
         outputSchema: OUTPUT_SCHEMAS.sheets_append_rows,
@@ -89,14 +91,14 @@ export function registerSheetsTools(server, makeClient) {
     server.registerTool("sheets_update_range", {
         title: "Update Spreadsheet Range",
         description: 'Overwrite a range (A1 notation, e.g. "Ledger!B2:C3") with values. Typed like sheets_append_rows; ' +
-            "at most 10000 cells per call. Same approval rule as sheets_append_rows: free on a file Nooticr created or one the customer allowed you to edit, otherwise it waits for their approval.",
-        annotations: WRITE,
+            "at most 10000 cells per call. Same approval rule as sheets_append_rows: free on a file Nooticr created or one the customer allowed you to edit, otherwise it waits for their approval. Use to change values that are already in a sheet.",
+        annotations: OVERWRITE,
         inputSchema: z.object({ appId, id: spreadsheetId, range: z.string(), values: rows }).strict(),
         outputSchema: OUTPUT_SCHEMAS.sheets_update_range,
     }, passthrough("sheets_update_range"));
     server.registerTool("sheets_add_sheet", {
         title: "Add Spreadsheet Tab",
-        description: "Add an empty sheet (tab) to a spreadsheet. Same approval rule as sheets_append_rows: free on a file Nooticr created or one the customer allowed you to edit, otherwise it waits for their approval.",
+        description: "Add an empty sheet (tab) to a spreadsheet. Same approval rule as sheets_append_rows: free on a file Nooticr created or one the customer allowed you to edit, otherwise it waits for their approval. Use when a spreadsheet needs a new tab.",
         annotations: WRITE,
         inputSchema: z.object({ appId, id: spreadsheetId, name: z.string() }).strict(),
         outputSchema: OUTPUT_SCHEMAS.sheets_add_sheet,

package/dist/shared/store-read.js

@@ -40,7 +40,7 @@ export function registerStoreReadTools(server, makeClient) {
             "shop \"your-store.myshopify.com\"). Optionally appId ties the store to one product. The " +
             "owner approves at Amazon or Shopify; nothing is connected until they do, and no " +
             "credential passes through this tool. Nooticr only asks for access to listing copy and " +
-            "prices. Each call mints a fresh link. No cost to call.",
+            "prices. Each call mints a fresh link. No cost to call. Use when the user wants to connect their Amazon or Shopify store.",
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
         inputSchema: z
             .object({
@@ -60,7 +60,7 @@ export function registerStoreReadTools(server, makeClient) {
             "exact SKU; Shopify: product search), limit (up to 50), cursor from nextCursor, " +
             "productRef to read one product by SKU or GID, includeIssues, includePricing (Amazon). " +
             "For Amazon, source \"report\" reads the whole catalogue through a report: it answers " +
-            "status in_progress with a reportId and poll arguments until done. Read-only. No cost to call.",
+            "status in_progress with a reportId and poll arguments until done. Read-only. No cost to call. Use when the user asks about the products in their connected store.",
         annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
         inputSchema: z
             .object({