seed-mcp/docs_mcp/lessons.md

# crop_seed API lessons

Curated knowledge that **does not live in the scraped corpus** but
that an agent needs to interpret search_docs / get_page results
correctly. This file is the source for `crop_seed_api_lessons(topic)`.

Each section starts with a `## <slug>` heading; the tool returns
sections whose slug matches the topic (substring match) or all
sections when `topic` is None.

This file is the *only* place the MCP injects opinionated content.
Everything else returned by the server comes verbatim from a vendor
catalog. Lessons here should be: factual, well-cited, and conservative
about what the corpus actually contains.

---

## pioneer

**Pioneer (Corteva) is NOT in the seed-mcp corpus.** The MCP intentionally
does not scrape pioneer.com. Per Pioneer's published Terms of Service:

> "you shall not use any manual or automated software, devices or
> other processes (including but not limited to spiders, robots,
> scrapers, crawlers, avatars, data mining tools or the like) to
> 'scrape' or download data from the Services"

Pioneer additionally runs Imperva WAF on their catalog API and
login-walls dealer lookup, so a polite scrape isn't technically
feasible either.

**Agent behavior when a farmer asks about Pioneer / P-series hybrids:**

1. Tell the farmer plainly: "I don't have Pioneer's variety data
   indexed — Pioneer doesn't allow automated indexing of their
   catalog."
2. Recommend pioneer.com → *Find a Sales Rep* (or call 1-800-247-6803)
   for hybrid specs and local recommendations.
3. If the farmer wants an independent third-party rating for a
   specific Pioneer hybrid, mention that **university extension
   performance trials** (Iowa State, Illinois Crop Sciences, Purdue,
   Nebraska, Ohio State) publish multi-location yield data on
   Pioneer hybrids alongside competitors — useful if they want
   apples-to-apples data without going through Pioneer's own
   marketing.
4. **Do NOT invent Pioneer hybrid ratings.** If asked "what's the
   disease tolerance of P1142AM?", the only correct answer is
   "I don't have that data — please consult Pioneer or an
   extension service."

This is the canonical anti-hallucination policy for the seed-mcp.
There is no Pioneer data; there is no inference. Direct the farmer
to a primary source.

---

## rating-scales

Different vendors publish ratings on different conventions. The
chunker normalizes the *labels* in the chunk preamble but always
preserves the source's `_scale_direction` field in the sidecar.

**Bayer (DEKALB / Asgrow / WestBred)**: `1-9 (9 = best)`. A
GRAY LEAF SPOT rating of 8 means EXCELLENT tolerance. A rating of 2
means SUSCEPTIBLE.

**Syngenta Golden Harvest**: `9-to-1 (9 = best, 1 = worst)` —
this is the *direction* Golden Harvest publishes, but the *meaning*
of high numbers is the same: high = best. Where the chunker says
"normalize" for Golden Harvest, that just means we've already
re-stated it as `1-9 (9 = best)` in the chunk preamble; the source's
`_scale_direction` field still says `9-to-1` so you can detect the
provenance.

**Syngenta NK and AgriPro**: `1-9 (1 = best, lower = more
resistant)`. **REVERSED from Bayer and Golden Harvest.** NK's
tech-sheet PDFs literally print *"1-9 Scale: 1 = Best, 9 = Worst"*
in the footer; AgriPro's positioning on stripe-rust-resistant
varieties (e.g. AP Iliad with Stripe Rust 1, Eyespot 2) confirms
the same direction. On NK, this applies both to disease tolerance
AND to numeric agronomic ratings (Emergence, Standability, Shatter
Tolerance, Green Stem — all 1 = best). Cross-vendor comparisons
MUST consult the `_scale_direction` field in each side's sidecar
before drawing conclusions.

(Agronomic ratings on AgriPro are qualitative —
"Excellent / Very Good / Good / Fair" — and have no direction
issue. NK's soybean tech sheets ALSO publish soil-type adaptation
as Best/Good/Fair/Poor labels which are qualitative.)

**Beck's**: ratings live behind SeedIQ login; only identity-level
data is publicly available, so most disease/agronomic ratings are
absent from Beck's records in this corpus.

**Always check the chunk's "Rating scale" line or call
`lookup_variety(source_key)` and look at `_scale_direction` if you
are unsure.** Cross-vendor comparisons are valid AFTER you've
confirmed each side uses the same direction.

**Non-numeric values** appear for some characteristics and should be
read literally:
- `R`, `MR`, `S` for soybean disease resistance = Resistant / Moderately
  Resistant / Susceptible (not 1-9).
- `Rps1c`, `Rps3a`, `Rps1k`, etc. = specific Phytophthora resistance
  gene present.
- `R1`, `R3` (under SOYBEAN CYST NEMATODE) = effective against
  SCN race 1 / race 3.
- `A`, `B`, `C` under HERBICIDE sensitivity = grade letters where A
  is most tolerant.

---

## maturity-semantics

Maturity is encoded differently per crop. Don't conflate the units.

