Skip to main content

​
MarginFront MCP Tools Reference

This is a complete list of the core MarginFront MCP tools. There are 58 tools total, organized into groups: read-only, write, diagnostic, destructive, canonical analytics, pricing setup, portal sessions, catalog discovery, spend controls, credit pools, customer alerts, and matters. Your AI assistant calls these tools automatically when you ask it questions about your MarginFront data. You don’t need to memorize tool names. Just ask in plain English and the AI picks the right tool. Detailed parameters and examples for every tool live in the machine-readable llms-mcp.txt, which is the canonical source the MCP server and AI clients both read.

​
Read-Only Tools (10)

These tools look things up without changing anything.

​
1. verify

What it does: Checks that your API key is valid and shows which organization it belongs to. This is the “hello world” of MCP — call it first to make sure everything is wired up. Parameters: None. What it returns: Your organization name and a verified status. Example prompt: “Verify my MarginFront connection”

​
2. list_customers

What it does: Lists your customers with optional search and pagination. Good for browsing your customer list or finding a specific customer by name. Parameters: What it returns: A list of customers with their names, MarginFront UUIDs, external IDs, and status. Example prompt: “Show me my MarginFront customers”

​
3. get_customer

What it does: Gets detailed information about one specific customer, including their subscriptions. Parameters: What it returns: Full customer details — name, email, phone, external ID, status, and all their subscriptions. Example prompt: “Tell me about customer 7a2b3c4d-5e6f-7890-abcd-ef1234567890”
Note: This tool needs the MarginFront UUID, not the external ID you use in your own system. Use list_customers first to find the UUID.

​
4. list_invoices

What it does: Lists invoices with optional filters by status or customer. Parameters: What it returns: A list of invoices showing status, amounts, customer name, and dates. Example prompt: “Show me all pending invoices”

​
5. get_invoice

What it does: Gets full details about one invoice, including every line item and payment history. Parameters: What it returns: The complete invoice — line items (what was billed), amounts, payment status, customer info, and dates. Example prompt: “Show me the details on invoice 1a2b3c4d-5e6f-7890-abcd-ef1234567890”

​
6. list_events

What it does: Lists usage events (the raw records of what your customers actually used) with optional filters. Parameters: What it returns: A list of events, each showing the model used, token counts, calculated cost, customer, and timestamp. Example prompt: “What events were logged today?” or “Show me events for customer acme-001 this week.”

​
7. get_usage_analytics

What it does: Gets aggregated usage analytics (totals and trends) for a date range. Unlike list_events which shows individual events, this gives you the big picture — totals, breakdowns, and time-series data. Parameters: What it returns: Summary totals (total cost, total events, total tokens) plus a breakdown grouped however you specified. Example prompt: “Show me usage analytics for April grouped by customer”

​
8. list_subscriptions

What it does: Lists customer subscriptions (which customer is on which pricing plan). Parameters: What it returns: A list of subscriptions showing status, plan name, billing dates, and customer info. Example prompt: “Show me all active subscriptions”

​
9. list_agents

What it does: Lists your agents with optional search and filters. Each row’s id is the agent UUID that create_signal, create_pricing_strategy, link_plan_to_agent, and create_subscription ask for. Recording usage auto-creates agents on the first event, so this is also how you find an agent that was created that way (its agentCode is the code the first event used). Parameters: What it returns: A paginated list of agents, each with its id, name, agentCode, active status, and counts of signals, linked plans, and subscriptions. Example prompt: “Show me my agents” or “Find the agent with code cs-bot”

​
10. list_signals

What it does: Lists signals with optional filters. Each row’s id is the signal UUID that create_pricing_strategy needs for usage charge types and credit pools. Recording usage auto-creates signals on the first event, so this is also how you find a signal that was created that way (its name is the signalName the first event used). Parameters: What it returns: A paginated list of signals, each with its id, name, short name, agent UUID, and type. Example prompt: “List the signals on the cs-bot agent”

