Rawa

Add competitor

add_competitor

Start tracking a competitor's ads on one ad channel: Meta (Facebook and Instagram, the default), TikTok, Snapchat, Google or LinkedIn, so its ads and reports appear in list_competitor_ads and get_competitor_analyses. Search by company name: when the name matches one advertiser it is added, otherwise a list of candidates comes back and you add the right one by passing its advertiserId and name (with the same channel). Costs 50 credits per competitor added, charged once, then 50 credits a day while it is tracked; searching is free. Pass dryRun to see the cost without adding; it quotes even when the add would be refused (the brand's watchlist full, the advertiser already tracked), and says why in wouldRefuse. Once the user agrees, pass the quoted credits as expectedCredits; an add that would cost a different amount is refused. Give each new add a new requestId, and repeat it unchanged only on a retry: a retry within 2 minutes returns the first result and is not charged again. Without a requestId, the same arguments within 2 minutes count as a retry. Needs an admin who has allowed generation over MCP, and may be limited to admins.

Input Schema

Name	Required	Description
`name`	No	The candidate's name, required alongside advertiserId.
`query`	No	The competitor's name, as it appears on the channel (its Facebook page on Meta).
`dryRun`	No	Find the advertiser and return what adding it would cost, without adding it or charging.
`brandId`	No	A brand id from get_workspace or list_brands, or the brand's name. Omit it when the organization has a single brand.
`channel`	No	The ad channel to track the competitor on. Defaults to meta.
`requestId`	No	Your own unique id for this request. Use a new one for every new request, even with the same arguments. Repeat it unchanged only to retry this exact call within 2 minutes; the retry returns the first result.
`advertiserId`	No	The advertiserId of a candidate from an earlier call. name is required with it.
`expectedCredits`	No	The credits the dryRun quoted and the user agreed to. The call is refused if it would cost a different amount.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 29, 2026

changedInput schema / properties / brandId / description

Previous value: -"A brand id from get_workspace or list_brands. Omit it when the organization has a single brand."New value: +"A brand id from get_workspace or list_brands, or the brand's name. Omit it when the organization has a single brand."

First observedOct 23, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Beyond annotations, the description discloses the full cost model (50 credits per add, then 50 credits/day, search free), dryRun quote behavior including refusal cases, expectedCredits mismatch refusal, requestId retry semantics, and admin permission requirements. This is exactly the kind of behavioral context the annotations do not 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?

The description is dense and front-loaded with the main action before costs, dryRun, retries, and permissions. It is longer than typical but every sentence contributes necessary operational context for a complex mutation tool, though the single-paragraph structure could be easier to scan.

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?

Given the tool's complexity, eight parameters, existing output schema, and mutation annotations, the description covers the critical gaps an agent needs: cost, dryRun workflow, expectedCredits guard, retry behavior, ambiguity handling, and permissions. Nothing essential for correct invocation appears 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 meaningful workflow semantics: query vs advertiserId/name candidate flow, keeping the same channel when adding a candidate, and how expectedCredits must match the dryRun quote. It does not add syntax-level details beyond the schema, but it clarifies parameter relationships well.

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 states a specific verb and resource: 'Start tracking a competitor's ads' on a named ad channel, and connects the result to list_competitor_ads and get_competitor_analyses. An agent can distinguish this from list_competitors or get_competitor_analyses 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?

The description gives clear operational context: use query to search by company name, handle multiple candidates by passing advertiserId and name, and use dryRun before agreeing to costs. It does not explicitly state when not to use this tool or name remove_competitor as the alternative for stopping tracking, so it stops short of the full when/when-not/alternatives bar.

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

All Rawa 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?