GovIntelligence

Resolve a free-text mention to canonical entities — products, organizations/parties, manufacturers, NUTS regions, market domains, market segments. Call this FIRST when the user names something (a vendor, a product, a place, a market sector); then pass the returned ids/names as structured filters into `market_overview` / `lot_search` / `org_details` / `lot_details`. Mapping: result.type "product" → pass `value` in `products: [...]`; "organization" → pass `id` in `party: [{id}]` (buyer-side); "manufacturer" → pass `id` in `manufacturers: [{id}]` (vendor-side, carries `product_count`); "nuts" → pass `id` (the code) in `nuts: {id}`; "domain"/"segment" → pass `id` in `domain` / `segment`. A party that plays both roles surfaces twice (once as `organization`, once as `manufacturer`) with the same `id`; pick by intent. A `product` row with `has_manufacturer_party: false` is community-maintained OSS — pass via `products: [...]` only and do not expect a manufacturer filter to resolve it. Manufacturer and organization searches are gated to query length ≥ 3 (products and domains run at length ≥ 2); a 2-char query like "MS" returns only products + domains by design. For full enumeration of domains/segments (no keyword to fuzz), use `taxonomy_browse`. Skip this tool when the user already gave you an exact id or code.

entity_search

List YOUR visible organization folders — named groups of organizations (i2_party) you own, plus folders shared with your team. Each row carries `id`, `name`, `org_count`, `visibility` ("private" | "shared") and `is_own`. This is the discovery counterpart to the caller-scoped `folder` facet on `lot_search`: pass a returned `id` (or exact `name`) as `folder: {id|name}` to filter lots to that folder's member organizations. Folders are USER/TEAM-scoped — unlike every other entity in this API, the same folder name may resolve to a different folder (or to nothing) for a different caller, so always resolve names via YOUR own `folder_list` rather than assuming a shared vocabulary. Optional `nameContains` filters the list by a case-insensitive name substring. persistent_url opens the /saved/folders page.

folder_list

Full lot detail aligned with /procurement/[notice_id]/[lot_id]: lot/notice metadata, CPV, organizations, results, products, related news. Use the `notice_id` and `lot_id` returned by `lot_search` items. `lifecycle_phase` and `is_awarded` are promoted to the top level of `data` (they are also on the `lot` object) — quote the phase rather than deriving lot status from notice types. `data.lot` is a declared field projection, not a database row dump: every field it can carry is in this tool's `outputSchema`, and a date field appears ONLY when the lot has that date — a missing `award_date` or `planned_period_start` means "not published", so do not read its absence as an error or retry for it. The same rule applies to `results[]` and `notice_documents[]`. All date fields are ISO 8601 datetimes in UTC. `lot.aggregated_payload` carries the four curated keys kept from the source notice JSON (`award_criteria`, `document_links`, `access_tool`, `framework_agreement`); the notices themselves are listed in `notice_documents[]` for identification only — their bodies are already parsed into the rest of the response, so there is nothing further to extract from them.

lot_details

Given a lot, return the buyer's historical preferred-vendor concentration: which vendors the buyer has repeatedly awarded similar contracts to, at four taxonomy levels (domain, segment, manufacturer, product). Powered by the same query that backs /api/procurement/[notice_id]/[lot_id]/incumbents. Highest-signal capture-mode answer ("I am bidding on this — who is the incumbent I need to beat?"). Insights are filtered by minimum group size (≥5 lots) and dominant share (≥60%) before bottom-up generalization (e.g. if all products under SAP are awarded to the same vendor, the manufacturer-level row absorbs the product-level rows). Empty `insights` array means the buyer has no concentrated patterns above those thresholds — a real signal in itself ("competitive market"). Use the returned `vendor_party_id` directly with `org_details` to learn more about the incumbent.

lot_incumbents