​
Write Tools (7)

These tools create or modify data. They change things in MarginFront, so the AI will usually confirm before calling them.

​
11. record_usage

What it does: Records a single usage event — one measurement of a customer using your AI agent. This is how MarginFront learns what to bill for. There are three patterns the same tool accepts:
  • Single-service LLM event (chatbots, summarizers, etc.): pass top-level model + modelProvider + inputTokens + outputTokens.
  • Single-service non-LLM event (SMS, web scraping, API calls, etc.): pass top-level model + modelProvider + quantity.
  • Multi-service event (one outcome backed by multiple underlying services, e.g. one report that called Claude AND queried Google Maps): pass a services[] array, one entry per underlying service. Top-level quantity stays signal-level (default 1). Top-level model / modelProvider are omitted.
The single-service shape and multi-service shape are mutually exclusive. Send top-level model + modelProvider OR send services[], never both, never neither. The MCP tool rejects with a clear English error before the request leaves the agent if you mix shapes. Parameters: What it returns:
  • For single-service: the event ID, calculated cost (in USD), and timestamp.
  • For multi-service: the parent event ID, rolled-up totalCostUsd (sum across services), a services[] array showing per-service cost + status, and timestamp.
If any service in a multi-service event isn’t in the pricing table, the parent’s totalCostUsd stays null until ALL services are mapped (the cost rule). The services[] response array shows exactly which entries are unresolved so you can call map_model on the right one. Use get_needs_attention to see all unmapped models across all events. Example prompts:
  • Single-service: "Record a usage event: customer acme-001 used cs-bot, signal messages, gpt-4o from openai, 500 input tokens, 120 output tokens"
  • Multi-service: "Record one cold outreach for customer acme-001 on the outreach-bot. The outreach used Exa search (1 call), Hunter enrichment (1 call), Claude Opus to write the message (4500 input + 1200 output tokens, 1 call), and Pipedream to send (1 call). Track it as ONE event."
Important: If you get a “NEEDS_COST_BACKFILL” response, do NOT re-send the event. The event was saved. The model (or one of the services) just isn’t in the pricing table yet. Use get_needs_attention to see which models need mapping, then map_model to fix them.

​
12. record_usage_batch

What it does: Records multiple usage events at once (1 to 100 per request). Each record has the same fields as record_usage — including the choice between single-service shape (top-level model + modelProvider) and multi-service shape (services[]). You can mix all three patterns (single-service LLM, single-service non-LLM, multi-service) in the same batch. Parameters: What it returns: A summary showing how many succeeded, how many failed, and per-record details for each. Successes include the same shape as record_usage. Failed records that were still saved (like NEEDS_COST_BACKFILL or MISSING_VOLUME_DATA) are flagged — do NOT retry those. For multi-service failed records, the response includes a servicesStatus[] array so you see which specific service in the batch entry needs fixing. Example prompt: “Record these for customer acme-001: 3 messages on cs-bot using gpt-4o from openai (200 input / 50 output each), and one cold outreach on outreach-bot that used Exa (1 call), Hunter (1 call), Claude Opus (4500/1200 tokens, 1 call), and Pipedream (1 call).“

​
13. create_customer

What it does: Creates a new customer in MarginFront. Parameters: What it returns: The newly created customer with their MarginFront UUID. Example prompt: “Create a customer called Beta Corp with external ID beta-001”
Tip: Always set externalId when creating a customer. That’s the ID you’ll use when recording usage events later, so it should match whatever ID you use for this customer in your own system.

​
14. create_agent

