Get Upgrade Justification
metrx_get_upgrade_justificationRead-onlyIdempotent
Generate ROI reports to justify upgrading from Free to paid tiers by analyzing usage patterns, calculating optimization potential, and projecting monthly savings.
Instructions
Generate an ROI report explaining why an upgrade from Free to Lite/Pro tier makes sense. Analyzes current usage patterns, calculates optimization potential at higher tiers, and provides a structured upgrade recommendation with projected monthly savings. Do NOT use if already on Lite or Pro tier — not relevant for paid users.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| period_days | No | Number of days to analyze for upgrade justification (default: 30) |
Implementation Reference
- src/tools/upgrade-justification.ts:41-61 (handler)The main handler function for metrx_get_upgrade_justification that fetches dashboard data, handles errors, and returns the formatted justification report.
async ({ period_days }) => { // Get dashboard summary for the period const result = await client.get<DashboardSummary>('/dashboard', { period_days: period_days ?? 30, }); if (result.error) { return { content: [{ type: 'text', text: `Error fetching upgrade data: ${result.error}` }], isError: true, }; } const data = result.data!; const text = formatUpgradeJustification(data, period_days ?? 30); return { content: [{ type: 'text', text }], }; } ); - src/tools/upgrade-justification.ts:14-62 (handler)Main tool registration and handler function. The tool is registered as 'get_upgrade_justification' and includes the async handler that fetches dashboard data and formats it as an upgrade justification report.
export function registerUpgradeJustificationTools(server: McpServer, client: MetrxApiClient): void { // ── get_upgrade_justification ── server.registerTool( 'get_upgrade_justification', { title: 'Get Upgrade Justification', description: 'Generate an ROI report explaining why an upgrade from Free to Lite/Pro tier makes sense. ' + 'Analyzes current usage patterns, calculates optimization potential at higher tiers, ' + 'and provides a structured upgrade recommendation with projected monthly savings. ' + 'Do NOT use if already on Lite or Pro tier — not relevant for paid users.', inputSchema: { period_days: z .number() .int() .min(7) .max(90) .default(30) .describe('Number of days to analyze for upgrade justification (default: 30)'), }, annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, }, }, async ({ period_days }) => { // Get dashboard summary for the period const result = await client.get<DashboardSummary>('/dashboard', { period_days: period_days ?? 30, }); if (result.error) { return { content: [{ type: 'text', text: `Error fetching upgrade data: ${result.error}` }], isError: true, }; } const data = result.data!; const text = formatUpgradeJustification(data, period_days ?? 30); return { content: [{ type: 'text', text }], }; } ); } - Input schema definition using zod for the tool. Validates the period_days parameter (number, integer, 7-90 range, default 30).
period_days: z .number() .int() .min(7) .max(90) .default(30) .describe('Number of days to analyze for upgrade justification (default: 30)'), }, - src/tools/upgrade-justification.ts:16-61 (registration)Tool registration with schema definition including input validation (period_days), tool metadata, and the handler implementation.
server.registerTool( 'get_upgrade_justification', { title: 'Get Upgrade Justification', description: 'Generate an ROI report explaining why an upgrade from Free to Lite/Pro tier makes sense. ' + 'Analyzes current usage patterns, calculates optimization potential at higher tiers, ' + 'and provides a structured upgrade recommendation with projected monthly savings. ' + 'Do NOT use if already on Lite or Pro tier — not relevant for paid users.', inputSchema: { period_days: z .number() .int() .min(7) .max(90) .default(30) .describe('Number of days to analyze for upgrade justification (default: 30)'), }, annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, }, }, async ({ period_days }) => { // Get dashboard summary for the period const result = await client.get<DashboardSummary>('/dashboard', { period_days: period_days ?? 30, }); if (result.error) { return { content: [{ type: 'text', text: `Error fetching upgrade data: ${result.error}` }], isError: true, }; } const data = result.data!; const text = formatUpgradeJustification(data, period_days ?? 30); return { content: [{ type: 'text', text }], }; } ); - Helper function formatUpgradeJustification that transforms dashboard data into a structured upgrade justification report with ROI projections, tier comparisons, and recommendations.
function formatUpgradeJustification(summary: DashboardSummary, periodDays: number): string { const lines: string[] = ['## Upgrade Justification Report', '']; // Current tier (assumed Free if no optimization data) lines.push('### Current Status'); lines.push(`**Analysis Period**: Last ${periodDays} days`); lines.push(`**Current Tier**: Free`); lines.push(`**Active Agents**: ${summary.agents.active} / ${summary.agents.total}`); lines.push(`**Total LLM Calls**: ${summary.cost.total_calls.toLocaleString()}`); lines.push(`**Current Monthly Cost**: ${formatCents(summary.cost.total_cost_cents)}`); lines.push(`**Error Rate**: ${formatPct(summary.cost.error_rate)}`); lines.push(''); // Optimization potential (available in Free tier but limited) const currentSavings = summary.optimization?.total_savings_cents || 0; const currentSavingsMontly = (currentSavings / periodDays) * 30; lines.push('### Optimization Potential'); lines.push( `**Available Optimizations**: ${summary.optimization?.suggestion_count || 0} suggestions` ); lines.push( `**Identified Monthly Savings**: ${formatCents(currentSavingsMontly)} (without upgrade)` ); lines.push(''); // Tier comparison and upgrade benefits lines.push('### Upgrade Benefits (Lite Tier)'); lines.push('The Lite tier includes:'); lines.push('- Advanced optimization recommendations (10x more suggestions)'); lines.push('- Real-time failure prediction'); lines.push('- Model routing experiments'); lines.push('- Revenue attribution (if enabled)'); lines.push('- Priority API rate limits (300 req/min vs 30)'); lines.push(''); // Calculate projected ROI const monthlyCost = (summary.cost.total_cost_cents / periodDays) * 30; const liteTierPrice = 29900; // $299/month in cents const upgratedSavings = currentSavingsMontly * 1.5; // Estimate 50% more optimization with Lite lines.push('### ROI Projection'); lines.push(`**Projected Monthly LLM Cost**: ${formatCents(monthlyCost)}`); lines.push(`**Lite Tier Subscription**: ${formatCents(liteTierPrice)}`); lines.push(`**Additional Savings with Lite**: ${formatCents(upgratedSavings)}`); lines.push(''); const netBenefit = upgratedSavings - (liteTierPrice - (currentSavingsMontly / 100) * 100000); // simplified calculation const breakEven = netBenefit > 0 ? 'Upgrade pays for itself immediately' : `Breakeven in ${Math.ceil((liteTierPrice / upgratedSavings) * 30)} days`; lines.push('### Recommendation'); if (summary.cost.total_calls > 100000) { lines.push( `🟢 **Strongly Recommended**: Your volume (${summary.cost.total_calls.toLocaleString()} calls) qualifies for Lite tier.` ); lines.push(`${breakEven}`); if (summary.optimization && summary.optimization.suggestion_count > 5) { lines.push( `You have ${summary.optimization.suggestion_count} active optimization opportunities that Lite tier can fully leverage.` ); } } else if (summary.cost.total_calls > 50000) { lines.push(`🟡 **Consider Lite**: Your volume is growing and you have optimization potential.`); lines.push( 'Upgrade once you hit 100k calls/month or if you need real-time failure prediction.' ); } else { lines.push(`⚠️ **Not Yet Recommended**: Free tier is sufficient for your current volume.`); lines.push('Revisit this when you reach 50,000+ calls per month.'); } lines.push(''); lines.push('---'); lines.push( '*Run `get_cost_summary` periodically to track growth and identify when upgrade becomes beneficial.*' ); return lines.join('\n'); } - Helper function that formats the upgrade justification report, calculating ROI, tier comparisons, and generating recommendations based on usage patterns.
function formatUpgradeJustification(summary: DashboardSummary, periodDays: number): string { const lines: string[] = ['## Upgrade Justification Report', '']; // Current tier (assumed Free if no optimization data) lines.push('### Current Status'); lines.push(`**Analysis Period**: Last ${periodDays} days`); lines.push(`**Current Tier**: Free`); lines.push(`**Active Agents**: ${summary.agents.active} / ${summary.agents.total}`); lines.push(`**Total LLM Calls**: ${summary.cost.total_calls.toLocaleString()}`); lines.push(`**Current Monthly Cost**: ${formatCents(summary.cost.total_cost_cents)}`); lines.push(`**Error Rate**: ${formatPct(summary.cost.error_rate)}`); lines.push(''); // Optimization potential (available in Free tier but limited) const currentSavings = summary.optimization?.total_savings_cents || 0; const currentSavingsMontly = (currentSavings / periodDays) * 30; lines.push('### Optimization Potential'); lines.push( `**Available Optimizations**: ${summary.optimization?.suggestion_count || 0} suggestions` ); lines.push( `**Identified Monthly Savings**: ${formatCents(currentSavingsMontly)} (without upgrade)` ); lines.push(''); // Tier comparison and upgrade benefits lines.push('### Upgrade Benefits (Lite Tier)'); lines.push('The Lite tier includes:'); lines.push('- Advanced optimization recommendations (10x more suggestions)'); lines.push('- Real-time failure prediction'); lines.push('- Model routing experiments'); lines.push('- Revenue attribution (if enabled)'); lines.push('- Priority API rate limits (300 req/min vs 30)'); lines.push(''); // Calculate projected ROI const monthlyCost = (summary.cost.total_cost_cents / periodDays) * 30; const liteTierPrice = 29900; // $299/month in cents const upgratedSavings = currentSavingsMontly * 1.5; // Estimate 50% more optimization with Lite lines.push('### ROI Projection'); lines.push(`**Projected Monthly LLM Cost**: ${formatCents(monthlyCost)}`); lines.push(`**Lite Tier Subscription**: ${formatCents(liteTierPrice)}`); lines.push(`**Additional Savings with Lite**: ${formatCents(upgratedSavings)}`); lines.push(''); const netBenefit = upgratedSavings - (liteTierPrice - (currentSavingsMontly / 100) * 100000); // simplified calculation const breakEven = netBenefit > 0 ? 'Upgrade pays for itself immediately' : `Breakeven in ${Math.ceil((liteTierPrice / upgratedSavings) * 30)} days`; lines.push('### Recommendation'); if (summary.cost.total_calls > 100000) { lines.push( `🟢 **Strongly Recommended**: Your volume (${summary.cost.total_calls.toLocaleString()} calls) qualifies for Lite tier.` ); lines.push(`${breakEven}`); if (summary.optimization && summary.optimization.suggestion_count > 5) { lines.push( `You have ${summary.optimization.suggestion_count} active optimization opportunities that Lite tier can fully leverage.` ); } } else if (summary.cost.total_calls > 50000) { lines.push(`🟡 **Consider Lite**: Your volume is growing and you have optimization potential.`); lines.push( 'Upgrade once you hit 100k calls/month or if you need real-time failure prediction.' ); } else { lines.push(`⚠️ **Not Yet Recommended**: Free tier is sufficient for your current volume.`); lines.push('Revisit this when you reach 50,000+ calls per month.'); } lines.push(''); lines.push('---'); lines.push( '*Run `get_cost_summary` periodically to track growth and identify when upgrade becomes beneficial.*' ); return lines.join('\n'); } - src/types.ts:44-67 (schema)Type definition for DashboardSummary which is the primary data structure used by the upgrade justification tool to analyze cost, agents, and optimization potential.
export interface DashboardSummary { is_preview: boolean; stage: string; period_days: number; agents: { total: number; active: number }; agents_list: AgentSummary[]; cost: { total_calls: number; total_cost_cents: number; error_calls: number; error_rate: number; }; attribution?: { total_outcomes: number; total_revenue_cents: number; net_value_cents: number; roi_multiplier: number; }; optimization?: { total_savings_cents: number; suggestion_count: number; top_suggestion?: string; }; } - src/server-factory.ts:78-78 (registration)Call to registerUpgradeJustificationTools in the server factory, which registers all tools including the upgrade justification tool.
registerUpgradeJustificationTools(server, apiClient); - src/index.ts:44-44 (registration)Import statement that brings in the registerUpgradeJustificationTools function.
import { registerUpgradeJustificationTools } from './tools/upgrade-justification.js'; - src/server-factory.ts:65-67 (registration)The wrapper that adds the 'metrx_' prefix to all tool names, transforming 'get_upgrade_justification' to 'metrx_get_upgrade_justification'.
// Register with metrx_ prefix (primary name only — no deprecated aliases) const prefixedName = name.startsWith(METRX_PREFIX) ? name : `${METRX_PREFIX}${name}`; originalRegisterTool(prefixedName, config, wrappedHandler); - src/index.ts:113-113 (registration)Call to registerUpgradeJustificationTools that registers the tool with the MCP server and applies the 'metrx_' namespace prefix.
registerUpgradeJustificationTools(server, apiClient);