support Contact support
    • Maestro
    • Developers
    • Use the APIs

    Manage reports using MCP server

    Table of Contents

    Overview Maestro MCP connection Available tools Reporting Agent Report request processing Prompt best practices Prompt examples

    Overview

    With Equativ's MCP server implementation, you can use natural language prompts to generate reports. You can use the Ask AI Maestro Agent, directly in the Maestro user interface, or a third-party MCP host, such as Claude.

    Maestro MCP connection

    To connect your MCP host to Equativ's MCP server, refer to Manage your deals and campaigns using MCP server for technical documentation. 

    Available tools

    Tool Usage
    run-report Invokes the Reporting Agent, which combines the other tools in this table, based on a natural language prompt. See section “Reporting Agent”, later in this document.
    get-dimensions Gets the criteria, including definitions, to break down the reporting data, for example: by deal, by day, or by country.
    get-metrics Gets the available performance indicators, for example impressions, spend, or eCPM.
    get-filter-suggestions Finds the ID of a deal, advertiser, or publisher, based on their names.
    run-instant-report Generates a report for the selected period.
    run-compare-report Compares performance between two periods.

    Reporting Agent

    The Reporting Agent (run-report tool) combines all other tools mentioned in section “Available tools”. It doesn't require the exact names of dimensions, metrics, or filter IDs, as it is able to resolve them automatically from a natural language prompt.

    If a request fails—for example, due to incompatible fields or invalid filters—the agent interprets the error, adjusts its parameters, and automatically retries without requiring further intervention.

    When using the Ask AI Maestro Agent in the Maestro user interface, the Reporting Agent is enabled by default. In third-party environments, such as Claude Desktop or Claude Code, you must explicitly invoke it using the run-report tool, as it is not enabled by default.

    Report request processing

    When a reporting request is received, the Reporting Agent follows a 5-step workflow:

    1. Use case: Selects the use case (currently, RTB use case only).
    2. Field discovery: Calls the tools to list accessible dimensions and metrics for your account.
    3. Field selection: Selects relevant fields while respecting compatibility rules between dimensions and metrics (incompatible fields are excluded automatically).
    4. Filter resolution: Calls get-filter-suggestions to convert the names mentioned in the prompt, such as deal, advertiser, or publisher, into the concrete IDs required by the API.
    5. Report execution: Calls run-report, with results returned immediately.

    Prompt best practices

    For a successful report on the first try, specify the following:

    • Period: For example: "last week", "since January 1st", or "last 30 days" (max. 90-day rolling). Preferably, use absolute dates.
    • Metric(s): For example: “impressions”, “spend”, “eCPM”, or “fill rate”.
    • Dimension(s): Optional. For example: “deal”, “day”, “country”, or “publisher”.
    • Filter: Optional. A specific deal, advertiser, or publisher by name. If known, use IDs.
    • Comparisons: Both periods to be compared. For example: “this week vs. last week”.

    ✅ Precise prompt: "Show me impressions and spend for the last 7 days, by deal, for Acme deals."

    ❌ Vague prompt: "Give me some figures on my deals." With this prompt, the agent has to guess the period, metrics, and level of detail.

     

    Avoid requesting more than 90 days of history, or stepping outside the RTB use case.

     

    Prompt examples

    • Show me impressions and spend from last week, by deal name, for Acme family deals.
    • What are the top 10 revenue-generating campaigns over the past 30 days?

     

     

     

    RELATED ARTICLES