MCP Tools — Documentation

list_available_data

Discover valid crop codes, region codes, and the (crop, region) pairs that actually have price data.

list_available_data() -> object

Call this FIRST. It returns the full vocabulary the other tools accept: every crop code, every region code, and — crucially — the exact (crop, region) pairs that have price history. Only pairs listed under `available_price_pairs` can be used with get_commodity_price or forecast_crop_price. Never guess codes that are not listed here.

Parameters

No parameters.

Returns

An object with `crops` (code, name, category), `regions` (code, name, country), and `available_price_pairs` (crop_code, region_code, months, start_date, end_date).

Example — arguments

{}

Example — response

{
  "crops": [
    {
      "code": "MAIZE",
      "name": "Maize",
      "category": "Cereals"
    },
    {
      "code": "WHEAT-W",
      "name": "Winter Wheat",
      "category": "Cereals"
    }
  ],
  "regions": [
    {
      "code": "US-CORN",
      "name": "US Corn Belt",
      "country": "United States"
    },
    {
      "code": "BR-SOY",
      "name": "Mato Grosso",
      "country": "Brazil"
    }
  ],
  "available_price_pairs": [
    {
      "crop_code": "MAIZE",
      "region_code": "US-CORN",
      "months": 139,
      "start_date": "2015-01-01",
      "end_date": "2026-07-01"
    }
  ]
}

search_crop_knowledge

Semantic (RAG) search over the agronomic knowledge base.

search_crop_knowledge(query: string, crop_code?: string | null) -> object

Embeds the query with the Azure OpenAI embedding model and runs a pgvector cosine-similarity search over the agronomic_knowledge table. Returns the most relevant articles about crop management, pest control, disease management, soil health and best practices, ranked by similarity. Pass an optional crop_code to restrict results to a single crop.

Parameters

Returns

An object with `query`, `crop_code`, `count`, and `results` — each result has id, title, content, category, source and a similarity score (0–1).

Example — arguments

{
  "query": "how to manage rust disease in wheat",
  "crop_code": "WHEAT-W"
}

Example — response

{
  "query": "how to manage rust disease in wheat",
  "crop_code": "WHEAT-W",
  "count": 1,
  "results": [
    {
      "id": 41,
      "title": "Winter Wheat Disease Control Best Practices",
      "content": "Preventive fungicide programs and resistant varieties ...",
      "category": "disease_control",
      "source": "Agronomy",
      "similarity": 0.89
    }
  ]
}

get_commodity_price

Latest 12 months of historical prices (USD/tonne) for a crop in a region.

get_commodity_price(crop_code: string, region_code: string) -> object

Returns the most recent 12 months of price history for a (crop, region) pair. Only works for pairs listed by list_available_data. If the pair has no data, the response carries an `error` message instead of failing.

Parameters

Returns

An object with `prices` (id, crop_id, region_id, price_date, price_usd_tonne, volume_traded, source), `total`, `crop`, `region`. On an unknown pair, `error` and `status_code` are returned instead.

Example — arguments

{
  "crop_code": "MAIZE",
  "region_code": "US-CORN"
}

Example — response

{
  "prices": [
    {
      "id": 148213,
      "crop_id": 3,
      "region_id": 1,
      "price_date": "2026-07-01",
      "price_usd_tonne": 214.86,
      "volume_traded": 198450,
      "source": "SYNTHETIC-DEMO"
    }
  ],
  "total": 1,
  "crop": "Maize",
  "region": "US Corn Belt"
}

forecast_crop_price

ML price forecast (USD/tonne) with a confidence interval, via Azure ML.

forecast_crop_price(crop_code: string, region_code: string, target_date: string) -> object

Builds model features from recent price history + macro indicators and calls the Azure ML managed online endpoint (Gradient Boosting model). Requires existing price history for the pair (see list_available_data). Returns a predicted price with confidence bounds, or a clear error — never a fabricated value.

Parameters

Returns

An object with crop_id, region_id, target_date, predicted_price, confidence_low, confidence_high, model_version, prediction_date. On bad input or a pair with no history, an `error` is returned instead.

Example — arguments

{
  "crop_code": "MAIZE",
  "region_code": "US-CORN",
  "target_date": "2026-12-01"
}

Example — response

{
  "id": 752,
  "crop_id": 3,
  "region_id": 1,
  "target_date": "2026-12-01",
  "predicted_price": 221.47,
  "confidence_low": 203.75,
  "confidence_high": 239.19,
  "model_version": "crop-price-gbr",
  "prediction_date": "2026-07-27T10:15:00Z"
}

get_agronomic_advice

Evidence-based advice for a specific crop issue, via semantic search.

get_agronomic_advice(crop_code: string, issue: string) -> object

Searches the knowledge base for guidance on a specific issue for a crop. First tries crop-specific articles; if none are found it falls back to general best-practice guidance (scope='general') rather than returning nothing. Never fabricates recommendations.

Parameters

Returns

An object with crop_code, issue, scope ('crop_specific' or 'general'), an optional note, and `recommendations` (knowledge-base articles).

Example — arguments

{
  "crop_code": "MAIZE",
  "issue": "nitrogen_deficiency"
}

Example — response

{
  "crop_code": "MAIZE",
  "issue": "nitrogen_deficiency",
  "scope": "crop_specific",
  "note": null,
  "recommendations": [
    {
      "id": 12,
      "title": "Maize Fertilization Best Practices",
      "content": "Split nitrogen applications matched to maize growth stages ...",
      "category": "fertilization",
      "source": "Agronomy",
      "similarity": 0.86
    }
  ]
}