AdsAgent — Meta Ads MCP

entities_lookup_by_name

Read-only

Find ads, ad groups, and campaigns by name, and find which ad groups use a creative or file name. Use this tool when the user asks to find an ad, an ad group, or a campaign by name, or asks where a creative or file is used. Do not use insight search or a creative library for that question. Exact matching ignores case and preserves spelling. Substring matching ignores case, media extensions, and separator differences such as spaces, underscores, dots, and hyphens. Separators do not match arbitrary letters. A name matches as a substring when its folded form has at least 8 characters, or at least 2 characters when that form contains Han, Hiragana, Katakana, or Hangul. Accepts 1-50 names of 1-255 characters each. ad_account_ids is optional; on Meta pass act_ followed by digits, or digits only. Returns delivery status, the parent campaign status, the parent ad group status, the budget owner, today's spend, last-7-day spend, and prepare_groups. status=delivering omits rows that are not delivering. Reads cached data only and does not change anything. When next_cursor is set, pass it as result_cursor to read the next page. A result without next_cursor has no further page.

Input Schema

Name	Required	Description	Default
`names`	Yes
`levels`	No
`status`	No		delivering
`group_by`	No		group
`result_cursor`	No
`ad_account_ids`	No	Limit the search to these ad accounts. The channel's account prefix is optional: on Meta, act_123 and 123 are the same account.

Output Schema

Name	Required	Description	Default
`rows`	Yes
`as_of`	Yes
`limits`	Yes
`channel`	Yes
`queries`	Yes
`coverage`	Yes
`warnings`	Yes
`truncated`	Yes
`lookup_ref`	Yes
`next_cursor`	Yes
`prepare_groups`	Yes
`excluded_from_prepare`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedOct 25, 2026
- addedInput schema / properties / ad_account_ids / description
```
Added value: +"Limit the search to these ad accounts. The channel's account prefix is optional: on Meta, act_123 and 123 are the same account."
```
- addedInput schema / properties / names / items / maxLength
```
Added value: +255
```
- addedInput schema / properties / names / items / minLength
```
Added value: +1
```

Changed44 schema fields changedOct 22, 2026

removedOutput schema / $defs