What it does: Creates an agent — the billable thing you meter (a chatbot, a report generator, a pipeline). Pricing plans link to agents and subscriptions bill per agent, so this comes first when setting up from zero. Requires: a key with the Developer role (Admin and Owner keys also work). Parameters: What it returns: The created agent with its MarginFront UUID — the agent ID that create_signal, pricing, and subscriptions need. Example prompt: “Create an agent called Customer Support Agent with code cs-bot”
If the code already exists: the API answers with a conflict. That’s common, because recording usage auto-creates agents. Don’t retry — call list_agents to fetch the existing agent’s UUID and keep going.

​
15. create_signal

What it does: Creates a signal — the billing unit an agent tracks, like "messages" or "reports-generated". The signal name is the line item your customer reads on their invoice, so match the language they bill by (“per page” means the signal is "pages"). Create the signal before pricing: usage and credit-pool strategies need its UUID up front, and this tool returns it. Requires: a key with the Developer role (Admin and Owner keys also work). Parameters: What it returns: The created signal with its MarginFront UUID — the signal ID that create_pricing_strategy needs. Example prompt: “Create a signal called messages on the cs-bot agent”
If the name already exists on that agent: the API answers with a conflict (recording usage auto-creates signals). Call list_signals to fetch the existing signal’s UUID instead of retrying.

​
16. generate_invoice

What it does: Builds a draft invoice from a subscription’s tracked usage. Reads the period’s usage events, applies the subscription’s pricing strategies, and writes a draft invoice with line items and totals — ready to preview, edit, or send. This is the right tool when you want to “bill now” instead of waiting for the end of the billing period. The draft starts in draft status; nothing is sent to the customer until you (or the auto-finalize step) move it to issued. Parameters: What it returns: The full draft invoice, including line items, totals, and the invoice UUID. Example prompt: “Generate a draft invoice for Acme Corp’s Growth Plan subscription using this period’s usage”

​
17. send_invoice

What it does: Emails an invoice to the customer with a “Pay Now” button that opens Stripe Checkout pre-filled with the invoice details. Use this after generate_invoice to actually deliver a draft, or to re-send an invoice that has already been issued. The customer’s stored email address is used by default — pass recipientEmail to override (for example, to route the invoice to a different billing contact). Parameters: What it returns: A confirmation including the email provider’s message ID (for delivery tracking) and the address the email was actually sent to (after applying any override). Example prompts:
  • “Email the latest draft invoice to Acme Corp”
  • “Send invoice inv_abc to [email protected] with the subject ‘May invoice — auto-charge in 5 days’”
Side effect: if the invoice is still a draft when you call this, sending it auto-finalizes the status to issued. This matches the dashboard Send button and the end-of-period auto-finalize step. Once the customer pays via the Stripe Checkout link, the invoice flips to paid automatically — no follow-up call needed.

​
Diagnostic Tool (1)

This tool helps you find and fix data issues.

​
18. get_needs_attention

What it does: Finds usage events where the model+provider combination isn’t in the pricing table. These events were saved (the data isn’t lost), but their cost is null because MarginFront doesn’t know how much that model costs. Parameters: What it returns: Groups of unrecognized model+provider combinations, each with a count of how many events are affected. Example prompt: “Are there any MarginFront events with unknown models?”
Important: These events ARE saved — they just have cost=null. Do NOT re-send them. Use map_model (below) to tell MarginFront what pricing to use, and it will backfill the costs automatically.

​
Destructive Tool (1)

This tool modifies existing data. “Destructive” sounds scary, but it’s actually a fix-it tool — and it’s safe to run more than once (it’s idempotent, meaning running it twice produces the same result as running it once).

​
19. map_model

What it does: Maps an unknown model to a known one in the pricing table, then backfills costs for all affected events. This creates a permanent, organization-scoped mapping — once you map it, future events with the same model+provider will have their costs calculated automatically. You tell it the “source” (the unknown model) and the “target” (the known model to price it as). You can identify the target two ways:
  • By name: pass targetModel + targetProvider (e.g., map “gpt-4o-2024-08-06” to “gpt-4o” from “openai”).
  • By ID: pass targetPricingId (the UUID of the specific pricing table row).
