get_usage_warnings

Monitor Claude usage and receive alerts when approaching typical limits to prevent unexpected costs or interruptions.

Instructions

Get usage warnings with default thresholds (80% and 90% of typical limits)

Input Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Implementation Reference

src/index.ts:268-285 (handler)

The MCP tool handler for 'get_usage_warnings'. Uses default token limits, calls checkUsageLimits on TelemetryService, and formats warnings for response.

case 'get_usage_warnings': {
  // Use default thresholds
  const defaultLimits: UsageLimits = {
    dailyTokenLimit: 100000, // Example default
    weeklyTokenLimit: 500000, // Example default
    sessionTokenLimit: 50000, // Example default
  };

  const warnings = await this.telemetryService.checkUsageLimits(defaultLimits);
  return {
    content: [
      {
        type: 'text',
        text: this.formatUsageWarnings(warnings, true),
      },
    ],
  };
}

src/index.ts:105-112 (registration)

Tool registration in ListTools response, specifying name, description, and empty input schema.

{
  name: 'get_usage_warnings',
  description: 'Get usage warnings with default thresholds (80% and 90% of typical limits)',
  inputSchema: {
    type: 'object',
    properties: {},
  },
},

src/telemetry-service.ts:177-232 (helper)

Core helper function that computes usage warnings by comparing current metrics against provided limits at 80% and 90% thresholds.

async checkUsageLimits(limits: UsageLimits): Promise<UsageWarnings> {
  const summary = await this.getUsageSummary();
  const warnings: string[] = [];
  const percentages: any = {};

  // Check daily limits
  if (limits.dailyTokenLimit) {
    const dailyPercent = (summary.today.tokens / limits.dailyTokenLimit) * 100;
    percentages.dailyTokens = dailyPercent;
    if (dailyPercent > 90) {
      warnings.push(`Daily token usage at ${dailyPercent.toFixed(1)}% of limit`);
    } else if (dailyPercent > 80) {
      warnings.push(`Daily token usage approaching limit (${dailyPercent.toFixed(1)}%)`);
    }
  }

  // Check weekly limits
  if (limits.weeklyTokenLimit) {
    const weeklyPercent = (summary.thisWeek.tokens / limits.weeklyTokenLimit) * 100;
    percentages.weeklyTokens = weeklyPercent;
    if (weeklyPercent > 90) {
      warnings.push(`Weekly token usage at ${weeklyPercent.toFixed(1)}% of limit`);
    } else if (weeklyPercent > 80) {
      warnings.push(`Weekly token usage approaching limit (${weeklyPercent.toFixed(1)}%)`);
    }
  }

  // Check session limits
  if (limits.sessionTokenLimit) {
    const sessionPercent = (summary.currentSession.tokens / limits.sessionTokenLimit) * 100;
    percentages.sessionTokens = sessionPercent;
    if (sessionPercent > 90) {
      warnings.push(`Session token usage at ${sessionPercent.toFixed(1)}% of limit`);
    } else if (sessionPercent > 80) {
      warnings.push(`Session token usage approaching limit (${sessionPercent.toFixed(1)}%)`);
    }
  }

  // Similar checks for cost limits...
  if (limits.dailyCostLimit) {
    const dailyCostPercent = (summary.today.cost / limits.dailyCostLimit) * 100;
    percentages.dailyCost = dailyCostPercent;
    if (dailyCostPercent > 80) {
      warnings.push(`Daily cost approaching limit (${dailyCostPercent.toFixed(1)}%)`);
    }
  }

  return {
    warnings,
    usage: {
      current: summary.today,
      limits,
      percentages
    }
  };
}

src/index.ts:428-451 (helper)

Helper method to format UsageWarnings into a user-friendly markdown response.

private formatUsageWarnings(warnings: UsageWarnings, isDefault: boolean = false): string {
  let result = '## Usage Warnings\n\n';
  
  if (warnings.warnings.length === 0) {
    result += '✅ No usage warnings - you\'re within safe limits\n\n';
  } else {
    result += '⚠️ **Warnings**:\n';
    warnings.warnings.forEach((warning: string) => {
      result += `- ${warning}\n`;
    });
    result += '\n';
  }

  if (isDefault) {
    result += '_Note: Using default limit thresholds. Use check_usage_limits with custom limits for precise tracking._\n\n';
  }

  result += '**Current Usage**:\n';
  result += `- Tokens: ${warnings.usage.current.tokens.toLocaleString()}\n`;
  result += `- Cost: $${warnings.usage.current.cost.toFixed(4)}\n`;
  result += `- Sessions: ${warnings.usage.current.sessions}\n`;

  return result;
}

src/types.ts:75-98 (schema)

TypeScript interfaces defining UsageLimits (input-like for limits) and UsageWarnings (output structure) used by the tool.

export interface UsageLimits {
  dailyTokenLimit?: number;
  weeklyTokenLimit?: number;
  sessionTokenLimit?: number;
  dailyCostLimit?: number;
  weeklyCostLimit?: number;
  sessionCostLimit?: number;
}

export interface UsageWarnings {
  warnings: string[];
  usage: {
    current: UsageData;
    limits: UsageLimits;
    percentages: {
      dailyTokens?: number;
      weeklyTokens?: number;
      sessionTokens?: number;
      dailyCost?: number;
      weeklyCost?: number;
      sessionCost?: number;
    };
  };
}

Claude Telemetry MCP