feat: simplify pricing output in search-actors

Search results dumped all 6 pricing tiers (FREE through DIAMOND) for every
event of every actor, bloating output with no value (e.g. Google Maps Scraper
returned 9 events x 6 tiers = 54 price entries). Only the user's tier matters
in a search listing.

Now search-actors shows only the user's tier price (FREE fallback) plus a
short hint about other tiers. fetch-actor-details is untouched and still
returns full tiered pricing.

- Extend user cache to also return userPlanTier from the same API call
- Add pricingInfoToSimplifiedString and pricingInfoToSimplifiedStructured
- Add userTier to ActorCardOptions, branch in card formatters
- Add pricingNote field to StructuredPricingInfo for the hint

Author: claude

src/mcp/server.ts

@@ -76,7 +76,7 @@ import { createProgressTracker } from '../utils/progress.js';
 import { getServerInstructions } from '../utils/server-instructions/index.js';
 import { classifyFailureCategory, extractAjvErrorDetails, extractToolTelemetry, getToolStatusFromError } from '../utils/tool_status.js';
 import { buildActorFields, extractActorId, extractActorName, getToolFullName, getToolPublicFieldOnly } from '../utils/tools.js';
-import { getUserIdFromTokenCached } from '../utils/userid_cache.js';
+import { getUserInfoCached } from '../utils/userid_cache.js';
 import { getPackageVersion } from '../utils/version.js';
 import { connectMCPClient } from './client.js';
 import { EXTERNAL_TOOL_CALL_TIMEOUT_MSEC, LOG_LEVEL_MAP } from './const.js';
