Skip to content
Developers
Get an API token

Agent patterns

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

View MarkdownOpen in Claude(opens in a new tab)

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

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.

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.

EVA fetch_data and Forecasts lists page by cursor; M&A Intelligence pages with limit and offset. Page sizes and cursor rules: Pagination.

  • 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 or EVA REST, not an agent.
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.

  • 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.

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.