**Corn — Relative maturity (RM days)**: integer roughly 75-120.
Lower = shorter season, suitable for higher latitudes / shorter
growing windows. 110 RM is a Central Iowa default; 85 RM suits
northern Minnesota or short-season silage; 115+ RM fits southern
Indiana / southern Illinois / Missouri Delta. The number is
**Pioneer-style RM days**, normalized across the industry.

**Soybeans — Maturity group (MG)**: float 00 (zero-zero) to 9.0
expressed with one decimal. A "3.5 MG" soybean is for central
Iowa. Northern North Dakota / Minnesota plant 0.0–1.5 MG. Mid-South
plants 5.0+. Each tenth of an MG ≈ 7-10 days of additional season.
Sidecar field: `maturity_group` (e.g. "3.5", "0.7").

**Wheat — Class + heading**: Winter / spring decision is separate
from "class" (HRW / HRS / SRW / SWW / SWS / durum):
- HRW = Hard Red Winter — Plains states bread wheat
- HRS = Hard Red Spring — Northern Plains, North Dakota, Montana
- SRW = Soft Red Winter — Eastern Corn Belt, Ohio Valley
- SWW = Soft White Winter — Pacific Northwest
- SWS = Soft White Spring — Pacific Northwest
- Durum — North Dakota / Montana, pasta wheat
Maturity is qualitative: Early / Medium-Early / Medium / Medium-Late / Late.
**WestBred's product page JSON does not always expose the wheat class
as a structured field** — sometimes it's only in the marketing
narrative (e.g. "WB1376CLP is a Soft White Winter Clearfield® Plus
Wheat variety"). Read `positioning_statement` carefully when the
sidecar's `wheat_class` is null.

---

## trait-glossary

Common trait codes that appear in `trait_stack`:

**Corn:**
- `SSRIB` — SmartStax® RIB Complete® corn blend (above + below-ground
  insect protection + Roundup Ready + LibertyLink, with refuge-in-bag)
- `VT2PRIB` — VT Double PRO® RIB Complete® (above-ground insect
  protection + Roundup Ready, refuge-in-bag)
- `VT4PRIB` — VT4 PRO® RIB Complete® (newer above-ground protection)
- `Trecepta` — Trecepta® (Trecepta + Roundup Ready + LibertyLink, for
  earworm + western bean cutworm pressure)
- `SmartStax PRO` — SmartStax® PRO® (RNAi corn rootworm)
- `PowerCore` — PowerCore® Refuge Advanced (older above-ground stack)
- `Conventional` — no biotech traits (organic / specialty channels)

**Soybeans:**
- `XF` — XtendFlex® (Roundup Ready 2 Xtend + dicamba + glufosinate)
- `Xtend` — Roundup Ready 2 Xtend® (dicamba + glyphosate)
- `RR2Y` — Roundup Ready 2 Yield® (glyphosate only)
- `E3` — Enlist E3® (2,4-D + glyphosate + glufosinate)
- `LL/LL+GT27` — LibertyLink® / LibertyLink + GT27 (glufosinate +
  glyphosate + isoxaflutole)
- `Conkesta E3` — Bt-stack for caterpillar pressure (BR/AR markets)
- `SR` — SR® (sulfonylurea-tolerant, Asgrow-specific)

**Wheat:**
- `Clearfield` / `CLP` — Clearfield® / Clearfield® Plus (imazamox
  tolerance)
- `CoAXium` — CoAXium® (quizalofop tolerance) — note: AgriPro's
  catalog flag, NOT in the WestBred corpus.

Always render the full trait name (`trait_descriptions`) when telling
the farmer "this variety has X trait" — bare trait codes are
ambiguous in print.

---

## scn-resistance

Soybean Cyst Nematode resistance ratings are critical for fields
with SCN pressure (most of the Corn Belt). Read carefully:

- `R3` under SOYBEAN CYST NEMATODE = Resistant to race 3 (the most
  common race nationally). Most "SCN-resistant" soybeans on the
  market are R3.
- `R1, R3` = Resistant to both race 1 AND race 3. Higher value;
  useful in long-rotation SCN fields where race shifts have occurred.
- `MR3` = Moderately Resistant to race 3. Some yield loss expected
  under high SCN pressure.
- `S` = Susceptible.
- Some Bayer Asgrow XF lines (e.g. AG29XF4) use **Peking-type SCN
  resistance**, which is genetically distinct from the more common
  PI 88788 source. Peking is more durable when SCN populations
  have eroded PI 88788 effectiveness. Look for "Peking type" in the
  positioning statement.

**Recommended workflow when a farmer asks about SCN:** call
`search_docs` with the user's MG range + "SCN-resistant", then
`lookup_variety` on the top 2-3 candidates to verify the exact race
coverage and resistance source.

---

## regional-listings

The `regional_recommendations` array in each sidecar is sourced from
Bayer's "local profiles" — varieties get assigned to regional Seed
Guide bundles (e.g. *"2026 Washington, Oregon, SEED GUIDE"*) with a
named regional agronomist contact. This is the closest signal we have
to *"is this variety recommended for the farmer's geography?"* but
note:

- A variety being absent from a regional listing **does not** mean
  it's unsuitable — Bayer's local agronomists curate these lists.
- Listings are vendor-side recommendations, not third-party trial
  data.
- When the farmer mentions a region, try filtering or scanning for
  varieties whose `regional_recommendations[].product_list_name`
  mentions that region.

Other vendors handle regional placement differently. Golden Harvest
publishes a separate "plot report" system per state/year/site;
NK publishes ratings as PDF tech sheets without regional flags.

---

## sources-not-yet-indexed

If `list_versions()` doesn't show a vendor in the `vendor` facet, the
corpus does not have it yet. Direct the farmer to that vendor's
public catalog or their seed dealer.

**Already indexed**: Bayer (DEKALB / Asgrow / WestBred), Syngenta
(Golden Harvest, NK, AgriPro).

**Not yet indexed**:

- **Beck's PFR (research)** — 2,089 head-to-head trial documents
  on the public Sanity GROQ API. Different shape from variety
  records — these are studies, not hybrids. Surfacing them would
  benefit a separate tool (e.g. `search_pfr_studies`) rather than
  share a corpus with variety identity.
- **Beck's products** — ~860 products. Identity-only (SeedIQ login
  gates the ratings).

