meta-ads-mcp

get_adset_by_id

Fetch a Facebook ad set's targeting, budget, scheduling, and status by its ID. Get a complete snapshot of any ad set's configuration and performance.

Instructions

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

This function accesses the Facebook Graph API to retrieve information about a single ad set, including details about its targeting, budget, scheduling, and status.

Args: adset_id (str): The ID of the ad set 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 set's ID - 'name': The ad set's name - 'account_id': The ID of the ad account this ad set belongs to - 'campaign_id': The ID of the campaign this ad set belongs to - 'bid_amount': The bid amount for this ad set - 'bid_strategy': Strategy used for bidding. Options include: 'LOWEST_COST_WITHOUT_CAP', 'LOWEST_COST_WITH_BID_CAP', 'COST_CAP' - 'billing_event': The billing event type. Options include: 'APP_INSTALLS', 'CLICKS', 'IMPRESSIONS', 'LINK_CLICKS', 'NONE', 'OFFER_CLAIMS', 'PAGE_LIKES', 'POST_ENGAGEMENT', 'THRUPLAY' - 'budget_remaining': The remaining budget for this ad set (in cents/smallest currency unit) - 'configured_status': The status set by the user. Options include: 'ACTIVE', 'PAUSED', 'DELETED', 'ARCHIVED' - 'created_time': When the ad set was created - 'daily_budget': The daily budget for this ad set (in cents/smallest currency unit) - 'daily_min_spend_target': The minimum daily spend target (in cents/smallest currency unit) - 'daily_spend_cap': The daily spend cap (in cents/smallest currency unit) - 'destination_type': Type of destination for the ads - 'effective_status': The effective status (actual status). Options include: 'ACTIVE', 'PAUSED', 'DELETED', 'PENDING_REVIEW', 'DISAPPROVED', 'PREAPPROVED', 'PENDING_BILLING_INFO', 'CAMPAIGN_PAUSED', 'ARCHIVED', 'ADSET_PAUSED', 'IN_PROCESS', 'WITH_ISSUES' - 'end_time': When the ad set will end (in ISO 8601 format) - 'frequency_control_specs': Specifications for frequency control - 'lifetime_budget': The lifetime budget (in cents/smallest currency unit) - 'lifetime_imps': The maximum number of lifetime impressions - 'lifetime_min_spend_target': The minimum lifetime spend target - 'lifetime_spend_cap': The lifetime spend cap - 'optimization_goal': The optimization goal for this ad set. Options include: 'APP_INSTALLS', 'BRAND_AWARENESS', 'CLICKS', 'ENGAGED_USERS', 'EVENT_RESPONSES', 'IMPRESSIONS', 'LEAD_GENERATION', 'LINK_CLICKS', 'NONE', 'OFFER_CLAIMS', 'OFFSITE_CONVERSIONS', 'PAGE_ENGAGEMENT', 'PAGE_LIKES', 'POST_ENGAGEMENT', 'QUALITY_LEAD', 'REACH', 'REPLIES', 'SOCIAL_IMPRESSIONS', 'THRUPLAY', 'VALUE', 'VISIT_INSTAGRAM_PROFILE' - 'pacing_type': List of pacing types. Options include: 'standard', 'no_pacing' - 'promoted_object': The object this ad set is promoting - 'recommendations': Recommendations for improving this ad set - 'rf_prediction_id': The Reach and Frequency prediction ID - 'source_adset_id': ID of the source ad set if this is a copy - 'start_time': When the ad set starts (in ISO 8601 format) - 'status': Deprecated. The ad set's status. Use 'effective_status' instead. - 'targeting': The targeting criteria for this ad set (complex object) - 'time_based_ad_rotation_id_blocks': Time-based ad rotation blocks - 'time_based_ad_rotation_intervals': Time-based ad rotation intervals in seconds - 'updated_time': When this ad set was last updated - 'use_new_app_click': Whether to use the newer app click tracking

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

Example: ```python # Get basic ad set information adset = get_adset_by_id( adset_id="23843211234567", fields=["name", "campaign_id", "effective_status", "targeting", "budget_remaining"] )

# Get detailed scheduling information
adset_schedule = get_adset_by_id(
    adset_id="23843211234567",
    fields=["name", "start_time", "end_time", "daily_budget", "lifetime_budget"]
)
```

Input Schema

TableJSON Schema

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

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.1/5.0

Behavior3/5

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

No annotations are provided, so the description carries the burden. It discloses that it accesses the Facebook Graph API, that fields is optional with a default set returned, and that the return is a dictionary. It also documents deprecated fields (status) and field options. However, it doesn't disclose potential errors (e.g., invalid ID, permission failures), rate limits, or whether the default field set is comprehensive. The behavior is mostly transparent for a read operation, but some operational details are missing.

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

Conciseness3/5

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

The description is long and detailed, but the field list is necessary given 0% schema coverage. The structure is clear: overview, args, returns, examples. However, it is somewhat verbose—the field list could be trimmed or moved to the schema, and the repeated enum options add bulk. It earns a 3 because it's well-organized but not tightly concise.

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 complexity (2 params, one with a huge field list) and no annotations, the description covers the essential context: what it does, what parameters mean, what it returns, and examples. It doesn't cover error handling or permission requirements, but for a read-only retrieval tool with an output schema, it is largely complete. The output schema exists, so return values are further specified.

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 description coverage is 0%, so the description must fully compensate. It does: adset_id is explained as 'The ID of the ad set to retrieve information for', and fields is explained in depth with a list of ~40 available fields, their meanings, and enum options. The examples show realistic usage. This is far beyond what the bare schema provides.

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 states the tool retrieves detailed information about a specific Facebook ad set by its ID, naming the resource (ad set) and the action (retrieve). It distinguishes itself from sibling tools like get_adsets_by_ids (plural) and get_adset_insights (insights) by focusing on a single ad set's detailed fields. The verb 'retrieves' is specific and the resource is unambiguous.

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

Usage Guidelines4/5

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

The description explains the tool accesses the Facebook Graph API to retrieve a single ad set's details, and the examples show typical use cases (basic info, scheduling info). It doesn't explicitly state when NOT to use it or name alternatives, but the context of 'by ID' and the sibling list (e.g., get_adsets_by_ids, get_adsets_by_adaccount) makes the usage context reasonably clear. It lacks explicit exclusions or alternative routing.

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

Deploy Server