Samuelz® Marketing

Werbeleistung lesen

get_advertising_performance

Read-onlyIdempotent

Read costs, campaigns, impressions, clicks, conversions and provider-attributed ROAS for the exact Google Ads or OpenAI Ads connection, using provider account currency/timezone and inclusive dates. level=account, campaign, keyword or ad. Each row commercial reports paidBookingsCount, grossRevenueMinor, netMarginMinor after partner payout and fee, roasBps, roasRatio, netMarginRoasBps, netContributionMinor (net margin minus ad cost), repeatBookingsCount, repeatRevenueMinor and rebookingUrl from paid primary bookings with gclid, msclkid or utm assignment. Repeat metrics are later paid bookings by the same customer. rebookingUrl is prepared for follow-up and is not sent automatically. The advertising overview also returns enhancedConversionsEnabled and userIdentifierFields for the bound Google Ads account: field names only, never customer email or phone. Follow nextCursor; do not sum page ratios or currencies. Optional comparison is a separate live report. Requires marketing:read and current module/provider authority; OpenAI requires separate Settings report consent and does not serve keyword or ad rows. Provider ROAS is not settled revenue. No campaign/budget/event writes. POST /api/v1/tenant/read/get_advertising_performance.

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": {
      "connectionId": "<connectionId>",
      "dateRange": "<dateRange>"
    },
    "name": "get_advertising_performance"
  }
}

Input Schema

Name	Required	Default
`level`	No	account
`limit`	No
`cursor`	No
`dateRange`	Yes
`comparison`	No
`connectionId`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

No schema history has been recorded yet.

TDQS

A4.3/5.0

Behavior5/5

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses auth scopes (marketing:read, provider authority), a separate consent requirement for OpenAI, that provider ROAS is not settled revenue, that rebookingUrl is prepared but not sent, that enhancedConversionsEnabled returns field names only and never PII, and that no campaign/budget/event writes occur. These are exactly the behavioral facts annotations cannot convey.

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?

Purpose is front-loaded in the first sentence and the operational caveats follow in tight order. The middle metric enumeration is a long run-on list, but with no output schema nearly all of it is load-bearing information rather than filler.

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?

With no output schema, the description must explain the return shape, and it does — naming the commercial row fields, repeat-booking definitions, the enhanced-conversion fields, and pagination/aggregation caveats. Together with the auth and consent prerequisites, an agent has everything needed to call this correctly and interpret results.

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 description coverage is 0%, so the description carries the burden and largely does: it enumerates the level enum values, states dateRange is inclusive and uses provider currency/timezone, explains comparison is a separate live report, and gives cursor handling via nextCursor. connectionId and limit semantics are left thin, which keeps it below a 5.

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

Purpose4/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 set: 'Read costs, campaigns, impressions, clicks, conversions and provider-attributed ROAS for the exact Google Ads or OpenAI Ads connection,' and names the supported levels. This is far more specific than the title, but it never explicitly distinguishes itself from advertising-adjacent siblings like get_campaign_performance or get_search_performance.

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?

It supplies concrete operating conditions: follow nextCursor, don't sum page ratios or currencies, comparison is a separate live report, and OpenAI connections do not serve keyword or ad rows. What is missing is explicit routing against alternative tools; an agent must infer when to prefer this over a sibling reporting tool.

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

All Samuelz® Marketing 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?