Given a lot, return other lots related to it via similarity matching — overlapping CPV + similar name, same segment + overlapping CPV (or same segment alone when the lot has no CPV codes), overlapping canonical products, or overlapping manufacturers. Powered by the same query that backs the website /procurement/[notice_id]/[lot_id]/flow page. This is a similarity traversal, NOT a filter — it cannot be expressed via lot_search. The natural follow-up after `lot_details` for "what else is this buyer doing similar to this contract?" Each related lot carries a `tier` array showing which dimension(s) matched, plus the matched CPV codes / products / manufacturers when applicable. Default `scope` is "buyer-only" (capped at 100 related lots from the same buyer). Pass `scope: "full"` to widen across all buyers (no cap; can be heavy). Every row (and the echoed `source_lot`) carries `lifecycle_phase`, so you can tell which matches are still biddable from which are running or finished contracts without a second call. Paginated: `page` / `pageSize` (default 20, max 40 — a lower ceiling than `lot_search`, because these rows are fatter and a bigger page would not fit a client tool-result limit), with `total` = rows available to page through and `total_matches` = the uncapped tier count. Rows are ordered by lifecycle relevance first (open, then pre-tender, running, closed, unawarded, expired) and recency second, so page 1 is what is still actionable rather than merely what was announced last. The ordering is applied by the traversal itself, BEFORE its 100-row cap, so in "buyer-only" scope the rows you can page through are the 100 most relevant matches rather than the 100 most recently announced. Rows are lean on purpose: one flat `url` per row (no tracking parameters — the self-describing link object is on the envelope `persistent_url` only), `buyer` and `winner` as `{id, name}` (expand either with `org_details`), no row `buyer` at all in "buyer-only" scope (it is `data.buyer`), and `project_name` / `matched_products` / `matched_manufacturers` absent when they would add nothing.

lot_related

Paginated lot list with the full F1 filter set (date windows, party roles, winner/milestone flags). The optional `view` parameter targets a specific lot-listing page on the website — procurement (default, all lots), awards (an award event happened), expiring (every running contract, soonest end first), capture (lifecycle phase "open", i.e. bidding is genuinely open) — and routes persistent_url to the matching path. Returns one row per lot with: title, buyer, winner (when known), estimated/awarded value, submission_deadline, publication_date, top_cpv, top_nuts, lifecycle_phase, is_awarded, and a detail URL. `lifecycle_phase` is the database's own phase for the lot (pre-tender / open / closed / unawarded / active / potentially active / expired) — read it instead of inferring a status from notice types or from the presence of a winner. It is orthogonal to `is_awarded`: an awarded lot can be active, expired or unawarded. Filter on it with the `phase` argument, which narrows any `view`; the retired "other" view (tenders that ran and were not awarded) is `phase: ["unawarded"]`, listed on the website at /procurement?phase=unawarded. Arguments are validated strictly: an argument this schema does not list is an error, never a silently ignored filter — if a call fails on an unrecognized key, use the declared argument instead of retrying without it. Tip: when the user names a vendor, product, region, or sector, do NOT put those names in `query`/`searchTerms`. First call `entity_search` to resolve them, then pass the canonical ids/names as structured filters (`manufacturers`, `products`, `nuts`, `domain`, `segment`). Reserve `query` for thematic phrases like "AI" or "cloud migration". When free-text input is provided, the response also carries `meta.search_semantics` (which DB columns the SQL hit, language handling, OR/AND logic), and may include `meta.warnings` (your free-text term matched a known product/manufacturer — consider the structured filter) or `meta.did_you_mean` (zero hits but the term resolves to an entity — retry with the `example_filter` shown).

lot_search