Parameters:
*You must provide either targetPricingId OR both targetModel + targetProvider. One or the other, not both.
What it returns: Confirmation of the mapping, how many events had their costs backfilled, and the mapping ID. Example prompt: “Map model gpt-4o-2024-08-06 from openai to gpt-4o from openai”
Safe to run again: If you accidentally run this twice with the same inputs, nothing bad happens. It’s idempotent.

​
Diagnostic Tools (2)

​
20. get_missing_volume

What it does: Lists usage events that landed in the MISSING_VOLUME_DATA state: events where the agent didn’t send tokens (for LLM calls) or quantity (for non-LLM). The platform stored them anyway, waiting for the volume data to arrive. Parameters: What it returns: Groups by model and provider, each with an event count and the costUnit, so you know whether that group needs tokens or quantity when you fix it with fill_volume. Example prompt: “Show me any LLM events still missing tokens” or “Which events landed without quantity this month?“

​
21. fill_volume

What it does: Supplies the missing volume data for MISSING_VOLUME_DATA events, in bulk. You name the model + provider (the same grouping get_missing_volume returns), give the volume to apply, and every matching incomplete event is updated in one operation: cost recalculates and the events flip to PROCESSED. Parameters: What it returns: A summary: the model and provider, the volume applied, and how many events were backfilled with calculated costs. Example prompt: “Fill in 1500 input and 400 output tokens for the gpt-4o events that are missing volume”
Heads up: the same volume numbers are applied to EVERY matching incomplete event for that model + provider. Future events still need correct volume fields in the request itself.

​
Canonical Analytics Tools (3)

These tools expose MarginFront’s single source of truth for revenue, cost, and MRR. They return the same numbers the dashboard KPI tiles display.

​
22. get_customer_revenue

What it does: Returns revenue, cost, and margin for a single customer over a date range. Use this when an AI agent needs to answer “how much has this customer paid us?” or “what’s our margin on this account?” without loading the full analytics view. Parameters: What it returns: Revenue (billed invoiced amount over the window), cost (sum of usageCost for attributed events), and margin = revenue − cost. Also breaks down revenue by type (usage, recurring, seat, onetime). Example prompt: “What’s our revenue and margin for Acme Corp this quarter?“

​
23. get_cost_metrics

What it does: Returns the full cost breakdown across the organization (or filtered to a single customer / agent). Includes per-day, per-agent, per-customer, per-signal, per-plan, per-model splits. Optional prior-window trend comparison. Parameters: What it returns: Total cost, event counts, and breakdown arrays (byAgent, byCustomer, bySignal, byDay, byPlan, byModel). When includePriorWindow is true, also returns prior with the same shape for the preceding equivalent period. Example prompt: “Break down our AI costs by model for last month” or “Show cost trend for Deal Ops agent week over week.”

​
24. get_mrr

What it does: Returns Monthly Recurring Revenue using one of three canonical variants. MarginFront tracks three distinct MRR computations because “what’s our MRR?” has three different right answers depending on what question you’re asking. Parameters: What it returns: The MRR amount for the requested variant + breakdown by revenue type (usage, recurring, seat, onetime). Example prompt: “What was our MRR last month?” (defaults to canonical) or “What’s our run-rate MRR if usage keeps trending?” (runRate) or “What’s our committed MRR floor for forecasting?” (committed).

​
Pricing Setup Tools (7)

​
25. create_pricing_plan

What it does: Creates a new pricing plan for an agent. A pricing plan is a container for pricing strategies (which are the per-signal billing rules). Parameters: What it returns: The new plan with its UUID. Example prompt: “Create a Growth plan for our Outreach Writer agent”

​
26. list_pricing_plans

What it does: Lists all pricing plans for the organization, with optional filtering by agent. Parameters: What it returns: Array of plans with their UUID, name, description, agent binding, and an embedded list of pricing strategies attached.

