twelvebit Analytics

Ad spend and campaign performance

get_ads_report

Read-onlyIdempotent

Imported Meta Ads and Google Ads spend, impressions and ad-platform clicks, by platform, campaign and day. Includes sync status, complete-day coverage, account currency/time zone, conversion provenance and last-touch website performance for the shared measured period. Platform clicks are not website visits. Full-period totals are null when incomplete; observed_totals is the imported subtotal. Unavailable revenue/ROAS is null, not zero. Read only: does not run a sync. Daily resolution, at most 366 days; only 120 days of imports are retained. No visit filters; 24h is unsupported. Campaign pagination does not change platform totals or daily data.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "get_ads_report"
  }
}

Input Schema

Name	Required	Description
`to`	No	Last day, inclusive (YYYY-MM-DD).
`from`	No	First day (YYYY-MM-DD, site time zone). Use with to instead of period.
`site`	No	Site domain (example.com), id or public id (tb_…). Optional with a site key, or when the account has one site.
`limit`	No	Campaign rows per page, default 50. Platform totals always include every campaign.
`offset`	No	Campaign offset, default 0. Use pagination.next_offset for the next page.
`period`	No	Time range. Default 30d. today, yesterday, 24h, 7d, 30d, 90d, 12m, wtd, mtd, ytd, all.
`provider`	No	Only meta_ads or google_ads. Omit for both, sharing one performance window.
`include_daily`	No	Include platform daily ad metrics and measured spend/revenue, default true.

Schema Changelog

Changes observed during successful MCP inspections.

AddedOct 30, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Well beyond the readOnly/idempotent annotations, the description discloses null-vs-zero semantics for revenue and ROAS, the incomplete-period behavior of full-period totals, what observed_totals means, retention limits, and the fact that campaign pagination does not alter totals. That is exactly the kind of non-obvious behavior an agent needs before calling.

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

Conciseness5/5

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

Dense but front-loaded: the first sentence establishes the resource and dimensions, then subsequent sentences each add a distinct constraint or caveat with no filler. Every sentence carries signal about either content or limits.

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

Completeness4/5

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

For a tool with no output schema and eight optional parameters, the description covers semantics of nulls, totals, retention, and pagination well. It leaves the shape of the returned campaign rows and pagination fields (e.g. next_offset usage beyond the schema hint) largely unexplained.

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 3 baseline applies, but the description adds real meaning: 24h is called out as effectively unsupported despite being in the enum, pagination is clarified as not affecting platform totals, and daily resolution bounds are stated. It stops short of explaining which parameters control sync status or conversion provenance.

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?

States a specific verb+resource: imported Meta Ads and Google Ads spend, impressions and platform clicks, broken down by platform, campaign and day. The scope is unambiguous and clearly separable from sibling reporting tools such as get_paid_sales or get_revenue, since it explicitly says platform clicks are not website visits.

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?

Gives clear operating context and several exclusions: read only, does not run a sync, no visit filters, 24h unsupported, 120-day import retention, 366-day cap. It does not, however, explicitly route the agent to an alternative tool when those limits are hit or when attributed revenue is wanted instead.

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

All twelvebit Analytics 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?