@cite42/mcp 0.7.0 → 0.8.0

package/README.md

@@ -138,7 +138,7 @@ Cite42 exposes 29 MCP tools: 4 free account tools (including the compatibility a
 ### Account & pricing (free)
 
 - `cite42_balance`: check the connected account’s remaining Cite42 balance in USD.
-- `cite42_credits`: compatibility alias for older integrations.
+- `cite42_credits`: alias of `cite42_balance` for older integrations.
 - `cite42_pricing`: get current per-tool prices and estimate a planned set of calls.
 - `cite42_usage`: read recent call status and cost together with the remaining balance.
 
@@ -156,7 +156,7 @@ Cite42 exposes 29 MCP tools: 4 free account tools (including the compatibility a
 - `cite42_keywords`: get seed search volume, CPC, and competition, with optional related keyword ideas.
 - `cite42_keywords_batch`: check volume, CPC, and competition for two to 50 seed keywords in one request; billed by outcome (call `cite42_pricing` for rates).
 - `cite42_trends`: get Google Trends interest over time, related and rising queries, and a trend label.
-- `cite42_reddit_trends`: find relevant Reddit discussions and supported questions, pain points, and product mentions, with source quotes. Uses a limited sample of titles and excerpts, not complete comment conversations or measured growth. Read `relevantThreads`; `risingThreads` remains a deprecated compatibility alias. Check `analysis.status` and `warnings` for coverage and analysis failures.
+- `cite42_reddit_trends`: find relevant Reddit discussions with cited summaries and read up to three pages through Gemini URL context. Returns page titles, authors, post excerpts, relative ages, available scores/comment counts and sampled human comments. Pages may be cached and model extraction is not independently verified. Exact dates, growth and quote-based insight arrays remain unavailable. Read `relevantThreads`; `risingThreads` is a deprecated compatibility alias. Check `coverage` and `warnings` for missing fields and out-of-window threads.
 - `cite42_youtube_trends`: find YouTube rising videos, creator angles, title patterns, and opportunities.
 
 ### Research workflows (multi-source, one call)
@@ -213,17 +213,15 @@ smoke test against a loopback fake API. See [local MCP testing](../../docs/mcp-t
 - Docs: [Cite42 API & MCP documentation](https://www.cite42.dev/docs)
 - Pricing: [Cite42 pay-per-call pricing](https://www.cite42.dev/pricing)
 
-### USD billing and older clients
+### USD billing
 
-Quote the `cite42Billing` block for the amount charged and remaining Cite42 balance.
-Its `chargedUsd` and `remainingUsd` values are decimal strings in USD. Legacy
-`cite42Credits` numbers keep their original units for compatibility.
+Every paid result carries a `cite42Billing` block with the amount charged and the remaining
+Cite42 balance. Its `chargedUsd` and `remainingUsd` values are decimal strings in USD.
+Credits are retired: since 0.8.0 the package no longer returns `cite42Credits`, and
+`cite42_credits` answers exactly like `cite42_balance`.
 
-Call `cite42_pricing` with `{ "currency": "USD" }` for dollar prices. With no argument,
-the legacy table is preserved and dollar prices are in the `usd` block.
-REST clients can use `GET /v1/pricing?currency=USD`; the default REST response remains
-compatible with existing installations. Update the MCP package to receive the new
-USD guidance and `cite42_balance` tool. Tracker activation still accepts the exact
+`cite42_pricing` always returns the USD price table; an older `currency` argument is ignored.
+REST clients can use `GET /v1/pricing?currency=USD`. Tracker activation still accepts the exact
 integer `maxCostMicroPerRun` returned by the API; present its USD equivalent to users.
 
 ## Optional AI visibility recommendations

package/dist/stdio.cjs

@@ -3,7 +3,7 @@
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://www.cite42.dev/api/v1";
-var MICRO_CREDITS_PER_CREDIT = 1e3;
+var FUNDS_LOCATION = "the Cite42 dashboard at https://www.cite42.dev/app";
 function toUsd(micro) {
   const [whole, fraction = ""] = (micro / 1e5).toFixed(5).split(".");
   return `${whole}.${fraction.slice(0, Math.max(2, fraction.replace(/0+$/, "").length))}`;
@@ -20,16 +20,6 @@ function toCite42Balance(micro) {
 function isJsonObject(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function toCredits(microCredits) {
-  return microCredits / MICRO_CREDITS_PER_CREDIT;
-}
-function formatCredits(microCredits) {
-  const credits = toCredits(microCredits);
-  return credits.toLocaleString(
-    "en-US",
-    Number.isInteger(credits) ? { maximumFractionDigits: 0 } : { minimumFractionDigits: 0, maximumFractionDigits: 2 }
-  );
-}
 function isTrackerCommitment(billing) {
   return typeof billing.balanceMicro === "number" && typeof billing.costMicroPerRun === "number";
 }
@@ -53,38 +43,17 @@ function toCite42McpResult(value) {
     ...replay ? { originalChargedUsd: toUsd(originalCost) } : {},
     message: (replay ? `Replay of an identical request from the last 2 minutes. This attempt was free; $${toUsd(originalCost)} USD was charged once, by the original Cite42 call.` : `Cite42: $${toUsd(cost)} USD charged; $${toUsd(balance)} USD remaining.`) + lowBalanceNotice
   };
-  const lowCredits = typeof warning === "string";
-  const message = `Cite42 credits: ${formatCredits(cost)} charged; ${formatCredits(balance)} remaining.`;
-  return {
-    ...result,
-    cite42Billing,
-    // Legacy numeric fields retain their original units for existing integrations.
-    cite42Credits: {
-      charged: toCredits(cost),
-      remaining: toCredits(balance),
-      ...replay ? { originalCharged: toCredits(originalCost) } : {},
-      message: replay ? `Replay of an identical request from the last 2 minutes. This attempt was free; ${toCredits(originalCost)} credits were charged once, by the original call.` : lowCredits ? `${message} Low Cite42 credit balance.` : message
-    }
-  };
-}
-function toCite42CreditsBalance(balanceMicroCredits) {
-  return {
-    ...toCite42Balance(balanceMicroCredits),
-    cite42Credits: {
-      remaining: toCredits(balanceMicroCredits),
-      message: `Cite42 credits: ${formatCredits(balanceMicroCredits)} remaining. This balance check was free.`
-    }
-  };
+  return { ...result, cite42Billing };
 }
 function errorMessageForMcp(status, path, body) {
   try {
     const payload = JSON.parse(body);
     if (isJsonObject(payload) && isJsonObject(payload.error) && typeof payload.error.code === "string") {
       if (payload.error.code === "daily_limit_exceeded" || payload.error.code === "monthly_limit_exceeded") {
-        return "Cite42 spending limit reached. Adjust your limit at https://www.cite42.dev/app/billing.";
+        return `Cite42 spending limit reached. Change it in ${FUNDS_LOCATION}.`;
       }
       if (payload.error.code === "insufficient_credits") {
-        return "Insufficient Cite42 balance. Add funds at https://www.cite42.dev/app/billing.";
+        return `Insufficient Cite42 balance. Add funds in ${FUNDS_LOCATION}.`;
       }
     }
   } catch {
@@ -176,18 +145,18 @@ var modelEnum = import_zod.z.enum(["chatgpt", "claude", "perplexity", "gemini",
 var QUERY_MAX_CHARS = 2e3;
 var SHORT_TEXT_MAX_CHARS = 200;
 var TIMEFRAME_MAX_CHARS = 80;
-var MODEL_SELECTION_DESCRIPTION = 'Optional model subset. Omit to query the default surfaces (chatgpt, perplexity, gemini). Pass ["perplexity"] or ["perplexity","claude"] when the user names specific surfaces or wants to reduce cost. The full set is chatgpt, claude, perplexity, gemini, google_ai_overview \u2014 to query all of them, set fullSweep instead of listing them.';
-var FULL_SWEEP_DESCRIPTION = "Query all five AI surfaces instead of the three default ones, adding claude and google_ai_overview. Costs more per call. Use it when the user wants complete cross-model coverage, is comparing surfaces against each other, or asks specifically about Claude or Google AI Overviews. Ignored when models is given.";
-var MCP_USAGE_GUIDANCE = "Covers AI-search, citation, SEO, keyword, trend, and market-research data. If a plan needs more than 20 endpoint calls or may use more than $5 USD, estimate the cost in USD and ask the user before continuing. Quote Cite42 costs and balances in USD using cite42Billing or the USD pricing table. Legacy credit fields are for compatibility only. These funds belong to Cite42, not the host or model provider. AI visibility metrics include counts; quote them with percentages, not as a market-wide score. Optional recommendations are a separate paid call, never automatic. Recommendations take the requestId of a visibility result and the page URL, or a page URL alone for a free technical check; they run only when the user requests advice and knows any additional cost. Free: cite42_balance for the remaining balance, cite42_pricing for exact per-tool prices and cost estimates, cite42_usage for recent calls.";
-var MODEL_PRICING = "Pricing is per selected AI surface. Omitting models queries the three default surfaces (chatgpt, perplexity, gemini); fullSweep: true queries all five, adding claude and google_ai_overview at a higher cost. Use the models field when the user names a surface or asks to reduce spending, and call cite42_pricing for exact current rates.";
-var DATA_PRICING = "Data tools have flat per-call prices; call cite42_pricing for exact current rates.";
-var KEYWORDS_PRICING = "Pricing: billed by outcome \u2014 cheapest when the seed has no search volume, more when it has metrics, most with ideas:true. Call cite42_pricing for exact current rates.";
-var WORKFLOW_PRICING = "Pricing: workflow cost is calculated from the tools that run successfully and the selected model rates.";
+var MODEL_SELECTION_DESCRIPTION = "AI surfaces to query, each billed separately; pass a subset when the user names surfaces or wants a lower cost. Omit for the defaults (chatgpt, perplexity, gemini); fullSweep queries all five. google_ai_overview accepts queries up to 700 characters, the others 2000.";
+var FULL_SWEEP_DESCRIPTION = "Query all five AI surfaces (adds claude and google_ai_overview) for full cross-surface coverage, at a higher cost. Ignored when models is given.";
+var PAID_TOOL_BILLING = "Billed in USD (result field cite42Billing) to the user's prepaid Cite42 balance; exact prices from cite42_pricing (free). For plans over 20 calls or $5, estimate the cost and confirm with the user first.";
+var RECOMMENDATIONS_INPUT_NOTE = "Its requestId can be passed to cite42_recommendations when the user asks for improvement advice.";
+var MODEL_PRICING = "Priced per AI surface queried.";
+var KEYWORDS_PRICING = "Billed by outcome: cheapest when the seed has no search volume, more when it has metrics, most with ideas:true.";
+var WORKFLOW_PRICING = "Billed for the steps that succeed, at per-surface rates.";
 function workflowDescription(description) {
-  return `${description} ${MCP_USAGE_GUIDANCE} ${MODEL_PRICING} ${DATA_PRICING} ${WORKFLOW_PRICING}`;
+  return `${description} ${WORKFLOW_PRICING} ${PAID_TOOL_BILLING}`;
 }
 function readOnly(title, openWorldHint = true) {
-  return { annotations: { title, readOnlyHint: true, openWorldHint } };
+  return { annotations: { title, readOnlyHint: true, destructiveHint: false, openWorldHint } };
 }
 function mutation(title, options = {}) {
   return {
@@ -209,7 +178,7 @@ function shortText(description) {
 var aivRecommendations = (0, import_tools.createTool)({
   id: "cite42_recommendations",
   mcp: readOnly("Recommend AI visibility next steps"),
-  description: "Page-level AI visibility recommendations. With a saved result (requestId, trackerRunId or evidence) it reports on one measured prompt, charged only when the report includes page-comparison advice backed by quotes from inspected pages. Without one: url alone runs a free technical check of the page (robots.txt crawler access, indexing, rendering) and returns suggested buyer questions; url with query first runs a citations check, priced like cite42_citations, then the report. Prices are in cite42_pricing. Fetches the page, its robots.txt and up to two pages the AI surfaces cited, as returned HTML without JavaScript. No site-wide crawl, keyword advice or tracker activation. " + MCP_USAGE_GUIDANCE,
+  description: "Page-level AI visibility recommendations, for when the user asks how to improve a page. With a saved result (requestId, trackerRunId or evidence) it reports on one measured prompt, charged only when the report includes page-comparison advice backed by quotes from inspected pages. Without one: url alone runs a free technical check of the page (robots.txt crawler access, indexing, rendering) and returns suggested buyer questions; url with query first runs a citations check, priced like cite42_citations, then the report. Prices are in cite42_pricing. Fetches the page, its robots.txt and up to two pages the AI surfaces cited, as returned HTML without JavaScript. No site-wide crawl, keyword advice or tracker activation. " + PAID_TOOL_BILLING,
   inputSchema: import_zod.z.object({
     requestId: import_zod.z.string().trim().min(1).max(128).optional().describe("A requestId from your own successful Cite42 call within the last 30 days."),
     trackerRunId: import_zod.z.string().trim().min(1).max(128).optional().describe("A specific finished run of your own tracker within the last 30 days."),
@@ -249,60 +218,52 @@ function optionalShortText(description) {
 var modelsInput = import_zod.z.array(modelEnum).nonempty().optional().describe(MODEL_SELECTION_DESCRIPTION);
 var fullSweepInput = import_zod.z.boolean().optional().describe(FULL_SWEEP_DESCRIPTION);
 var competitorList = import_zod.z.array(shortText("Competitor brand/domain name.")).nonempty().max(20);
+async function fetchBalance() {
+  const usage = await aivGet("/usage");
+  const micro = usage.balance?.microCredits;
+  if (typeof micro !== "number" || !Number.isFinite(micro)) {
+    throw new Error("Cite42 usage response did not include a balance.");
+  }
+  return toCite42Balance(micro);
+}
 var aivBalance = (0, import_tools.createTool)({
   id: "cite42_balance",
   mcp: readOnly("Check Cite42 balance", false),
-  description: "Check the remaining Cite42 balance for the connected account. Free. " + MCP_USAGE_GUIDANCE,
+  description: "Check the remaining Cite42 balance in USD for the connected account. Free.",
   inputSchema: import_zod.z.object({}),
-  execute: async () => {
-    const usage = await aivGet("/usage");
-    const microCredits = usage.balance?.microCredits;
-    if (typeof microCredits !== "number" || !Number.isFinite(microCredits)) {
-      throw new Error("Cite42 usage response did not include a balance.");
-    }
-    return toCite42Balance(microCredits);
-  }
+  execute: fetchBalance
 });
 var aivCredits = (0, import_tools.createTool)({
   id: "cite42_credits",
   mcp: readOnly("Check Cite42 balance (legacy alias)", false),
-  description: "Check the remaining Cite42 balance for the connected account. Free. " + MCP_USAGE_GUIDANCE,
+  description: "Alias of cite42_balance for older integrations. Free.",
   inputSchema: import_zod.z.object({}),
-  execute: async () => {
-    const usage = await aivGet("/usage");
-    const microCredits = usage.balance?.microCredits;
-    if (typeof microCredits !== "number" || !Number.isFinite(microCredits)) {
-      throw new Error("Cite42 usage response did not include a balance.");
-    }
-    return toCite42CreditsBalance(microCredits);
-  }
+  execute: fetchBalance
 });
 var aivPricing = (0, import_tools.createTool)({
   id: "cite42_pricing",
   mcp: readOnly("Get Cite42 price table", false),
-  description: 'Get the exact Cite42 price table. Pass currency: USD for dollar prices; otherwise read the usd block (legacy fields are compatibility only): per-model rates, flat-rate tools, workflow maximums, and which tools are free. Use it to answer any "how much does X cost" question or to estimate a plan before running it. Free. ' + MCP_USAGE_GUIDANCE,
-  inputSchema: import_zod.z.object({
-    currency: import_zod.z.enum(["USD", "credits"]).optional().describe("Use USD for dollar prices. Omit only for legacy compatibility.")
-  }),
-  execute: async (input) => input.currency === "USD" ? aivGet("/pricing?currency=USD") : { ...await aivGet("/pricing"), usd: await aivGet("/pricing?currency=USD") }
+  description: "Get the exact Cite42 price table in USD: per-surface rates, flat-rate tools, workflow maximums, and which tools are free. Use it for cost questions and to estimate a plan before running it. Free.",
+  // No currency switch: prices are USD only. An older client's `currency` argument is ignored.
+  inputSchema: import_zod.z.object({}),
+  execute: async () => aivGet("/pricing?currency=USD")
 });
 var aivUsage = (0, import_tools.createTool)({
   id: "cite42_usage",
   mcp: readOnly("Get recent Cite42 usage", false),
-  description: "Get recent Cite42 usage for the connected account: the last calls with their cost and status, plus the remaining balance in USD. Free. " + MCP_USAGE_GUIDANCE,
+  description: "Get recent Cite42 usage for the connected account: the last calls with their cost and status, plus the remaining balance in USD. Free.",
   inputSchema: import_zod.z.object({}),
   execute: async () => {
     const usage = await aivGet("/usage");
-    const microCredits = usage.balance?.microCredits;
-    if (typeof microCredits !== "number" || !Number.isFinite(microCredits)) {
+    const micro = usage.balance?.microCredits;
+    if (typeof micro !== "number" || !Number.isFinite(micro)) {
       throw new Error("Cite42 usage response did not include a balance.");
     }
     return {
-      ...toCite42CreditsBalance(microCredits),
+      ...toCite42Balance(micro),
       recentCalls: (usage.recent ?? []).slice(0, 20).map((row) => ({
         endpoint: row.endpoint,
         status: row.status,
-        credits: typeof row.costMicro === "number" ? toCredits(row.costMicro) : void 0,
         costUsd: typeof row.costMicro === "number" ? toUsd(row.costMicro) : void 0,
         at: row.createdAt
       }))
@@ -312,7 +273,7 @@ var aivUsage = (0, import_tools.createTool)({
 var aivSearch = (0, import_tools.createTool)({
   id: "cite42_search",
   mcp: readOnly("Search AI models"),
-  description: `Run a query against AI models (ChatGPT, Claude, Perplexity, Gemini, and Google AI Overviews) and return each model's answer along with the sources it cited. ${MODEL_PRICING} ${MCP_USAGE_GUIDANCE}`,
+  description: `Run a query against AI models (ChatGPT, Claude, Perplexity, Gemini, and Google AI Overviews) and return each model's answer along with the sources it cited. ${MODEL_PRICING} ${PAID_TOOL_BILLING}`,
   inputSchema: import_zod.z.object({
     query: queryText("The concise AI-search/market-research query to run against the selected models."),
     models: modelsInput,
@@ -323,7 +284,7 @@ var aivSearch = (0, import_tools.createTool)({
 var aivCitations = (0, import_tools.createTool)({
   id: "cite42_citations",
   mcp: readOnly("Find AI citations"),
-  description: `Find which sources a model's web search surfaces for a query. Aggregates cited URLs across models with per-model counts; optionally checks whether a specific URL is cited. Measures the retrieval corpus behind a prompt \u2014 which domains own your category in AI search, and where your content is missing \u2014 not the citation links a consumer chat UI renders for a logged-in user. ${MODEL_PRICING} ${MCP_USAGE_GUIDANCE}`,
+  description: `Find which sources a model's web search surfaces for a query. Aggregates cited URLs across models with per-model counts; optionally checks whether a specific URL is cited. Measures the retrieval corpus behind a prompt \u2014 which domains own your category in AI search, and where your content is missing \u2014 not the citation links a consumer chat UI renders for a logged-in user. ${RECOMMENDATIONS_INPUT_NOTE} ${MODEL_PRICING} ${PAID_TOOL_BILLING}`,
   inputSchema: import_zod.z.object({
     query: queryText("The concise query to look up cited sources for."),
     url: import_zod.z.string().trim().max(500).optional().describe("Optional URL to check whether it was cited."),
@@ -335,7 +296,7 @@ var aivCitations = (0, import_tools.createTool)({
 var aivRankings = (0, import_tools.createTool)({
   id: "cite42_rankings",
   mcp: readOnly("Measure AI brand rankings"),
-  description: `Measure how a set of brands/competitors rank in AI answers for a query: mention rate, average position, and a per-model breakdown across ChatGPT, Claude, Perplexity, Gemini, and Google AI Overviews. ${MODEL_PRICING} ${MCP_USAGE_GUIDANCE}`,
+  description: `Measure how a set of brands/competitors rank in AI answers for a query: mention rate, average position, and a per-model breakdown across ChatGPT, Claude, Perplexity, Gemini, and Google AI Overviews. ${RECOMMENDATIONS_INPUT_NOTE} ${MODEL_PRICING} ${PAID_TOOL_BILLING}`,
   inputSchema: import_zod.z.object({
     query: queryText("The concise query to measure brand/competitor visibility on."),
     competitors: competitorList.describe("Brand or domain names to track within the AI-generated answers."),
@@ -347,7 +308,7 @@ var aivRankings = (0, import_tools.createTool)({
 var aivCompare = (0, import_tools.createTool)({
   id: "cite42_compare",
   mcp: readOnly("Compare brand against competitors"),
-  description: `Compare one primary brand head-to-head against a competitor set in AI answers: per-brand rankings plus a co-mention graph of which brands the models name together. ${MODEL_PRICING} ${MCP_USAGE_GUIDANCE}`,
+  description: `Compare one primary brand head-to-head against a competitor set in AI answers: per-brand rankings plus a co-mention graph of which brands the models name together. ${RECOMMENDATIONS_INPUT_NOTE} ${MODEL_PRICING} ${PAID_TOOL_BILLING}`,
   inputSchema: import_zod.z.object({
     query: queryText("The concise query to compare the brand and competitors on."),
     brand: shortText("Your brand, ranked alongside the competitors."),
@@ -360,7 +321,7 @@ var aivCompare = (0, import_tools.createTool)({
 var aivSentiment = (0, import_tools.createTool)({
   id: "cite42_sentiment",
   mcp: readOnly("Score brand sentiment in AI answers"),
-  description: `Score how each AI model talks about a brand for a query: a positive/neutral/negative split per model with the verbatim phrases driving the tone, plus an aggregate across models. ${MODEL_PRICING} ${MCP_USAGE_GUIDANCE}`,
+  description: `Score how each AI model talks about a brand for a query: a positive/neutral/negative split per model with the verbatim phrases driving the tone, plus an aggregate across models. ${RECOMMENDATIONS_INPUT_NOTE} ${MODEL_PRICING} ${PAID_TOOL_BILLING}`,
   inputSchema: import_zod.z.object({
     query: queryText("The concise query whose answers are scored for brand sentiment."),
     brand: shortText("The brand to score sentiment for in each model answer."),
@@ -372,7 +333,7 @@ var aivSentiment = (0, import_tools.createTool)({
 var aivKeywords = (0, import_tools.createTool)({
   id: "cite42_keywords",
   mcp: readOnly("Get SEO keyword data"),
-  description: `Classic keyword data for a seed term. Omit ideas when the user only needs that seed's monthly search volume, CPC, or competition. Set ideas:true only when the user asks for related, alternative, or long-tail suggestions from provider candidates. Not a multi-model AI-search query. The reply echoes requestedKeyword and carries status "exact" or "no_data"; when the seed has no search volume, any related term that does appears under alternatives \u2014 never treat an alternative's metrics as the requested keyword's. ${KEYWORDS_PRICING} ${MCP_USAGE_GUIDANCE}`,
+  description: `Classic keyword data for a seed term. Omit ideas when the user only needs that seed's monthly search volume, CPC, or competition. Set ideas:true only when the user asks for related, alternative, or long-tail suggestions from provider candidates. Not a multi-model AI-search query. The reply echoes requestedKeyword and carries status "exact" or "no_data"; when the seed has no search volume, any related term that does appears under alternatives \u2014 never treat an alternative's metrics as the requested keyword's. ${KEYWORDS_PRICING} ${PAID_TOOL_BILLING}`,
   inputSchema: import_zod.z.object({
     seed: queryText("Seed keyword or concise topic to fetch search volume, CPC, and competition for."),
     country: import_zod.z.string().trim().max(8).optional().describe('ISO-2 country code for localized metrics. Defaults to "us".'),
@@ -388,7 +349,7 @@ var aivKeywords = (0, import_tools.createTool)({
 var aivKeywordsBatch = (0, import_tools.createTool)({
   id: "cite42_keywords_batch",
   mcp: readOnly("Get batch SEO keyword data"),
-  description: `Check search volume, CPC, and competition for two to 50 distinct seed keywords in one request. No related ideas. Billed by outcome; call cite42_pricing for current rates. ${MCP_USAGE_GUIDANCE}`,
+  description: `Check search volume, CPC, and competition for two to 50 distinct seed keywords in one request. No related ideas. Billed by outcome. ${PAID_TOOL_BILLING}`,
   inputSchema: import_zod.z.object({
     seeds: import_zod.z.array(import_zod.z.string().trim().min(1).max(80).refine(
       (seed) => seed.split(/\s+/).length <= 10,
@@ -405,7 +366,7 @@ var aivKeywordsBatch = (0, import_tools.createTool)({
 var aivTrends = (0, import_tools.createTool)({
   id: "cite42_trends",
   mcp: readOnly("Get Google Trends data"),
-  description: `Google Trends interest-over-time, related and rising queries, and a rising/falling/stable label for a term. A flat-priced data tool, not an AI-model query. ${DATA_PRICING} ${MCP_USAGE_GUIDANCE}`,
+  description: `Google Trends interest-over-time, related and rising queries, and a rising/falling/stable label for a term. A flat-priced data tool, not an AI-model query. ${PAID_TOOL_BILLING}`,
   inputSchema: import_zod.z.object({
     term: queryText("Search term or concise topic to pull Google Trends interest-over-time for."),
     timeframe: import_zod.z.string().trim().max(TIMEFRAME_MAX_CHARS).optional().describe('Trends window, e.g. "past_12_months", "past_30_days", "past_5_years".'),
@@ -416,7 +377,7 @@ var aivTrends = (0, import_tools.createTool)({
 var aivRedditTrends = (0, import_tools.createTool)({
   id: "cite42_reddit_trends",
   mcp: readOnly("Find Reddit discussions"),
-  description: `Discover relevant Reddit discussions through Gemini Google Search. Returns labeled model summaries, citations and coverage warnings, with no author quotes or quote-based insights. Does not measure growth or read complete comment conversations. ${DATA_PRICING} ${MCP_USAGE_GUIDANCE}`,
+  description: "Discover relevant Reddit discussions with Google Search and read up to three thread pages through Gemini URL context. Returns Gemini-read titles, authors, post excerpts, relative ages, available scores/comment counts and sampled human comments, plus cited model summaries. Check coverage and warnings: pages may be cached, extraction is not independently verified, and exact dates, growth and quote-based insights are unavailable. risingThreads is a deprecated alias of relevantThreads. " + PAID_TOOL_BILLING,
   inputSchema: import_zod.z.object({
     topic: queryText("Topic, category, product, or audience to research on Reddit."),
     subreddits: import_zod.z.array(shortText("Subreddit name without r/.")).max(20).optional().describe("Optional subreddit names, without r/."),
@@ -427,7 +388,7 @@ var aivRedditTrends = (0, import_tools.createTool)({
 var aivYoutubeTrends = (0, import_tools.createTool)({
   id: "cite42_youtube_trends",
   mcp: readOnly("Get YouTube trend data"),
-  description: `YouTube trend data for rising videos, creator angles, title patterns, channel examples, and video-market opportunities around a topic. ${DATA_PRICING} ${MCP_USAGE_GUIDANCE}`,
+  description: `YouTube trend data for rising videos, creator angles, title patterns, channel examples, and video-market opportunities around a topic. ${PAID_TOOL_BILLING}`,
   inputSchema: import_zod.z.object({
     topic: queryText("Topic, keyword, niche, or audience to research on YouTube."),
     region: import_zod.z.string().trim().max(8).optional().describe('ISO-2 country/region code. Defaults to "US".'),
@@ -448,7 +409,9 @@ var aivFindContentOpportunities = (0, import_tools.createTool)({
     brand: optionalShortText("Optional brand/domain to account for."),
     competitors: competitorList.optional().describe("Competitor brands/domains."),
     country: import_zod.z.string().trim().max(8).optional().describe('ISO-2 country code. Defaults to "us".'),
-    channels: import_zod.z.array(channelEnum).optional().describe("Optional data sources to include.")
+    channels: import_zod.z.array(channelEnum).optional().describe("Optional data sources to include."),
+    models: modelsInput,
+    fullSweep: fullSweepInput
   }),
   execute: async (input, context) => aivPost("/workflows/content-opportunities", input, context?.abortSignal ?? context?.mcp?.extra.signal)
 });
@@ -461,7 +424,9 @@ var aivAnalyzeTopicDemand = (0, import_tools.createTool)({
   inputSchema: import_zod.z.object({
     topic: queryText("Topic, keyword, category, or audience demand to analyze."),
     country: import_zod.z.string().trim().max(8).optional().describe('ISO-2 country code. Defaults to "us".'),
-    timeframe: import_zod.z.string().trim().max(TIMEFRAME_MAX_CHARS).optional().describe('Trend window. Defaults to "past_12_months".')
+    timeframe: import_zod.z.string().trim().max(TIMEFRAME_MAX_CHARS).optional().describe('Trend window. Defaults to "past_12_months".'),
+    models: modelsInput,
+    fullSweep: fullSweepInput
   }),
   execute: async (input, context) => aivPost("/workflows/topic-demand", input, context?.abortSignal ?? context?.mcp?.extra.signal)
 });
@@ -469,7 +434,7 @@ var aivMapAiPrompts = (0, import_tools.createTool)({
   id: "cite42_map_ai_prompts",
   mcp: readOnly("Map buyer prompts for AI search"),
   description: workflowDescription(
-    "Run the AI-prompt-map workflow: research for a list of buyer prompts worth tracking, from AI search, SEO demand, trends, citations, Reddit, and YouTube data. It returns evidence and a suggested prompt, not a finished list: write the prompts from it, then offer to track the best of them with cite42_tracker_create once the user has seen them."
+    "Run the AI-prompt-map workflow: research for a list of buyer prompts worth tracking, from AI search, SEO demand, trends, citations, Reddit, and YouTube data. It returns evidence and a suggested prompt, not a finished list; prompts written from it can be tracked with cite42_tracker_create."
   ),
   inputSchema: import_zod.z.object({
     topic: queryText("Market, product category, buyer problem, or audience to map prompts for."),
@@ -477,7 +442,9 @@ var aivMapAiPrompts = (0, import_tools.createTool)({
     brand: optionalShortText("Optional brand/domain to include in prompt tracking recommendations."),
     competitors: competitorList.optional().describe("Competitor brands/domains."),
     country: import_zod.z.string().trim().max(8).optional().describe('ISO-2 country code. Defaults to "us".'),
-    timeframe: import_zod.z.string().trim().max(TIMEFRAME_MAX_CHARS).optional().describe('Trend window. Defaults to "past_12_months".')
+    timeframe: import_zod.z.string().trim().max(TIMEFRAME_MAX_CHARS).optional().describe('Trend window. Defaults to "past_12_months".'),
+    models: modelsInput,
+    fullSweep: fullSweepInput
   }),
   execute: async (input, context) => aivPost("/workflows/ai-prompt-map", input, context?.abortSignal ?? context?.mcp?.extra.signal)
 });
@@ -491,7 +458,9 @@ var aivAnalyzeCompetitorContent = (0, import_tools.createTool)({
     competitors: competitorList.describe("Competitor brands, domains, or channels to analyze."),
     topic: import_zod.z.string().trim().min(1).max(QUERY_MAX_CHARS).optional().describe("Optional topic/category to constrain the analysis."),
     brand: optionalShortText("Optional primary brand/domain to compare against."),
-    country: import_zod.z.string().trim().max(8).optional().describe('ISO-2 country code. Defaults to "us".')
+    country: import_zod.z.string().trim().max(8).optional().describe('ISO-2 country code. Defaults to "us".'),
+    models: modelsInput,
+    fullSweep: fullSweepInput
   }),
   execute: async (input, context) => aivPost("/workflows/competitor-content", input, context?.abortSignal ?? context?.mcp?.extra.signal)
 });
@@ -522,7 +491,9 @@ var aivGenerateContentBrief = (0, import_tools.createTool)({
     audience: optionalShortText("Optional target audience or ICP."),
     brand: optionalShortText("Optional brand/domain the brief is for."),
     goal: optionalShortText("Optional content goal, e.g. rank, earn citations, convert."),
-    country: import_zod.z.string().trim().max(8).optional().describe('ISO-2 country code. Defaults to "us".')
+    country: import_zod.z.string().trim().max(8).optional().describe('ISO-2 country code. Defaults to "us".'),
+    models: modelsInput,
+    fullSweep: fullSweepInput
   }),
   execute: async (input, context) => aivPost("/workflows/content-brief", input, context?.abortSignal ?? context?.mcp?.extra.signal)
 });
@@ -578,11 +549,11 @@ var trackerDefinitionFields = {
     "AI surfaces to query for every prompt. Omit for the three defaults (chatgpt, perplexity, gemini), or list surfaces explicitly \u2014 including all five \u2014 to fix the recurring cost."
   )
 };
-var TRACKER_BILLING_DESCRIPTION = "Tracker management and stored-report reads are free. Each scheduled or manual run bills one call per prompt at the normal per-model rates; the activation response and tracker record expose the accepted maximum cost per run. Present the returned USD amounts to users; activation still takes the exact estimatedCostMicroPerRun integer returned by the tracker.";
+var TRACKER_BILLING_DESCRIPTION = "Managing trackers and reading reports is free; each run bills one call per prompt at the per-surface rates.";
 var aivTrackerCreate = (0, import_tools.createTool)({
   id: "cite42_tracker_create",
   mcp: mutation("Create Cite42 tracker draft"),
-  description: "Create a draft weekly or monthly tracker: one measurement \u2014 rankings, compare, citations, or sentiment \u2014 applied to a list of prompts, with the brand, competitors and AI surfaces set once for all of them. When the user has no prompt list yet, run cite42_map_ai_prompts first and track the prompts you write from its research. Creation does not start recurring calls. " + TRACKER_BILLING_DESCRIPTION,
+  description: "Create a draft weekly or monthly tracker: one measurement \u2014 rankings, compare, citations, or sentiment \u2014 applied to a list of prompts, with the brand, competitors and AI surfaces set once for all of them. Prompt lists can come from cite42_map_ai_prompts research. Creation does not start recurring calls. " + TRACKER_BILLING_DESCRIPTION,
   inputSchema: import_zod.z.object(trackerDefinitionFields),
   execute: async (input) => aivPost("/trackers", input)
 });
@@ -599,7 +570,7 @@ var aivTrackerActivate = (0, import_tools.createTool)({
     openWorldHint: true,
     idempotentHint: true
   }),
-  description: `Activate or resume recurring weekly or monthly tool calls. maxCostMicroPerRun must equal the tracker estimate being accepted; activation authorizes future billed calls until the tracker is paused. The response carries a billing block with the balance, the cost per run, and runsDryAt \u2014 the date the balance stops covering the account's active trackers \u2014 so relay it. When tracker emails are enabled, activation sends a setup summary and every completed run sends current results and suggested next steps, even when nothing changed. Activation is refused when the balance cannot cover even the next run; tell the user to top up at cite42.dev/app/billing. ${TRACKER_BILLING_DESCRIPTION}`,
+  description: `Activate or resume recurring weekly or monthly tool calls. maxCostMicroPerRun must equal the tracker's latest estimatedCostMicroPerRun; activation authorizes future billed calls until paused. The response includes the balance, the cost per run, and runsDryAt, the date the balance stops covering active trackers. When tracker emails are enabled, activation sends a setup summary and every completed run sends current results and suggested next steps, even when nothing changed. Activation is refused when the balance cannot cover the next run. ${TRACKER_BILLING_DESCRIPTION}`,
   inputSchema: import_zod.z.object({
     trackerId: trackerIdInput,
     maxCostMicroPerRun: import_zod.z.number().int().nonnegative().describe("Exact estimatedCostMicroPerRun returned by the latest tracker record.")
@@ -703,7 +674,7 @@ if (!resolveApiKey()) {
   );
   process.exit(1);
 }
-buildCite42Server("0.7.0").startStdio().catch((error) => {
+buildCite42Server("0.8.0").startStdio().catch((error) => {
   console.error("[@cite42/mcp] Fatal error:", error);
   process.exit(1);
 });

package/dist/stdio.mjs

@@ -2,7 +2,7 @@
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://www.cite42.dev/api/v1";
-var MICRO_CREDITS_PER_CREDIT = 1e3;
+var FUNDS_LOCATION = "the Cite42 dashboard at https://www.cite42.dev/app";
 function toUsd(micro) {
   const [whole, fraction = ""] = (micro / 1e5).toFixed(5).split(".");
   return `${whole}.${fraction.slice(0, Math.max(2, fraction.replace(/0+$/, "").length))}`;
@@ -19,16 +19,6 @@ function toCite42Balance(micro) {
 function isJsonObject(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function toCredits(microCredits) {
-  return microCredits / MICRO_CREDITS_PER_CREDIT;
-}
-function formatCredits(microCredits) {
-  const credits = toCredits(microCredits);
-  return credits.toLocaleString(
-    "en-US",
-    Number.isInteger(credits) ? { maximumFractionDigits: 0 } : { minimumFractionDigits: 0, maximumFractionDigits: 2 }
-  );
-}
 function isTrackerCommitment(billing) {
   return typeof billing.balanceMicro === "number" && typeof billing.costMicroPerRun === "number";
 }
@@ -52,38 +42,17 @@ function toCite42McpResult(value) {
     ...replay ? { originalChargedUsd: toUsd(originalCost) } : {},
     message: (replay ? `Replay of an identical request from the last 2 minutes. This attempt was free; $${toUsd(originalCost)} USD was charged once, by the original Cite42 call.` : `Cite42: $${toUsd(cost)} USD charged; $${toUsd(balance)} USD remaining.`) + lowBalanceNotice
   };
-  const lowCredits = typeof warning === "string";
-  const message = `Cite42 credits: ${formatCredits(cost)} charged; ${formatCredits(balance)} remaining.`;
-  return {
-    ...result,
-    cite42Billing,
-    // Legacy numeric fields retain their original units for existing integrations.
-    cite42Credits: {
-      charged: toCredits(cost),
-      remaining: toCredits(balance),
-      ...replay ? { originalCharged: toCredits(originalCost) } : {},
-      message: replay ? `Replay of an identical request from the last 2 minutes. This attempt was free; ${toCredits(originalCost)} credits were charged once, by the original call.` : lowCredits ? `${message} Low Cite42 credit balance.` : message
-    }
-  };
-}
-function toCite42CreditsBalance(balanceMicroCredits) {
-  return {
-    ...toCite42Balance(balanceMicroCredits),
-    cite42Credits: {
-      remaining: toCredits(balanceMicroCredits),
-      message: `Cite42 credits: ${formatCredits(balanceMicroCredits)} remaining. This balance check was free.`
-    }
-  };
+  return { ...result, cite42Billing };
 }
 function errorMessageForMcp(status, path, body) {
   try {
     const payload = JSON.parse(body);
     if (isJsonObject(payload) && isJsonObject(payload.error) && typeof payload.error.code === "string") {
       if (payload.error.code === "daily_limit_exceeded" || payload.error.code === "monthly_limit_exceeded") {
-        return "Cite42 spending limit reached. Adjust your limit at https://www.cite42.dev/app/billing.";
+        return `Cite42 spending limit reached. Change it in ${FUNDS_LOCATION}.`;
       }
       if (payload.error.code === "insufficient_credits") {
-        return "Insufficient Cite42 balance. Add funds at https://www.cite42.dev/app/billing.";
+        return `Insufficient Cite42 balance. Add funds in ${FUNDS_LOCATION}.`;
       }
     }
   } catch {
@@ -175,18 +144,18 @@ var modelEnum = z.enum(["chatgpt", "claude", "perplexity", "gemini", "google_ai_
 var QUERY_MAX_CHARS = 2e3;
 var SHORT_TEXT_MAX_CHARS = 200;
 var TIMEFRAME_MAX_CHARS = 80;
-var MODEL_SELECTION_DESCRIPTION = 'Optional model subset. Omit to query the default surfaces (chatgpt, perplexity, gemini). Pass ["perplexity"] or ["perplexity","claude"] when the user names specific surfaces or wants to reduce cost. The full set is chatgpt, claude, perplexity, gemini, google_ai_overview \u2014 to query all of them, set fullSweep instead of listing them.';
-var FULL_SWEEP_DESCRIPTION = "Query all five AI surfaces instead of the three default ones, adding claude and google_ai_overview. Costs more per call. Use it when the user wants complete cross-model coverage, is comparing surfaces against each other, or asks specifically about Claude or Google AI Overviews. Ignored when models is given.";
-var MCP_USAGE_GUIDANCE = "Covers AI-search, citation, SEO, keyword, trend, and market-research data. If a plan needs more than 20 endpoint calls or may use more than $5 USD, estimate the cost in USD and ask the user before continuing. Quote Cite42 costs and balances in USD using cite42Billing or the USD pricing table. Legacy credit fields are for compatibility only. These funds belong to Cite42, not the host or model provider. AI visibility metrics include counts; quote them with percentages, not as a market-wide score. Optional recommendations are a separate paid call, never automatic. Recommendations take the requestId of a visibility result and the page URL, or a page URL alone for a free technical check; they run only when the user requests advice and knows any additional cost. Free: cite42_balance for the remaining balance, cite42_pricing for exact per-tool prices and cost estimates, cite42_usage for recent calls.";
-var MODEL_PRICING = "Pricing is per selected AI surface. Omitting models queries the three default surfaces (chatgpt, perplexity, gemini); fullSweep: true queries all five, adding claude and google_ai_overview at a higher cost. Use the models field when the user names a surface or asks to reduce spending, and call cite42_pricing for exact current rates.";
-var DATA_PRICING = "Data tools have flat per-call prices; call cite42_pricing for exact current rates.";
-var KEYWORDS_PRICING = "Pricing: billed by outcome \u2014 cheapest when the seed has no search volume, more when it has metrics, most with ideas:true. Call cite42_pricing for exact current rates.";
-var WORKFLOW_PRICING = "Pricing: workflow cost is calculated from the tools that run successfully and the selected model rates.";
+var MODEL_SELECTION_DESCRIPTION = "AI surfaces to query, each billed separately; pass a subset when the user names surfaces or wants a lower cost. Omit for the defaults (chatgpt, perplexity, gemini); fullSweep queries all five. google_ai_overview accepts queries up to 700 characters, the others 2000.";
+var FULL_SWEEP_DESCRIPTION = "Query all five AI surfaces (adds claude and google_ai_overview) for full cross-surface coverage, at a higher cost. Ignored when models is given.";
+var PAID_TOOL_BILLING = "Billed in USD (result field cite42Billing) to the user's prepaid Cite42 balance; exact prices from cite42_pricing (free). For plans over 20 calls or $5, estimate the cost and confirm with the user first.";
+var RECOMMENDATIONS_INPUT_NOTE = "Its requestId can be passed to cite42_recommendations when the user asks for improvement advice.";
+var MODEL_PRICING = "Priced per AI surface queried.";
+var KEYWORDS_PRICING = "Billed by outcome: cheapest when the seed has no search volume, more when it has metrics, most with ideas:true.";
+var WORKFLOW_PRICING = "Billed for the steps that succeed, at per-surface rates.";
 function workflowDescription(description) {
-  return `${description} ${MCP_USAGE_GUIDANCE} ${MODEL_PRICING} ${DATA_PRICING} ${WORKFLOW_PRICING}`;
+  return `${description} ${WORKFLOW_PRICING} ${PAID_TOOL_BILLING}`;
 }
 function readOnly(title, openWorldHint = true) {
-  return { annotations: { title, readOnlyHint: true, openWorldHint } };
+  return { annotations: { title, readOnlyHint: true, destructiveHint: false, openWorldHint } };
 }
 function mutation(title, options = {}) {
   return {
@@ -208,7 +177,7 @@ function shortText(description) {
 var aivRecommendations = createTool({
   id: "cite42_recommendations",
   mcp: readOnly("Recommend AI visibility next steps"),
-  description: "Page-level AI visibility recommendations. With a saved result (requestId, trackerRunId or evidence) it reports on one measured prompt, charged only when the report includes page-comparison advice backed by quotes from inspected pages. Without one: url alone runs a free technical check of the page (robots.txt crawler access, indexing, rendering) and returns suggested buyer questions; url with query first runs a citations check, priced like cite42_citations, then the report. Prices are in cite42_pricing. Fetches the page, its robots.txt and up to two pages the AI surfaces cited, as returned HTML without JavaScript. No site-wide crawl, keyword advice or tracker activation. " + MCP_USAGE_GUIDANCE,
+  description: "Page-level AI visibility recommendations, for when the user asks how to improve a page. With a saved result (requestId, trackerRunId or evidence) it reports on one measured prompt, charged only when the report includes page-comparison advice backed by quotes from inspected pages. Without one: url alone runs a free technical check of the page (robots.txt crawler access, indexing, rendering) and returns suggested buyer questions; url with query first runs a citations check, priced like cite42_citations, then the report. Prices are in cite42_pricing. Fetches the page, its robots.txt and up to two pages the AI surfaces cited, as returned HTML without JavaScript. No site-wide crawl, keyword advice or tracker activation. " + PAID_TOOL_BILLING,
   inputSchema: z.object({
     requestId: z.string().trim().min(1).max(128).optional().describe("A requestId from your own successful Cite42 call within the last 30 days."),
     trackerRunId: z.string().trim().min(1).max(128).optional().describe("A specific finished run of your own tracker within the last 30 days."),
@@ -248,60 +217,52 @@ function optionalShortText(description) {
 var modelsInput = z.array(modelEnum).nonempty().optional().describe(MODEL_SELECTION_DESCRIPTION);
 var fullSweepInput = z.boolean().optional().describe(FULL_SWEEP_DESCRIPTION);
 var competitorList = z.array(shortText("Competitor brand/domain name.")).nonempty().max(20);
+async function fetchBalance() {
+  const usage = await aivGet("/usage");
+  const micro = usage.balance?.microCredits;
+  if (typeof micro !== "number" || !Number.isFinite(micro)) {
+    throw new Error("Cite42 usage response did not include a balance.");
+  }
+  return toCite42Balance(micro);
+}
 var aivBalance = createTool({
   id: "cite42_balance",
   mcp: readOnly("Check Cite42 balance", false),
-  description: "Check the remaining Cite42 balance for the connected account. Free. " + MCP_USAGE_GUIDANCE,
+  description: "Check the remaining Cite42 balance in USD for the connected account. Free.",
   inputSchema: z.object({}),
-  execute: async () => {
-    const usage = await aivGet("/usage");
-    const microCredits = usage.balance?.microCredits;
-    if (typeof microCredits !== "number" || !Number.isFinite(microCredits)) {
-      throw new Error("Cite42 usage response did not include a balance.");
-    }
-    return toCite42Balance(microCredits);
-  }
+  execute: fetchBalance
 });
 var aivCredits = createTool({
   id: "cite42_credits",
   mcp: readOnly("Check Cite42 balance (legacy alias)", false),
-  description: "Check the remaining Cite42 balance for the connected account. Free. " + MCP_USAGE_GUIDANCE,
+  description: "Alias of cite42_balance for older integrations. Free.",
   inputSchema: z.object({}),
-  execute: async () => {
-    const usage = await aivGet("/usage");
-    const microCredits = usage.balance?.microCredits;
-    if (typeof microCredits !== "number" || !Number.isFinite(microCredits)) {
-      throw new Error("Cite42 usage response did not include a balance.");
-    }
-    return toCite42CreditsBalance(microCredits);
-  }
+  execute: fetchBalance
 });
 var aivPricing = createTool({
   id: "cite42_pricing",
   mcp: readOnly("Get Cite42 price table", false),
-  description: 'Get the exact Cite42 price table. Pass currency: USD for dollar prices; otherwise read the usd block (legacy fields are compatibility only): per-model rates, flat-rate tools, workflow maximums, and which tools are free. Use it to answer any "how much does X cost" question or to estimate a plan before running it. Free. ' + MCP_USAGE_GUIDANCE,
-  inputSchema: z.object({
-    currency: z.enum(["USD", "credits"]).optional().describe("Use USD for dollar prices. Omit only for legacy compatibility.")
-  }),
-  execute: async (input) => input.currency === "USD" ? aivGet("/pricing?currency=USD") : { ...await aivGet("/pricing"), usd: await aivGet("/pricing?currency=USD") }
+  description: "Get the exact Cite42 price table in USD: per-surface rates, flat-rate tools, workflow maximums, and which tools are free. Use it for cost questions and to estimate a plan before running it. Free.",
+  // No currency switch: prices are USD only. An older client's `currency` argument is ignored.
+  inputSchema: z.object({}),
+  execute: async () => aivGet("/pricing?currency=USD")
 });
 var aivUsage = createTool({
   id: "cite42_usage",
   mcp: readOnly("Get recent Cite42 usage", false),
-  description: "Get recent Cite42 usage for the connected account: the last calls with their cost and status, plus the remaining balance in USD. Free. " + MCP_USAGE_GUIDANCE,
+  description: "Get recent Cite42 usage for the connected account: the last calls with their cost and status, plus the remaining balance in USD. Free.",
   inputSchema: z.object({}),
   execute: async () => {
     const usage = await aivGet("/usage");
-    const microCredits = usage.balance?.microCredits;
-    if (typeof microCredits !== "number" || !Number.isFinite(microCredits)) {
+    const micro = usage.balance?.microCredits;
+    if (typeof micro !== "number" || !Number.isFinite(micro)) {
       throw new Error("Cite42 usage response did not include a balance.");
     }
     return {
-      ...toCite42CreditsBalance(microCredits),
+      ...toCite42Balance(micro),
       recentCalls: (usage.recent ?? []).slice(0, 20).map((row) => ({
         endpoint: row.endpoint,
         status: row.status,
-        credits: typeof row.costMicro === "number" ? toCredits(row.costMicro) : void 0,
         costUsd: typeof row.costMicro === "number" ? toUsd(row.costMicro) : void 0,
         at: row.createdAt
       }))
@@ -311,7 +272,7 @@ var aivUsage = createTool({
 var aivSearch = createTool({
   id: "cite42_search",
   mcp: readOnly("Search AI models"),
-  description: `Run a query against AI models (ChatGPT, Claude, Perplexity, Gemini, and Google AI Overviews) and return each model's answer along with the sources it cited. ${MODEL_PRICING} ${MCP_USAGE_GUIDANCE}`,
+  description: `Run a query against AI models (ChatGPT, Claude, Perplexity, Gemini, and Google AI Overviews) and return each model's answer along with the sources it cited. ${MODEL_PRICING} ${PAID_TOOL_BILLING}`,
   inputSchema: z.object({
     query: queryText("The concise AI-search/market-research query to run against the selected models."),
     models: modelsInput,
@@ -322,7 +283,7 @@ var aivSearch = createTool({
 var aivCitations = createTool({
   id: "cite42_citations",
   mcp: readOnly("Find AI citations"),
-  description: `Find which sources a model's web search surfaces for a query. Aggregates cited URLs across models with per-model counts; optionally checks whether a specific URL is cited. Measures the retrieval corpus behind a prompt \u2014 which domains own your category in AI search, and where your content is missing \u2014 not the citation links a consumer chat UI renders for a logged-in user. ${MODEL_PRICING} ${MCP_USAGE_GUIDANCE}`,
+  description: `Find which sources a model's web search surfaces for a query. Aggregates cited URLs across models with per-model counts; optionally checks whether a specific URL is cited. Measures the retrieval corpus behind a prompt \u2014 which domains own your category in AI search, and where your content is missing \u2014 not the citation links a consumer chat UI renders for a logged-in user. ${RECOMMENDATIONS_INPUT_NOTE} ${MODEL_PRICING} ${PAID_TOOL_BILLING}`,
   inputSchema: z.object({
     query: queryText("The concise query to look up cited sources for."),
     url: z.string().trim().max(500).optional().describe("Optional URL to check whether it was cited."),
@@ -334,7 +295,7 @@ var aivCitations = createTool({
 var aivRankings = createTool({
   id: "cite42_rankings",
   mcp: readOnly("Measure AI brand rankings"),
-  description: `Measure how a set of brands/competitors rank in AI answers for a query: mention rate, average position, and a per-model breakdown across ChatGPT, Claude, Perplexity, Gemini, and Google AI Overviews. ${MODEL_PRICING} ${MCP_USAGE_GUIDANCE}`,
+  description: `Measure how a set of brands/competitors rank in AI answers for a query: mention rate, average position, and a per-model breakdown across ChatGPT, Claude, Perplexity, Gemini, and Google AI Overviews. ${RECOMMENDATIONS_INPUT_NOTE} ${MODEL_PRICING} ${PAID_TOOL_BILLING}`,
   inputSchema: z.object({
     query: queryText("The concise query to measure brand/competitor visibility on."),
     competitors: competitorList.describe("Brand or domain names to track within the AI-generated answers."),
@@ -346,7 +307,7 @@ var aivRankings = createTool({
 var aivCompare = createTool({
   id: "cite42_compare",
   mcp: readOnly("Compare brand against competitors"),
-  description: `Compare one primary brand head-to-head against a competitor set in AI answers: per-brand rankings plus a co-mention graph of which brands the models name together. ${MODEL_PRICING} ${MCP_USAGE_GUIDANCE}`,
+  description: `Compare one primary brand head-to-head against a competitor set in AI answers: per-brand rankings plus a co-mention graph of which brands the models name together. ${RECOMMENDATIONS_INPUT_NOTE} ${MODEL_PRICING} ${PAID_TOOL_BILLING}`,
   inputSchema: z.object({
     query: queryText("The concise query to compare the brand and competitors on."),
     brand: shortText("Your brand, ranked alongside the competitors."),
@@ -359,7 +320,7 @@ var aivCompare = createTool({
 var aivSentiment = createTool({
   id: "cite42_sentiment",
   mcp: readOnly("Score brand sentiment in AI answers"),
-  description: `Score how each AI model talks about a brand for a query: a positive/neutral/negative split per model with the verbatim phrases driving the tone, plus an aggregate across models. ${MODEL_PRICING} ${MCP_USAGE_GUIDANCE}`,
+  description: `Score how each AI model talks about a brand for a query: a positive/neutral/negative split per model with the verbatim phrases driving the tone, plus an aggregate across models. ${RECOMMENDATIONS_INPUT_NOTE} ${MODEL_PRICING} ${PAID_TOOL_BILLING}`,
   inputSchema: z.object({
     query: queryText("The concise query whose answers are scored for brand sentiment."),
     brand: shortText("The brand to score sentiment for in each model answer."),
@@ -371,7 +332,7 @@ var aivSentiment = createTool({
 var aivKeywords = createTool({
   id: "cite42_keywords",
   mcp: readOnly("Get SEO keyword data"),
-  description: `Classic keyword data for a seed term. Omit ideas when the user only needs that seed's monthly search volume, CPC, or competition. Set ideas:true only when the user asks for related, alternative, or long-tail suggestions from provider candidates. Not a multi-model AI-search query. The reply echoes requestedKeyword and carries status "exact" or "no_data"; when the seed has no search volume, any related term that does appears under alternatives \u2014 never treat an alternative's metrics as the requested keyword's. ${KEYWORDS_PRICING} ${MCP_USAGE_GUIDANCE}`,
+  description: `Classic keyword data for a seed term. Omit ideas when the user only needs that seed's monthly search volume, CPC, or competition. Set ideas:true only when the user asks for related, alternative, or long-tail suggestions from provider candidates. Not a multi-model AI-search query. The reply echoes requestedKeyword and carries status "exact" or "no_data"; when the seed has no search volume, any related term that does appears under alternatives \u2014 never treat an alternative's metrics as the requested keyword's. ${KEYWORDS_PRICING} ${PAID_TOOL_BILLING}`,
   inputSchema: z.object({
     seed: queryText("Seed keyword or concise topic to fetch search volume, CPC, and competition for."),
     country: z.string().trim().max(8).optional().describe('ISO-2 country code for localized metrics. Defaults to "us".'),
@@ -387,7 +348,7 @@ var aivKeywords = createTool({
 var aivKeywordsBatch = createTool({
   id: "cite42_keywords_batch",
   mcp: readOnly("Get batch SEO keyword data"),
-  description: `Check search volume, CPC, and competition for two to 50 distinct seed keywords in one request. No related ideas. Billed by outcome; call cite42_pricing for current rates. ${MCP_USAGE_GUIDANCE}`,
+  description: `Check search volume, CPC, and competition for two to 50 distinct seed keywords in one request. No related ideas. Billed by outcome. ${PAID_TOOL_BILLING}`,
   inputSchema: z.object({
     seeds: z.array(z.string().trim().min(1).max(80).refine(
       (seed) => seed.split(/\s+/).length <= 10,
@@ -404,7 +365,7 @@ var aivKeywordsBatch = createTool({
 var aivTrends = createTool({
   id: "cite42_trends",
   mcp: readOnly("Get Google Trends data"),
-  description: `Google Trends interest-over-time, related and rising queries, and a rising/falling/stable label for a term. A flat-priced data tool, not an AI-model query. ${DATA_PRICING} ${MCP_USAGE_GUIDANCE}`,
+  description: `Google Trends interest-over-time, related and rising queries, and a rising/falling/stable label for a term. A flat-priced data tool, not an AI-model query. ${PAID_TOOL_BILLING}`,
   inputSchema: z.object({
     term: queryText("Search term or concise topic to pull Google Trends interest-over-time for."),
     timeframe: z.string().trim().max(TIMEFRAME_MAX_CHARS).optional().describe('Trends window, e.g. "past_12_months", "past_30_days", "past_5_years".'),
@@ -415,7 +376,7 @@ var aivTrends = createTool({
 var aivRedditTrends = createTool({
   id: "cite42_reddit_trends",
   mcp: readOnly("Find Reddit discussions"),
-  description: `Discover relevant Reddit discussions through Gemini Google Search. Returns labeled model summaries, citations and coverage warnings, with no author quotes or quote-based insights. Does not measure growth or read complete comment conversations. ${DATA_PRICING} ${MCP_USAGE_GUIDANCE}`,
+  description: "Discover relevant Reddit discussions with Google Search and read up to three thread pages through Gemini URL context. Returns Gemini-read titles, authors, post excerpts, relative ages, available scores/comment counts and sampled human comments, plus cited model summaries. Check coverage and warnings: pages may be cached, extraction is not independently verified, and exact dates, growth and quote-based insights are unavailable. risingThreads is a deprecated alias of relevantThreads. " + PAID_TOOL_BILLING,
   inputSchema: z.object({
     topic: queryText("Topic, category, product, or audience to research on Reddit."),
     subreddits: z.array(shortText("Subreddit name without r/.")).max(20).optional().describe("Optional subreddit names, without r/."),
@@ -426,7 +387,7 @@ var aivRedditTrends = createTool({
 var aivYoutubeTrends = createTool({
   id: "cite42_youtube_trends",
   mcp: readOnly("Get YouTube trend data"),
-  description: `YouTube trend data for rising videos, creator angles, title patterns, channel examples, and video-market opportunities around a topic. ${DATA_PRICING} ${MCP_USAGE_GUIDANCE}`,
+  description: `YouTube trend data for rising videos, creator angles, title patterns, channel examples, and video-market opportunities around a topic. ${PAID_TOOL_BILLING}`,
   inputSchema: z.object({
     topic: queryText("Topic, keyword, niche, or audience to research on YouTube."),
     region: z.string().trim().max(8).optional().describe('ISO-2 country/region code. Defaults to "US".'),
@@ -447,7 +408,9 @@ var aivFindContentOpportunities = createTool({
     brand: optionalShortText("Optional brand/domain to account for."),
     competitors: competitorList.optional().describe("Competitor brands/domains."),
     country: z.string().trim().max(8).optional().describe('ISO-2 country code. Defaults to "us".'),
-    channels: z.array(channelEnum).optional().describe("Optional data sources to include.")
+    channels: z.array(channelEnum).optional().describe("Optional data sources to include."),
+    models: modelsInput,
+    fullSweep: fullSweepInput
   }),
   execute: async (input, context) => aivPost("/workflows/content-opportunities", input, context?.abortSignal ?? context?.mcp?.extra.signal)
 });
@@ -460,7 +423,9 @@ var aivAnalyzeTopicDemand = createTool({
   inputSchema: z.object({
     topic: queryText("Topic, keyword, category, or audience demand to analyze."),
     country: z.string().trim().max(8).optional().describe('ISO-2 country code. Defaults to "us".'),
-    timeframe: z.string().trim().max(TIMEFRAME_MAX_CHARS).optional().describe('Trend window. Defaults to "past_12_months".')
+    timeframe: z.string().trim().max(TIMEFRAME_MAX_CHARS).optional().describe('Trend window. Defaults to "past_12_months".'),
+    models: modelsInput,
+    fullSweep: fullSweepInput
   }),
   execute: async (input, context) => aivPost("/workflows/topic-demand", input, context?.abortSignal ?? context?.mcp?.extra.signal)
 });
@@ -468,7 +433,7 @@ var aivMapAiPrompts = createTool({
   id: "cite42_map_ai_prompts",
   mcp: readOnly("Map buyer prompts for AI search"),
   description: workflowDescription(
-    "Run the AI-prompt-map workflow: research for a list of buyer prompts worth tracking, from AI search, SEO demand, trends, citations, Reddit, and YouTube data. It returns evidence and a suggested prompt, not a finished list: write the prompts from it, then offer to track the best of them with cite42_tracker_create once the user has seen them."
+    "Run the AI-prompt-map workflow: research for a list of buyer prompts worth tracking, from AI search, SEO demand, trends, citations, Reddit, and YouTube data. It returns evidence and a suggested prompt, not a finished list; prompts written from it can be tracked with cite42_tracker_create."
   ),
   inputSchema: z.object({
     topic: queryText("Market, product category, buyer problem, or audience to map prompts for."),
@@ -476,7 +441,9 @@ var aivMapAiPrompts = createTool({
     brand: optionalShortText("Optional brand/domain to include in prompt tracking recommendations."),
     competitors: competitorList.optional().describe("Competitor brands/domains."),
     country: z.string().trim().max(8).optional().describe('ISO-2 country code. Defaults to "us".'),
-    timeframe: z.string().trim().max(TIMEFRAME_MAX_CHARS).optional().describe('Trend window. Defaults to "past_12_months".')
+    timeframe: z.string().trim().max(TIMEFRAME_MAX_CHARS).optional().describe('Trend window. Defaults to "past_12_months".'),
+    models: modelsInput,
+    fullSweep: fullSweepInput
   }),
   execute: async (input, context) => aivPost("/workflows/ai-prompt-map", input, context?.abortSignal ?? context?.mcp?.extra.signal)
 });
@@ -490,7 +457,9 @@ var aivAnalyzeCompetitorContent = createTool({
     competitors: competitorList.describe("Competitor brands, domains, or channels to analyze."),
     topic: z.string().trim().min(1).max(QUERY_MAX_CHARS).optional().describe("Optional topic/category to constrain the analysis."),
     brand: optionalShortText("Optional primary brand/domain to compare against."),
-    country: z.string().trim().max(8).optional().describe('ISO-2 country code. Defaults to "us".')
+    country: z.string().trim().max(8).optional().describe('ISO-2 country code. Defaults to "us".'),
+    models: modelsInput,
+    fullSweep: fullSweepInput
   }),
   execute: async (input, context) => aivPost("/workflows/competitor-content", input, context?.abortSignal ?? context?.mcp?.extra.signal)
 });
@@ -521,7 +490,9 @@ var aivGenerateContentBrief = createTool({
     audience: optionalShortText("Optional target audience or ICP."),
     brand: optionalShortText("Optional brand/domain the brief is for."),
     goal: optionalShortText("Optional content goal, e.g. rank, earn citations, convert."),
-    country: z.string().trim().max(8).optional().describe('ISO-2 country code. Defaults to "us".')
+    country: z.string().trim().max(8).optional().describe('ISO-2 country code. Defaults to "us".'),
+    models: modelsInput,
+    fullSweep: fullSweepInput
   }),
   execute: async (input, context) => aivPost("/workflows/content-brief", input, context?.abortSignal ?? context?.mcp?.extra.signal)
 });
@@ -577,11 +548,11 @@ var trackerDefinitionFields = {
     "AI surfaces to query for every prompt. Omit for the three defaults (chatgpt, perplexity, gemini), or list surfaces explicitly \u2014 including all five \u2014 to fix the recurring cost."
   )
 };
-var TRACKER_BILLING_DESCRIPTION = "Tracker management and stored-report reads are free. Each scheduled or manual run bills one call per prompt at the normal per-model rates; the activation response and tracker record expose the accepted maximum cost per run. Present the returned USD amounts to users; activation still takes the exact estimatedCostMicroPerRun integer returned by the tracker.";
+var TRACKER_BILLING_DESCRIPTION = "Managing trackers and reading reports is free; each run bills one call per prompt at the per-surface rates.";
 var aivTrackerCreate = createTool({
   id: "cite42_tracker_create",
   mcp: mutation("Create Cite42 tracker draft"),
-  description: "Create a draft weekly or monthly tracker: one measurement \u2014 rankings, compare, citations, or sentiment \u2014 applied to a list of prompts, with the brand, competitors and AI surfaces set once for all of them. When the user has no prompt list yet, run cite42_map_ai_prompts first and track the prompts you write from its research. Creation does not start recurring calls. " + TRACKER_BILLING_DESCRIPTION,
+  description: "Create a draft weekly or monthly tracker: one measurement \u2014 rankings, compare, citations, or sentiment \u2014 applied to a list of prompts, with the brand, competitors and AI surfaces set once for all of them. Prompt lists can come from cite42_map_ai_prompts research. Creation does not start recurring calls. " + TRACKER_BILLING_DESCRIPTION,
   inputSchema: z.object(trackerDefinitionFields),
   execute: async (input) => aivPost("/trackers", input)
 });
@@ -598,7 +569,7 @@ var aivTrackerActivate = createTool({
     openWorldHint: true,
     idempotentHint: true
   }),
-  description: `Activate or resume recurring weekly or monthly tool calls. maxCostMicroPerRun must equal the tracker estimate being accepted; activation authorizes future billed calls until the tracker is paused. The response carries a billing block with the balance, the cost per run, and runsDryAt \u2014 the date the balance stops covering the account's active trackers \u2014 so relay it. When tracker emails are enabled, activation sends a setup summary and every completed run sends current results and suggested next steps, even when nothing changed. Activation is refused when the balance cannot cover even the next run; tell the user to top up at cite42.dev/app/billing. ${TRACKER_BILLING_DESCRIPTION}`,
+  description: `Activate or resume recurring weekly or monthly tool calls. maxCostMicroPerRun must equal the tracker's latest estimatedCostMicroPerRun; activation authorizes future billed calls until paused. The response includes the balance, the cost per run, and runsDryAt, the date the balance stops covering active trackers. When tracker emails are enabled, activation sends a setup summary and every completed run sends current results and suggested next steps, even when nothing changed. Activation is refused when the balance cannot cover the next run. ${TRACKER_BILLING_DESCRIPTION}`,
   inputSchema: z.object({
     trackerId: trackerIdInput,
     maxCostMicroPerRun: z.number().int().nonnegative().describe("Exact estimatedCostMicroPerRun returned by the latest tracker record.")
@@ -702,7 +673,7 @@ if (!resolveApiKey()) {
   );
   process.exit(1);
 }
-buildCite42Server("0.7.0").startStdio().catch((error) => {
+buildCite42Server("0.8.0").startStdio().catch((error) => {
   console.error("[@cite42/mcp] Fatal error:", error);
   process.exit(1);
 });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cite42/mcp",
   "mcpName": "dev.cite42/mcp",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Cite42 MCP server: AI visibility and SEO data for AI agents. See how the AI models behind ChatGPT, Claude, Perplexity and Gemini, plus Google AI Overviews, mention your brand and which sources they cite, with SEO keyword data, Google, Reddit and YouTube trends, and weekly or monthly trackers that watch a list of prompts over time. Works with Claude Code, Claude Desktop, Codex CLI, Cursor, and any MCP client.",
   "license": "MIT",
   "type": "module",