​
27. get_pricing_plan

What it does: Returns full details on a single pricing plan, including all its pricing strategies and their rates. Parameters: What it returns: Plan with name, description, agent, and every pricing strategy (chargeType, pricingModel, rates, tiers, minimum commitments).

​
28. create_pricing_strategy

What it does: Creates a pricing strategy on an existing plan. A strategy is the per-signal rule: “for this metric, charge this way.” Parameters: What it returns: The new strategy’s UUID and validated config.

​
29. list_pricing_strategies

What it does: Lists all pricing strategies on a plan. Parameters: What it returns: Array of strategies with their config.
What it does: Attaches an existing pricing plan to an agent. An agent can be attached to multiple plans (each pricing different customer tiers). Parameters: What it returns: The junction row confirming the link.

​
31. create_subscription

What it does: Creates a subscription tying a customer to an agent + plan. Once created, events fired for this (customer, agent, signal) combination bill against this subscription’s pricing strategies. Parameters: What it returns: New subscription with its UUID, scoped to the (customer, agent, plan) triple. Example prompt: “Create a Growth Plan subscription for Acme Corp on the Outreach Writer agent, billed monthly, usage model.”

​
Portal Sessions (4)

These four tools let an AI assistant mint and manage one-time portal links — the URLs you send to your customers so they can see their own billing on a MarginFront-hosted page. See the Portal Sessions API reference for the full plain-English explanation.

​
32. create_portal_session

What it does: Mints a one-time portal link for a customer. The URL is good for one hour and stops working the moment the customer opens it. Parameters: What it returns: The session ID, the URL to send your customer, the token, customer details, and the expiry timestamp. Example prompt: “Send acme-001 a portal link”

​
33. get_portal_session

What it does: Looks up one portal session by ID. Use this to check whether a link has been opened or has expired. Does NOT return the token or url — those are only shown at creation. Parameters: What it returns: Session metadata — customer, expiry, redeem status. Example prompt: “Has Acme opened the portal link I sent yesterday?“

​
34. list_portal_sessions

What it does: Lists portal sessions your organization has created. Useful for audit or support. Tokens are intentionally omitted from the response. Parameters: What it returns: A list of session metadata records. Example prompt: “Show me all portal links we sent Acme this month”

​
35. revoke_portal_session

What it does: Immediately invalidates a portal session. Use this if you sent a link to the wrong customer or need to cut access early. Hard delete — the session row is removed. Parameters: What it returns: A confirmation that the session was revoked. Example prompt: “Cancel the portal link I sent Acme yesterday”

​
Catalog Discovery (1)

This tool lets the AI look up canonical model and provider names from MarginFront’s global service pricing catalog before firing usage events. Use it to avoid the “guess and check until cost resolves” cycle.

​
36. list_catalog_services

What it does: Browses the global service catalog — every model and non-LLM service MarginFront can calculate cost for. Filter by provider, service type, or free-text search to find the canonical model + modelProvider names to send with record_usage so cost auto-resolves on ingest. The catalog is read-only and global (not org-scoped). Parameters: What it returns: Paginated catalog entries. Each entry includes canonicalName (what to send as model), provider (what to send as modelProvider), serviceType, per-unit inputCost / outputCost, costUnit, and contextWindow for LLMs. Example prompts:
  • “What canonical name should I use for GPT-4o when recording usage?”
  • “List every Google service in the MarginFront catalog.”
  • “Find the catalog entry for Twilio SMS so I can record an event.”
Tip: Pair this with record_usage — look up the canonical name first, then fire the event using that exact name and provider. Cost resolves automatically without a NEEDS_COST_BACKFILL round trip. See the Services Catalog reference for the full field list.

​
Spend Controls (5)

