Skip to content

Open-source agentic AI Search Execution Platform. Track AI visibility, find opportunities, and let agents turn signals into prioritized actions and drafted fixes across ChatGPT, Claude, Gemini, Google AI Overviews, Google AI Mode, Perplexity, Grok, and Microsoft Copilot.

feat(mcp/agent): implement prompt-level performance aggregation tool (#181)

Pallavi Kumarie4679435b73d
diff --git a/supabase/migrations/00013_prompt_performance_aggregates.sql b/supabase/migrations/00013_prompt_performance_aggregates.sql
new file mode 100644
index 000000000..7539cd550
--- /dev/null
+++ b/supabase/migrations/00013_prompt_performance_aggregates.sql
@@ -0,0 +1,75 @@
+-- DB-side aggregation for prompt-level performance (#139).
+--
+-- Excludes `platform = 'chatgpt-shopping'` to ensure ChatGPT Shopping rows
+-- (which use different models and scoring dynamics) do not skew the organic
+-- visibility and mentions of the brand's prompts.
+-- SECURITY DEFINER allows the RPC to run with elevated privileges while Node
+-- data functions enforce tenant membership.
+
+CREATE OR REPLACE FUNCTION public.prompt_performance_aggregates(
+ p_brand_id uuid,
+ p_models text[] DEFAULT NULL,
+ p_region text DEFAULT NULL,
+ p_date_from timestamptz DEFAULT NULL,
+ p_date_to timestamptz DEFAULT NULL,
+ p_topic_id uuid DEFAULT NULL
+)
+RETURNS jsonb
+LANGUAGE sql
+STABLE
+SECURITY DEFINER
+SET search_path = public
+AS $$
+ WITH filtered AS (
+ SELECT pr.prompt_id, pr.visibility_score, pr.mention_count, pr.citation_count, pr.competitor_mentions
+ FROM public.prompt_results pr
+ WHERE pr.brand_id = p_brand_id
+ AND pr.platform <> 'chatgpt-shopping'
+ AND (p_models IS NULL OR pr.model_used = ANY (p_models))
+ AND (p_region IS NULL OR pr.region = p_region)
+ AND (p_date_from IS NULL OR pr.created_at >= p_date_from)
+ AND (p_date_to IS NULL OR pr.created_at <= p_date_to)
+ AND (p_topic_id IS NULL OR EXISTS (
+ SELECT 1 FROM public.prompts p
+ WHERE p.id = pr.prompt_id AND p.topic_id = p_topic_id))
+ ),
+ aggregated AS (
+ SELECT
+ f.prompt_id,
+ COUNT(*) AS result_count,
+ COALESCE(SUM(f.visibility_score), 0) AS sum_visibility,
+ COALESCE(SUM(f.mention_count), 0)::bigint AS total_mentions,
+ COALESCE(SUM(f.citation_count), 0)::bigint AS total_citations,
+ COALESCE(SUM((
+ SELECT COALESCE(SUM((cm.value->>'visibility_score')::numeric), 0)
+ FROM jsonb_array_elements(COALESCE(f.competitor_mentions, '[]'::jsonb)) cm
+ )), 0) AS comp_sum_visibility,
+ COALESCE(SUM((
+ SELECT COUNT(*)
+ FROM jsonb_array_elements(COALESCE(f.competitor_mentions, '[]'::jsonb)) cm
+ )), 0)::bigint AS comp_count
+ FROM filtered f
+ GROUP BY f.prompt_id
+ )
+ SELECT COALESCE(
+ (SELECT jsonb_agg(
+ jsonb_build_object(
+ 'prompt_id', a.prompt_id,
+ 'prompt_text', p.text,
+ 'topic_name', t.name,
+ 'result_count', a.result_count,
+ 'sum_visibility', a.sum_visibility,
+ 'total_mentions', a.total_mentions,
+ 'total_citations', a.total_citations,
+ 'comp_sum_visibility', a.comp_sum_visibility,
+ 'comp_count', a.comp_count
+ )
+ )
+ FROM aggregated a
+ JOIN public.prompts p ON p.id = a.prompt_id
+ LEFT JOIN public.topics t ON t.id = p.topic_id),
+ '[]'::jsonb);
+$$;
+
+GRANT EXECUTE ON FUNCTION public.prompt_performance_aggregates(uuid, text[], text, timestamptz, timestamptz, uuid)
+ TO authenticated, service_role;
diff --git a/web/src/app/api/mcp/prompt-performance/route.ts b/web/src/app/api/mcp/prompt-performance/route.ts
new file mode 100644
index 000000000..6044ae95b
--- /dev/null
+++ b/web/src/app/api/mcp/prompt-performance/route.ts
@@ -0,0 +1,71 @@
+import { NextResponse } from 'next/server';
+import { authenticateMcpRequest } from '@/lib/mcp-auth';
+import { getPromptPerformanceFor } from '@/lib/mcp/data';
+
+/**
+ * GET /api/mcp/prompt-performance
+ *
+ * Parallel REST surface for the `get_prompt_performance` MCP tool — same
+ * data-layer function, same ownership guarantee. Query params mirror the
+ * MCP args: brand_id (required), date_from, date_to, topic_id, sort_by,
+ * order, limit, model, region.
+ */
+export async function GET(req: Request) {
+ const auth = await authenticateMcpRequest(req);
+ if (auth instanceof NextResponse) return auth;
+
+ const url = new URL(req.url);
+ const brandId = url.searchParams.get('brand_id');
+ if (!brandId) {
+ return NextResponse.json({ error: 'brand_id is required' }, { status: 400 });
+ }
+
+ const sortByParam = url.searchParams.get('sort_by') || undefined;
+ if (
+ sortByParam &&
+ !['visibility', 'mentions', 'citations', 'appearances'].includes(sortByParam)
+ ) {
+ return NextResponse.json(
+ { error: 'sort_by must be "visibility", "mentions", "citations", or "appearances"' },
+ { status: 400 },
+ );
+ }
+
+ const orderParam = url.searchParams.get('order') || undefined;
+ if (orderParam && !['desc', 'asc'].includes(orderParam)) {
+ return NextResponse.json({ error: 'order must be "desc" or "asc"' }, { status: 400 });
+ }
+
+ let limit: number | undefined;
+ const limitParam = url.searchParams.get('limit');
+ if (limitParam !== null) {
+ limit = parseInt(limitParam, 10);
+ if (isNaN(limit) || limit < 1 || limit > 100) {
+ return NextResponse.json(
+ { error: 'limit must be a number between 1 and 100' },
+ { status: 400 },
+ );
+ }
+ }
+
+ try {
+ const result = await getPromptPerformanceFor(auth, {
+ brandId,
+ dateFrom: url.searchParams.get('date_from') ?? undefined,
+ dateTo: url.searchParams.get('date_to') ?? undefined,
+ topicId: url.searchParams.get('topic_id') ?? undefined,
+ sortBy: sortByParam as 'visibility' | 'mentions' | 'citations' | 'appearances' | undefined,
+ order: orderParam as 'desc' | 'asc' | undefined,
+ limit,
+ model: url.searchParams.get('model') ?? undefined,
+ region: url.searchParams.get('region') ?? undefined,
+ });
+ if (!result) {
+ return NextResponse.json({ error: 'Brand not found' }, { status: 404 });
+ }
+ return NextResponse.json(result);
+ } catch (err) {
+ const message = err instanceof Error ? err.message : 'Failed';
+ return NextResponse.json({ error: message }, { status: 500 });
+ }
+}
diff --git a/web/src/lib/agent/system-prompt.ts b/web/src/lib/agent/system-prompt.ts
index aad81cfc6..9a9cf6324 100644
--- a/web/src/lib/agent/system-prompt.ts
+++ b/web/src/lib/agent/system-prompt.ts
@@ -39,6 +39,7 @@ You have these tools, all scoped to the authenticated user's organization:
- **list_citations** — URLs and domains AI engines cite alongside the brand, classified by source type (news / review / owned / social / forum / competitor / you). Returns totals, source-type breakdown, and top cited domains + URLs.
- **list_topics** — topics on a brand with prompt count each. Use for coverage audits.
- **list_prompts** — prompts being tracked for a brand. Use when the user asks what is being tracked or wants to drill into a specific topic.
+- **get_prompt_performance** — aggregates performance (average visibility, total mentions, citations, appearances, and competitor score) grouped by prompt over a date range. Use to answer questions like "what is the best-performing prompt today?" or "which prompts dropped this week?".
- **list_content_opportunities** — content gaps for a brand sorted by opportunity score. Use for "what should I write?" questions.
- **render_chart** — render a chart inline in the chat (line / bar / pie). Call this *after* a data tool when the answer is meaningfully easier to read as a chart than as a sentence. See "Visualization" below.
@@ -47,7 +48,7 @@ You have these tools, all scoped to the authenticated user's organization:
Reach for \`render_chart\` when a chart would carry the answer better than prose:
- **line** for "how has X changed over time?" — pair with \`get_visibility_trend\`. \`xKey\` is the date field; one or more series (visibility, mentions, citations).
-- **bar** for "compare X across N entities" — pair with \`get_competitor_comparison\` (brand vs competitors) or \`list_citations\` (source-type breakdown). \`xKey\` is the entity name; one series per metric.
+- **bar** for "compare X across N entities" — pair with \`get_competitor_comparison\` (brand vs competitors), \`list_citations\` (source-type breakdown), or \`get_prompt_performance\` (prompts comparison). \`xKey\` is the entity name (e.g. \`prompt_text\` or competitor name); one series per metric.
- **pie** for "what's the share of X?" — pair with \`get_competitor_comparison\`'s share of voice, or citation domain mix. \`valueKey\` + \`labelKey\`.
Hard rules:
diff --git a/web/src/lib/agent/tools.ts b/web/src/lib/agent/tools.ts
index ea768cc7f..ce1de53e4 100644
--- a/web/src/lib/agent/tools.ts
+++ b/web/src/lib/agent/tools.ts
@@ -11,6 +11,7 @@ import {
listContentOpportunitiesFor,
listPromptsFor,
listTopicsFor,
+ getPromptPerformanceFor,
} from '@/lib/mcp/data';
/**
@@ -169,6 +170,34 @@ export function buildAgentTools(auth: McpAuthContext) {
}),
}),
+ get_prompt_performance: tool({
+ description:
+ 'Get aggregate performance metrics (average visibility, total mentions, citations, appearances, and competitor score) grouped by prompt over a date range. Use to answer questions like "what is the best-performing prompt today?" or "which prompts dropped this week?".',
+ inputSchema: z.object({
+ brand_id: z.string().uuid(),
+ date_from: z.string().optional(),
+ date_to: z.string().optional(),
+ topic_id: z.string().uuid().optional(),
+ sort_by: z.enum(['visibility', 'mentions', 'citations', 'appearances']).optional(),
+ order: z.enum(['desc', 'asc']).optional(),
+ limit: z.number().int().min(1).max(100).optional(),
+ model: z.string().optional(),
+ region: z.string().optional(),
+ }),
+ execute: async (args) =>
+ getPromptPerformanceFor(auth, {
+ brandId: args.brand_id,
+ dateFrom: args.date_from,
+ dateTo: args.date_to,
+ topicId: args.topic_id,
+ sortBy: args.sort_by,
+ order: args.order,
+ limit: args.limit,
+ model: args.model,
+ region: args.region,
+ }),
+ }),
+
render_chart: tool({
description:
'Render a chart inline in the chat. Call this AFTER you have the data from another tool (e.g. get_visibility_trend, get_competitor_comparison, list_citations) and you want to visualize it. Pick the chart type: "line" for time series (trends over dates), "bar" for cross-entity comparisons (brand vs competitors, source-type breakdown), "pie" for share-of-X distributions. Pass the data array straight from the previous tool result — never invent or reformat numbers. The tool just echoes the spec back; the UI renders the chart.',
diff --git a/web/src/lib/mcp/data.ts b/web/src/lib/mcp/data.ts
index 81b4ee364..eaf9d2576 100644
--- a/web/src/lib/mcp/data.ts
+++ b/web/src/lib/mcp/data.ts
@@ -1622,3 +1622,149 @@ export async function getProductVisibility(
merchant_domains,
};
}
+
+// ── Prompt Performance ────────────────────────────────────────────────────────
+
+export interface PromptPerformanceParams {
+ brandId: string;
+ dateFrom?: string;
+ dateTo?: string;
+ topicId?: string;
+ sortBy?: 'visibility' | 'mentions' | 'citations' | 'appearances';
+ order?: 'desc' | 'asc';
+ limit?: number;
+ model?: string;
+ region?: string;
+}
+
+export interface PromptPerformanceOutput {
+ brand: { id: string; name: string };
+ window: { dateFrom: string | null; dateTo: string | null };
+ prompts: Array<{
+ prompt_id: string;
+ prompt_text: string;
+ topic_name: string | null;
+ result_count: number;
+ avg_visibility: number;
+ total_mentions: number;
+ total_citations: number;
+ avg_competitor_score: number;
+ }>;
+}
+
+interface PromptPerformanceRpcResult {
+ prompt_id: string;
+ prompt_text: string;
+ topic_name: string | null;
+ result_count: number;
+ sum_visibility: number;
+ total_mentions: number;
+ total_citations: number;
+ comp_sum_visibility: number;
+ comp_count: number;
+}
+
+/**
+ * Aggregates prompt-level performance over the given window.
+ * Enforces organization ownership.
+ */
+export async function getPromptPerformanceFor(
+ auth: McpAuthContext,
+ params: PromptPerformanceParams,
+): Promise<PromptPerformanceOutput | null> {
+ if (!auth.organizationId) return null;
+
+ const { data: brand } = await supabaseAdmin
+ .from('brands')
+ .select('id, name')
+ .eq('id', params.brandId)
+ .eq('organization_id', auth.organizationId)
+ .maybeSingle();
+ if (!brand) return null;
+
+ const p_models = params.model
+ ? params.model
+ .split(',')
+ .map((s) => s.trim())
+ .filter(Boolean)
+ : null;
+
+ const { data, error } = await supabaseAdmin.rpc('prompt_performance_aggregates', {
+ p_brand_id: params.brandId,
+ p_models: p_models && p_models.length > 0 ? p_models : null,
+ p_region: params.region ?? null,
+ p_date_from: params.dateFrom ?? null,
+ p_date_to: expandDateToEndOfDay(params.dateTo) ?? null,
+ p_topic_id: params.topicId ?? null,
+ });
+
+ if (error) throw new Error(error.message);
+
+ const raw = (data as unknown as PromptPerformanceRpcResult[]) ?? [];
+
+ let prompts = raw.map((item) => {
+ const result_count = Number(item.result_count);
+ const avg_visibility =
+ result_count > 0 ? Math.round(Number(item.sum_visibility) / result_count) : 0;
+ const avg_competitor_score =
+ Number(item.comp_count) > 0
+ ? Math.round(Number(item.comp_sum_visibility) / Number(item.comp_count))
+ : 0;
+
+ return {
+ prompt_id: item.prompt_id,
+ prompt_text: item.prompt_text,
+ topic_name: item.topic_name,
+ result_count,
+ avg_visibility,
+ total_mentions: Number(item.total_mentions),
+ total_citations: Number(item.total_citations),
+ avg_competitor_score,
+ };
+ });
+
+ // Sorting
+ const sortBy = params.sortBy ?? 'visibility';
+ const order = params.order ?? 'desc';
+ const isAsc = order === 'asc';
+
+ prompts.sort((a, b) => {
+ let valA = 0;
+ let valB = 0;
+ if (sortBy === 'visibility') {
+ valA = a.avg_visibility;
+ valB = b.avg_visibility;
+ } else if (sortBy === 'mentions') {
+ valA = a.total_mentions;
+ valB = b.total_mentions;
+ } else if (sortBy === 'citations') {
+ valA = a.total_citations;
+ valB = b.total_citations;
+ } else if (sortBy === 'appearances') {
+ valA = a.result_count;
+ valB = b.result_count;
+ }
+
+ if (valA !== valB) {
+ return isAsc ? valA - valB : valB - valA;
+ }
+ // Stable fallback sorting
+ return a.prompt_id.localeCompare(b.prompt_id);
+ });
+
+ // Limiting
+ const limit = Math.min(Math.max(params.limit ?? 10, 1), 100);
+ prompts = prompts.slice(0, limit);
+
+ return {
+ brand: {
+ id: brand.id,
+ name: brand.name,
+ },
+ window: {
+ dateFrom: params.dateFrom ?? null,
+ dateTo: params.dateTo ?? null,
+ },
+ prompts,
+ };
+}
diff --git a/web/src/lib/mcp/server.ts b/web/src/lib/mcp/server.ts
index 1122980c3..93def22b1 100644
--- a/web/src/lib/mcp/server.ts
+++ b/web/src/lib/mcp/server.ts
@@ -19,6 +19,7 @@ import {
getPromptVolumesFor,
listShoppingCards,
getProductVisibility,
+ getPromptPerformanceFor,
} from './data';
/**
@@ -584,5 +585,65 @@ export function createMcpServer(auth: McpAuthContext): McpServer {
},
);
+ server.registerTool(
+ 'get_prompt_performance',
+ {
+ description:
+ 'Get aggregate performance metrics (average visibility, total mentions, citations, appearances, and competitor score) grouped by prompt over a date range. Use to answer questions like "what is the best-performing prompt today?" or "which prompts dropped this week?".',
+ inputSchema: {
+ brand_id: relaxedUuid.describe('Brand UUID, from list_brands.'),
+ date_from: z
+ .string()
+ .optional()
+ .describe('Optional ISO timestamp (inclusive) lower bound, e.g. 2026-05-01T00:00:00Z.'),
+ date_to: z.string().optional().describe('Optional ISO timestamp (inclusive) upper bound.'),
+ topic_id: relaxedUuid
+ .optional()
+ .describe('Optional topic UUID (from list_topics) to filter to one topic.'),
+ sort_by: z
+ .enum(['visibility', 'mentions', 'citations', 'appearances'])
+ .optional()
+ .describe('Optional field to sort by. Default is "visibility".'),
+ order: z.enum(['desc', 'asc']).optional().describe('Sort order. Default is "desc".'),
+ limit: z
+ .number()
+ .int()
+ .min(1)
+ .max(100)
+ .optional()
+ .describe('Optional limit on prompts returned (default 10, max 100).'),
+ model: z
+ .string()
+ .optional()
+ .describe(
+ 'Optional model slug filter, or comma-separated list of slugs to filter a provider family.',
+ ),
+ region: z.string().optional().describe('Optional region code filter (e.g. "US", "TR").'),
+ },
+ },
+ async (args) => {
+ const result = await getPromptPerformanceFor(auth, {
+ brandId: args.brand_id,
+ dateFrom: args.date_from,
+ dateTo: args.date_to,
+ topicId: args.topic_id,
+ sortBy: args.sort_by,
+ order: args.order,
+ limit: args.limit,
+ model: args.model,
+ region: args.region,
+ });
+ if (result === null) {
+ return {
+ content: [{ type: 'text', text: 'Brand not found' }],
+ isError: true,
+ };
+ }
+ return {
+ content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+ };
+ },
+ );
+
return server;
}