@@ -1364,7 +1364,7 @@ export class ActorsMcpServer {
         let userId: string | null = null;
         if (apifyToken) {
             const apifyClient = new ApifyClient({ token: apifyToken });
-            userId = await getUserIdFromTokenCached(apifyToken, apifyClient);
+            ({ userId } = await getUserInfoCached(apifyToken, apifyClient));
             log.debug('Telemetry: fetched userId', { userId, mcpSessionId });
         }
         const capabilities = this.options.initializeRequestData?.params?.capabilities;

src/tools/core/search_actors_common.ts

@@ -4,9 +4,10 @@ import { z } from 'zod';
 import { HelperTools } from '../../const.js';
 import { getWidgetConfig, WIDGET_URIS } from '../../resources/widgets.js';
 import type { ActorStoreList, HelperTool, StructuredActorCard, ToolInputSchema } from '../../types.js';
-import { formatActorToActorCard, formatActorToStructuredCard } from '../../utils/actor_card.js';
+import { DEFAULT_CARD_OPTIONS, formatActorToActorCard, formatActorToStructuredCard } from '../../utils/actor_card.js';
 import { compileSchema } from '../../utils/ajv.js';
 import { buildMCPResponse } from '../../utils/mcp.js';
+import type { PricingTier } from '../../utils/pricing_info.js';
 import { actorSearchOutputSchema } from '../structured_output_schemas.js';
 
 /**
@@ -112,10 +113,12 @@ export type SearchActorsResult = {
 
 export function buildSearchActorsResult(
     actors: ActorStoreList[],
+    userTier?: PricingTier,
 ): SearchActorsResult {
+    const options = { ...DEFAULT_CARD_OPTIONS, userTier };
     return {
-        actorCardText: actors.map((actor) => formatActorToActorCard(actor)).join('\n\n'),
-        actorCardStructured: actors.map((actor) => formatActorToStructuredCard(actor)),
+        actorCardText: actors.map((actor) => formatActorToActorCard(actor, options)).join('\n\n'),
+        actorCardStructured: actors.map((actor) => formatActorToStructuredCard(actor, options)),
     };
 }
 

src/tools/default/search_actors.ts

@@ -4,6 +4,7 @@ import { HelperTools } from '../../const.js';
 import type { InternalToolArgs, ToolEntry } from '../../types.js';
 import { searchAndFilterActors } from '../../utils/actor_search.js';
 import { buildMCPResponse } from '../../utils/mcp.js';
+import { getUserInfoCached } from '../../utils/userid_cache.js';
 import {
     buildSearchActorsEmptyResponse,
     buildSearchActorsResult,
@@ -18,7 +19,7 @@ import {
 export const defaultSearchActors: ToolEntry = Object.freeze({
     ...searchActorsMetadata,
     call: async (toolArgs: InternalToolArgs) => {
-        const { args, apifyToken, userRentedActorIds, apifyMcpServer } = toolArgs;
+        const { args, apifyToken, apifyClient, userRentedActorIds, apifyMcpServer } = toolArgs;
         const parsed = searchActorsArgsSchema.parse(args);
         const actors = await searchAndFilterActors({
             keywords: parsed.keywords,
@@ -33,7 +34,8 @@ export const defaultSearchActors: ToolEntry = Object.freeze({
             return buildSearchActorsEmptyResponse(parsed.keywords);
         }
 
-        const { actorCardText, actorCardStructured } = buildSearchActorsResult(actors);
+        const { userPlanTier } = await getUserInfoCached(apifyToken, apifyClient);
+        const { actorCardText, actorCardStructured } = buildSearchActorsResult(actors, userPlanTier);
         const structuredContent = {
             actors: actorCardStructured,
             query: parsed.keywords,

src/tools/openai/search_actors.ts

@@ -6,6 +6,7 @@ import type { InternalToolArgs, ToolEntry } from '../../types.js';
 import { formatActorForWidget, type WidgetActor } from '../../utils/actor_card.js';
 import { searchAndFilterActors } from '../../utils/actor_search.js';
 import { buildMCPResponse } from '../../utils/mcp.js';
+import { getUserInfoCached } from '../../utils/userid_cache.js';
 import {
     buildSearchActorsEmptyResponse,
     buildSearchActorsResult,
@@ -20,7 +21,7 @@ import {
 export const openaiSearchActors: ToolEntry = Object.freeze({
     ...searchActorsMetadata,
     call: async (toolArgs: InternalToolArgs) => {
-        const { args, apifyToken, userRentedActorIds, apifyMcpServer } = toolArgs;
+        const { args, apifyToken, apifyClient, userRentedActorIds, apifyMcpServer } = toolArgs;
         const parsed = searchActorsArgsSchema.parse(args);
         const actors = await searchAndFilterActors({
             keywords: parsed.keywords,
@@ -35,7 +36,8 @@ export const openaiSearchActors: ToolEntry = Object.freeze({
             return buildSearchActorsEmptyResponse(parsed.keywords);
         }
 
-        const { actorCardText, actorCardStructured } = buildSearchActorsResult(actors);
+        const { userPlanTier } = await getUserInfoCached(apifyToken, apifyClient);
+        const { actorCardText, actorCardStructured } = buildSearchActorsResult(actors, userPlanTier);
         const structuredContent: {
             actors: typeof actorCardStructured;
             query: string;

src/tools/structured_output_schemas.ts

@@ -75,6 +75,7 @@ export const pricingSchema = {
         trialMinutes: { type: 'number', description: 'Trial period in minutes' },
         tieredPricing: tieredPricingSchema,
         events: pricingEventsSchema,
+        pricingNote: { type: 'string', description: 'Note about additional pricing tiers available via fetch-actor-details' },
     },
     required: ['model', 'isFree'],
 };

src/types.ts

@@ -18,7 +18,7 @@ import type { FAILURE_CATEGORY, TELEMETRY_ENV, TOOL_STATUS } from './const.js';
 import type { ActorsMcpServer } from './mcp/server.js';
 import type { PaymentProvider } from './payments/types.js';
 import type { CATEGORY_NAMES } from './tools/categories.js';
-import type { StructuredPricingInfo } from './utils/pricing_info.js';
+import type { PricingTier, StructuredPricingInfo } from './utils/pricing_info.js';
 import type { ProgressTracker } from './utils/progress.js';
 
 export type SchemaProperties = {
@@ -616,6 +616,12 @@ export type ActorCardOptions = {
     includeRating?: boolean;
     /** Include metadata (developer, categories, last modified date, deprecation warning) */
     includeMetadata?: boolean;
+    /**
+     * If set, simplify pricing to only show this tier's price (with FREE fallback)
+     * and append a hint about other tiers. Used by search-actors.
+     * When undefined, full pricing is shown (used by fetch-actor-details).
+     */
+    userTier?: PricingTier;
 }
 
 /**

src/utils/actor_card.ts

@@ -3,6 +3,8 @@ import type { Actor, ActorCardOptions, ActorStoreList, StructuredActorCard } fro
 import {
     getCurrentPricingInfo,
     type PricingInfo,
+    pricingInfoToSimplifiedString,
+    pricingInfoToSimplifiedStructured,
     pricingInfoToString,
     pricingInfoToStructured,
     type StructuredPricingInfo,
@@ -34,7 +36,7 @@ function getActorPricingInfo(actor: Actor | ActorStoreList): PricingInfo | null
     return getCurrentPricingInfo(actor.pricingInfos || [], new Date());
 }
 
-const DEFAULT_CARD_OPTIONS: ActorCardOptions = {
+export const DEFAULT_CARD_OPTIONS: ActorCardOptions = {
     includeDescription: true,
     includeStats: true,
     includePricing: true,
@@ -180,7 +182,9 @@ export function formatActorToActorCard(
     }
 
     if (options.includePricing) {
-        const pricingString = pricingInfoToString(data.pricingInfo);
+        const pricingString = options.userTier
+            ? pricingInfoToSimplifiedString(data.pricingInfo, options.userTier)
+            : pricingInfoToString(data.pricingInfo);
         markdownLines.push(`- **[Pricing](${data.actorUrl}/pricing):** ${pricingString}`);
     }
 
@@ -224,6 +228,13 @@ export function formatActorToStructuredCard(
 ): StructuredActorCard {
     const data = extractActorData(actor, options);
 
+    let pricing: StructuredPricingInfo = { model: 'FREE', isFree: true };
+    if (options.includePricing) {
+        pricing = options.userTier
+            ? pricingInfoToSimplifiedStructured(data.pricingInfo, options.userTier)
+            : pricingInfoToStructured(data.pricingInfo);
+    }
+
     return {
         title: data.title,
         url: data.actorUrl,
@@ -233,9 +244,7 @@ export function formatActorToStructuredCard(
         developer: data.developer,
         description: data.description,
         categories: data.categories,
-        pricing: options.includePricing
-            ? pricingInfoToStructured(data.pricingInfo)
-            : { model: 'FREE', isFree: true },
+        pricing,
         stats: data.stats,
         rating: data.rating,
         modifiedAt: data.modifiedAt,

src/utils/pricing_info.ts

@@ -57,8 +57,30 @@ export type StructuredPricingInfo = {
             priceUsd: number;
         }[];
     }[];
+    /** Hint added when pricing is simplified to a single tier. */
+    pricingNote?: string;
 };
 
