> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qwairy.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Filter Compatibility

> Canonical filter contract and tool-by-tool compatibility for all Qwairy MCP tools.

This page documents filter behavior across the customer MCP. Live tool discovery (`tools/list`) remains authoritative for the current tool inventory and input schemas.

## Global evidence filters

The following parameters are available on every tool listed in the **Global evidence tools** section below.

| Parameter           | Type              | Description                                                                  |
| ------------------- | ----------------- | ---------------------------------------------------------------------------- |
| `period`            | integer or string | Rolling days (1-3650), `"all"`, or `"custom"` with `startDate` and `endDate` |
| `startDate`         | string            | Inclusive UTC start date in `YYYY-MM-DD` format                              |
| `endDate`           | string            | Inclusive UTC end date in `YYYY-MM-DD` format                                |
| `providers`         | string\[]         | AI provider or model IDs; values are ORed                                    |
| `provider`          | string            | Legacy single-provider alias                                                 |
| `topicIds`          | string\[]         | Topic UUIDs returned by `list_topics`; values are ORed                       |
| `topic` / `topicId` | string            | Legacy single-topic aliases                                                  |
| `tagIds`            | string\[]         | Tag UUIDs returned by `list_tags`; values are ORed                           |
| `tag` / `tagId`     | string            | Legacy single-tag aliases                                                    |
| `funnelStages`      | string\[]         | Any of `TOFU`, `MOFU`, and `BOFU`; values are ORed                           |

Values inside one array are ORed. Different dimensions are ANDed. For example, two providers plus one topic and one tag means “either provider, inside this topic, and carrying this tag.”

Custom dates must be provided as a complete pair. Both endpoints are inclusive UTC calendar days. Invalid dates, UUIDs, provider values, funnel stages, incomplete ranges, and unsupported periods return `INVALID_PARAMETER`.

Most evidence tools default to 30 days. `get_competitors` intentionally preserves its established all-time result when no window is supplied. Pass `period: 30` when you want the same explicit 30-day scope used by most dashboard views.

When a tool returns `appliedFilters`, that object echoes the resolved period, dates, providers, topics, tags, and funnel stages used for the result.

## Global evidence tools

The following tools support the complete global evidence contract above:

* `get_brand_performance`
* `get_competitors`
* `get_competitor_evolution`
* `get_prompts`
* `get_prompt_answers`
* `get_answers`
* `get_source_domains`
* `get_source_urls`
* `get_source_trends`
* `get_topics`
* `get_visibility_trend`
* `get_sentiment_trend`
* `get_provider_breakdown`
* `get_keyword_triggers`
* `get_content_opportunities`
* `get_competitor_comparison`
* `get_prompt_signals`
* `get_overview`
* `get_shopping_insights`
* `get_social_insights`
* `get_local_insights`
* `get_query_fan_out`
* `get_page_presence`
* `get_source_profile`
* `get_competitor_position`
* `get_matrix`
* `get_sponsored_content`
* `get_backlink_opportunities`

Tool-specific selectors such as `relationship`, `competitorId`, `domain`, `type`, `isSelf`, `status`, `promptId`, `granularity`, `groupBy`, `limit`, and `offset` can be combined with the global filters when advertised by that tool.

## Action Center filters

`get_actions` uses the dashboard Action Center vocabulary:

| Parameter                                | Type      | Description                                          |
| ---------------------------------------- | --------- | ---------------------------------------------------- |
| `period`                                 | string    | `"1"`, `"7"`, `"14"`, `"30"`, `"all"`, or `"custom"` |
| `periodStart` / `periodEnd`              | string    | Inclusive custom range used with `period: "custom"`  |
| `providers`                              | string\[] | Evidence provider IDs                                |
| `topicIds`                               | string\[] | Topic UUIDs                                          |
| `tagIds`                                 | string\[] | Tag UUIDs                                            |
| `funnelStages`                           | string\[] | `TOFU`, `MOFU`, or `BOFU`                            |
| `actionId`, `status`, `type`, `category` | string    | Action-specific selectors                            |
| `limit`                                  | integer   | Max actions to return (default: 25, max: 100)        |

## Measure date filters

The following tools support `period`, inclusive `startDate`/`endDate`, and legacy `days`:

* `get_ai_revenue`
* `get_search_console_metrics`
* `get_bing_metrics`
* `get_referrer_analytics`

Use either `days` or `period`, not both. Numeric `period` accepts 1-3650; legacy `days` accepts 1-365. For the four connected-provider tools above, `"all"` maps to a 16-month lookback. Rolling and `"all"` windows end on the previous UTC day; custom dates use the exact inclusive range supplied.

`get_page_performance` uses the same date vocabulary but page-level crawler evidence retains at most 30 analytic days. Numeric periods and custom ranges longer than 30 days return `INVALID_PARAMETER`; `period: "all"` means all retained page history.

## Tool-specific filters and selectors

The following tools do not consume the global answer-evidence filters:

| Tool                     | Supported filters or selectors                                        |
| ------------------------ | --------------------------------------------------------------------- |
| `list_brands`            | None                                                                  |
| `list_pitch_audits`      | `teamId`, `status`, `limit`, `offset`                                 |
| `get_pitch_audit`        | `auditId`, `subjectId`, `includeAnswers`, `includeCoCompetitorScores` |
| `list_topics`            | `search`, `limit`, `offset`                                           |
| `list_tags`              | `search`, `limit`, `offset`                                           |
| `get_answer_details`     | `brandId`, `answerId`                                                 |
| `get_brand_perception`   | Latest completed snapshot for `brandId`                               |
| `get_technical_status`   | Current technical state for `brandId`                                 |
| `get_perception_history` | `limit`                                                               |
| `get_crawler_activity`   | Current retained crawler lifecycle for `brandId`                      |
| `get_site_diagnostics`   | `limit`                                                               |
| `search_documentation`   | Public documentation `query`                                          |

Snapshot and detail tools intentionally do not accept evidence filters: they return one selected record or the latest/current state rather than an aggregate over answer evidence.

## Examples

```json theme={null}
{
  "brandId": "brand-uuid",
  "period": 30,
  "providers": ["openai", "anthropic"],
  "topicIds": ["topic-uuid"],
  "tagIds": ["tag-uuid"],
  "funnelStages": ["BOFU"]
}
```

```json theme={null}
{
  "brandId": "brand-uuid",
  "startDate": "2026-08-01",
  "endDate": "2026-08-22",
  "tag": "tag-uuid"
}
```