Skip to main content
Bhumi exposes 14 read-only MCP tools for querying farm data. All tools are available to paid-tier API key holders. Free-tier keys have access to search_farms, get_farm, list_products, and get_stats.
All tools are invoked automatically by your AI assistant in response to natural language prompts. You do not call them directly — the AI resolves your request to the appropriate tool and parameters.

​
Tool index

Search for farms by geographic location, text query, product types, categories, certifications, or state. Returns farm profiles sorted by distance (when coordinates are provided) or relevance.Parameters
​
lat
number
Latitude of the search center. Provide with lng to enable distance-based sorting and radius filtering.
​
lng
number
Longitude of the search center.
​
radius_miles
number
default:"25"
Search radius in miles. Accepted range: 1–100.
​
query
string
Text search that matches against farm name, city, and state.
​
products
string[]
Filter by product types, e.g. ["eggs", "raw milk"].
​
categories
string[]
Filter by product categories, e.g. ["dairy", "produce"].
​
certifications
string[]
Filter by certifications, e.g. ["organic", "usda"].
​
state
string
Filter by US state abbreviation, e.g. "WY" or "OR". Used for non-geographic searches.
​
page
number
default:"1"
Page number for pagination.
​
per_page
number
default:"20"
Results per page. Accepted range: 1–50.
Example
User: "Search for organic dairy farms within 30 miles of Portland, Oregon"

→ search_farms({
    lat: 45.52,
    lng: -122.68,
    radius_miles: 30,
    products: ["raw milk", "cheese"],
    certifications: ["organic"]
  })
ReturnsArray of farm objects including name, city, state, distance_mi, products, categories, certifications, quality_tier, and delivery_enabled. Includes pagination metadata: count, page, per_page, has_more.
Fetch a complete farm profile by UUID. Returns all available farm data including products with pricing, story, certifications, practices, contact info, operating hours, images, and quality scores.Parameters
​
farm_id
string
required
Farm UUID.
Example
User: "Tell me about Triple 7 Farm"

→ get_farm({ farm_id: "abc-123-..." })
ReturnsComplete farm object with fields including id, name, city, state, address, lat, lng, phone, website, email, description, story, farmer_name, categories, products, certifications, practices, delivery_options, google_rating, quality_tier, hours_json, and a nested product_listings array with id, name, price, unit, category, and in_stock.
List all product types available on the platform, each with a count of how many farms carry it. Useful for exploring what’s available in a region before doing a more targeted search.Parameters
​
state
string
Filter by US state abbreviation to see products available only in that state.
Example
User: "What products are available from farms in Wyoming?"

→ list_products({ state: "WY" })
ReturnsArray of objects sorted by popularity: { name: string, farm_count: number }. Example: { name: "pastured eggs", farm_count: 342 }.
Search for a specific food item near a location. Instead of searching for farms and then checking what they carry, this tool starts with the product and returns farms that have it — along with matching product listings, prices, and stock status.Uses fuzzy name matching, so "eggs" will match "pastured eggs", "farm eggs", etc.Parameters
​
product
string
required
Product name to search for, e.g. "raw milk", "eggs", "honey".
​
lat
number
Latitude of the search center.
​
lng
number
Longitude of the search center.
​
radius_miles
number
default:"25"
Search radius in miles. Accepted range: 1–100.
​
state
string
Filter by US state abbreviation. Used when coordinates are not provided.
​
certifications
string[]
Filter results to farms with specific certifications, e.g. ["organic"].
​
in_stock_only
boolean
default:"false"
When true, only returns farms that have at least one in-stock listing for the product.
​
page
number
default:"1"
Page number for pagination.
​
per_page
number
default:"20"
Results per page. Accepted range: 1–50.
Example
User: "Where can I get raw milk near Portland?"

→ find_food({
    product: "raw milk",
    lat: 45.52,
    lng: -122.68,
    radius_miles: 30,
    in_stock_only: true
  })
ReturnsObject with product_searched, count, page, per_page, has_more, and a farms array. Each farm includes distance_mi and a matching_products array with id, name, price, unit, and in_stock.
Fetch all product listings for a farm with full pricing, stock status, descriptions, and category groupings. Includes a summary with total counts, in-stock vs out-of-stock breakdown, and price range.Parameters
​
farm_id
string
required
Farm UUID.
​
category
string
Filter results to a specific category, e.g. "dairy" or "meat".
​
in_stock_only
boolean
default:"false"
When true, only returns products that are currently in stock.
Example
User: "What does Triple 7 Farm sell?"

→ get_farm_products({ farm_id: "abc-123-..." })
ReturnsObject with:
  • farm — basic farm info
  • summary — { total, in_stock, categories, price_range }
  • products — flat array of all product listings
  • products_by_category — same products grouped by category name
