360dialog

Read agent usage insights

mba_get_agent_usage_insights

Read-only

Read the billed usage of a Meta Business Agent account over a billing date range, one entry per HOUR, DAY or MONTH bucket: billable messages, billable tokens, and cost in the account's currency. Returns {usage}; an empty array means no usage in the range. Each entry carries its bucket start and end (Unix seconds, end exclusive), plus channel and sender_id when they are in dimensions. Metrics left out of metric_types are omitted from every entry, not returned as null. Tokens are BILLED tokens, the figure on the invoice, which can be fewer than the tokens the agent consumed. Known limitations: usage insights are ONLY AVAILABLE for numbers whose stack uses its own WABA access token; for any other number this tool returns an error that says so. The range is start INCLUSIVE, end EXCLUSIVE, and dates are evaluated in the billable account's timezone, so a day bucket can be 23 or 25 hours long. MONTH needs a range of whole months: start on the 1st, end on the last day of a month.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "app_id": "<app_id>",
      "billable_account_id": "<billable_account_id>",
      "start": "<start>",
      "end": "<end>",
      "granularity": "<granularity>"
    },
    "name": "mba_get_agent_usage_insights"
  }
}

Input Schema

Name	Required	Description
`end`	Yes	End of the range, Unix seconds. Exclusive: buckets that start before it.
`start`	Yes	Start of the range, Unix seconds. Inclusive: buckets that start at or after it.
`app_id`	Yes	The 360dialog channel's app_id. Identifies which WhatsApp number the agent belongs to.
`channels`	No	Only usage on these messaging surfaces.
`dimensions`	No	Split each bucket by these axes. Omit to total the whole agent per bucket.
`sender_ids`	No	Only usage attributed to these sending entities.
`granularity`	Yes	Size of each bucket.
`metric_types`	No	Which metrics to return. Omit for all of them.
`billable_account_id`	Yes	The billable account ID of the Meta Business Agent account. No other tool returns it: Meta Billing Hub shows it under Accounts > Meta Business Agent accounts. It is not the Business Manager ID the budget tools take.

Schema Changelog

Changes observed during successful MCP inspections.

AddedNov 10, 2026
RemovedNov 10, 2026
AddedNov 10, 2026
RemovedNov 10, 2026
First observedNov 8, 2026

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only signal a safe read; the description adds substantial behavior beyond that: the {usage} return key, empty-array semantics for no usage, strict start-inclusive/end-exclusive boundary behavior, timezone evaluation producing 23- or 25-hour day buckets, whole-month constraints for MONTH granularity, and a documented error mode for unsupported numbers. This is exactly the kind of operational context annotations cannot carry.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and bucket semantics, and nearly every sentence contributes a distinct constraint (boundaries, timezone, MONTH rules, billed vs. consumed tokens). It runs as one dense paragraph, so the limitation and boundary rules are harder to scan than they would be as separate sentences, but there is little wasted wording.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 9-parameter, 5-required analytical read with no output schema, the description supplies return shape, omission semantics, boundary rules, timezone/DST behavior, granularity constraints, and failure modes. Nothing an agent needs in order to call it correctly appears to be missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning the schema lacks: dates are evaluated in the billable account's timezone, MONTH requires a whole-month range starting on the 1st and ending on the last day, and dimensions control whether channel/sender_id appear per entry. It also clarifies that metrics excluded from metric_types are omitted rather than null.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: read billed usage of a Meta Business Agent account over a billing date range, bucketed per HOUR/DAY/MONTH. It enumerates the returned metrics (billable messages, billable tokens, cost) and even distinguishes itself from the sibling budget tools by warning that billable_account_id is not the Business Manager ID. An agent can identify this tool without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage context is clear: billed usage vs. consumed tokens, and the explicit precondition that insights only exist for numbers using their own WABA access token, otherwise an error is returned. It does not name a direct alternative for related reads (e.g., mba_get_agent_budgets or get_invoices) beyond the billable_account_id caveat, so it stops short of full when-to-use routing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All 360dialog tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?