# Agent patterns

Source: https://developers.novilabs.com/ai/patterns/

> Habits that get correct, cheap answers from Novi's MCP servers, grounded in the tools they offer.

## Start from the guide

Read the server's description of its data before the first query.

| Server | First call |
| --- | --- |
| Novi Forecasts | `describe_dataset`: basin, formations, as-of date, models and what they can do. `get_conventions` for units, BOE and P-levels |
| Novi EVA | `get_data_guide` for a topic (`querying`, `units`, `percentiles`, `production`, `forecasts`, `benchmarking`). `get_chart_guide` and `get_map_guide` before charts and maps |
| Novi M&A Intelligence | `ma_filter_values` before guessing a filter value |

## Search, then describe, then fetch

Find exact names before you filter on them. A guessed name fails or matches the wrong thing.

| Step | Novi EVA | Novi Forecasts | Novi M&A Intelligence |
| --- | --- | --- | --- |
| Search | `search_columns` for column references. `resolve_values` for exact stored values, such as `Reeves` to `Reeves, TX` | `find_wells`, `well_facets` | `ma_search_deals` from a sentence |
| Describe | `describe_columns`: units, definitions, supported operations | `model_card` | `ma_filter_values` |
| Fetch | `group_by` for counts and measures, `fetch_data` for well rows | `get_well`, `forecast_wells`, `get_plan` | `ma_filter_deals`, `ma_get_deal` |

When `resolve_values` returns several matches, ask the person.

## Let the server aggregate

Ask for the number, not the rows. Server totals cover the whole cohort; a page of rows does not.

- EVA `group_by` computes counts, sums, averages and medians over every matching well. Do not compute statistics from a truncated `fetch_data` page.
- EVA `group_by` with `benchmark: {}` ranks per-foot productivity in one call.
- M&A Intelligence `ma_summarize_deals` answers "how much" over a filter in one call, with the count of deals each figure covers.
- Forecasts `get_plan` returns a plan's totals per design, pad and zone.

## Page with cursors

EVA `fetch_data` and Forecasts lists page by cursor; M&A Intelligence pages with `limit` and `offset`. Page sizes and
cursor rules: [Pagination](https://developers.novilabs.com/platform/pagination/).

## Keep bulk data out of the model

- Forecasts `export_plan` writes a done plan to files and returns a download link. The Claude skill can then answer from the export zip.
- EVA caps a data tool result at 64 KiB and returns `LIMIT_EXCEEDED` past it. Narrow the filter or ask for fewer columns.
- EVA `get_chart` takes `include_series: false` and `include_png: false` when only the summary is needed.
- For a whole basin's rows, use [Novi UDM Data](https://developers.novilabs.com/data/delivery/) or [EVA REST](https://developers.novilabs.com/eva/api/), not an agent.

## Read-only by default

| Server | What tools can change |
| --- | --- |
| Novi EVA | Nothing. Every tool is read-only |
| Novi Forecasts | Tools read, or start a plan or an export. `save_forecast_source` saves only after asking you. No tool deletes |
| Novi M&A Intelligence | Only your own comps basket, up to 50 deals |

The Claude skill may call the Forecasts REST API directly, with reads and the documented `POST` calls, never `DELETE`.

## Check what came back

- EVA data results carry `truncated`, `warnings`, `coverage` and `freshness`. Check `truncated` and `warnings` before you rely on a result.
- An EVA `DEPENDENCY_ERROR` is a failed read, never zero production. Report it as an error.
- Do not retry an EVA `ACCESS_DENIED` with guessed columns. Tell the person what is outside their subscription.
- An unknown basin in M&A Intelligence is an error that lists the valid names, not an empty result.

## State the basis

Say which units, window and convention a number uses. In EVA, a bare year means production vintage, and hybrid units are the default. P10 means Low in Forecasts and High in EVA charts: name the case. See [Units and conventions](https://developers.novilabs.com/concepts/units-and-conventions/) and [P-levels](https://developers.novilabs.com/concepts/p-levels/).
