Skip to main content
Glama

Summarize rival ad patterns

summarize_rival_ad_patterns
Idempotent

Summarizes observed ad patterns for one of the account’s brands: up to three brand-specific insights and up to twelve standout image ads (at most three per advertiser), from the brand’s tracked competitors or, with category, from a one-time Ad Library sample that tracks nothing. Patterns describe the sample, not measured sales performance. state insufficient_evidence means fewer than two standout ads were found; a category, or more tracked competitors, widens the evidence. Samples carry no totals and stale observations are marked. Ads returned draw on the daily workspace reading allowance.

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": "summarize_rival_ad_patterns"
  }
}

Input Schema

NameRequiredDescriptionDefault
brand_idNoBrand id from list_brands. Needed when the account has several brands; an account with one brand uses it automatically.
categoryNoOptional category or market in plain words, such as gym software. Switches the evidence from tracked competitors to a one-time sample of Ad Library advertisers in that category; nothing is tracked.
response_formatNoOutput format: text (default) or json. table is not available for this tool.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -{
      -  "$schema": "https://json-schema.org/draft/2020-12/schema",
      -  "additionalProperties": false,
      -  "properties": {
      -    "allowance": {
      -      "anyOf": [
      -        {
      -          "additionalProperties": false,
      -          "description": "Free daily ad-return allowance for this workspace, resetting at midnight UTC.",
      -          "properties": {
      -            "daily_limit": {
      -              "description": "Maximum free ad examples returned per UTC day.",
      -              "type": "number"
      -            },
      -            "remaining": {
      -              "description": "Free ad examples still available today.",
      -              "type": "number"
      -            },
      -            "resets_at": {
      -              "description": "ISO timestamp when the allowance or credits reset.",
      -              "type": "string"
      -            }
      -          },
      -          "required": [
      -            "daily_limit",
      -            "remaining",
      -            "resets_at"
      -          ],
      -          "type": "object"
      -        },
      -        {
      -          "type": "null"
      -        }
      -      ],
      -      "description": "Free daily ad-return allowance for this workspace, resetting at midnight UTC."
      -    },
      -    "cache_key": {
      -      "anyOf": [
      -        {
      -          "description": "Evidence and brand version cache identity.",
      -          "type": "string"
      -        },
      -        {
      -          "type": "null"
      -        }
      -      ],
      -      "description": "Evidence and brand version cache identity."
      -    },
      -    "cost_credits": {
      -      "anyOf": [
      -        {
      -          "const": 0,
      -          "description": "Credits quoted or charged by this operation.",
      -          "type": "number"
      -        },
      -        {
      -          "type": "null"
      -        }
      -      ],
      -      "description": "Credits quoted or charged by this operation."
      -    },
      -    "insights": {
      -      "anyOf": [
      -        {
      -          "description": "At most three supported brand-specific insights.",
      -          "items": {
      -            "additionalProperties": false,
      -            "description": "insights value in this response.",
      -            "properties": {
      -              "ads": {
      -                "anyOf": [
      -                  {
      -                    "description": "Canonical supporting standout ads.",
      -                    "items": {
      -                      "additionalProperties": false,
      -                      "description": "Bounded sample of accessible ads with delivery evidence; not a complete library inventory.",
      -                      "properties": {
      -                        "ad_library_url": {
      -                          "anyOf": [
      -                            {
      -                              "description": "ad library url value in this response.",
      -                              "type": "string"
      -                            },
      -                            {
      -                              "type": "null"
      -                            }
      -                          ],
      -                          "description": "ad library url value in this response."
      -                        },
      -                        "advertiser": {
      -                          "anyOf": [
      -                            {
      -                              "description": "advertiser value in this response.",
      -                              "type": "string"
      -                            },
      -                            {
      -                              "type": "null"
      -                            }
      -                          ],
      -                          "description": "Advertiser name."
      -                        },
      -                        "advertiser_id": {
      -                          "description": "Canonical advertiser identity.",
      -                          "type": "string"
      -                        },
      -                        "baseline": {
      -                          "description": "Whether a sampled median is available.",
      -                          "type": "string"
      -                        },
      -                        "body_text": {
      -                          "anyOf": [
      -                            {
      -                              "description": "body text value in this response.",
      -                              "type": "string"
      -                            },
      -                            {
      -                              "type": "null"
      -                            }
      -                          ],
      -                          "description": "body text value in this response."
      -                        },
      -                        "body_text_truncated": {
      -                          "anyOf": [
      -                            {
      -                              "description": "body text truncated value in this response.",
      -                              "type": "boolean"
      -                            },
      -                            {
      -                              "type": "null"
      -                            }
      -                          ],
      -                          "description": "body text truncated value in this response."
      -                        },
      -                        "confirmation_stale": {
      -                          "anyOf": [
      -                            {
      -                              "description": "confirmation stale value in this response.",
      -                              "type": "boolean"
      -                            },
      -                            {
      -                              "type": "null"
      -                            }
      -                          ],
      -                          "description": "confirmation stale value in this response."
      -                        },
      -                        "cta": {
      -                          "anyOf": [
      -                            {
      -                              "description": "cta value in this response.",
      -                              "type": "string"
      -                            },
      -                            {
      -                              "type": "null"
      -                            }
      -                          ],
      -                          "description": "cta value in this response."
      -                        },
      -                        "end_date": {
      -                          "anyOf": [
      -                            {
      -                              "description": "Provider end date (YYYY-MM-DD); null if still running or unknown.",
      -                              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      -                              "type": "string"
      -                            },
      -                            {
      -                              "type": "null"
      -                            }
      -                          ],
      -                          "description": "Provider end date (YYYY-MM-DD); null if still running or unknown."
      -                        },
      -                        "facebook_page_id": {
      -                          "anyOf": [
      -                            {
      -                              "description": "facebook page id value in this response.",
      -                              "type": "string"
      -                            },
      -                            {
      -                              "type": "null"
      -                            }
      -                          ],
      -                          "description": "facebook page id value in this response."
      -                        },
      -                        "filters": {
      -                          "anyOf": [
      -                            {
      -                              "additionalProperties": false,
      -                              "description": "filters value in this response.",
      -                              "properties": {
      -                                "angle": {
      -                                  "anyOf": [
      -                                    {
      -                                      "description": "angle value in this response.",
      -                                      "type": "string"
      -                                    },
      -                                    {
      -                                      "type": "null"
      -                                    }
      -                                  ],
      -                                  "description": "angle value in this response."
      -                                },
      -                                "industry_slug": {
      -                                  "anyOf": [
      -                                    {
      -                                      "description": "Industry filter value, when known.",
      -                                      "type": "string"
      -                                    },
      -                                    {
      -                                      "type": "null"
      -                                    }
      -                                  ],
      -                                  "description": "Industry filter value, when known."
      -                                }
      -                              },
      -                              "type": "object"
      -                            },
      -                            {
      -                              "type": "null"
      -                            }
      -                          ],
      -                          "description": "filters value in this response."
      -                        },
      -                        "first_seen": {
      -                          "anyOf": [
      -                            {
      -                              "description": "first seen value in this response.",
      -                              "type": "string"
      -                            },
      -                            {
      -                              "type": "null"
      -                            }
      -                          ],
      -                          "description": "first seen value in this response."
      -                        },
      -                        "for": {
      -                          "anyOf": [
      -                            {
      -                              "description": "for value in this response.",
      -                              "maxLength": 40,
      -                              "type": "string"
      -                            },
      -                            {
      -                              "type": "null"
      -                            }
      -                          ],
      -                          "description": "for value in this response."
      -                        },
      -                        "format": {
      -                          "anyOf": [
      -                            {
      -                              "description": "Static image or video media format.",
      -                              "enum": [
      -                                "static",
      -                                "video"
      -                              ],
      -                              "type": "string"
      -                            },
      -                            {
      -                              "type": "null"
      -                            }
      -                          ],
      -                          "description": "Static image or video media format."
      -                        },
      -                        "group_id": {
      -                          "anyOf": [
      -                            {
      -                              "description": "Provider variation/collation group; null when unavailable.",
      -                              "type": "string"
      -                            },
      -                            {
      -                              "type": "null"
      -                            }
      -                          ],
      -                          "description": "Provider variation/collation group; null when unavailable."
      -                        },
      -                        "hook": {
      -                          "anyOf": [
      -                            {
      -                              "additionalProperties": false,
      -                              "description": "Observed opening speech, image text, visual or written hook; null when evidence is unavailable.",
      -                              "properties": {
      -                                "on_screen": {
      -                                  "description": "on screen value in this response.",
      -                                  "items": {
      -                                    "description": "on screen value in this response.",
      -                                    "maxLength": 240,
      -                                    "type": "string"
      -                                  },
      -                                  "maxItems": 3,
      -                                  "type": "array"
      -                                },
      -                                "opening_visual": {
      -                                  "anyOf": [
      -                                    {
      -                                      "description": "opening visual value in this response.",
      -                                      "maxLength": 400,
      -                                      "type": "string"
      -                                    },
      -                                    {
      -                                      "type": "null"
      -                                    }
      -                                  ],
      -                                  "description": "opening visual value in this response."
      -                                },
      -                                "source": {
      -                                  "description": "Where the accessible ad or advertiser evidence came from.",
      -                                  "enum": [
      -                                    "video",
      -                                    "image"
      -                                  ],
      -                                  "type": "string"
      -                                },
      -                                "spoken": {
      -                                  "anyOf": [
      -                                    {
      -                                      "description": "spoken value in this response.",
      -                                      "maxLength": 1000,
      -                                      "type": "string"
      -                                    },
      -                                    {
      -                                      "type": "null"
      -                                    }
      -                                  ],
      -                                  "description": "spoken value in this response."
      -                                },
      -                                "type": {
      -                                  "anyOf": [
      -                                    {
      -                                      "description": "type value in this response.",
      -                                      "maxLength": 120,
      -                                      "type": "string"
      -                                    },
      -                                    {
      -                                      "type": "null"
      -                                    }
      -                                  ],
      -                                  "description": "Stored hook category; may be present when opener text is unavailable. Null when no stored type is known."
      -                                },
      -                                "written": {
      -                                  "anyOf": [
      -                                    {
      -                                      "description": "written value in this response.",
      -                                      "maxLength": 500,
      -                                      "type": "string"
      -                                    },
      -                                    {
      -                                      "type": "null"
      -                                    }
      -                                  ],
      -                                  "description": "written value in this response."
      -                                }
      -                              },
      -                              "required": [
      -                                "spoken",
      -                                "on_screen",
      -                                "opening_visual",
      -                                "written",
      -                                "type",
      -                                "source"
      -                              ],
      -                              "type": "object"
      -                            },
      -                            {
      -                              "type": "null"
      -                            }
      -                          ],
      -                          "description": "Observed opening speech, image text, visual or written hook; null when evidence is unavailable."
      -                        },
      -                        "hook_type": {
      -                          "anyOf": [
      -                            {
      -                              "description": "hook type value in this response.",
      -                              "type": "string"
      -                            },
      -                            {
      -                              "type": "null"
      -                            }
      -                          ],
      -                          "description": "hook type value in this response."
      -                        },
      -                        "hook_type_filter": {
      -                          "anyOf": [
      -                            {
      -                              "description": "hook type filter value in this response.",
      -                              "type": "string"
      -                            },
      -                            {
      -                              "type": "null"
      -                            }
      -                          ],
      -                          "description": "hook type filter value in this response."
      -                        },
      -                        "id": {
      -                          "anyOf": [
      -                            {
      -                              "description": "id value in this response.",
      -                              "type": "string"
      -                            },
      -                            {
      -                              "type": "null"
      -                            }
      -                          ],
      -                          "description": "id value in this response."
      -                        },
      -                        "image_url": {
      -                          "anyOf": [
      -                            {
      -                              "description": "image url value in this response.",
      -                              "type": "string"
      -                            },
      -                            {
      -                              "type": "null"
      -                            }
      -                          ],
      -                          "description": "image url value in this response."
      -                        },
      -                        "landing_url": {
      -                          "anyOf": [
      -                            {
      -                              "description": "landing url value in this response.",
      -                              "type": "string"
      -                            },
      -                            {
      -                              "type": "null"
      -                            }
      -                          ],
      -                          "description": "landing url value in this response."
      -                        },
      -                        "last_confirmed_at": {
      -                          "anyOf": [
      -                            {
      -                              "description": "Most recent confirmed delivery timestamp, when known.",
      -                              "type": "string"
      -                            },
      -                            {
      -                              "type": "null"
      -                            }
      -                          ],
      -                          "description": "Most recent confirmed delivery timestamp, when known."
      -                        },
      -                        "last_seen": {
      -                          "anyOf": [
      -                            {
      -                              "description": "last seen value in this response.",
      -                              "type": "string"
      -                            },
      -                            {
      -                              "type": "null"
      -                            }
      -                          ],
      -                          "description": "last seen value in this response."
      -                        },
      -                        "logo_url": {
      -                          "anyOf": [
      -                            {
      -                              "description": "logo url value in this response.",
      -                              "type": "string"
      -                            },
      -                            {
      -                              "type": "null"
      -                            }
      -                          ],
      -                          "description": "Durable advertiser logo URL if available."
      -                        },
      -                        "original_headline": {
      -                          "anyOf": [
      -                            {
      -                              "description": "original headline value in this response.",
      -                              "type": "string"
      -                            },
      -                            {
      -                              "type": "null"
      -                            }
      -                          ],
      -                          "description": "original headline value in this response."
      -                        },
      -                        "page_name": {
      -                          "anyOf": [
      -                            {
      -                              "description": "page name value in this response.",
      -                              "type": "string"
      -                            },
      -                            {
      -                              "type": "null"
      -                            }
      -                          ],
      -                          "description": "page name value in this response."
      -                        },
      -                        "platforms": {
      -                          "anyOf": [
      -                            {
      -                              "description": "platforms value in this response.",
      -                              "items": {
      -                                "description": "platforms value in this response.",
      -                                "type": "string"
      -                              },
      -                              "type": "array"
      -                            },
      -                            {
      -                              "type": "null"
      -                            }
      -                          ],
      -                          "description": "platforms value in this response."
      -                        },
      -                        "reasons": {
      -                          "description": "Qualification rules met by this ad.",
      -                          "items": {
      -                            "description": "reasons value in this response.",
      -                            "type": "string"
      -                          },
      -                          "type": "array"
      -                        },
      -                        "rival_median_days": {
      -                          "anyOf": [
      -                            {
      -                              "description": "rival median days value in this response.",
      -                              "type": "number"
      -                            },
      -                            {
      -                              "type": "null"
      -                            }
      -                          ],
      -                          "description": "Median run days in the recent eligible sample."
      -                        },
      -                        "run_duration_days": {
      -                          "anyOf": [
      -                            {
      -                              "description": "Computed from the provider start date to the last confirmed delivery; null when unknown.",
      -                              "maximum": 9007199254740991,
      -                              "minimum": 0,
      -                              "type": "integer"
      -                            },
      -                            {
      -                              "type": "null"
      -                            }
      -                          ],
      -                          "description": "Computed from the provider start date to the last confirmed delivery; null when unknown."
      -                        },
      -                        "schema_version": {
      -                          "anyOf": [
      -                            {
      -                              "const": 1,
      -                              "description": "schema version value in this response.",
      -                              "type": "number"
      -                            },
      -                            {
      -                              "type": "null"
      -                            }
      -                          ],
      -                          "description": "schema version value in this response."
      -                        },
      -                        "source": {
      -                          "anyOf": [
      -                            {
      -                              "description": "Where the accessible ad or advertiser evidence came from.",
      -                              "type": "string"
      -                            },
      -                            {
      -                              "type": "null"
      -                            }
      -                          ],
      -                          "description": "Where the accessible ad or advertiser evidence came from."
      -                        },
      -                        "start_date": {
      -                          "anyOf": [
      -                            {
      -                              "description": "Provider start date (YYYY-MM-DD); null when the provider did not report one.",
      -                              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      -                              "type": "string"
      -                            },
      -                            {
      -                              "type": "null"
      -                            }
      -                          ],
      -                          "description": "Provider start date (YYYY-MM-DD); null when the provider did not report one."
      -                        },
      -                        "steal_caution": {
      -                          "anyOf": [
      -                            {
      -                              "description": "steal caution value in this response.",
      -                              "type": "string"
      -                            },
      -                            {
      -                              "type": "null"
      -                            }
      -                          ],
      -                          "description": "steal caution value in this response."
      -                        },
      -                        "still_running": {
      -                          "anyOf": [
      -                            {
      -                              "description": "Current delivery evidence: true, false or null when unknown.",
      -                              "type": "boolean"
      -                            },
      -                            {
      -                              "type": "null"
      -                            }
      -                          ],
      -                          "description": "Current delivery evidence: true, false or null when unknown."
      -                        },
      -                        "strength": {
      -                          "anyOf": [
      -                            {
      -                              "description": "strength value in this response.",
      -                              "type": "string"
      -                            },
      -                            {
      -                              "type": "null"
      -                            }
      -                          ],
      -                          "description": "strength value in this response."
      -                        },
      -                        "strength_label": {
      -                          "anyOf": [
      -                            {
      -                              "description": "Delivery-based label: winner, solid or testing. Cautions are separate.",
      -                              "enum": [
      -                                "winner",
      -                                "solid",
      -                                "testing"
      -                              ],
      -                              "type": "string"
      -                            },
      -                            {
      -                              "type": "null"
      -                            }
      -                          ],
      -                          "description": "Delivery-based label: winner, solid or testing. Cautions are separate."
      -                        },
      -                        "variation_count": {
      -                          "anyOf": [
      -                            {
      -                              "description": "variation count value in this response.",
      -                              "type": "number"
      -                            },
      -                            {
      -                              "type": "null"
      -                            }
      -                          ],
      -                          "description": "variation count value in this response."
      -                        },
      -                        "video_asset_missing": {
      -                          "anyOf": [
      -                            {
      -                              "description": "video asset missing value in this response.",
      -                              "type": "boolean"
      -                            },
      -                            {
      -                              "type": "null"
      -                            }
      -                          ],
      -                          "description": "video asset missing value in this response."
      -                        },
      -                        "video_thumbnail_url": {
      -                          "anyOf": [
      -                            {
      -                              "description": "video thumbnail url value in this response.",
      -                              "type": "string"
      -                            },
      -                            {
      -                              "type": "null"
      -                            }
      -                          ],
      -                          "description": "video thumbnail url value in this response."
      -                        },
      -                        "video_url": {
      -                          "anyOf": [
      -                            {
      -                              "description": "video url value in this response.",
      -                              "type": "string"
      -                            },
      -                            {
      -                              "type": "null"
      -                            }
      -                          ],
      -                          "description": "video url value in this response."
      -                        },
      -                        "why": {
      -                          "anyOf": [
      -                            {
      -                              "description": "why value in this response.",
      -                              "type": "string"
      -                            },
      -                            {
      -                              "type": "null"
      -                            }
      -                          ],
      -                          "description": "why value in this response."
      -                        },
      -                        "your_rival": {
      -                          "anyOf": [
      -                            {
      -                              "description": "your rival value in this response.",
      -                              "type": "boolean"
      -                            },
      -                            {
      -                              "type": "null"
      -                            }
      -                          ],
      -                          "description": "your rival value in this response."
      -                        }
      -                      },
      -                      "type": "object"
      -                    },
      -                    "maxItems": 3,
      -                    "type": "array"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "Canonical supporting standout ads."
      -              },
      -              "brand_line": {
      -                "anyOf": [
      -                  {
      -                    "description": "Application of the pattern to supplied brand facts.",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "Application of the pattern to supplied brand facts."
      -              },
      -              "headline": {
      -                "anyOf": [
      -                  {
      -                    "description": "One sentence describing the shared pattern.",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "One sentence describing the shared pattern."
      -              },
      -              "source_ad_ids": {
      -                "anyOf": [
      -                  {
      -                    "description": "Two or three canonical supporting ad references.",
      -                    "items": {
      -                      "description": "source ad ids value in this response.",
      -                      "type": "string"
      -                    },
      -                    "type": "array"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "Two or three canonical supporting ad references."
      -              }
      -            },
      -            "type": "object"
      -          },
      -          "maxItems": 3,
      -          "type": "array"
      -        },
      -        {
      -          "type": "null"
      -        }
      -      ],
      -      "description": "At most three supported brand-specific insights."
      -    },
      -    "reading_use": {
      -      "anyOf": [
      -        {
      -          "additionalProperties": false,
      -          "description": "reading use value in this response.",
      -          "properties": {
      -            "ads_returned": {
      -              "anyOf": [
      -                {
      -                  "description": "ads returned value in this response.",
      -                  "type": "number"
      -                },
      -                {
      -                  "type": "null"
      -                }
      -              ],
      -              "description": "ads returned value in this response."
      -            },
      -            "message": {
      -              "anyOf": [
      -                {
      -                  "description": "message value in this response.",
      -                  "type": "string"
      -                },
      -                {
      -                  "type": "null"
      -                }
      -              ],
      -              "description": "message value in this response."
      -            }
      -          },
      -          "type": "object"
      -        },
      -        {
      -          "type": "null"
      -        }
      -      ],
      -      "description": "reading use value in this response."
      -    },
      -    "retry_at": {
      -      "anyOf": [
      -        {
      -          "description": "Earliest retry time for an expired or failed insight attempt, when supplied.",
      -          "type": "string"
      -        },
      -        {
      -          "type": "null"
      -        }
      -      ],
      -      "description": "Earliest retry time for an expired or failed insight attempt, when supplied."
      -    },
      -    "standouts": {
      -      "anyOf": [
      -        {
      -          "description": "Up to twelve standout ads, at most three per advertiser.",
      -          "items": {
      -            "additionalProperties": false,
      -            "description": "standouts value in this response.",
      -            "properties": {
      -              "ad_library_url": {
      -                "anyOf": [
      -                  {
      -                    "description": "ad library url value in this response.",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "ad library url value in this response."
      -              },
      -              "advertiser": {
      -                "anyOf": [
      -                  {
      -                    "description": "advertiser value in this response.",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "Advertiser name."
      -              },
      -              "advertiser_id": {
      -                "description": "Canonical advertiser identity.",
      -                "type": "string"
      -              },
      -              "baseline": {
      -                "description": "Whether a sampled median is available.",
      -                "type": "string"
      -              },
      -              "body_text": {
      -                "anyOf": [
      -                  {
      -                    "description": "body text value in this response.",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "body text value in this response."
      -              },
      -              "body_text_truncated": {
      -                "anyOf": [
      -                  {
      -                    "description": "body text truncated value in this response.",
      -                    "type": "boolean"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "body text truncated value in this response."
      -              },
      -              "confirmation_stale": {
      -                "anyOf": [
      -                  {
      -                    "description": "confirmation stale value in this response.",
      -                    "type": "boolean"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "confirmation stale value in this response."
      -              },
      -              "cta": {
      -                "anyOf": [
      -                  {
      -                    "description": "cta value in this response.",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "cta value in this response."
      -              },
      -              "end_date": {
      -                "anyOf": [
      -                  {
      -                    "description": "Provider end date (YYYY-MM-DD); null if still running or unknown.",
      -                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "Provider end date (YYYY-MM-DD); null if still running or unknown."
      -              },
      -              "facebook_page_id": {
      -                "anyOf": [
      -                  {
      -                    "description": "facebook page id value in this response.",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "facebook page id value in this response."
      -              },
      -              "filters": {
      -                "anyOf": [
      -                  {
      -                    "additionalProperties": false,
      -                    "description": "filters value in this response.",
      -                    "properties": {
      -                      "angle": {
      -                        "anyOf": [
      -                          {
      -                            "description": "angle value in this response.",
      -                            "type": "string"
      -                          },
      -                          {
      -                            "type": "null"
      -                          }
      -                        ],
      -                        "description": "angle value in this response."
      -                      },
      -                      "industry_slug": {
      -                        "anyOf": [
      -                          {
      -                            "description": "Industry filter value, when known.",
      -                            "type": "string"
      -                          },
      -                          {
      -                            "type": "null"
      -                          }
      -                        ],
      -                        "description": "Industry filter value, when known."
      -                      }
      -                    },
      -                    "type": "object"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "filters value in this response."
      -              },
      -              "first_seen": {
      -                "anyOf": [
      -                  {
      -                    "description": "first seen value in this response.",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "first seen value in this response."
      -              },
      -              "for": {
      -                "anyOf": [
      -                  {
      -                    "description": "for value in this response.",
      -                    "maxLength": 40,
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "for value in this response."
      -              },
      -              "format": {
      -                "anyOf": [
      -                  {
      -                    "description": "Static image or video media format.",
      -                    "enum": [
      -                      "static",
      -                      "video"
      -                    ],
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "Static image or video media format."
      -              },
      -              "group_id": {
      -                "anyOf": [
      -                  {
      -                    "description": "Provider variation/collation group; null when unavailable.",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "Provider variation/collation group; null when unavailable."
      -              },
      -              "hook": {
      -                "anyOf": [
      -                  {
      -                    "additionalProperties": false,
      -                    "description": "Observed opening speech, image text, visual or written hook; null when evidence is unavailable.",
      -                    "properties": {
      -                      "on_screen": {
      -                        "description": "on screen value in this response.",
      -                        "items": {
      -                          "description": "on screen value in this response.",
      -                          "maxLength": 240,
      -                          "type": "string"
      -                        },
      -                        "maxItems": 3,
      -                        "type": "array"
      -                      },
      -                      "opening_visual": {
      -                        "anyOf": [
      -                          {
      -                            "description": "opening visual value in this response.",
      -                            "maxLength": 400,
      -                            "type": "string"
      -                          },
      -                          {
      -                            "type": "null"
      -                          }
      -                        ],
      -                        "description": "opening visual value in this response."
      -                      },
      -                      "source": {
      -                        "description": "Where the accessible ad or advertiser evidence came from.",
      -                        "enum": [
      -                          "video",
      -                          "image"
      -                        ],
      -                        "type": "string"
      -                      },
      -                      "spoken": {
      -                        "anyOf": [
      -                          {
      -                            "description": "spoken value in this response.",
      -                            "maxLength": 1000,
      -                            "type": "string"
      -                          },
      -                          {
      -                            "type": "null"
      -                          }
      -                        ],
      -                        "description": "spoken value in this response."
      -                      },
      -                      "type": {
      -                        "anyOf": [
      -                          {
      -                            "description": "type value in this response.",
      -                            "maxLength": 120,
      -                            "type": "string"
      -                          },
      -                          {
      -                            "type": "null"
      -                          }
      -                        ],
      -                        "description": "Stored hook category; may be present when opener text is unavailable. Null when no stored type is known."
      -                      },
      -                      "written": {
      -                        "anyOf": [
      -                          {
      -                            "description": "written value in this response.",
      -                            "maxLength": 500,
      -                            "type": "string"
      -                          },
      -                          {
      -                            "type": "null"
      -                          }
      -                        ],
      -                        "description": "written value in this response."
      -                      }
      -                    },
      -                    "required": [
      -                      "spoken",
      -                      "on_screen",
      -                      "opening_visual",
      -                      "written",
      -                      "type",
      -                      "source"
      -                    ],
      -                    "type": "object"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "Observed opening speech, image text, visual or written hook; null when evidence is unavailable."
      -              },
      -              "hook_type": {
      -                "anyOf": [
      -                  {
      -                    "description": "hook type value in this response.",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "hook type value in this response."
      -              },
      -              "hook_type_filter": {
      -                "anyOf": [
      -                  {
      -                    "description": "hook type filter value in this response.",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "hook type filter value in this response."
      -              },
      -              "id": {
      -                "anyOf": [
      -                  {
      -                    "description": "id value in this response.",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "id value in this response."
      -              },
      -              "image_url": {
      -                "anyOf": [
      -                  {
      -                    "description": "image url value in this response.",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "image url value in this response."
      -              },
      -              "landing_url": {
      -                "anyOf": [
      -                  {
      -                    "description": "landing url value in this response.",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "landing url value in this response."
      -              },
      -              "last_confirmed_at": {
      -                "anyOf": [
      -                  {
      -                    "description": "Most recent confirmed delivery timestamp, when known.",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "Most recent confirmed delivery timestamp, when known."
      -              },
      -              "last_seen": {
      -                "anyOf": [
      -                  {
      -                    "description": "last seen value in this response.",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "last seen value in this response."
      -              },
      -              "logo_url": {
      -                "anyOf": [
      -                  {
      -                    "description": "logo url value in this response.",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "Durable advertiser logo URL if available."
      -              },
      -              "original_headline": {
      -                "anyOf": [
      -                  {
      -                    "description": "original headline value in this response.",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "original headline value in this response."
      -              },
      -              "page_name": {
      -                "anyOf": [
      -                  {
      -                    "description": "page name value in this response.",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "page name value in this response."
      -              },
      -              "platforms": {
      -                "anyOf": [
      -                  {
      -                    "description": "platforms value in this response.",
      -                    "items": {
      -                      "description": "platforms value in this response.",
      -                      "type": "string"
      -                    },
      -                    "type": "array"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "platforms value in this response."
      -              },
      -              "reasons": {
      -                "description": "Qualification rules met by this ad.",
      -                "items": {
      -                  "description": "reasons value in this response.",
      -                  "type": "string"
      -                },
      -                "type": "array"
      -              },
      -              "rival_median_days": {
      -                "anyOf": [
      -                  {
      -                    "description": "rival median days value in this response.",
      -                    "type": "number"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "Median run days in the recent eligible sample."
      -              },
      -              "run_duration_days": {
      -                "anyOf": [
      -                  {
      -                    "description": "Computed from the provider start date to the last confirmed delivery; null when unknown.",
      -                    "maximum": 9007199254740991,
      -                    "minimum": 0,
      -                    "type": "integer"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "Computed from the provider start date to the last confirmed delivery; null when unknown."
      -              },
      -              "schema_version": {
      -                "anyOf": [
      -                  {
      -                    "const": 1,
      -                    "description": "schema version value in this response.",
      -                    "type": "number"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "schema version value in this response."
      -              },
      -              "source": {
      -                "anyOf": [
      -                  {
      -                    "description": "Where the accessible ad or advertiser evidence came from.",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "Where the accessible ad or advertiser evidence came from."
      -              },
      -              "start_date": {
      -                "anyOf": [
      -                  {
      -                    "description": "Provider start date (YYYY-MM-DD); null when the provider did not report one.",
      -                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "Provider start date (YYYY-MM-DD); null when the provider did not report one."
      -              },
      -              "steal_caution": {
      -                "anyOf": [
      -                  {
      -                    "description": "steal caution value in this response.",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "steal caution value in this response."
      -              },
      -              "still_running": {
      -                "anyOf": [
      -                  {
      -                    "description": "Current delivery evidence: true, false or null when unknown.",
      -                    "type": "boolean"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "Current delivery evidence: true, false or null when unknown."
      -              },
      -              "strength": {
      -                "anyOf": [
      -                  {
      -                    "description": "strength value in this response.",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "strength value in this response."
      -              },
      -              "strength_label": {
      -                "anyOf": [
      -                  {
      -                    "description": "Delivery-based label: winner, solid or testing. Cautions are separate.",
      -                    "enum": [
      -                      "winner",
      -                      "solid",
      -                      "testing"
      -                    ],
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "Delivery-based label: winner, solid or testing. Cautions are separate."
      -              },
      -              "variation_count": {
      -                "anyOf": [
      -                  {
      -                    "description": "variation count value in this response.",
      -                    "type": "number"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "variation count value in this response."
      -              },
      -              "video_asset_missing": {
      -                "anyOf": [
      -                  {
      -                    "description": "video asset missing value in this response.",
      -                    "type": "boolean"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "video asset missing value in this response."
      -              },
      -              "video_thumbnail_url": {
      -                "anyOf": [
      -                  {
      -                    "description": "video thumbnail url value in this response.",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "video thumbnail url value in this response."
      -              },
      -              "video_url": {
      -                "anyOf": [
      -                  {
      -                    "description": "video url value in this response.",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "video url value in this response."
      -              },
      -              "why": {
      -                "anyOf": [
      -                  {
      -                    "description": "why value in this response.",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "why value in this response."
      -              },
      -              "your_rival": {
      -                "anyOf": [
      -                  {
      -                    "description": "your rival value in this response.",
      -                    "type": "boolean"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "your rival value in this response."
      -              }
      -            },
      -            "type": "object"
      -          },
      -          "maxItems": 12,
      -          "type": "array"
      -        },
      -        {
      -          "type": "null"
      -        }
      -      ],
      -      "description": "Up to twelve standout ads, at most three per advertiser."
      -    },
      -    "state": {
      -      "anyOf": [
      -        {
      -          "description": "ready, pending, unavailable, or insufficient_evidence.",
      -          "type": "string"
      -        },
      -        {
      -          "type": "null"
      -        }
      -      ],
      -      "description": "ready, pending, unavailable, or insufficient_evidence."
      -    }
      -  },
      -  "type": "object"
      -}New value: +null
  2. Added

TDQS

A3.8/5.0
Behavior4/5

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

Beyond annotations, it discloses quota cost ('draw on the daily workspace reading allowance'), staleness marking, that samples carry no totals, and the insufficient_evidence state. That is real behavioral context for an openWorldHint tool. It does not explain why readOnlyHint is false despite the read-like purpose, leaving the consumption side-effect only loosely implied by the allowance sentence.

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?

One front-loaded paragraph that leads with what is returned before caveats. It is dense and packs several caveats into long run-on clauses, but no whole sentence is filler.

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

Completeness3/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 usefully sketches the return contract and edge states. It is silent on what happens when brand_id is omitted on a multi-brand account and on the invalid response_format value the schema warns about, which an agent calling with zero required params may hit.

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 description coverage is 100%, so the schema already documents brand_id, category, and response_format. The description mostly restates those semantics, adding only the evidence-widening consequence of category and the single-brand default. Baseline 3 is appropriate.

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 names a specific verb ('Summarizes') and resource ('observed ad patterns for one of the account's brands') and even quantifies the payload (up to three insights, up to twelve ads, at most three per advertiser). It also distinguishes two evidence modes: tracked competitors versus a one-time Ad Library sample. It never names a sibling such as list_tracked_rival_ads, so the boundary with adjacent tools is left implicit.

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 actionable conditions: supply a category to widen evidence with a one-time sample, add more tracked competitors for more evidence, and treat state 'insufficient_evidence' as meaning fewer than two standout ads were found. Missing is an explicit when-not or a direct comparison with the raw list tools, so the agent must infer when a summary beats a listing.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.