Check whether a specific product is currently available at a specific farm. Returns a clear availability status, matching product listings with pricing, and the farm’s operating hours — so you know both whether the product exists and when you can actually get it.Parameters
​
farm_id
string
required
Farm UUID.
​
product_name
string
required
Product name to check, e.g. "eggs" or "raw milk".
Example
User: "Does Meadowstone Farm have eggs?"

→ check_availability({
    farm_id: "abc-123-...",
    product_name: "eggs"
  })
ReturnsObject with:
  • status — one of available, out_of_stock, listed_no_pricing, or not_found
  • message — human-readable explanation of the status
  • matching_listings — array of product listings with name, price, unit, and in_stock
  • operating_hours — the farm’s hours so you know when to visit
Aggregate all products, categories, certifications, and place types from farms within a radius. Useful for answering broad discovery questions like “what local food can I find near me?” without specifying a product first.Parameters
​
lat
number
required
Latitude of the search center.
​
lng
number
required
Longitude of the search center.
​
radius_miles
number
default:"25"
Search radius in miles. Accepted range: 1–100.
​
limit
number
default:"500"
Maximum number of farms to scan. Accepted range: 1–500.
​
include_practices
boolean
default:"false"
When true, includes a practices array with farming practice names, counts, and percentages of nearby farms using each practice.
​
with_pricing
boolean
default:"false"
When true, adds a with_pricing count to each product indicating how many nearby farms have structured pricing for it.
Example
User: "What local food can I find near me?"

→ nearby_categories({
    lat: 40.71,
    lng: -74.01,
    radius_miles: 25
  })
ReturnsObject with:
  • total_farms — number of farms scanned
  • place_types — breakdown by place type (farm, market, etc.)
  • categories — array of { name, count, closest_mi } sorted by count
  • products — array of { name, count, closest_mi } (includes with_pricing count when requested)
  • certifications — array of { name, count } (includes pct when include_practices is true)
  • practices — array of { name, count, pct } (only when include_practices is true)
Compare pricing for a specific product across all farms within a radius. Returns aggregate statistics (average, min, max, median) and a per-farm breakdown sorted by distance. Uses fuzzy product name matching.Parameters
​
product
string
required
Product name to compare prices for, e.g. "eggs", "raw milk", "honey".
​
lat
number
required
Latitude of the search center.
​
lng
number
required
Longitude of the search center.
​
radius_miles
number
default:"25"
Search radius in miles. Accepted range: 1–100.
Example
User: "How much do eggs cost near me?"

→ compare_product_prices({
    product: "eggs",
    lat: 44.7,
    lng: -89.4,
    radius_miles: 25
  })
ReturnsObject with:
  • product — the searched product name
  • radius_miles — the radius used
  • farm_count — number of farms with priced listings
  • avg_price, min_price, max_price, median_price — aggregate statistics
  • prices — array of { price, unit, farm_name, distance_miles } sorted by distance
Get delivery and pickup availability statistics for all farms within a radius. Shows how many nearby farms offer delivery or on-farm pickup, and what percentage of farms in the area provide each option.Parameters
​
lat
number
required
Latitude of the search center.
​
lng
number
required
Longitude of the search center.
​
radius_miles
number
default:"25"
Search radius in miles.
Example
User: "Do farms near Portland offer delivery?"

→ get_area_delivery({ lat: 45.52, lng: -122.68, radius_miles: 25 })
ReturnsObject with:
  • total_farms — total farms in the area
  • delivery_enabled — count and percentage of farms offering delivery
  • offers_pickup — count and percentage of farms offering on-farm pickup
Analyze what sets a specific farm apart from nearby farms. Compares the farm’s products, practices, and certifications against all farms within the radius and identifies what it has that others don’t — including unique products, rare products, unique certifications, and delivery advantages.Parameters
​
farm_id
string
required
Farm UUID to analyze.
​
radius_miles
number
default:"25"
Comparison radius in miles. Accepted range: 1–100.
Example
User: "What makes Triple 7 Farm special?"

→ find_farm_differentiators({ farm_id: "abc-123-..." })
ReturnsObject with:
  • farm_name — name of the farm
  • radius_miles and nearby_farm_count
  • unique_products — products no other nearby farm carries
  • rare_products — products fewer than 3 other farms carry, each with other_farms count
  • unique_practices — farming practices not found at nearby farms
  • unique_certifications — certifications not held by nearby farms
  • has_delivery, area_delivery_pct — delivery advantage context
  • google_rating, area_avg_rating — rating comparison