+const SIMPLIFIED_PRICING_NOTE = 'Higher subscription tiers may offer lower prices. Use fetch-actor-details for complete pricing.';
+
+/**
+ * Picks the user's tier from a tiered pricing map, falling back to FREE, then the first available tier.
+ * Returns null if the map is empty.
+ */
+function pickTierEntry<T>(
+    tieredMap: Record<string, T> | undefined,
+    userTier: PricingTier,
+): { tier: string; value: T } | null {
+    if (!tieredMap) return null;
+    const entries = Object.entries(tieredMap);
+    if (entries.length === 0) return null;
+    const userMatch = entries.find(([t]) => t === userTier);
+    if (userMatch) return { tier: userMatch[0], value: userMatch[1] };
+    const freeMatch = entries.find(([t]) => t === 'FREE');
+    if (freeMatch) return { tier: freeMatch[0], value: freeMatch[1] };
+    return { tier: entries[0][0], value: entries[0][1] };
+}
+
 /**
  * Returns the most recent valid pricing information from a list of pricing infos,
  * based on the provided current date.
@@ -221,3 +243,99 @@ export function pricingInfoToStructured(pricingInfo: PricingInfo | null): Struct
 
     return structuredPricing;
 }
+
+/**
+ * Simplified text pricing for search-actors: shows only the user's tier price
+ * (with FREE fallback) and appends a hint about other tiers.
+ *
+ * Defaults to FREE when `userTier` is undefined.
+ */
+export function pricingInfoToSimplifiedString(
+    pricingInfo: PricingInfo | null,
+    userTier: PricingTier = 'FREE',
+): string {
+    if (pricingInfo === null || pricingInfo.pricingModel === ACTOR_PRICING_MODEL.FREE) {
+        return 'This Actor is free to use. You are only charged for Apify platform usage.';
+    }
+    if (pricingInfo.pricingModel === ACTOR_PRICING_MODEL.PRICE_PER_DATASET_ITEM) {
+        const customUnitName = pricingInfo.unitName !== 'result' ? pricingInfo.unitName : '';
+        const unitLabel = customUnitName || 'results';
+        const picked = pickTierEntry(pricingInfo.tieredPricing, userTier);
+        if (picked) {
+            return `This Actor charges per results${customUnitName ? ` (in this case named ${customUnitName})` : ''}; price per 1000 ${unitLabel} for ${picked.tier} tier: $${picked.value.tieredPricePerUnitUsd * 1000}. ${SIMPLIFIED_PRICING_NOTE}`;
+        }
+        return `This Actor charges per results${customUnitName ? ` (in this case named ${customUnitName})` : ''}; the price per 1000 ${unitLabel} is ${(pricingInfo.pricePerUnitUsd as number) * 1000} USD.`;
+    }
+    if (pricingInfo.pricingModel === ACTOR_PRICING_MODEL.FLAT_PRICE_PER_MONTH) {
+        const { value, unit } = convertMinutesToGreatestUnit(pricingInfo.trialMinutes || 0);
+        const picked = pickTierEntry(pricingInfo.tieredPricing, userTier);
+        if (picked) {
+            return `This Actor is rental; price for ${picked.tier} tier: $${picked.value.tieredPricePerUnitUsd} per month, with a trial period of ${value} ${unit}. ${SIMPLIFIED_PRICING_NOTE}`;
+        }
+        return `This Actor is rental and has a flat price of ${pricingInfo.pricePerUnitUsd} USD per month, with a trial period of ${value} ${unit}.`;
+    }
+    if (pricingInfo.pricingModel === ACTOR_PRICING_MODEL.PAY_PER_EVENT) {
+        const events = pricingInfo.pricingPerEvent?.actorChargeEvents;
+        if (!events) return 'Pricing information for events is not available.';
+        const lines: string[] = [];
+        let hasTieredEvent = false;
+        for (const rawEvent of Object.values(events)) {
+            const event = rawEvent as ActorChargeEvent;
+            let line = `\t- **${event.eventTitle}**: ${event.eventDescription} `;
+            if (typeof event.eventPriceUsd === 'number') {
+                line += `(Flat price: $${event.eventPriceUsd} per event)`;
+            } else if (event.eventTieredPricingUsd) {
+                hasTieredEvent = true;
+                const picked = pickTierEntry(event.eventTieredPricingUsd, userTier);
+                line += picked
+                    ? `(${picked.tier} tier: $${picked.value.tieredEventPriceUsd} per event)`
+                    : '(No price info)';
+            } else {
+                line += '(No price info)';
+            }
+            lines.push(line);
+        }
+        const suffix = hasTieredEvent ? `\n${SIMPLIFIED_PRICING_NOTE}` : '';
+        return `This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for the following events:\n${lines.join('\n')}${suffix}`;
+    }
+    return 'Pricing information is not available.';
+}
+
+/**
+ * Simplified structured pricing for search-actors: collapses tiered pricing arrays
+ * to a single entry for the user's tier (with FREE fallback) and sets `pricingNote`.
+ *
+ * Defaults to FREE when `userTier` is undefined.
+ */
+export function pricingInfoToSimplifiedStructured(
+    pricingInfo: PricingInfo | null,
+    userTier: PricingTier = 'FREE',
+): StructuredPricingInfo {
+    const result = pricingInfoToStructured(pricingInfo);
+    let simplified = false;
+
+    if (result.tieredPricing && result.tieredPricing.length > 0) {
+        const map = Object.fromEntries(result.tieredPricing.map((t) => [t.tier, t]));
+        const picked = pickTierEntry(map, userTier);
+        if (picked) {
+            result.tieredPricing = [picked.value];
+            simplified = true;
+        }
+    }
+
+    if (result.events) {
+        result.events = result.events.map((event) => {
+            if (!event.tieredPricing || event.tieredPricing.length === 0) return event;
+            const map = Object.fromEntries(event.tieredPricing.map((t) => [t.tier, t]));
+            const picked = pickTierEntry(map, userTier);
+            if (!picked) return event;
+            simplified = true;
+            return { ...event, tieredPricing: [picked.value] };
+        });
+    }
+
+    if (simplified) {
+        result.pricingNote = SIMPLIFIED_PRICING_NOTE;
+    }
+    return result;
+}