Removed value: -{
-  "AccountOut": {
-    "additionalProperties": false,
-    "properties": {
-      "currency": {
-        "title": "Currency",
-        "type": "string"
-      },
-      "id": {
-        "title": "Id",
-        "type": "string"
-      },
-      "name": {
-        "title": "Name",
-        "type": "string"
-      },
-      "timezone": {
-        "title": "Timezone",
-        "type": "string"
-      }
-    },
-    "required": [
-      "id",
-      "name",
-      "currency",
-      "timezone"
-    ],
-    "title": "AccountOut",
-    "type": "object"
-  },
-  "AdSummary": {
-    "additionalProperties": false,
-    "properties": {
-      "count": {
-        "title": "Count",
-        "type": "integer"
-      },
-      "ids": {
-        "items": {
-          "type": "string"
-        },
-        "title": "Ids",
-        "type": "array"
-      },
-      "statuses": {
-        "additionalProperties": {
-          "type": "integer"
-        },
-        "title": "Statuses",
-        "type": "object"
-      }
-    },
-    "required": [
-      "count",
-      "ids",
-      "statuses"
-    ],
-    "title": "AdSummary",
-    "type": "object"
-  },
-  "BudgetOwner": {
-    "additionalProperties": false,
-    "properties": {
-      "currency": {
-        "title": "Currency",
-        "type": "string"
-      },
-      "daily_minor": {
-        "anyOf": [
-          {
-            "type": "integer"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "title": "Daily Minor"
-      },
-      "id": {
-        "title": "Id",
-        "type": "string"
-      },
-      "level": {
-        "title": "Level",
-        "type": "string"
-      },
-      "lifetime_minor": {
-        "anyOf": [
-          {
-            "type": "integer"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "title": "Lifetime Minor"
-      },
-      "shared": {
-        "title": "Shared",
-        "type": "boolean"
-      }
-    },
-    "required": [
-      "level",
-      "id",
-      "daily_minor",
-      "lifetime_minor",
-      "currency",
-      "shared"
-    ],
-    "title": "BudgetOwner",
-    "type": "object"
-  },
-  "Coverage": {
-    "additionalProperties": false,
-    "properties": {
-      "notes": {
-        "items": {
-          "type": "string"
-        },
-        "title": "Notes",
-        "type": "array"
-      }
-    },
-    "required": [
-      "notes"
-    ],
-    "title": "Coverage",
-    "type": "object"
-  },
-  "EntityOut": {
-    "additionalProperties": false,
-    "properties": {
-      "id": {
-        "title": "Id",
-        "type": "string"
-      },
-      "name": {
-        "title": "Name",
-        "type": "string"
-      },
-      "status": {
-        "title": "Status",
-        "type": "string"
-      }
-    },
-    "required": [
-      "id",
-      "name",
-      "status"
-    ],
-    "title": "EntityOut",
-    "type": "object"
-  },
-  "Exclusion": {
-    "additionalProperties": false,
-    "properties": {
-      "reason_code": {
-        "title": "Reason Code",
-        "type": "string"
-      },
-      "row_ref": {
-        "title": "Row Ref",
-        "type": "integer"
-      }
-    },
-    "required": [
-      "row_ref",
-      "reason_code"
-    ],
-    "title": "Exclusion",
-    "type": "object"
-  },
-  "Freshness": {
-    "additionalProperties": false,
-    "properties": {
-      "entity_observed_at": {
-        "format": "date-time",
-        "title": "Entity Observed At",
-        "type": "string"
-      },
-      "stale": {
-        "title": "Stale",
-        "type": "boolean"
-      }
-    },
-    "required": [
-      "entity_observed_at",
-      "stale"
-    ],
-    "title": "Freshness",
-    "type": "object"
-  },
-  "GroupOut": {
-    "additionalProperties": false,
-    "properties": {
-      "id": {
-        "title": "Id",
-        "type": "string"
-      },
-      "level": {
-        "title": "Level",
-        "type": "string"
-      },
-      "name": {
-        "title": "Name",
-        "type": "string"
-      },
-      "status": {
-        "title": "Status",
-        "type": "string"
-      }
-    },
-    "required": [
-      "id",
-      "name",
-      "status",
-      "level"
-    ],
-    "title": "GroupOut",
-    "type": "object"
-  },
-  "Limits": {
-    "additionalProperties": false,
-    "properties": {
-      "max_bytes": {
-        "default": 48640,
-        "title": "Max Bytes",
-        "type": "integer"
-      },
-      "max_rows": {
-        "default": 1000,
-        "title": "Max Rows",
-        "type": "integer"
-      }
-    },
-    "title": "Limits",
-    "type": "object"
-  },
-  "LookupWarning": {
-    "additionalProperties": false,
-    "properties": {
-      "code": {
-        "title": "Code",
-        "type": "string"
-      },
-      "message": {
-        "title": "Message",
-        "type": "string"
-      }
-    },
-    "required": [
-      "code",
-      "message"
-    ],
-    "title": "LookupWarning",
-    "type": "object"
-  },
-  "MatchInfo": {
-    "additionalProperties": false,
-    "properties": {
-      "level": {
-        "enum": [
-          "ad",
-          "group",
-          "campaign"
-        ],
-        "title": "Level",
-        "type": "string"
-      },
-      "tier": {
-        "enum": [
-          "exact",
-          "exact_copy",
-          "contains"
-        ],
-        "title": "Tier",
-        "type": "string"
-      }
-    },
-    "required": [
-      "tier",
-      "level"
-    ],
-    "title": "MatchInfo",
-    "type": "object"
-  },
-  "PrepareGroup": {
-    "additionalProperties": false,
-    "properties": {
-      "args": {
-        "additionalProperties": true,
-        "title": "Args",
-        "type": "object"
-      },
-      "row_refs": {
-        "items": {
-          "type": "integer"
-        },
-        "title": "Row Refs",
-        "type": "array"
-      },
-      "tool": {
-        "title": "Tool",
-        "type": "string"
-      }
-    },
-    "required": [
-      "tool",
-      "args",
-      "row_refs"
-    ],
-    "title": "PrepareGroup",
-    "type": "object"
-  },
-  "QueryOutcome": {
-    "additionalProperties": false,
-    "properties": {
-      "ads": {
-        "title": "Ads",
-        "type": "integer"
-      },
-      "groups": {
-        "title": "Groups",
-        "type": "integer"
-      },
-      "index": {
-        "title": "Index",
-        "type": "integer"
-      },
-      "input": {
-        "title": "Input",
-        "type": "string"
-      },
-      "matched_levels": {
-        "items": {
-          "enum": [
-            "ad",
-            "group",
-            "campaign"
-          ],
-          "type": "string"
-        },
-        "title": "Matched Levels",
-        "type": "array"
-      },
-      "normalized": {
-        "title": "Normalized",
-        "type": "string"
-      },
-      "status": {
-        "enum": [
-          "matched",
-          "ambiguous",
-          "not_found",
-          "stale_only",
-          "status_filtered"
-        ],
-        "title": "Status",
-        "type": "string"
-      },
-      "suggestions": {
-        "items": {
-          "type": "string"
-        },
-        "title": "Suggestions",
-        "type": "array"
-      }
-    },
-    "required": [
-      "index",
-      "input",
-      "normalized",
-      "status",
-      "matched_levels",
-      "groups",
-      "ads",
-      "suggestions"
-    ],
-    "title": "QueryOutcome",
-    "type": "object"
-  },
-  "ResultRow": {
-    "additionalProperties": false,
-    "properties": {
-      "account": {
-        "$ref": "#/$defs/AccountOut"
-      },
-      "ads": {
-        "anyOf": [
-          {
-            "$ref": "#/$defs/AdSummary"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null
-      },
-      "budget_owner": {
-        "anyOf": [
-          {
-            "$ref": "#/$defs/BudgetOwner"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null
-      },
-      "campaign": {
-        "$ref": "#/$defs/EntityOut"
-      },
-      "freshness": {
-        "$ref": "#/$defs/Freshness"
-      },
-      "group": {
-        "anyOf": [
-          {
-            "$ref": "#/$defs/GroupOut"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null
-      },
-      "group_count": {
-        "anyOf": [
-          {
-            "type": "integer"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "title": "Group Count"
-      },
-      "match": {
-        "$ref": "#/$defs/MatchInfo"
-      },
-      "query_index": {
-        "title": "Query Index",
-        "type": "integer"
-      },
-      "spend": {
-        "$ref": "#/$defs/SpendOut"
-      }
-    },
-    "required": [
-      "query_index",
-      "match",
-      "account",
-      "campaign",
-      "spend",
-      "freshness"
-    ],
-    "title": "ResultRow",
-    "type": "object"
-  },
-  "SpendOut": {
-    "additionalProperties": false,
-    "properties": {
-      "currency": {
-        "title": "Currency",
-        "type": "string"
-      },
-      "last_7d_minor": {
-        "anyOf": [
-          {
-            "type": "integer"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "title": "Last 7D Minor"
-      },
-      "metrics_as_of": {
-        "anyOf": [
-          {
-            "format": "date-time",
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "title": "Metrics As Of"
-      },
-      "today_complete": {
-        "title": "Today Complete",
-        "type": "boolean"
-      },
-      "today_minor": {
-        "anyOf": [
-          {
-            "type": "integer"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "title": "Today Minor"
-      }
-    },
-    "required": [
-      "today_minor",
-      "last_7d_minor",
-      "currency",
-      "metrics_as_of",
-      "today_complete"
-    ],
-    "title": "SpendOut",
-    "type": "object"
-  }
-}

removedOutput schema / properties / coverage / $ref
```
Removed value: -"#/$defs/Coverage"
```
addedOutput schema / properties / coverage / additionalProperties
```
Added value: +false
```

addedOutput schema / properties / coverage / properties

Added value: +{
+  "notes": {
+    "items": {
+      "type": "string"
+    },
+    "title": "Notes",
+    "type": "array"
+  }
+}

addedOutput schema / properties / coverage / required
```
Added value: +[
+  "notes"
+]
```
addedOutput schema / properties / coverage / title
```
Added value: +"Coverage"
```
addedOutput schema / properties / coverage / type
```
Added value: +"object"
```
removedOutput schema / properties / excluded_from_prepare / items / $ref
```
Removed value: -"#/$defs/Exclusion"
```
addedOutput schema / properties / excluded_from_prepare / items / additionalProperties
```
Added value: +false
```

addedOutput schema / properties / excluded_from_prepare / items / properties

Added value: +{
+  "reason_code": {
+    "title": "Reason Code",
+    "type": "string"
+  },
+  "row_ref": {
+    "title": "Row Ref",
+    "type": "integer"
+  }
+}

addedOutput schema / properties / excluded_from_prepare / items / required
```
Added value: +[
+  "row_ref",
+  "reason_code"
+]
```
addedOutput schema / properties / excluded_from_prepare / items / title
```
Added value: +"Exclusion"
```
addedOutput schema / properties / excluded_from_prepare / items / type
```
Added value: +"object"
```
removedOutput schema / properties / limits / $ref
```
Removed value: -"#/$defs/Limits"
```
addedOutput schema / properties / limits / additionalProperties
```
Added value: +false
```

addedOutput schema / properties / limits / properties

Added value: +{
+  "max_bytes": {
+    "default": 48640,
+    "title": "Max Bytes",
+    "type": "integer"
+  },
+  "max_rows": {
+    "default": 1000,
+    "title": "Max Rows",
+    "type": "integer"
+  }
+}

addedOutput schema / properties / limits / title
```
Added value: +"Limits"
```
addedOutput schema / properties / limits / type
```
Added value: +"object"
```

removedOutput schema / properties / next_cursor / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / next_cursor / type
```
Added value: +[
+  "null",
+  "string"
+]
```
removedOutput schema / properties / prepare_groups / items / $ref
```
Removed value: -"#/$defs/PrepareGroup"
```
addedOutput schema / properties / prepare_groups / items / additionalProperties
```
Added value: +false
```

addedOutput schema / properties / prepare_groups / items / properties

Added value: +{
+  "args": {
+    "title": "Args",
+    "type": "object"
+  },
+  "row_refs": {
+    "items": {
+      "type": "integer"
+    },
+    "title": "Row Refs",
+    "type": "array"
+  },
+  "tool": {
+    "title": "Tool",
+    "type": "string"
+  }
+}

addedOutput schema / properties / prepare_groups / items / required
```
Added value: +[
+  "tool",
+  "args",
+  "row_refs"
+]
```
addedOutput schema / properties / prepare_groups / items / title
```
Added value: +"PrepareGroup"
```
addedOutput schema / properties / prepare_groups / items / type
```
Added value: +"object"
```
removedOutput schema / properties / queries / items / $ref
```
Removed value: -"#/$defs/QueryOutcome"
```
addedOutput schema / properties / queries / items / additionalProperties
```
Added value: +false
```

addedOutput schema / properties / queries / items / properties

Added value: +{
+  "ads": {
+    "title": "Ads",
+    "type": "integer"
+  },
+  "groups": {
+    "title": "Groups",
+    "type": "integer"
+  },
+  "index": {
+    "title": "Index",
+    "type": "integer"
+  },
+  "input": {
+    "title": "Input",
+    "type": "string"
+  },
+  "matched_levels": {
+    "items": {
+      "enum": [
+        "ad",
+        "group",
+        "campaign"
+      ],
+      "type": "string"
+    },
+    "title": "Matched Levels",
+    "type": "array"
+  },
+  "normalized": {
+    "title": "Normalized",
+    "type": "string"
+  },
+  "status": {
+    "enum": [
+      "matched",
+      "ambiguous",
+      "not_found",
+      "stale_only",
+      "status_filtered"
+    ],
+    "title": "Status",
+    "type": "string"
+  },
+  "suggestions": {
+    "items": {
+      "type": "string"
+    },
+    "title": "Suggestions",
+    "type": "array"
+  }
+}

addedOutput schema / properties / queries / items / required

Added value: +[
+  "index",
+  "input",
+  "normalized",
+  "status",
+  "matched_levels",
+  "groups",
+  "ads",
+  "suggestions"
+]

addedOutput schema / properties / queries / items / title
```
Added value: +"QueryOutcome"
```
addedOutput schema / properties / queries / items / type
```
Added value: +"object"
```
removedOutput schema / properties / rows / items / $ref
```
Removed value: -"#/$defs/ResultRow"
```
addedOutput schema / properties / rows / items / additionalProperties
```
Added value: +false
```

addedOutput schema / properties / rows / items / properties

Added value: +{
+  "account": {
+    "additionalProperties": false,
+    "properties": {
+      "currency": {
+        "title": "Currency",
+        "type": "string"
+      },
+      "id": {
+        "title": "Id",
+        "type": "string"
+      },
+      "name": {
+        "title": "Name",
+        "type": "string"
+      },
+      "timezone": {
+        "title": "Timezone",
+        "type": "string"
+      }
+    },
+    "required": [
+      "id",
+      "name",
+      "currency",
+      "timezone"
+    ],
+    "title": "AccountOut",
+    "type": "object"
+  },
+  "ads": {
+    "additionalProperties": false,
+    "default": null,
+    "properties": {
+      "count": {
+        "title": "Count",
+        "type": "integer"
+      },
+      "ids": {
+        "items": {
+          "type": "string"
+        },
+        "title": "Ids",
+        "type": "array"
+      },
+      "statuses": {
+        "additionalProperties": {
+          "type": "integer"
+        },
+        "title": "Statuses",
+        "type": "object"
+      }
+    },
+    "required": [
+      "count",
+      "ids",
+      "statuses"
+    ],
+    "title": "AdSummary",
+    "type": [
+      "null",
+      "object"
+    ]
+  },
+  "budget_owner": {
+    "additionalProperties": false,
+    "default": null,
+    "properties": {
+      "currency": {
+        "title": "Currency",
+        "type": "string"
+      },
+      "daily_minor": {
+        "title": "Daily Minor",
+        "type": [
+          "integer",
+          "null"
+        ]
+      },
+      "id": {
+        "title": "Id",
+        "type": "string"
+      },
+      "level": {
+        "title": "Level",
+        "type": "string"
+      },
+      "lifetime_minor": {
+        "title": "Lifetime Minor",
+        "type": [
+          "integer",
+          "null"
+        ]
+      },
+      "shared": {
+        "title": "Shared",
+        "type": "boolean"
+      }
+    },
+    "required": [
+      "level",
+      "id",
+      "daily_minor",
+      "lifetime_minor",
+      "currency",
+      "shared"
+    ],
+    "title": "BudgetOwner",
+    "type": [
+      "null",
+      "object"
+    ]
+  },
+  "campaign": {
+    "additionalProperties": false,
+    "properties": {
+      "id": {
+        "title": "Id",
+        "type": "string"
+      },
+      "name": {
+        "title": "Name",
+        "type": "string"
+      },
+      "status": {
+        "title": "Status",
+        "type": "string"
+      }
+    },
+    "required": [
+      "id",
+      "name",
+      "status"
+    ],
+    "title": "EntityOut",
+    "type": "object"
+  },
+  "freshness": {
+    "additionalProperties": false,
+    "properties": {
+      "entity_observed_at": {
+        "format": "date-time",
+        "title": "Entity Observed At",
+        "type": "string"
+      },
+      "stale": {
+        "title": "Stale",
+        "type": "boolean"
+      }
+    },
+    "required": [
+      "entity_observed_at",
+      "stale"
+    ],
+    "title": "Freshness",
+    "type": "object"
+  },
+  "group": {
+    "additionalProperties": false,
+    "default": null,
+    "properties": {
+      "id": {
+        "title": "Id",
+        "type": "string"
+      },
+      "level": {
+        "title": "Level",
+        "type": "string"
+      },
+      "name": {
+        "title": "Name",
+        "type": "string"
+      },
+      "status": {
+        "title": "Status",
+        "type": "string"
+      }
+    },
+    "required": [
+      "id",
+      "name",
+      "status",
+      "level"
+    ],
+    "title": "GroupOut",
+    "type": [
+      "null",
+      "object"
+    ]
+  },
+  "group_count": {
+    "default": null,
+    "title": "Group Count",
+    "type": [
+      "integer",
+      "null"
+    ]
+  },
+  "match": {
+    "additionalProperties": false,
+    "properties": {
+      "level": {
+        "enum": [
+          "ad",
+          "group",
+          "campaign"
+        ],
+        "title": "Level",
+        "type": "string"
+      },
+      "tier": {
+        "enum": [
+          "exact",
+          "exact_copy",
+          "contains"
+        ],
+        "title": "Tier",
+        "type": "string"
+      }
+    },
+    "required": [
+      "tier",
+      "level"
+    ],
+    "title": "MatchInfo",
+    "type": "object"
+  },
+  "query_index": {
+    "title": "Query Index",
+    "type": "integer"
+  },
+  "spend": {
+    "additionalProperties": false,
+    "properties": {
+      "currency": {
+        "title": "Currency",
+        "type": "string"
+      },
+      "last_7d_minor": {
+        "title": "Last 7D Minor",
+        "type": [
+          "integer",
+          "null"
+        ]
+      },
+      "metrics_as_of": {
+        "anyOf": [
+          {
+            "format": "date-time",
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "title": "Metrics As Of"
+      },
+      "today_complete": {
+        "title": "Today Complete",
+        "type": "boolean"
+      },
+      "today_minor": {
+        "title": "Today Minor",
+        "type": [
+          "integer",
+          "null"
+        ]
+      }
+    },
+    "required": [
+      "today_minor",
+      "last_7d_minor",
+      "currency",
+      "metrics_as_of",
+      "today_complete"
+    ],
+    "title": "SpendOut",
+    "type": "object"
+  }
+}

addedOutput schema / properties / rows / items / required

Added value: +[
+  "query_index",
+  "match",
+  "account",
+  "campaign",
+  "spend",
+  "freshness"
+]

addedOutput schema / properties / rows / items / title
```
Added value: +"ResultRow"
```
addedOutput schema / properties / rows / items / type
```
Added value: +"object"
```
removedOutput schema / properties / warnings / items / $ref
```
Removed value: -"#/$defs/LookupWarning"
```
addedOutput schema / properties / warnings / items / additionalProperties
```
Added value: +false
```

addedOutput schema / properties / warnings / items / properties

Added value: +{
+  "code": {
+    "title": "Code",
+    "type": "string"
+  },
+  "message": {
+    "title": "Message",
+    "type": "string"
+  }
+}

addedOutput schema / properties / warnings / items / required
```
Added value: +[
+  "code",
+  "message"
+]
```
addedOutput schema / properties / warnings / items / title
```
Added value: +"LookupWarning"
```
addedOutput schema / properties / warnings / items / type
```
Added value: +"object"
```

AddedOct 20, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Beyond the readOnly/non-destructive annotations, it discloses cached-data-only reads, no side effects, delivery-status filtering behavior, the exact result payload (delivery status, parent statuses, budget owner, today/7-day spend, prepare_groups), and cursor pagination semantics — rich context the annotations cannot supply.

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 purpose and routing before the matching rules, and nearly every sentence carries operational information. It is a dense single block though — the matching rules and pagination notes could be separated for faster scanning.

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?

For a 6-parameter lookup with an output schema, an agent has everything needed: when to call it, how names match, account ID format, status filtering, what comes back, and how to page. Nothing material 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 only 17%, and the description compensates well: exact-vs-substring matching rules, case/extension/separator folding, minimum folded lengths (8 chars; 2 for Han/Kana/Hangul), 1-50 names of 1-255 chars, Meta ad_account_ids act_ prefix, status filtering, and result_cursor/next_cursor flow. It leaves 'levels' and 'group_by' unexplained, which are meaningful shaping parameters.

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?

States specific verbs and resources: find ads/ad groups/campaigns by name, and find which ad groups use a creative or file name. This is distinguishable from the sibling entity/creative tools without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says when to use it ('the user asks to find an ad, an ad group, or a campaign by name, or asks where a creative or file is used') and when not to ('Do not use insight search or a creative library for that question'), naming the alternatives to avoid.

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

All AdsAgent — Meta Ads MCP 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?