meta-ads-mcp

get_ad_by_id

Fetch a specific Facebook ad's details by ID, including status, targeting, creative, budget, and performance metrics for reporting and analysis.

Instructions

Retrieves detailed information about a specific Facebook ad by its ID.

This function accesses the Facebook Graph API to retrieve information about a single ad object, including details about its status, targeting, creative, budget, and performance metrics.

Args: ad_id (str): The ID of the ad to retrieve information for. fields (Optional[List[str]]): A list of specific fields to retrieve. If None, a default set of fields will be returned. Available fields include: - 'id': The ad's ID - 'name': The ad's name - 'account_id': The ID of the ad account this ad belongs to - 'adset_id': The ID of the ad set this ad belongs to - 'campaign_id': The ID of the campaign this ad belongs to - 'adlabels': Labels applied to the ad - 'bid_amount': The bid amount for this ad - 'bid_type': The bid type of this ad - 'bid_info': The bid info for this ad - 'configured_status': The configured status of this ad - 'conversion_domain': The conversion domain for this ad - 'created_time': When the ad was created - 'creative': The ad creative - 'effective_status': The effective status of this ad - 'issues_info': Information about issues with this ad - 'recommendations': Recommendations for improving this ad - 'status': The status of this ad - 'tracking_specs': The tracking specs for this ad - 'updated_time': When this ad was last updated - 'preview_shareable_link': Link for previewing this ad

Returns: Dict: A dictionary containing the requested ad information.

Example: python # Get basic ad information ad = get_ad_by_id( ad_id="23843211234567", fields=["name", "adset_id", "campaign_id", "effective_status", "creative"] )

Input Schema

TableJSON Schema

Name	Required	Description	Default
`ad_id`	Yes
`fields`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 21, 2026

TDQS

A4.4/5.0

Behavior4/5

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

There are no annotations provided, so the description takes on the full burden. It explains that it calls the Facebook Graph API, lists available fields, and mentions that a default set is returned if fields is None. This adds behavioral context (e.g., making an API call, default behavior) beyond what the schema provides.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is detailed but well-structured: a brief summary, then bullet-list fields, and an example. It is somewhat longer than necessary but each section adds value, and the key info (purpose and fields) is front-loaded.

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

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (2 params, output schema present), the description covers purpose, parameters, and returns. It does not explicitly explain the return format in detail, but the output schema exists, so that is acceptable. The field list could be improved by noting that 'fields' may exclude the default fields, but overall complete.

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

Parameters5/5

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

Schema coverage is 0%, so the description must compensate, and it does excellently. It lists and explains 20 available fields for the 'fields' parameter, and clarifies that 'ad_id' is the ID of the ad to retrieve. This goes far beyond the minimal schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly specifies the verb 'retrieves' and the resource 'detailed information about a specific Facebook ad by its ID'. It distinguishes this from sibling tools like get_ads_by_adaccount or get_ad_insights by focusing on a single ad's details.

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 states the purpose is to retrieve info for a specific ad ID, which implies when to use it versus listing tools. However, it does not explicitly exclude other tools or mention when not to use it, but the context is clear given the tool's specificity.

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

Deploy Server