Spytrend

Creative family monthly share year over year

get_creative_family_monthly_share

Read-only

Monthly share of a category's top creative families (ads reusing one exact creative) among the category's ads launched in each complete month per country, beside the same family's share in the same month a year earlier and the change in percentage points; months not available yet come back as null, never 0. QUOTA: 1 MCP credit per call. PRICING: on paid plans ×1 after 500 MCP credits/month; one-time consent via accept_pricing_terms; before calling, get the maximum debit from estimate_cost (free) and tell the user.

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_creative_family_monthly_share"
  }
}

Input Schema

Name	Required	Description
`category`	No	AI category of the ads (default ecommerce_and_retail, the only one available)
`to_month`	No	last month of the window YYYY-MM; default: the latest complete month available
`countries`	No	ISO-2 country codes, upper case, at most 5, each answered separately; empty — all countries together
`top_families`	No	families per country and month, the most-launched first, 1-10 (default 3)
`window_months`	No	complete calendar months compared with the same months a year earlier, 1-24 (default 24); they end at the latest complete month available

Output Schema

Name	Required	Description
`data`	No
`error`	No	Present only when isError is true: machine-readable failure. The human explanation stays in content.
`params`	No	Request parameter echo: applied = parameters that shaped this result; normalized = parameters rewritten before applying (alias, type coercion, resolved id); ignored = parameters that were accepted but NOT applied, with the reason.
`addon_hints`	No	Add-on modules that have additional data for objects of this result (no prices, no paid values). subscription_status=active: the account has the module — use its normal path. Do not push a purchase the user did not ask about.

Schema Changelog

Changes observed during successful MCP inspections.

AddedNov 4, 2026

TDQS

A4.4/5.0

Behavior5/5

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

Beyond the readOnly/openWorld annotations it discloses cost (1 MCP credit per call), paid-plan multiplier after 500 credits, the consent prerequisite, and the critical edge-case behavior that unavailable months return null rather than 0. That null-vs-zero rule is exactly the kind of behavioral detail an agent cannot infer from annotations or schema.

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 metric definition before the quota and pricing clauses, and no filler sentences. It is one very long run-on sentence, though, and the pricing block competes with the metric description for attention.

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?

An output schema exists, so return shape need not be explained, and the description covers the remaining agent-critical gaps: cost, consent, null semantics, and the year-over-year comparison basis. Nothing needed to invoke this tool correctly is missing.

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

Parameters3/5

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

Schema coverage is 100% with defaults and bounds documented for every parameter, so the schema carries the burden. The description adds meaning only for the domain concept ('ads reusing one exact creative') and the per-country/per-month answering model, not for individual parameter values.

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 names the exact metric (monthly share of a category's top creative families among ads launched that month), the comparison (same family, same month a year earlier, plus the percentage-point change), and the grouping (per country). It even defines the core concept — 'ads reusing one exact creative' — so no sibling tool could be confused with it.

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 gives a concrete pre-call workflow: get the maximum debit from estimate_cost (free), obtain one-time consent via accept_pricing_terms, and inform the user. It does not say when to prefer this over adjacent analytics tools such as get_ads_analytics or budget_aggregates, so the alternative-selection guidance is absent.

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

All Spytrend 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.