*MCP › Reference › Platform › AI*

# Ask the AI about your data

> Answers in natural language a question about the data of your account, optionally also searching the web.

> **Requires human confirmation:** Put this tool on your client's “ask before running” list. The annotations are hints that the server declares, not guarantees: do not decide the approval from `destructiveHint` alone.

> **Server annotation:** It spends AI credits of the account and can search the web: a stronger vector for instruction injection than free-text fields. It is annotated as not read-only for that reason.

It NEVER writes anything: the engine runs without a single write tool loaded, and what it can read is bounded by the permission guardrail of the owner of the API key, table by table. It consumes AI credits of the account: without quota it responds 402 addon_required without ever asking the model. It can take tens of seconds on questions that chain several queries; if `needsMoreContext` comes true, the answer is empty and you should rephrase with more detail instead of retrying the same.

TOOL `filmo_ai_ask` · `ai:ask` · 120/min · May need an add-on · Server annotation: Open world · Requires human confirmation

## Arguments

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `question` | string | Yes | Natural-language question about the data of your account. Required. |
| `webSearch` | boolean | No | Also allows web search to answer. Defaults to false: only the data of the account is consulted. = `false` |
| `mode` | string | No | Answer mode. Today only "instant" (a single pass, no conversation). Documented so that future modes are additive. = `"instant"` |

## Result

On success the result carries `structuredContent` with `data` and `meta`. These are the attributes of `data`.

| Name | Type | Description |
| --- | --- | --- |
| `answer` | string | Answer in markdown. Empty string when needsMoreContext is true. |
| `needsMoreContext` | boolean | True when the AI finished without being able to answer and needs more context. In that case `answer` comes empty: rephrase the question with more detail instead of retrying as is. |
| `webSearchSources` | object[] | Cited web sources. Empty if web search was not requested or if none was used. |
| `webSearchSources.url` | string | URL of the consulted source. |
| `webSearchSources.title` | string | Source title. |
| `webSearchSources.favicon` | string | URL of the site favicon, to render the source. |

*Call · filmo_ai_ask*

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "filmo_ai_ask",
    "arguments": {
      "question": "<question>"
    }
  }
}
```

*Result (generated from the schema)*

```json
{
  "structuredContent": {
    "data": {
      "answer": "<answer>",
      "needsMoreContext": true,
      "webSearchSources": [
        {
          "url": "https://example.com",
          "title": "Example",
          "favicon": "<favicon>"
        }
      ]
    },
    "meta": {
      "rateLimit": {
        "limit": 120,
        "remaining": 119,
        "reset": 42
      }
    }
  }
}
```

## Sample prompts

*Prompt*

```text
Ask the account: which customers rented the most last quarter?
```

## The same operation by REST

This tool runs [`POST /api/v1/ai/ask`](https://docs.filmo.io/rest-api/endpoint-reference/ai/ask-the-ai-about-your-data).

---

Canonical URL: https://docs.filmo.io/mcp/tools/ai/filmo-ai-ask  
Last updated: 2026-10-25