src/utils/userid_cache.ts

@@ -2,32 +2,50 @@ import { createHash } from 'node:crypto';
 
 import type { ApifyClient } from '../apify_client.js';
 import { USER_CACHE_MAX_SIZE, USER_CACHE_TTL_SECS } from '../const.js';
+import type { PricingTier } from './pricing_info.js';
 import { TTLLRUCache } from './ttl_lru.js';
 
-// LRU cache with TTL for user info - stores the raw User object from API
-const userIdCache = new TTLLRUCache<string>(USER_CACHE_MAX_SIZE, USER_CACHE_TTL_SECS);
+const VALID_PRICING_TIERS = new Set<PricingTier>(['FREE', 'BRONZE', 'SILVER', 'GOLD', 'PLATINUM', 'DIAMOND']);
+
+export type CachedUserInfo = {
+    userId: string | null;
+    userPlanTier: PricingTier;
+};
+
+// LRU cache with TTL for user info - keyed by hashed token
+const userInfoCache = new TTLLRUCache<CachedUserInfo>(USER_CACHE_MAX_SIZE, USER_CACHE_TTL_SECS);
+
+function normalizePlanTier(planId: string | undefined): PricingTier {
+    if (!planId) return 'FREE';
+    const upper = planId.toUpperCase();
+    return VALID_PRICING_TIERS.has(upper as PricingTier) ? (upper as PricingTier) : 'FREE';
+}
 
 /**
- * Gets user ID from token, using cache to avoid repeated API calls
- * Token is hashed before caching to avoid storing raw tokens
- * Returns userId or null if not found
+ * Gets user info (id + plan tier) from token, using cache to avoid repeated API calls.
+ * Token is hashed before caching to avoid storing raw tokens.
+ *
+ * Defensive defaults: `userPlanTier` is always present. Returns 'FREE' when the plan
+ * is missing, unrecognized, or the API call fails. Failed lookups are NOT cached so
+ * the next call retries.
  */
-export async function getUserIdFromTokenCached(
+export async function getUserInfoCached(
     token: string,
     apifyClient: ApifyClient,
-): Promise<string | null> {
+): Promise<CachedUserInfo> {
     const tokenHash = createHash('sha256').update(token).digest('hex');
-    const cachedId = userIdCache.get(tokenHash);
-    if (cachedId) return cachedId;
+    const cached = userInfoCache.get(tokenHash);
+    if (cached) return cached;
 
     try {
         const user = await apifyClient.user('me').get();
-        if (!user || !user.id) {
-            return null;
-        }
-        userIdCache.set(tokenHash, user.id);
-        return user.id;
+        const info: CachedUserInfo = {
+            userId: user?.id ?? null,
+            userPlanTier: normalizePlanTier(user?.plan?.id),
+        };
+        userInfoCache.set(tokenHash, info);
+        return info;
     } catch {
-        return null;
+        return { userId: null, userPlanTier: 'FREE' };
     }
 }