find_customers
ChatGPTUse this when the user names a UsageTap customer and you need its exact external customer ID for a follow-up tool, or when the user asks to look up a customer by friendly name, exact contact email, or external ID. Defaults to ACTIVE and returns at most 20 bounded matches so ambiguity can be resolved. Use list_customers for broad enumeration. Contact email is masked unless explicitly requested.
get_customer_signals
ChatGPTUse this when the user asks which UsageTap customers just joined (including zero usage), need attention, are approaching or have exhausted limits, changed usage, recently activated, or should be prioritized for human outreach. Filter read-only signals by severity, type, lifecycle status, customer ID, or plan. Use get_usage_anomalies for organization-level time-series anomalies and get_customer_usage for one customer's current allowance details. This tool never contacts or modifies customers and does not track CRM workflow state.
get_customer_usage
ChatGPTUse this when the user asks for one UsageTap customer's current plan, meter allowances, remaining balances, entitlements, or API rate-limit status. The input must be the exact external customer ID; if the user supplies only a name or email, call find_customers first. This returns a current snapshot, not historical usage or a forecast.
get_customer_usage_context
ChatGPTUse this when the user needs one customer's account brief, recent usage movement, replenishment outlook, forecast status, or an evidence-based explanation of why the account needs review. The input must be the exact external customer ID; call find_customers first for a friendly name or email. Use get_customer_usage for only the current allowance snapshot and summarize_calls for model, provider, feature, or call rankings. This tool cannot contact customers, change plans, or guarantee service interruption.
get_usage_anomalies
ChatGPTUse this when the user asks what is unusual, spiking, or dropping in the authenticated organization's UsageTap calls, tokens, or USD cost. It returns UsageTap's existing bounded daily and hourly anomaly results for one selected metric. Use get_customer_signals for customer allowance or customer-attention conditions. This tool does not recalculate or invent anomalies.
get_usage_overview
ChatGPTUse this when the user asks for a high-level recent UsageTap usage overview for the entire authenticated organization and does not require a custom date range or grouping. It returns the server-defined bounded period, totals, daily series, USD cost, tokens, calls, and active-customer counts. Use summarize_calls for explicit ranges or ranked breakdowns. This tool does not forecast future usage.
list_calls
ChatGPTUse this when the user needs individual UsageTap LLM call records or row-level inspection for an explicit time range. Supply inclusive startTime and exclusive endTime spanning at most 31 days, and optionally an exact customerId. Results are newest first and paginated; they include customer, feature, provider/model, status, tokens, and recorded USD cost but never prompt or response content. Use summarize_calls for totals or rankings and get_usage_overview for a ready-made recent organization summary.
list_customers
ChatGPTUse this when the user wants to browse, enumerate, or count UsageTap customers by lifecycle status without naming a specific customer. Defaults to ACTIVE and returns a paginated customer directory; follow nextCursor until null for a complete list. Use find_customers for a name, email, or external-ID lookup. This tool does not return usage totals, and contact email is masked unless explicitly requested.
refresh_customer_usage_view
ChatGPTUse from the customer usage widget to refresh its facts or select another forecast metric without opening another widget. Requires the displayed customer's exact ID.
show_customer_usage
ChatGPTUse this when the user asks for one UsageTap customer's interactive usage card or visual forecast. It returns a concise text fallback, structured customer context, and an interactive card. First use find_customers for a name or email, then pass the exact customer ID. Set view=forecast for a chart or forecast, otherwise use overview. The existing get_customer_usage and get_customer_usage_context tools remain available for data-only requests. Forecast quality and funding qualify any allowance exhaustion estimate. Read-only; no plan changes, purchases, or outreach.
summarize_calls
ChatGPTUse this when the user asks for UsageTap call, token, or USD-cost totals or top rankings over an explicit time range, grouped by customer, feature, model, provider, UTC day, or status. Supply inclusive startTime and exclusive endTime spanning at most 31 days. Use list_calls for individual records and get_usage_overview when no custom range or grouping is needed. Bounded reads return no partial totals if incomplete; check missingCostCalls and missingTokenCalls before treating metering as complete.
