Skip to main content
Glama
Sign In

Mojeeb

by app.mojeeb.mcp
OverviewDiscussionsAdmin

List an agent's ads

list_ads
Read-onlyIdempotent

List an agent's ads

The Meta ads customers have reached the agent through, newest first by when Mojeeb first saw each, with what each brought in: taps by channel, private replies to comments on its own posts, and the conversations, contacts and leads it touched. An ad appears once a customer taps it (Messenger, Instagram or WhatsApp) or, on Instagram, once a comment arrives on its ad media; Mojeeb never reads Ads Manager, so spend and reach are not here. Filter with active_since (ads seen on or after an instant) or search (a part of the title, case-insensitive). A conversation's attribution and latest_ad_id point at these ads, and listConversations takes an ad_id to list the threads an ad brought in.

Input Schema

NameRequiredDescriptionDefault
limitNoPage size, 1 to 100 (values outside are clamped). Default 20.
cursorNoOpaque cursor from the previous page's `next_cursor`. Omit for the first page. A cursor the API didn't return is `422 invalid_request`.
searchNoA part of the ad's title, case-insensitive. It can't contain `,` `(` `)` `"` `*` `%` or `\` (`422 invalid_request_body`).
agent_idYesThe agent the resource belongs to. Another company's agent, or the nil UUID, is `404 agent_not_found`; an agent outside the key's agent list is `403 agent_not_authorized`.
active_sinceNoOnly ads seen (`last_seen_at`) on or after this instant.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • changedInput schema / properties / active_since / description
      Previous value: -"Only ads touched (`last_seen_at`) on or after this instant."New value: +"Only ads seen (`last_seen_at`) on or after this instant."
    • changedInput schema / properties / search / description
      Previous value: -"A part of the ad's title, case-insensitive. It can't contain `,` `(` `)` `\"` `*` `%` or `\\` (`422 invalid_request`)."New value: +"A part of the ad's title, case-insensitive. It can't contain `,` `(` `)` `\"` `*` `%` or `\\` (`422 invalid_request_body`)."
  2. Added

TDQS

A4.1/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds real context beyond that: result ordering ('newest first by when Mojeeb first saw each'), the exact inclusion trigger for an ad, and an explicit data-availability limitation (no spend or reach).

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 the core action, then the definition, then filters, then cross-references. It is somewhat dense and long for a list tool, but each sentence carries distinct information (definition, ordering, exclusions, filters, related tools) rather than padding.

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?

With no output schema, the description correctly compensates by enumerating what each returned ad contains (taps by channel, private replies, conversations, contacts, leads) and the ordering. Pagination and error behavior live in the schema, so the remaining gap is minor.

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 all five parameters including clamping, cursor semantics, and error codes. The description's mentions of active_since and search largely restate what the schema says, adding little parameter-level detail 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 verb and resource ('List an agent's ads') and goes further by defining what an 'ad' means in this system (a customer tap on Messenger/Instagram/WhatsApp, or an Instagram comment on ad media). This distinguishes it cleanly from get_ad and from the various list_* siblings.

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 concrete filter conditions for active_since and search, and explicitly states scope exclusions (spend and reach are not available because Ads Manager is never read), which tells the agent when not to rely on this tool. It also cross-references listConversations' ad_id, but does not explicitly say when to use list_ads versus get_ad.

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

All Mojeeb toolsInspect
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