flayr

Set ad spend caps

ads_caps_set

[writes · ads:spend scope] Sets the brand's monthly and/or per-campaign activation caps, in cents (e.g. 50000 = $500). Inside the owner's agent ceiling it is applied at once; above it the result is approval_requested: tell the user the owner has an approval request in Ads > Agent activity, and repeat the same call once they approve. Pass agentName and reason; both are shown to the owner. (Wraps POST /api/v2/ads/caps.)

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": {
      "agentName": "<agentName>",
      "reason": "<reason>"
    },
    "name": "ads_caps_set"
  }
}

Input Schema

Name	Required	Description
`reason`	Yes	Why the agent is doing this. Shown to the owner and kept in the audit trail.
`brandId`	No	A brand id (GET /api/v2/brands) or "personal"; default: the key owner's active brand.
`agentName`	Yes	Which agent is acting. Shown to the owner in Ads > Agent activity.
`monthlyMaxMinor`	No	Monthly activation cap, whole cents (100 to 10000000).
`perCampaignMaxMinor`	No	Per-campaign activation cap, whole cents (100 to 10000000).

Schema Changelog

Changes observed during successful MCP inspections.

AddedNov 7, 2026

TDQS

A4.3/5.0

Behavior5/5

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

Goes well past the annotations by disclosing the auth scope, the two-path execution model (immediate apply vs `approval_requested` result), the human-visible surface for the approval, and the underlying endpoint. The annotations only cover the generic safety profile (non-read-only, open-world, non-idempotent), so this description carries real behavioral weight.

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 scope tag and action, then the conditional approval branch. Dense but every clause carries operational information; the parenthetical endpoint reference is the only arguably optional element.

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?

Five-parameter mutation tool with no output schema, yet the description tells the agent what the notable non-default response looks like and how to react to it, plus the required supporting parameters. Nothing essential to correct invocation is 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 genuine meaning: the cents convention with a concrete conversion example, and the fact that agentName and reason are shown to the owner (which explains why they are required).

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?

Names a specific verb and resource ("Sets the brand's monthly and/or per-campaign activation caps") and states the unit convention (cents, 50000 = $500). It does not explicitly distinguish itself from the close sibling ads_account_spend_limit_set, which an agent could plausibly confuse with brand-level caps.

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 procedural context: requires the `ads:spend` scope, and tells the agent exactly what to do when the cap exceeds the owner's agent ceiling (tell the user about the approval request in Ads > Agent activity, then repeat the call after approval). It stops short of naming when to prefer this over ads_account_spend_limit_set or ads_campaign_approve.

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

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