Find farms near a specific farm that sell overlapping products. Returns competitors sorted by distance, product overlap, or rating. Useful for competitive analysis or for consumers who want alternatives.Parameters
​
farm_id
string
required
Farm UUID to find competitors for.
​
radius_miles
number
default:"25"
Search radius in miles. Accepted range: 1–100.
​
sort_by
string
default:"distance"
Sort order for results. One of "distance", "overlap" (by product overlap count), or "rating".
​
place_type
string
default:"farm"
Filter by place type. Use "farm" to include only farms, or "all" to include markets and stores.
Example
User: "Who are my competitors?"

→ get_nearby_competitors({ farm_id: "abc-123-...", sort_by: "overlap" })
ReturnsObject with:
  • farm_name — the reference farm’s name
  • your_products — the reference farm’s product list
  • competitors — array of competitor objects, each with farm_id, farm_name, distance_miles, overlapping_products, overlap_count, practices, certifications, google_rating, and has_delivery
Get raw market landscape data for a geographic area: total farm counts, quality score distribution (avg, median, min, max, tier breakdown), product/certification/practice/delivery breakdowns with counts and percentages, distance distribution, and pricing coverage. Optionally filter to a single product.Parameters
​
lat
number
required
Latitude of the search center.
​
lng
number
required
Longitude of the search center.
​
radius_miles
number
default:"25"
Search radius in miles. Accepted range: 1–100.
​
product
string
Optional product filter. When set, returns landscape data only for farms carrying that product.
Example
User: "What does the farm market look like near Portland?"

→ get_market_landscape({
    lat: 45.52,
    lng: -122.68,
    radius_miles: 25
  })
ReturnsObject with:
  • total_farms — farms in the area
  • quality — { avg_score, median_score, min_score, max_score, tiers: { premium, standard, basic, incomplete } }
  • distance_distribution — { within_5mi, within_10mi, within_25mi, beyond_25mi }
  • place_types — breakdown by type (farm, market, CSA, etc.)
  • products — top 30 products with { name, count, pct }
  • certifications — all certifications with { name, count, pct }
  • practices — top 20 practices with { name, count, pct }
  • delivery_options — delivery methods with { name, count, pct }
  • verification — verification status counts
  • pricing — { farms_with_structured_prices, pct_with_prices }
Get a farm’s structured operating hours, current open or closed status, next open time, and scheduled pickup windows. Hours are parsed from the farm’s raw data into a structured day-by-day format.Parameters
​
farm_id
string
required
Farm UUID.
​
timezone
string
default:"America/Chicago"
IANA timezone string for the farm, e.g. "America/Los_Angeles" or "America/New_York". Used to determine the current day and time for open/closed status.
Example
User: "Is Meadowstone Farm open today?"

→ get_farm_hours({ farm_id: "abc-123-..." })
ReturnsObject with:
  • farm — basic farm info (id, name, city, state, place_type, phone, website)
  • operating_hours — day-by-day hours object, e.g. { monday: "9:00 AM-5:00 PM", tuesday: "Closed", ... }
  • today — { day, hours, is_open_now }
  • next_open — { day, hours } for the next time the farm opens, e.g. { day: "tomorrow", hours: "9:00 AM-5:00 PM" }
  • pickup_windows — array of scheduled pickup slots with day, start_time, end_time, and max_orders
  • message — human-readable summary, e.g. “Meadowstone Farm is closed right now. Next open: tomorrow (9:00 AM-5:00 PM).”
Retrieve live statistics for the entire Bhumi platform. Useful for understanding the scope and geographic coverage of Bhumi’s farm data. Returns the same data as the REST GET /v1/stats endpoint.ParametersThis tool takes no parameters.Example
User: "How many farms does Bhumi have?"

→ get_stats()
ReturnsObject with:
  • total_farms — total number of farms in the database
  • states_covered — number of US states with at least one farm
  • delivery_enabled_farms — farms that offer delivery
  • place_types — breakdown by place type (farm, market, CSA, etc.)
  • top_products — top 10 products by farm count

​
Example conversations

User:      "I'm in Portland, OR. Find me farms that sell pastured eggs within 20 miles."

Assistant: I found 8 farms selling pastured eggs near Portland:

           1. Gales Meadow Farm — 4.2 mi, pastured eggs, organic vegetables
           2. Sauvie Island Farms — 7.8 mi, pastured eggs, berries, honey
           3. Helvetia Creamery — 12.1 mi, pastured eggs, raw milk, cheese
           ...

User:      "Tell me more about Gales Meadow Farm"

Assistant: Gales Meadow Farm — Forest Grove, OR

           Products: pastured eggs ($8/doz), organic vegetables, cut flowers
           Certifications: Oregon Tilth Organic
           Quality: Exceptional (92/100)
           Hours: Sat 9am–1pm (farm stand)
           (503) 555-0142 · galesmeadow.com