These tools read and manage spend caps: the limits your company sets on its own AI coding spend. They’re the same caps the dashboard’s Internal AI Spend page shows. See the Spend Controls API reference for what scopes, modes, and the ceiling rule mean. Reading the caps, current spend, and coverage (get_spend_controls) works with any secret key for your organization; a publishable key (mf_pk_...) is refused. The internal spend breakdown (get_internal_spend_breakdown) needs a little more: a secret key that belongs to an owner, admin, or finance user, because it exposes per-repo spend and teammate-level detail. The three write tools need an owner or finance user’s key. Any other key gets a clear 403 explaining which role is required.

​
37. get_spend_controls

What it does: Reads everything about your spend controls in one call: the cap policies (each with its plain sentence), spend-so-far for a period, and coverage (“N of M developers armed”). Parameters: What it returns: The caps (each with its sentence), the spend read-back for the period, and the coverage counts. spentUsd is null when there’s no priced usage yet: that’s honest absence, not $0. Example prompt: “What are our spend caps and how much have we used this week?“

​
38. get_internal_spend_breakdown

What it does: Breaks down internal coding-agent spend (Claude Code and Codex events only, never customer billing) for the current period, grouped by git repo or branch. Branch spend is the closest stand-in for cost per pull request. Events outside a tracked repo appear in the no-repo bucket (noMetadata), and coveragePercent says how much of the activity carries repo/branch metadata. spentUsd is null when there’s no priced usage: honest absence, not $0. Parameters: What it returns: Totals plus one row per repo (or repo#branch), each with spentUsd, event counts, and unpriced-event counts, alongside the noMetadata bucket and coveragePercent. Example prompt: “Break down our Claude Code spend by repo this month” or “Which branch cost the most this week?”
Who can call this: a secret key that belongs to an owner, admin, or finance user. Unlike the caps, spend, and coverage reads, the per-repo breakdown exposes teammate-level detail, so a developer-role key gets a 403.
Note: there’s no pr grouping on purpose. The pipeline records repo, branch, and commit, not PR numbers, and offering a PR grain that silently means “branch” would be a lie.

​
39. create_spend_cap

What it does: Creates a spend cap covering all AI tools. A developer cap can never be set higher than the whole-team ceiling; the server rejects the attempt with a plain message. Requires: an owner or finance key. Parameters: What it returns: The response leads with the new cap’s plain sentence (e.g. Cap created: Stop AI spend at $200 for [email protected] per week), followed by the full cap details. Example prompt: “Cap Alice’s AI coding spend at $200 a week and enforce it”

​
40. update_spend_cap

What it does: Adjusts an existing cap’s amount, period, mode, cool-off, or alert ladder. A cap’s identity (who it governs) can’t be changed: delete and recreate instead. Requires: an owner or finance key. Parameters: What it returns: The response leads with the updated cap’s plain sentence, followed by the full cap details. Example prompt: “Raise the team AI spend cap to $8,000”

​
41. delete_spend_cap

What it does: Deletes a cap. Deleting a whole-team ceiling is refused if it would leave a developer cap with nothing above it (the server says so plainly). Requires: an owner or finance key. Parameters: What it returns: The response leads with the removed cap’s plain sentence so you can confirm what was deleted. Example prompt: “Remove the spend cap on [email protected]”

​
Credit Pools (1)

This tool reads credit-pool countdowns: how many prepaid units each customer has left on plans that sell a pool (“5,000 tasks for 99amonth,then99 a month, then 0.03 each”). See the Credit Balances API reference for the endpoint-level detail and the Credit Pools recipe for the full story.

​
42. get_credit_balances

What it does: Reads your customers’ credit-pool countdowns: pool size, units used this period, units left, and units already billing as overage. Two numbers are deliberately different and both are true: remainingUnits counts manual top-ups, while overageInProgressUnits is the invoice’s own math (usage past the pool size, top-up blind). The invoice always matches overageInProgressUnits. Nothing stops at zero: the pool is a meter, not a breaker, so a customer past their pool keeps working and the overage keeps billing. Subscriptions whose plan sells no credit pool are absent, never listed with a zero. Read-only. Works with any secret key except an ingest-only key or a legal key, both of which get a clean 403; a publishable key (mf_pk_...) is refused. Parameters (all optional): What it returns: One row per credit-pool subscription (emptiest first) with the customer, plan, pool size, consumed, remaining, overage-in-progress, period dates, and whether alert emails are paused. Adding units and pausing alert emails happen in the dashboard or via the REST API (owner, admin, or finance); they aren’t MCP tools in v1. See the Credit Balances API reference for the write endpoints. Example prompts:
  • “Who’s running out of credits?”
  • “How many units does Acme have left?”
  • “Who’s in overage this month?”

​
Customer Alerts (4)

These four tools set and manage customer watches: per-customer tripwires that email you when one customer’s cost or revenue passes a dollar threshold. See the Customer Alerts API reference for the endpoint-level detail. A watch exposes one customer’s money, so all four tools — reads included — need a secret key that belongs to an owner, admin, or finance user. Any other key gets a clear 403; a publishable key (mf_pk_...) is refused.

​
43. get_customer_alerts

What it does: Lists your organization’s customer watches. Each row shows the watched customer (name and internal ID), the metric (cost or revenue), the dollar threshold, and the window. Parameters: None. What it returns: A list of watches, each with the customer, metric, threshold, window, and who the alerts email. Example prompt: “Show me all my customer cost alerts”

​
44. create_customer_alert

What it does: Creates a watch on one customer: email a named person when that customer’s cost or revenue passes a dollar threshold for the window you choose. Creating one sends the recipient a confirmation email. Parameters: What it returns: The created watch with its ID. Example prompt: “Email [email protected] when Acme Corp’s cost passes $500 this month”
Internal coding-spend accounts can’t be watched here. For your own team’s Claude Code and Codex spend, use the spend-cap tools instead.

​
45. update_customer_alert

What it does: Changes an existing watch’s metric, threshold, or window. The watched customer and the recipient are fixed at create — to change either, delete the watch and create a new one. Parameters: What it returns: The updated watch. Example prompt: “Raise the cost alert on Acme to $1,000”
An edit that collides with an existing watch gets the same friendly 409 the create path uses. A window that already alerted never re-fires just because you edited it.

​
46. delete_customer_alert

What it does: Removes a watch. Its unread in-app notifications go with it. Parameters: What it returns: A confirmation with the removed watch’s ID. Example prompt: “Delete the revenue alert on Acme Corp”

​
Matters for Law Firms (12)

These twelve tools give an AI assistant everything the dashboard’s Law tab does: tie AI usage to the legal matter it belongs to, sweep the rest with rules, and export a per-matter cost record that reconciles to the penny. See the Matters API reference for the full plain-English explanation. A matter is the case or file a firm bills its work against. A usage event attaches to a matter three ways, strongest first: a manual assignment, the event’s own metadata.matterId tag at record time, or a routing rule. Anything nothing claims stays in Unassigned. Every cost shown is the sum of real event costs, never an estimate. When an event’s cost isn’t resolved yet, it counts as 0 and is flagged in eventsMissingCost, so a nonzero count means the true cost is higher. All twelve tools need a secret key that belongs to an owner, admin, finance, or legal user. A legal key is a scoped key an owner or admin can mint so a firm can hand it to its own agent: it reaches these matter tools plus the usage-recording surface (record_usage, verify, its own key info, get_spend_controls) and nothing else. Customers, invoices, analytics, and pricing all answer 403 for it.

​
47. list_matters

What it does: Lists your matters, each with its all-time actual AI cost and event count. Parameters: What it returns: A paginated list of matters, each with id, matterNumber, name, clientName, status, actualCost, eventCount, and eventsMissingCost. Example prompt: “Show me our legal matters and what each has cost”

​
48. get_matter

What it does: Gets one matter with its all-time cost, event count, and its 100 most recent events. The full record lives in export_matter_audit; eventsCap states the cutoff. Parameters: What it returns: The matter, its actualCost, eventCount, eventsMissingCost, an events array, and eventsCap. Example prompt: “Show me the details on matter 2026-0142”

​
49. create_matter

What it does: Creates a matter. The matterNumber is the firm’s own case number, unique per organization. Events recorded with metadata.matterId equal to it (trimmed, exact) attach to this matter automatically. Parameters: What it returns: The created matter. Example prompt: “Create a matter numbered 2026-0142, Acme v. Widgets, for client Acme Corp”
If the number already exists: the API answers with a 409 conflict. Matter numbers are unique per organization.

​
50. update_matter

What it does: Updates a matter. Only the fields you send change. Closing a matter (status: closed) is a label only. It doesn’t stop anything at record time. Parameters: What it returns: The updated matter. Example prompt: “Close matter 2026-0142”

​
51. delete_matter

What it does: Deletes a matter. Its usage events survive and return to Unassigned (the response counts them); the matter’s routing rules are deleted with it. Parameters: What it returns: deleted, eventsReturnedToUnassigned, and routingRulesDeleted. Example prompt: “Delete matter 2026-0142”

​
52. list_unassigned_events

What it does: Lists the usage events no matter has claimed. totalResults is the true all-time count of unassigned events (never limited to the page), and totalCost is the cost of the whole set. Parameters: What it returns: A page of unassigned event rows (agent, signal, quantity, cost, source), plus totalResults, totalCost, and eventsMissingCost. Example prompt: “What legal usage is still unassigned?“

​
53. assign_event_to_matter

What it does: Manually puts one usage event on a matter, or pulls it off (pass matterId as null). A manual choice outranks a tag or a rule, and a manual unassignment is never swept back up by apply_matter_rules. Parameters: What it returns: assigned, eventId, matterId, and source (always "manual"). Example prompt: “Put event e2000000… on matter 2026-0142”

​
54. list_matter_rules

What it does: Lists your routing rules in evaluation order (lowest priority first, older rules before newer on a tie). That’s the exact order they run at record time and when you apply them. Parameters: What it returns: A page of rules, each with id, matterId, matterNumber, matterName, priority, agentCode, customerExternalId, and signalPattern. Example prompt: “Show me our matter routing rules”

​
55. upsert_matter_rule

What it does: Creates a routing rule (omit ruleId) or updates one (pass ruleId). A rule matches an event when every matcher it sets matches: agentCode exact, customerExternalId exact, signalPattern a case-insensitive substring of the signal name. At least one matcher is required; lower priority runs first. On update, sending a matcher as null clears it. Parameters: What it returns: The rule, including its matter’s number and name. Example prompt: “Route all research-bot events to matter 2026-0142”

​
56. delete_matter_rule

What it does: Deletes a routing rule. Events it already assigned keep their matter; only future matching stops. Parameters: What it returns: deleted. Example prompt: “Delete that routing rule”

​
57. apply_matter_rules

What it does: Sweeps your rules across events that are still Unassigned, in priority order. It touches only events with no matter and no attribution history, so it never overrides a tag, an earlier rule, or a manual choice. Parameters: None. What it returns: assigned, the count of events the sweep attached. Example prompt: “Apply the matter rules to catch up the unassigned events”

​
58. export_matter_audit

What it does: Returns the record a firm shows a client or a carrier: actual AI cost per matter for a window. The default summary view is one row per matter, plus an Unassigned row, plus organization totals, and it reconciles exactly with the dashboard’s CSV export for the same window. detail adds one row per event. Unresolved costs count as 0 and are flagged, never invented. Parameters: What it returns: periodStart, periodEnd, a summary array, totalCost, totalEvents, and eventsMissingCost. When format is detail, the response also carries a rows array. Example prompt: “Export the per-matter cost audit for August”