MCP tool reference

Look up the six examiner tools, their inputs, return values, defaults, and failure conditions.

Use your client’s live tools/list response to confirm the deployed schemas. This page documents the service in mcp_server.py and the durable-job behavior in mcp_jobs.py. Structured conveyances have domain rules beyond the transport’s object schema.

Tools and cost

The hosted transport is Streamable HTTP with a static bearer key. See Connect your agent for authentication. The shared key permits access to registered cases and paid starts; it does not provide personal accounts or case-specific permissions.

Tool results and the MCP envelope

The examples below show application data, not complete MCP protocol envelopes. Check the tool result’s isError before using its content.

In the locked Python SDK, list_surveys exposes an array under structuredContent.result, and may include separate text parts for individual rows. Start, status, and result tools expose structured objects. The two arithmetic tools return JSON in text content; a client must support that form as well as structured content.

An HTTP authentication failure is a transport error. A validation failure after tool dispatch is an MCP tool error. HTTP success alone does not prove that a tool succeeded.

list_surveys

Return the registered survey names and their county/abstract context. Use the exact returned survey value when selecting a pilot case.

Inputs: none. Pass an empty object:

{}

Return data: an array of objects with these fields:

The list is configuration data, not evidence that every case has usable PDFs. The owner prepares and confirms the case packet before a paid run.

compute_mineral_ownership

Calculate current mineral fee interests from a chronological list of structured conveyances. The tool uses exact rational arithmetic and makes no model calls.

Conveyance fields

The tool does not sort records or accept a date field. Supply chronological order. Use estate shares in probate_shares, rather than pre-multiplied tract fractions.

Each reservation has fraction, type, and of:

Use the documented values. The nested object schema does not enforce every enum or spelling. In particular, an unrecognized fraction basis is not a reliable way to request a different calculation.

Request and response example

This fictional patent followed by a half-tract deed leaves Samuel Hale and Thomas Reed with equal mineral fee interests:

{
  "conveyances": [
    {"vol_pg": "10/1", "kind": "PATENT", "grantee": "Samuel Hale"},
    {
      "vol_pg": "20/1",
      "kind": "DEED",
      "grantor": "Samuel Hale",
      "grantee": "Thomas Reed",
      "fraction": "1/2",
      "fraction_of": "TRACT"
    }
  ]
}

The successful application data is:

{
  "mineral_interests": {"Samuel Hale": "1/2", "Thomas Reed": "1/2"},
  "mineral_decimals": {"Samuel Hale": 0.5, "Thomas Reed": 0.5},
  "npri_burdens": {},
  "life_estates": {},
  "mineral_fee_sum": "1",
  "flags": [],
  "verification_scope": "arithmetic integrity only; it does not prove a complete or legally verified title chain",
  "verified": true
}

Return fields

verified=true applies to the supplied list. Missing real-world records can leave that list internally consistent. It does not establish legal title.

Failure conditions

Malformed or out-of-range explicit fractions return a tool error, including deed fractions, reservation fractions, and probate shares. Only an omitted or null deed fraction means all of the grantor’s interest.

An oversized mineral reservation produces an INVALID_RESERVATION review flag. A reservation that consumes an entire explicit partial grant also requires review. Invalid interests block an unqualified deterministic result. See Accuracy and limits for the remaining interpretation limits.

mineral_buying_summary

Calculate net mineral acres (NMA) for supplied interests using independently checked subject-tract acreage.

Reuse the fictional conveyances above and add gross_acres: 100. Each half-interest yields 50 NMA. The worked arithmetic prompts include a complete buying request.

NMA values are null unless the mineral fee sums to one, the calculation has no flags, and gross acreage is positive. Nonpositive acreage creates a curative item. NPRI burdens are separate from mineral fee acreage.

closeable is not landman approval or a legal opinion. It cannot detect every omitted record or incorrect input interpretation. Malformed fractions fail as described for compute_mineral_ownership.

start_title_exam

Launch a detached examination and return its job ID immediately. This tool uses paid models. Start only after selecting a prepared case and agreeing on spend.

survey_name, county, and abstract reject controls and have a 160-character limit. Context strings do not select a different legal workflow; the documented use case is Texas oil and gas records.

Case scope

• Registered case: supply an exact survey_name. The owner has configured its PDF directory and context. An explicit valid docs_dir overrides the directory for that request.
• Ad hoc case with PDFs: supply a server-side docs_dir and county.
• Ad hoc case without PDFs: only exa and browserbase support an empty directory; supply county and a nonempty seed. Other providers require a PDF directory.

There is no upload operation. A laptop directory path does not transfer files to the server. See Documents and sourcing for provider capabilities and identity checks.

Paid request template

Replace the survey placeholder with a value returned by list_surveys. This is a request template, not a runnable fictional case:

{
  "survey_name": "<exact registered survey>",
  "provider": "fixture",
  "driver": "bfs",
  "max_docs": 50,
  "validate": false,
  "allow_browser": false,
  "allow_purchase": false
}

The response has a generated lowercase UUID:

{
  "job_id": "<generated UUID>",
  "state": "queued",
  "status_tool": "get_title_exam_status",
  "results_tool": "get_title_exam_results"
}

The default deployment admits one queued or running examination. A busy server rejects another start; it does not place the request in a waiting queue. A lost client connection does not cancel the worker.

Gates and acquisition budget

Browser sourcing requires both ALLOW_BROWSER_SOURCING on the host and allow_browser=true in the request. Purchases also require ALLOW_BROWSER_PURCHASE and allow_purchase=true. Admission and execution check these independently. Both host gates are off in the pilot.

budget tracks estimated acquisition spend using cost_per_doc. It does not cap the total bill for models, search, browser sessions, and records. The ledger can exceed its threshold by one document estimate, and a charged but refused provider delivery can be absent from it. Use separate provider spending controls.

Invalid inputs, unsupported case combinations, disabled host gates, and occupied concurrency return tool errors. See Start-request errors for messages and corrective actions.

get_title_exam_status

Inspect one saved job. This call also reconciles a queued/running record whose worker has stopped.

Use the generated lowercase UUID. The tool accepts no filesystem path.

Summary fields

reports_ready requires a sourcing manifest and LRS/LOR timestamps at least as recent as that manifest. A filename alone does not prove freshness.

There is no live phase, percentage, or actual spend field. A missing count is not evidence that the worker has stalled. Read Review examination results before relying on a completed status.

Sourcing stop reasons

The default sourcing depth is 40. A terminus can look successful while coverage_limited=true keeps completion incomplete.

Invalid IDs return job_id must be a UUID generated by start_title_exam. A valid-format ID without a record returns unknown job_id.

get_title_exam_results

Read a summary or one available bounded report for a saved job.

A summary result has job_id, state, and summary. A report result adds artifact and string content.

Non-summary reads require reports_ready=true and the requested file to exist. An incomplete job can meet this condition and expose partial reports. Preserve that label in your review.

Reads stop at 100,000 bytes and append [truncated] if more content exists. There is no pagination or full-file download tool. Ask the owner for the full private artifact when truncation matters.

Unavailable current reports return current reports are not ready; use get_title_exam_status. A missing selected file returns artifact '<name>' is not available. Read the availability map before requesting optional validation.

Interface limits

The six tools cannot upload documents, list past jobs, cancel workers, save corrections, resume existing jobs, configure providers, or rotate credentials. Source PDFs, engine logs, raw extraction checkpoints, and arbitrary paths are not exposed.

Use First examination for the start/status/results sequence and Troubleshooting for recovery without duplicate work.