@nooticr/mcp 1.26.79 → 1.26.80

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({