Llm Usage MCP vs Spanlens

recommend_provider

Recommend the cheapest priced model that fits the workload + budget. v1 ranks by cost only. A future release will incorporate quality benchmarks (see `quality_snapshot` — the table is reserved for that purpose) and accept a `quality_priority` axis; for v1 those would rely on data we don't yet have, so the surface stays cost-only and honest. `expected_input_tokens` / `expected_output_tokens` default to a nominal 1k/1k workload when absent; the `reasoning` notes when defaults are in use. `budget_usd`, when set, filters out models that exceed it — if nothing fits, falls back to the cheapest model overall (the result fields are required, so there's no "no match" return shape) and the `reasoning` says so plainly. `providers` / `models` are optional whitelists (AND-combine when both passed). Both are applied before the budget cut, so an over- budget fallback returns the cheapest within the filter set rather than the cheapest priced model overall. A whitelist that matches nothing raises rather than fabricating a result — likely a spelling error in the caller's name list. `task_description` is **optional** and echoed into the reasoning but does not drive selection — the tool isn't an LLM and can't interpret free text. Omit it (or pass `None`) and the reasoning opens with `"Recommending …"` instead of `"For task 'X': …"`.

get_pricing

Return current pricing for one model, one provider, or all models. Both filters are optional and AND-combined. An unknown (provider, model) returns an empty list rather than an error — the caller can distinguish "model not in our table" from "no model matches your filter" by passing `provider` alone.

usage_summary

Return a one-shot summary of usage over a named calendar period. `period` is one of today | week | month | year (default: "week"). Boundaries are calendar UTC: `today` = since 00:00 UTC today, `week` = since Monday 00:00 UTC, `month` = since the 1st of the month, `year` = since January 1st. Returns totals, the top-3 providers and top-3 models by cost (with `pct` of total), and the single most expensive call in the window — or `largest_call=None` when the window is empty. `include_failed` defaults to `False`: totals, top-N rollups, and `largest_call` all exclude `success=False` rows (partial-stream captures and other failure rows). Pass `True` for symmetric debugging access to the failure population.

list_providers

List every provider we know about, with their models and OpenAI-compat flag. Sources the provider/model lists from `pricing_snapshot`, so a provider whose pricing hasn't been seeded simply doesn't appear. After `bootstrap()` runs on a fresh install this includes every v1 provider (anthropic, openai, qwen, deepseek). Order is alphabetical by provider, then by model within each provider.