meta-ads-mcp

get_adsets_by_ids

Retrieve detailed Facebook ad set data for multiple IDs in one API call. Specify ad set IDs and optional fields to get performance insights and campaign details quickly.

Instructions

Retrieves detailed information about multiple Facebook ad sets by their IDs.

This function allows batch retrieval of multiple ad sets in a single API call, improving efficiency when you need data for several ad sets.

Args: adset_ids (List[str]): A list of ad set IDs to retrieve information for. fields (Optional[List[str]]): A list of specific fields to retrieve for each ad set. If None, a default set of fields will be returned. See get_adset_by_id for a comprehensive list of available fields. date_format (Optional[str]): Format for date responses. Options: - 'U': Unix timestamp (seconds since epoch) - 'Y-m-d H:i:s': MySQL datetime format - None: ISO 8601 format (default)

Returns: Dict: A dictionary where keys are the ad set IDs and values are the corresponding ad set details.

Example: ```python # Get information for multiple ad sets adsets = get_adsets_by_ids( adset_ids=["23843211234567", "23843211234568", "23843211234569"], fields=["name", "campaign_id", "effective_status", "budget_remaining"], date_format="U" # Get dates as Unix timestamps )

# Access information for a specific ad set
if "23843211234567" in adsets:
    print(adsets["23843211234567"]["name"])
```

Input Schema

TableJSON Schema

Name	Required	Description	Default
`fields`	No
`adset_ids`	Yes
`date_format`	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/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 full burden. It discloses the read-only nature ('Retrieves') and explains return format and date formatting, but it doesn't mention authentication, rate limits, pagination, or behavior on invalid IDs. For a retrieval tool this is adequate but not comprehensive; it adds some value beyond the name, but significant behavioral context is missing.

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 longer than average but well-structured with Args, Returns, and a full example. Every sentence serves a purpose—the example is useful for showing calling conventions and response access. While it could be trimmed slightly, the structure is logical and information-dense, so it earns its length.

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 (batch retrieval, optional fields, date formatting), the description covers all parameters, the return structure, and a working example. It does not mention edge cases like partial failures or pagination, and the output schema is not shown, but the description does explain the dict format. This is nearly complete for an agent to call correctly, with minor gaps around error behavior.

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 fully explain each parameter. It does so thoroughly: adset_ids is clearly the list of IDs, fields is explained with default behavior and a pointer to get_adset_by_id for full options, and date_format lists all supported values ('U', 'Y-m-d H:i:s', None) with their meanings. The example demonstrates realistic usage, adding clarity beyond the 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 states a specific action ('Retrieves detailed information'), a precise resource ('Facebook ad sets'), and a specific scoping constraint ('by their IDs'). It also highlights the batch nature, clearly distinguishing it from singular and account/campaign-based siblings like get_adset_by_id and get_adsets_by_adaccount. No ambiguity remains.

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

Usage Guidelines3/5

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

The description implies usage when you have specific ad set IDs and need batch efficiency, but it does not explicitly contrast this with alternatives. For example, it doesn't say 'Use this when you have exact IDs; use get_adsets_by_adaccount when you want all adsets for an account.' The only reference to a sibling is for field lists, not for selection guidance. This is implied rather than explicit.

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

Deploy Server