Agent patterns
Habits that get correct, cheap answers from Novi's MCP servers, grounded in the tools they offer.
Start from the guide
Section titled “Start from the guide”Read the server’s description of its data before the first query.
| Server | First call |
|---|---|
| Novi Forecasts | describe_: basin, formations, as-of date, models and what they can do. get_ for units, BOE and P-levels |
| Novi EVA | get_ for a topic (querying, units, percentiles, production, forecasts, benchmarking). get_ and get_ before charts and maps |
| Novi M&A Intelligence | ma_ before guessing a filter value |
Search, then describe, then fetch
Section titled “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_ for column references. resolve_ for exact stored values, such as Reeves to Reeves, |
find_, well_ |
ma_ from a sentence |
| Describe | describe_: units, definitions, supported operations |
model_ |
ma_ |
| Fetch | group_ for counts and measures, fetch_ for well rows |
get_, forecast_, get_ |
ma_, ma_ |
When resolve_values returns several matches, ask the person.
Let the server aggregate
Section titled “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_bycomputes counts, sums, averages and medians over every matching well. Do not compute statistics from a truncatedfetch_datapage. - EVA
group_bywithbenchmark: {}ranks per-foot productivity in one call. - M&A Intelligence
ma_summarize_dealsanswers “how much” over a filter in one call, with the count of deals each figure covers. - Forecasts
get_planreturns a plan’s totals per design, pad and zone.
Page with cursors
Section titled “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.
Keep bulk data out of the model
Section titled “Keep bulk data out of the model”- Forecasts
export_planwrites 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_EXCEEDEDpast it. Narrow the filter or ask for fewer columns. - EVA
get_charttakesinclude_series: falseandinclude_png: falsewhen only the summary is needed. - For a whole basin’s rows, use Novi UDM Data or EVA REST, not an agent.
Read-only by default
Section titled “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_ 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
Section titled “Check what came back”- EVA data results carry
truncated,warnings,coverageandfreshness. Checktruncatedandwarningsbefore you rely on a result. - An EVA
DEPENDENCY_ERRORis a failed read, never zero production. Report it as an error. - Do not retry an EVA
ACCESS_DENIEDwith 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
Section titled “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 and P-levels.