---

## trial-data

The MCP exposes TWO complementary surfaces:

* **`search_docs`** — variety IDENTITY (what a hybrid IS):
  disease ratings, trait stack, maturity, vendor positioning.
* **`search_trials`** — variety PERFORMANCE (how it ACTUALLY did):
  ranked yield at specific cooperator fields and regions.

**Indexed trial sources**:

- **Golden Harvest plot reports** (~4,600 cross-vendor head-to-head
  trials, 2024+2025). Each trial = one cooperator's field at a
  specific state/year, comparing products from multiple brands
  (NK / DEKALB / Golden Harvest / Enogen / Pioneer / Channel, etc.)
  side by side. **This is the closest thing to independent
  comparison data the corpus has** — Bayer doesn't publish its own
  trial data, but GH publishes plots where DEKALB hybrids appear
  alongside their competitors.
- **AgriPro regional trial PDFs** (14 PDFs) — multi-year
  multi-location wheat performance for Northern Plains / Pacific
  Northwest / Plains regions. Variety + per-location yields
  preserved verbatim.

**Recommended workflow when a farmer asks about performance**:

1. Call `search_trials(crop, state, year, ...)` to find trials
   from the relevant region/season.
2. Identify the top performers in the rankings.
3. Call `lookup_variety(source_key=...)` for each leading hybrid to
   verify identity (RM, traits, disease ratings) — confirm the
   variety actually fits the farmer's situation, not just that it
   won someone else's trial.
4. If the leading variety is from a brand whose trial data isn't
   directly published (e.g. DEKALB), the GH plot reports often
   show it competing — that's still the agent's best public
   third-party signal.

**Trial data NOT in the corpus** (don't fabricate):

- **DEKALB / Asgrow / Channel** per-variety yield trials —
  Bayer keeps these in rep tools, not on the public catalog. The
  GH plot reports surface DEKALB/Asgrow performance indirectly,
  but per-variety dedicated trials aren't indexed.
- **NK yield results** — the data exists at
  `syngenta-us.com/nk/yield-results` but the ASMX endpoint is
  fiddly; not yet scraped. The variety identity is in the corpus
  (`search_docs` finds it), just not the per-region trial yields.
- **Pioneer trials** — ToS bans automation, so we have neither
  variety identity nor trial data. Direct the farmer to a
  Pioneer dealer.
- **University extension trials** (Iowa State, Illinois,
  Purdue, etc.) — third-party trial data that publishes Pioneer
  + competitors. Not in the corpus today; could be added in a
  future enrichment.

**Reading a GH plot report**:

Each plot has a cooperator name (the farmer running the trial), a
state, a year, planting/harvest dates, population, row width, and a
ranked table of products. The columns vary by crop:

- **Corn / Soy**: Rank | Brand | Product | Traits | Yield BU/Ac
  | %MST | Test Weight | Gross Revenue
- **Silage**: Rank | Brand | Product | Traits | Ton/Acre
  | Milk Per Acre | Milk Per Ton | Beef Per Acre | Beef Per Ton

Rank 1 = top performer at that site/year. Note that a single plot
is one data point — for a robust recommendation, look across
multiple plots from the same region.

---

## checking-your-work

Before quoting a specific number to a farmer, **always** call
`lookup_variety(source_key=...)` to confirm. The chunk text inside a
search_docs response is a faithful render of the sidecar, but the
sidecar IS the source of truth. Quoting from the canonical sidecar
makes you robust against:

- Chunk-text formatting bugs (e.g. a rare unicode issue trimming a
  value).
- Future chunker changes (a re-index might rewrite the body).
- Cross-vendor scale-direction differences (the sidecar's
  `_scale_direction` lets you state the convention explicitly).

If `lookup_variety` returns "not found" but `search_docs` surfaced the
chunk, that's a bug — please report it. (In normal operation, every
chunk's `source_key` round-trips to a valid sidecar.)