Aggregate market summary aligned with /analytics: a `summary` header (total_lots, lots_with_known_winner, value with coverage, latest_publication_date_range), top vendors, top buyers, top manufacturers, procedure breakdown, framework breakdown, two quarterly histograms (`lotCountsByPublicationQuarter` on the filter axis, `lotCountsByLatestActivityQuarter` on the lot-rollup axis). Accepts F1 filters honored by /analytics; lot-only filters (latestPublicationDate, plannedDate, expirationDate, submissionDeadline, partyRoles, knownWinnerOnly, requireMilestoneDates) are not accepted here — use lot_search for those. Arguments are validated STRICTLY: an argument this tool does not declare is rejected, never ignored, so a rejected call is a call to fix rather than a wider answer to mistrust. The lifecycle-phase facet IS honored: `phase: ["open"]` narrows every aggregate to lots in that phase, the same population /procurement?phase=open lists and the returned /analytics `persistent_url` opens. Use it to split a market by stage — what is out for bid now, what is running, what is expiring — instead of reading a stage out of the procedure or framework breakdowns. Always summarise the market from `summary` first: it is the only field that gives the true market size (`total_lots`), the share of lots attributable to a vendor (`lots_with_known_winner`), and a coverage-aware value total. Do NOT sum `lotCountsByLatestActivityQuarter[].count` for market size (it drops lots without publication dates and is bucketed on `i2_lot.latest_publication_date`, NOT the `publicationDate` filter axis) or `topVendors[].count` for vendor reach (it is LIMIT-truncated). Axis disclosure: when a `publicationDate` filter is set (which acts on `i2_notice.publication_date` via EXISTS), `summary.latest_publication_date_range` and `lotCountsByLatestActivityQuarter` are bucketed on `i2_lot.latest_publication_date` (each lot's most-recent notice rollup). A lot that passed the filter via an early notice can have a later `latest_publication_date` outside the filter window — that's expected, not a bug. Both fields encode their axis in the name; use them to characterise "when was the latest activity", not "what publication window did I filter on". `summary.value` carries `coverage.lots_with_value / lots_total`. Many tenders publish without an `estimated_value`, so the bare `total` is a lower bound — always quote the coverage ratio (or note "no value coverage") when summarising; never present `total` in isolation. `topVendors`, `topBuyers`, and `coOccurringManufacturers` are each capped at `limit` (default 10, max 100); the breakdown lists are unbounded. The applied cap is echoed in `meta.applied_limit`, so a list whose length equals `applied_limit` is likely truncated. `coOccurringManufacturers` reflects co-occurrence on bundled lots, not "leaders" of a filtered product/manufacturer. When you filter by `products` (e.g. `["PostgreSQL"]`), bundled lots will surface other manufacturers from the same lots (Oracle, Microsoft) — these are also-mentioned, not market leaders for the filtered product. When you filter by `manufacturers`, those ids are excluded from this list so it shows only the co-occurring others. Read the field as "what else shows up alongside my filter". Tip: when the user names a vendor, product, region, or sector, do NOT put those names in `query`/`searchTerms`. First call `entity_search` to resolve them, then pass the canonical ids/names as structured filters (`manufacturers`, `products`, `nuts`, `domain`, `segment`). Reserve `query` for thematic phrases like "AI" or "cloud migration". When free-text input is provided, the response also carries `meta.search_semantics` (which DB columns the SQL hit, language handling, OR/AND logic), and may include `meta.warnings` (your free-text term matched a known product/manufacturer — consider the structured filter) or `meta.did_you_mean` (zero hits but the term resolves to an entity — retry with the `example_filter` shown).

market_overview

Full organization detail aligned with /organization/[party_id]: metadata, KPI counts, top buyers/vendors/products, recent news, plus aggregated stats — award value split by role as `value_summary.buyer` (money awarded) and `value_summary.winner` (money won), procedure / framework / domain breakdowns, active-contract metrics split by role, and the most recent awarded lots split into `recent_lots_by_role.buyer` (tenders this org ran) vs `recent_lots_by_role.winner` (wins this org made as a vendor). Report the side that matches the org's role in the user's question, or both when it plays both — a side reading `0 / 0` means no contracts in that role, not no value data for the org. Every value total carries `coverage.contracts_with_value / contracts_total`; the dataset often lacks contract values, so `total` is a lower bound — always quote the coverage ratio, never present `total` in isolation. Use this to look up a `party_id` to feed into `lot_search` / `market_overview` as `party: [{ id }]`.

org_details

Enumerate the procurement taxonomy: domains and their segments, each with a `lot_count`. Call this when you do NOT yet know the domain/segment vocabulary — it returns the full grouped tree so you can ground a request like "what's happening in Beratung?" without guessing keywords. Pass `domain: {id|name}` to scope to a single domain's segments; omit to enumerate everything. `entity_search` remains the right tool for fuzzy lookup of a *named* domain or segment. `taxonomy_browse` is for enumeration. Round-trip: pass `segments[].id` to `lot_search` / `market_overview` as `segment: {id}` to scope to a single segment, or pass a `domains[].id` as `domain: {id}` to scope to every segment under that domain — both ids round-trip directly into F1 without further translation. No `persistent_url` (no dedicated UI view).

taxonomy_browse