compare_models

Instructions

Implementation Reference

• src/tools.ts:351-410 (handler)

  The core handler for the compare_models tool. Parses input (provider, min_context, mode), filters models from the pricing data, sorts by input cost, and returns the top 5 most cost-effective matches with details.

  case "compare_models": {
    const { provider, min_context, mode } = compareModelsSchema.parse(args);
    const models = await getModels();
  
    let filtered = Object.values(models);
  
    if (provider) {
      const lowerProvider = provider.toLowerCase();
      filtered = filtered.filter(
        (m) =>
          m.litellm_provider.toLowerCase().includes(lowerProvider) ||
          m.key.toLowerCase().includes(lowerProvider),
      );
    }
  
    if (min_context !== undefined) {
      filtered = filtered.filter(
        (m) => m.max_input_tokens !== null && m.max_input_tokens >= min_context,
      );
    }
  
    if (mode) {
      const lowerMode = mode.toLowerCase();
      filtered = filtered.filter((m) => m.mode.toLowerCase() === lowerMode);
    }
  
    if (filtered.length === 0) {
      return {
        content: [
          {
            type: "text",
            text: "No models match the given criteria. Try broadening your filters.",
          },
        ],
      };
    }
  
    // Sort by input cost (most cost-effective first)
    filtered.sort((a, b) => a.input_cost_per_token - b.input_cost_per_token);
    const top = filtered.slice(0, 5);
  
    const header = `Top ${top.length} most cost-effective models${provider ? ` (provider: ${provider})` : ""}${min_context ? ` (min context: ${formatTokenCount(min_context)})` : ""}${mode ? ` (mode: ${mode})` : ""}:\n`;
  
    const rows = top.map(
      (m, i) =>
        `${i + 1}. ${m.key}\n` +
        `   Provider: ${m.litellm_provider} | Mode: ${m.mode}\n` +
        `   Input: ${formatCost(m.input_cost_per_million)}/1M | Output: ${formatCost(m.output_cost_per_million)}/1M\n` +
        `   Context: ${formatTokenCount(m.max_input_tokens)} in / ${formatTokenCount(m.max_output_tokens)} out` +
        (m.cache_read_input_token_cost_per_million != null
          ? `\n   Prompt caching: ${formatCost(m.cache_read_input_token_cost_per_million)}/1M cached input`
          : ""),
    );
  
    const total = `\n(${filtered.length} models matched total)`;
  
    return {
      content: [{ type: "text", text: header + rows.join("\n\n") + total }],
    };
  }

• src/tools.ts:98-102 (schema)

  Zod validation schema for the compare_models tool's input parameters. All fields (provider, min_context, mode) are optional.

  const compareModelsSchema = z.object({
    provider: z.string().optional(),
    min_context: z.number().optional(),
    mode: z.string().optional(),
  });

• src/tools.ts:50-83 (registration)

  Registration of the compare_models tool in the tools array, defining its name, description, and JSON Schema input schema.

  {
    name: "compare_models",
    description:
      "Filter and compare models by provider, minimum context window, or mode. Returns top 5 most cost-effective matches.",
    inputSchema: {
      type: "object" as const,
      properties: {
        provider: {
          type: "string",
          description: "Filter by provider (e.g. 'anthropic', 'openai', 'google', 'amazon')",
        },
        min_context: {
          type: "number",
          description: "Minimum context window size in tokens",
        },
        mode: {
          type: "string",
          description:
            "Filter by mode (e.g. 'chat', 'embedding', 'completion', 'image_generation')",
        },
      },
      required: [],
    },
  },
  {
    name: "refresh_prices",
    description:
      "Force a re-fetch of pricing data from the LiteLLM registry. Use this if you suspect the cached data is stale.",
    inputSchema: {
      type: "object" as const,
      properties: {},
      required: [],
    },
  },

• src/index.ts:21-23 (registration)

  MCP server registration: the ListTools request returns the tools array (including compare_models), and the CallTool request dispatches to executeTool, which handles compare_models via its switch-case.

  server.setRequestHandler(ListToolsRequestSchema, async () => {
    return { tools };
  });

• src/tools.ts:104-116 (helper)

  Helper functions used by the compare_models handler: formatCost formats dollar amounts with appropriate precision, and formatTokenCount formats token counts with K/M suffixes.

  function formatCost(amount: number): string {
    if (amount < 0.0001) return `$${amount.toFixed(8)}`;
    if (amount < 0.01) return `$${amount.toFixed(6)}`;
    if (amount < 1) return `$${amount.toFixed(4)}`;
    return `$${amount.toFixed(2)}`;
  }
  
  function formatTokenCount(n: number | null): string {
    if (n === null) return "unknown";
    if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
    if (n >= 1_000) return `${(n / 1_000).toFixed(0)}K`;
    return n.toString();
  }