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

# Query mode and Execute mode

> Choose between managed Context queries and direct Meridian method execution.

## Query mode

Use Query mode when your application starts with a research question and benefits from Context selecting the correct Meridian method, validating the evidence, and assembling a response.

Pin Meridian with its tool ID when the workflow must use this provider:

```typescript theme={null}
const result = await client.query.run({
  query: "Use Meridian to compare BTC funding and dollar open interest across venues.",
  tools: [MERIDIAN_TOOL_ID],
  responseShape: "evidence_only",
  includeDataUrl: true,
});
```

Use `answer_with_evidence` when Context should also write the answer. Use `evidence_only` when your own application or agent will perform the analysis.

## Execute mode

Use Execute mode when you already know the exact Meridian method and arguments and want the structured result directly.

```typescript theme={null}
const matches = await client.discovery.search({
  query: "Meridian crypto market data",
  mode: "execute",
  surface: "execute",
  requireExecutePricing: true,
});
```

Only call `client.tools.execute()` after discovery confirms that the requested Meridian method is Execute-eligible.

## Decision table

| Requirement                               | Use                                       |
| ----------------------------------------- | ----------------------------------------- |
| Natural-language market question          | Query                                     |
| Context should select `futures` or `spot` | Query                                     |
| Your agent writes the final analysis      | Query with `evidence_only`                |
| Exact tool method and exact arguments     | Execute, when eligible                    |
| Long or broad historical query            | Query with a data URL or asynchronous job |
| Lowest orchestration ambiguity            | Execute, when eligible                    |