opportunity-exchange

Turn a natural-language economic question into an inspectable deterministic plan, resolve governed entities, execute a bounded set of existing OEX graph/data primitives, and return a citation-ready evidence bundle. OEX does not invoke a hosted model or generate a hidden reasoning chain; synthesize only from the returned evidence and limitations.

{
  "type": "object",
  "properties": {
    "question": {
      "type": "string",
      "maxLength": 1000,
      "description": "The economic question. Do not include personal or confidential information."
    },
    "entities": {
      "type": "array",
      "maxItems": 4,
      "description": "Optional exact entity hints. Use these when a place, business, occupation, sector, signal, or source is not stated unambiguously in the question.",
      "items": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "occupation",
              "municipality",
              "geography",
              "sector",
              "training-program",
              "noc-unit-group",
              "data-source",
              "data-provider",
              "economic-region",
              "census-division",
              "trade-region",
              "naics-industry",
              "industrial-facility",
              "open-source-signal",
              "organization",
              "project",
              "procurement-notice",
              "product-or-service",
              "job-posting",
              "employer",
              "business-source-observation",
              "establishment",
              "business"
            ]
          },
          "id": {
            "type": "string",
            "maxLength": 200
          }
        },
        "required": [
          "type",
          "id"
        ],
        "additionalProperties": false
      }
    },
    "minimumConfidence": {
      "type": "string",
      "enum": [
        "A",
        "B",
        "C",
        "D"
      ]
    },
    "depth": {
      "type": "integer",
      "minimum": 1,
      "maximum": 3,
      "description": "Maximum graph traversal depth; default 2."
    },
    "maxEvidenceCalls": {
      "type": "integer",
      "minimum": 1,
      "maximum": 8,
      "description": "Maximum governed evidence calls executed; default 6."
    }
  },
  "required": [
    "question"
  ],
  "additionalProperties": false
}

What OEX has asked about a subject, what it could not conclude, why, and which registered question logically follows. Governed and deterministic: every field is a typed governed value or a fixed catalogue constant, no model is invoked, and nothing is derived from prose. This is not a work queue — it carries no identifiers to act on, and OEX accepts no report that a dependency was addressed. A dependency stops being reported when the same question, asked again against changed governed evidence, no longer derives it. Use investigate_economic_question or the subject’s own resource for the facts; this reports only what remains unresolved. Follow only nextInquiries; awaiting_evidence means stop until admissible evidence changes. evidenceRequirements names public question prerequisites without exposing private sources. Already evaluated questions are replaced by their blockers.

{
  "type": "object",
  "properties": {
    "subjectKind": {
      "type": "string",
      "description": "The kind of subject. Kinds any registered inquiry type asks about are listed in the response under admissibility.inquirableSubjectKinds."
    },
    "subjectId": {
      "type": "string",
      "maxLength": 200,
      "description": "The canonical OEX identifier for the subject, such as a municipality slug."
    }
  },
  "required": [
    "subjectKind",
    "subjectId"
  ],
  "additionalProperties": false
}

Resolve a user-supplied name, slug, NOC code, SGC code, program, sector or governed source to its canonical OEX identity. Call this before joining datasets when the identifier is uncertain. Results include the correct follow-up MCP tool and arguments.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Name, alternate title, slug, or official identifier."
    },
    "type": {
      "type": "string",
      "enum": [
        "occupation",
        "municipality",
        "geography",
        "sector",
        "training-program",
        "noc-unit-group",
        "data-source",
        "data-provider",
        "economic-region",
        "census-division",
        "trade-region",
        "naics-industry",
        "industrial-facility",
        "open-source-signal",
        "organization",
        "project",
        "procurement-notice",
        "product-or-service",
        "job-posting",
        "employer",
        "business-source-observation",
        "establishment",
        "business"
      ],
      "description": "Optional entity-type constraint."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 20,
      "description": "Maximum matches; default 8."
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false
}

Fetch the governed context for one resolved entity in a single call. Accepts a canonical id, local slug or exact name and routes to the existing occupation, municipality, sector, training, NOC or source resource so evidence and provenance are preserved.

{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "occupation",
        "municipality",
        "geography",
        "sector",
        "training-program",
        "noc-unit-group",
        "data-source",
        "data-provider",
        "economic-region",
        "census-division",
        "trade-region",
        "naics-industry",
        "industrial-facility",
        "open-source-signal",
        "organization",
        "project",
        "procurement-notice",
        "product-or-service",
        "job-posting",
        "employer",
        "business-source-observation",
        "establishment",
        "business"
      ]
    },
    "id": {
      "type": "string",
      "description": "Exact canonical id, local slug, or name from resolve_entities."
    }
  },
  "required": [
    "type",
    "id"
  ],
  "additionalProperties": false
}

Query the materialized semantic graph without downloading whole datasets. Resolve an entity name/code and optional municipality geography, then return typed facts and relationships. This supports municipality-by-NAICS GDP and business queries without encoding classifications in metric names. Missing facts or edges mean unknown, never zero or false.

{
  "type": "object",
  "properties": {
    "entity": {
      "type": "string",
      "description": "Exact name, slug, graph id, NOC code, SGC code, source id, or provider id."
    },
    "geography": {
      "type": "string",
      "description": "Optional exact municipality name, slug, or SGC code for geography-scoped facts."
    },
    "type": {
      "type": "string",
      "enum": [
        "occupation",
        "municipality",
        "geography",
        "sector",
        "training-program",
        "noc-unit-group",
        "data-source",
        "data-provider",
        "economic-region",
        "census-division",
        "trade-region",
        "naics-industry",
        "industrial-facility",
        "open-source-signal",
        "organization",
        "project",
        "procurement-notice",
        "product-or-service",
        "job-posting",
        "employer",
        "business-source-observation",
        "establishment",
        "business"
      ],
      "description": "Optional entity-type constraint."
    },
    "bundle": {
      "type": "string",
      "enum": [
        "municipal-economic-profile-v1"
      ],
      "description": "Bounded metric preset. municipal-economic-profile-v1 requires one municipality entity."
    },
    "metrics": {
      "type": "array",
      "maxItems": 20,
      "items": {
        "type": "string"
      },
      "description": "Fact metrics, e.g. population."
    },
    "predicates": {
      "type": "array",
      "maxItems": 20,
      "items": {
        "type": "string"
      },
      "description": "Relationship predicates, e.g. classified_as or serves."
    },
    "truthStates": {
      "type": "array",
      "maxItems": 7,
      "items": {
        "type": "string",
        "enum": [
          "live",
          "snapshot",
          "measured_aggregate",
          "derived",
          "mixed",
          "metadata",
          "unavailable"
        ]
      }
    },
    "minimumConfidence": {
      "type": "string",
      "enum": [
        "A",
        "B",
        "C",
        "D"
      ]
    },
    "referencePeriodStart": {
      "type": "string",
      "description": "Inclusive ISO-8601 lower bound for fact reference periods."
    },
    "referencePeriodEnd": {
      "type": "string",
      "description": "Inclusive ISO-8601 upper bound for fact reference periods."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "description": "Maximum facts, relationships, or listed entities; default 25."
    },
    "depth": {
      "type": "integer",
      "minimum": 1,
      "maximum": 3,
      "description": "Hops to expand outward from entity; default 1. Above 1 adds an expansion block of nodes and edges annotated with the hop that reached them, so a containment chain such as municipality -> census-division -> economic-region can be fetched in one call instead of three. Requires entity."
    },
    "maxNodes": {
      "type": "integer",
      "minimum": 1,
      "maximum": 500,
      "description": "Ceiling on entities across the whole expansion; default 200. Distinct from limit, which bounds one level — without it a depth of 2 from a municipality would pull every business in it."
    }
  },
  "additionalProperties": false
}

Return the current database graph inventory by entity type, predicate and metric plus deterministic core reconciliation. ok=true means every governed core entity, alias, edge and fact is present; additional materializers may add records.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

Compare 2–10 exact Saskatchewan municipalities using the newest governed fact for each standard economic metric. A metric is comparable only when all resolved municipalities have the same unit and reference period; missing and mismatched evidence is returned explicitly.

{
  "type": "object",
  "properties": {
    "entities": {
      "type": "array",
      "minItems": 2,
      "maxItems": 10,
      "uniqueItems": true,
      "items": {
        "type": "string"
      },
      "description": "Municipality names, local slugs, or SGC codes."
    },
    "bundle": {
      "type": "string",
      "enum": [
        "municipal-economic-profile-v1"
      ],
      "description": "Comparison metric preset; defaults to municipal-economic-profile-v1."
    },
    "metrics": {
      "type": "array",
      "maxItems": 20,
      "items": {
        "type": "string"
      },
      "description": "Optional additional fact metrics."
    }
  },
  "required": [
    "entities"
  ],
  "additionalProperties": false
}

The Saskatchewan occupation catalogue: id, title, NOC code, sector, hourly wage, demand score. Start here to find role ids.

{
  "type": "object",
  "properties": {}
}

One occupation in full: market figures, entry requirements, working conditions, training programs, and per-community outcomes (net and discretionary monthly income at the median wage).

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Role id from list_roles."
    }
  },
  "required": [
    "id"
  ]
}

Compare two or three roles using the shared occupation fields: wages, demand, outlook, entry requirements and work profile.

{
  "type": "object",
  "properties": {
    "ids": {
      "type": "array",
      "minItems": 2,
      "maxItems": 3,
      "uniqueItems": true,
      "items": {
        "type": "string"
      },
      "description": "Two or three role ids from list_roles."
    }
  },
  "required": [
    "ids"
  ],
  "additionalProperties": false
}

Source-attributed hiring-activity evidence, newest first and filterable by occupation, sector and geography. data.recordPurpose and each row recordPurpose are hiring_activity_evidence; rows are observations with isActionable=false, not jobs offered for application through OEX. Check observationDate, lastVerifiedAt, provenance, meta.evidence.truthState and synthetic before using a record as current evidence.

{
  "type": "object",
  "properties": {
    "q": {
      "type": "string",
      "description": "Free-text search over title, employer and description."
    },
    "region": {
      "type": "string",
      "description": "Exact region name."
    },
    "municipality": {
      "type": "string",
      "description": "Exact municipality name."
    },
    "occupation": {
      "type": "string",
      "description": "Role id from the occupation catalogue."
    },
    "sector": {
      "type": "string",
      "description": "Sector id from the sector list."
    },
    "type": {
      "type": "string",
      "enum": [
        "full-time",
        "part-time",
        "seasonal",
        "casual",
        "contract"
      ],
      "description": "Employment type."
    },
    "minWage": {
      "type": "number",
      "description": "Minimum hourly wage, CAD."
    },
    "postedWithinDays": {
      "type": "integer",
      "description": "Only postings newer than this many days."
    },
    "limit": {
      "type": "integer",
      "description": "Page size, 1-200 (default 50)."
    },
    "offset": {
      "type": "integer",
      "description": "Pagination offset (default 0)."
    }
  }
}

The wage-vs-cost join: what an hourly wage actually leaves over each month in every Saskatchewan community, after tax, housing, utilities and commuting. Pass occupation (models its median wage, with posting counts; their truth state is in meta.evidence) or wage.

{
  "type": "object",
  "properties": {
    "occupation": {
      "type": "string",
      "description": "Role id from list_roles."
    },
    "wage": {
      "type": "number",
      "description": "Explicit hourly wage, CAD."
    }
  }
}

Rank Saskatchewan communities by monthly discretionary income for exactly one role or explicit hourly wage.

{
  "type": "object",
  "properties": {
    "occupation": {
      "type": "string",
      "description": "Role id whose median wage should be modelled."
    },
    "wage": {
      "type": "number",
      "exclusiveMinimum": 0,
      "description": "Explicit positive hourly wage in CAD."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 20,
      "description": "Number of ranked communities, 1-20 (default 10)."
    }
  },
  "additionalProperties": false
}

Sector rollups with provider-qualified hiring-record counts, median wage and occupation demand. Candidate profiles are excluded. Read meta.evidence before interpreting a count.

{
  "type": "object",
  "properties": {}
}

One sector: its occupations, provider-qualified postings by community, and notable employers.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Sector id from list_sectors."
    }
  },
  "required": [
    "id"
  ]
}

Aggregate hiring records associated with occupational credential requirements. Candidate profiles and holder counts are excluded; the result describes demand evidence, not a proven shortage.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

Search the public business directory by name, municipality, sector group and observed hiring flag. Preview providers return modelled activity scenarios, not business claims.

{
  "type": "object",
  "properties": {
    "q": {
      "type": "string",
      "description": "Case-insensitive text search over employer and sector names."
    },
    "municipality": {
      "type": "string",
      "description": "Municipality id from /api/v1/municipalities."
    },
    "sector": {
      "type": "string",
      "description": "Sector-group id from /api/v1/sectors."
    },
    "hiring": {
      "type": "boolean",
      "description": "true to filter on the disclosed hiring flag; preview providers expose modelled scenarios."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "description": "Result limit, 1-100 (default 25)."
    }
  },
  "additionalProperties": false
}

Saskatchewan merchandise exports by NAPCS section from Statistics Canada. Station-level CGC rows are excluded pending commercial redistribution permission.

{
  "type": "object",
  "properties": {}
}

Housing market by community: median price, listings, market velocity, and the own-vs-rent monthly cost on the local wage. Pass municipalityId for one community with the price trend and full ownership model.

{
  "type": "object",
  "properties": {
    "municipalityId": {
      "type": "string",
      "description": "Municipality id (e.g. saskatoon). Omit for all communities."
    }
  }
}

Named businesses holding a municipal licence in one community, from an attributed City snapshot. Answers who exists and in which industry, NOT who is hiring — use search_employers for that. Each row is a licence held on the reference date: it is not a legal-entity register, not current beyond that date, incomplete for excluded licence categories, and not evidence of ownership, employment, size or operating health. Home-based licences carry no address.

{
  "type": "object",
  "properties": {
    "municipalityId": {
      "type": "string",
      "description": "Municipality id. Only communities with a reviewed snapshot resolve."
    },
    "subsector": {
      "type": "string",
      "description": "Three-digit NAICS subsector code to filter by, e.g. 484."
    },
    "q": {
      "type": "string",
      "description": "Business-name contains match."
    },
    "limit": {
      "type": "number",
      "description": "Rows to return, 1-200 (default 50)."
    },
    "offset": {
      "type": "number",
      "description": "Rows to skip for paging."
    }
  },
  "required": [
    "municipalityId"
  ],
  "additionalProperties": false
}

Measured wages and vacancies (Statistics Canada, real data): LFS median/average hourly wages by occupation group × province, and JVWS job vacancies with average offered hourly wage by NOC 2021 unit group × province/territory. Pass noc for one unit group across geographies, province for one geography, both for one cell, neither for the national overview. Wage medians are group-level; each estimate names the published grouping that answered.

{
  "type": "object",
  "properties": {
    "noc": {
      "type": "string",
      "description": "Five-digit NOC 2021 unit-group code from list_noc_groups."
    },
    "province": {
      "type": "string",
      "description": "SGC 2021 code, postal abbreviation (e.g. SK), or \"canada\"."
    }
  },
  "additionalProperties": false
}

Measured rental markets (CMHC Rental Market Survey via Statistics Canada, real data): average rents by unit type (bachelor to 3+ bedroom) and rental vacancy rates for every surveyed centre in Canada, October survey. Pass province for one province’s centres, centre (cmhcCode) for one centre, neither for the national overview. Suppressed cells are null and unsurveyed centres absent — never zero.

{
  "type": "object",
  "properties": {
    "province": {
      "type": "string",
      "description": "SGC 2021 code or postal abbreviation (e.g. SK)."
    },
    "centre": {
      "type": "string",
      "description": "CMHC/StatCan geography code (cmhcCode) from a previous get_rents call."
    }
  },
  "additionalProperties": false
}

The complete NOC 2021 occupational classification: all 516 unit groups with bilingual titles, TEER tiers, and platform coverage flags. Use to map any Canadian occupation to its code.

{
  "type": "object",
  "properties": {}
}

The decision tool: evaluate realistic routes into work for a person's stated credentials, education, experience, driver licence, relocation boundary, housing and family needs, savings, and retraining limit. Returns pass/conflict/unknown plus the same ordered, versioned evidence panel used by REST and the human evaluator. OSINT and placeholder values are excluded from ranking. Request-scoped: constraints are evaluated in-process and never stored.

{
  "type": "object",
  "properties": {
    "credentials": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Credential names held and current, e.g. \"WHMIS\", \"Class 5 Licence\"."
    },
    "educationLevel": {
      "type": "string",
      "enum": [
        "Secondary school",
        "Secondary plus short certificate",
        "Secondary plus trade certificate",
        "Apprenticeship or journeyperson",
        "Diploma",
        "Bachelor degree"
      ],
      "description": "Highest education level."
    },
    "experienceAreas": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "mechanical_systems",
          "safety_systems",
          "field_operations",
          "process_monitoring",
          "electrical_basics",
          "coordination_admin",
          "care_delivery",
          "customer_service",
          "digital_systems",
          "logistics_handling",
          "physical_operations"
        ]
      },
      "description": "Capability areas with real working experience."
    },
    "licenceClass": {
      "type": "string",
      "enum": [
        "None",
        "Class 5",
        "Class 3",
        "Class 1A"
      ],
      "description": "Highest Saskatchewan driver licence currently held."
    },
    "currentMunicipalityId": {
      "type": "string",
      "enum": [
        "saskatoon",
        "regina",
        "prince-albert",
        "moose-jaw",
        "swift-current",
        "yorkton",
        "north-battleford",
        "weyburn",
        "estevan",
        "lloydminster",
        "warman",
        "martensville",
        "humboldt",
        "melfort",
        "meadow-lake",
        "melville",
        "kindersley",
        "nipawin",
        "rosetown",
        "la-ronge"
      ],
      "description": "Current community, required when maximumRelocationKm is supplied."
    },
    "allowedMunicipalityIds": {
      "type": "array",
      "uniqueItems": true,
      "items": {
        "type": "string",
        "enum": [
          "saskatoon",
          "regina",
          "prince-albert",
          "moose-jaw",
          "swift-current",
          "yorkton",
          "north-battleford",
          "weyburn",
          "estevan",
          "lloydminster",
          "warman",
          "martensville",
          "humboldt",
          "melfort",
          "meadow-lake",
          "melville",
          "kindersley",
          "nipawin",
          "rosetown",
          "la-ronge"
        ]
      },
      "description": "Optional destination allowlist."
    },
    "maximumRelocationKm": {
      "type": "number",
      "minimum": 0,
      "maximum": 2500,
      "description": "Maximum move from currentMunicipalityId; zero means local only."
    },
    "housingBudgetMonthly": {
      "type": "number",
      "minimum": 1,
      "maximum": 50000,
      "description": "Maximum monthly rent for the requested household."
    },
    "bedroomsRequired": {
      "type": "string",
      "enum": [
        "bachelor",
        "oneBedroom",
        "twoBedroom",
        "threeBedroomPlus"
      ],
      "description": "Rental unit size required by the household."
    },
    "incomeEarners": {
      "type": "integer",
      "minimum": 1,
      "maximum": 8,
      "description": "Income earners sharing housing and utilities."
    },
    "householdSize": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10,
      "description": "People represented by the regional Market Basket Measure basket."
    },
    "vehicleAvailable": {
      "type": "boolean",
      "description": "Whether the scenario includes a vehicle commute."
    },
    "savingsDollars": {
      "type": "number",
      "minimum": 0,
      "maximum": 1000000,
      "description": "Cash available for training before funding."
    },
    "maximumRetrainingWeeks": {
      "type": "number",
      "minimum": 0,
      "maximum": 520,
      "description": "Maximum acceptable retraining time; zero means direct entry."
    },
    "targetOccupationId": {
      "type": "string",
      "description": "Role id from list_roles — evaluates that target in depth."
    },
    "limit": {
      "type": "number",
      "description": "Ranked list size (default 8, max 20)."
    }
  }
}

Inspect official Saskatchewan CanadaBuys procurement observations by buyer, notice, or UNSPSC product/service category. Returns current and historical lifecycle evidence, amendments, conflicts, provenance, and explicit missing-evidence boundaries. It does not rank tenders, infer supplier fit, or expose private supplier/customer relationships.

{
  "type": "object",
  "properties": {
    "buyerId": {
      "type": "string",
      "description": "Exact source-scoped organization id from resolve_entities."
    },
    "categoryCode": {
      "type": "string",
      "pattern": "^\\d{8}$",
      "description": "Exact eight-digit UNSPSC code from resolve_entities."
    },
    "noticeId": {
      "type": "string",
      "description": "Exact source-stable procurement-notice id."
    },
    "includeHistory": {
      "type": "boolean",
      "description": "Include closed historical demand observations; default true."
    },
    "limit": {
      "type": "integer",
      "minimum": 0,
      "maximum": 500,
      "description": "Maximum observations returned; default 100."
    }
  },
  "additionalProperties": false
}

Compare the supply categories a business has published against the UNSPSC categories official buyers have requested. Returns category compatibility only, classed as inferred_compatibility: it establishes no qualification, eligibility, supplier relationship, competitiveness, or likelihood of award, and it never reads capabilities the business withheld from publication. Use inspect_procurement_activity for the buyer-side observations themselves.

{
  "type": "object",
  "properties": {
    "businessId": {
      "type": "string",
      "description": "Exact graph business id, e.g. business:<canonical-id>, from resolve_entities."
    },
    "includeHistory": {
      "type": "boolean",
      "description": "Include closed notices as historical demand evidence; default false."
    },
    "limit": {
      "type": "integer",
      "minimum": 0,
      "maximum": 200,
      "description": "Maximum overlapping notices returned; default 50."
    }
  },
  "required": [
    "businessId"
  ],
  "additionalProperties": false
}

Report occupational demand, credential demand, training availability and a training-route constraint indicator separately. It does not combine them into a shortage claim: a shortage is a claim about labour supply and requires a credential-holder denominator OEX does not hold. Advertised record counts are counts of advertisements, not of unfilled positions or people needed, and are not deduplicated across employers.

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "minimum": 0,
      "maximum": 200,
      "description": "Maximum rows per view; default 50."
    }
  },
  "additionalProperties": false
}

Find businesses whose published supply categories match the categories a business has published as things it buys. Returns potential_compatibility only: no relationship is asserted, neither party has said they have done business, and neither may be aware of the other. Nothing is matched on industry. Withheld categories on either side are excluded.

{
  "type": "object",
  "properties": {
    "businessId": {
      "type": "string",
      "description": "Exact graph business id, e.g. business:<canonical-id>, from resolve_entities."
    }
  },
  "required": [
    "businessId"
  ],
  "additionalProperties": false
}

Find businesses whose published purchasing categories match the categories a business has published as things it can supply. Returns potential_compatibility only: it is not a customer list, and a business appearing in it has expressed no interest in anything. Nothing is matched on industry. Withheld categories on either side are excluded.

{
  "type": "object",
  "properties": {
    "businessId": {
      "type": "string",
      "description": "Exact graph business id, e.g. business:<canonical-id>, from resolve_entities."
    }
  },
  "required": [
    "businessId"
  ],
  "additionalProperties": false
}

List governed Saskatchewan economic signals from official structured sources. Each row preserves lifecycle state and uncertainty; notices do not prove an award, project, hiring or outcome.

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "number",
      "minimum": 0,
      "maximum": 1000,
      "description": "Page size."
    },
    "offset": {
      "type": "number",
      "minimum": 0,
      "description": "Zero-based page offset."
    }
  },
  "additionalProperties": false
}

Get one governed economic signal by its source-stable id, including provenance, lifecycle state, mappings and uncertainty boundaries.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Signal id from list_economic_signals."
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false
}

Backward-compatible alias for list_economic_signals.

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "number",
      "minimum": 0,
      "maximum": 1000
    },
    "offset": {
      "type": "number",
      "minimum": 0
    }
  },
  "additionalProperties": false
}

Read the governed upstream source registry: publisher datasets, stable source ids, licence decisions, approved and excluded uses, checked releases, materialization bindings and refresh controls.

{
  "type": "object",
  "properties": {}
}

Read runtime provider contracts grouped as evidence, preview, planned, first-party and derived. Only the evidence group is eligible to support factual claims.

{
  "type": "object",
  "properties": {}
}

Resolve either a governed upstream source id or runtime provider id. Returns the matching source or categorized provider with its lineage; omit id for the upstream source registry.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Optional registered source id from get_data_sources or provider id from get_data_providers."
    }
  },
  "additionalProperties": false
}

Resolve a public graph assertion citation to its canonical entity or entities, exact assertion, source, observation time, truth state, confidence, publication scope, methodology and provenance. Accepts the OEX citation URN, token, or resolver URL returned beside a graph fact or relationship.

{
  "type": "object",
  "properties": {
    "citation": {
      "type": "string",
      "description": "citation.id, citation resolver URL, or versioned citation token."
    }
  },
  "required": [
    "citation"
  ],
  "additionalProperties": false
}

Modeled community GDP for Saskatchewan: official provincial sector GDP (36-10-0711-01, 2022 current dollars) allocated across all 951 census subdivisions by measured activity weights, reconciling to provincial totals. Returns benchmark/allocated/residual totals, top communities, the official 2017–2025 Saskatchewan real-GDP series, and the calculation version. Community figures are structured estimates, not official measurements.

{
  "type": "object",
  "properties": {}
}

Evidence availability and confidence-gate work queue for all 17 Saskatchewan cities and 149 towns. Returns current Tier A–D counts, evidence-domain coverage, public-model input counts, local-context status and the next defensible data action for each municipality.

{
  "type": "object",
  "properties": {}
}

One community’s GDP report by 2021 SGC census subdivision code (e.g. 4708004 for Swift Current): central estimate with the income/production range and every sector’s amount and percentage share, or the suppression reason where the data cannot support a point estimate. Codes come from get_economy_overview or /api/v1/economy.

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "description": "7-digit 2021 SGC census subdivision code."
    }
  },
  "required": [
    "code"
  ],
  "additionalProperties": false
}

Resolve user language or an official code to the canonical OEX identity and the correct next tool. Returns ranked candidates when the input is ambiguous.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Name, alternate title, slug, or official identifier."
    },
    "type": {
      "type": "string",
      "enum": [
        "occupation",
        "municipality",
        "geography",
        "sector",
        "training-program",
        "noc-unit-group",
        "data-source",
        "data-provider",
        "economic-region",
        "census-division",
        "trade-region",
        "naics-industry",
        "industrial-facility",
        "open-source-signal",
        "organization",
        "project",
        "procurement-notice",
        "product-or-service",
        "job-posting",
        "employer",
        "business-source-observation",
        "establishment",
        "business"
      ],
      "description": "Optional entity-type constraint."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 20,
      "description": "Maximum matches; default 8."
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false
}

Retrieve one governed entity record with its evidence, provenance, canonical links, and permitted interpretation.

{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "occupation",
        "municipality",
        "geography",
        "sector",
        "training-program",
        "noc-unit-group",
        "data-source",
        "data-provider",
        "economic-region",
        "census-division",
        "trade-region",
        "naics-industry",
        "industrial-facility",
        "open-source-signal",
        "organization",
        "project",
        "procurement-notice",
        "product-or-service",
        "job-posting",
        "employer",
        "business-source-observation",
        "establishment",
        "business"
      ]
    },
    "id": {
      "type": "string",
      "description": "Exact canonical id, local slug, or name from resolve_entities."
    }
  },
  "required": [
    "type",
    "id"
  ],
  "additionalProperties": false
}

Search across supported OEX entity classes using names, aliases, slugs, and official identifiers.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Name, alternate title, slug, or official identifier."
    },
    "type": {
      "type": "string",
      "enum": [
        "occupation",
        "municipality",
        "geography",
        "sector",
        "training-program",
        "noc-unit-group",
        "data-source",
        "data-provider",
        "economic-region",
        "census-division",
        "trade-region",
        "naics-industry",
        "industrial-facility",
        "open-source-signal",
        "organization",
        "project",
        "procurement-notice",
        "product-or-service",
        "job-posting",
        "employer",
        "business-source-observation",
        "establishment",
        "business"
      ],
      "description": "Optional entity-type constraint."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 20,
      "description": "Maximum matches; default 8."
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false
}

Search governed municipal licensed-business snapshots without inferring operating health, employment, ownership, or hiring.

{
  "type": "object",
  "properties": {
    "municipalityId": {
      "type": "string",
      "description": "Municipality id. Only communities with a reviewed snapshot resolve."
    },
    "subsector": {
      "type": "string",
      "description": "Three-digit NAICS subsector code to filter by, e.g. 484."
    },
    "q": {
      "type": "string",
      "description": "Business-name contains match."
    },
    "limit": {
      "type": "number",
      "description": "Rows to return, 1-200 (default 50)."
    },
    "offset": {
      "type": "number",
      "description": "Rows to skip for paging."
    }
  },
  "required": [
    "municipalityId"
  ],
  "additionalProperties": false
}

Retrieve the governed context and evidence boundary for one business entity. Licence presence establishes snapshot presence only.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Canonical business id from search_businesses or a graph query."
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false
}

Retrieve one municipality as a governed economic profile with canonical identity, available evidence, links, and qualifications.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Municipality name, slug, or SGC code."
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false
}

Compare 2–10 Saskatchewan communities and return explicit missing-data and comparability results for every requested metric.

{
  "type": "object",
  "properties": {
    "entities": {
      "type": "array",
      "minItems": 2,
      "maxItems": 10,
      "uniqueItems": true,
      "items": {
        "type": "string"
      },
      "description": "Municipality names, local slugs, or SGC codes."
    },
    "bundle": {
      "type": "string",
      "enum": [
        "municipal-economic-profile-v1"
      ],
      "description": "Comparison metric preset; defaults to municipal-economic-profile-v1."
    },
    "metrics": {
      "type": "array",
      "maxItems": 20,
      "items": {
        "type": "string"
      },
      "description": "Optional additional fact metrics."
    }
  },
  "required": [
    "entities"
  ],
  "additionalProperties": false
}

Retrieve governed Saskatchewan labour-demand evidence while keeping advertised openings, statistical vacancies, live listings, and modelled sector allocations distinct.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

Retrieve wage evidence for an occupation and geography with units, period, source, confidence, and comparability qualifications.

{
  "type": "object",
  "properties": {
    "noc": {
      "type": "string",
      "description": "Five-digit NOC 2021 unit-group code from list_noc_groups."
    },
    "province": {
      "type": "string",
      "description": "SGC 2021 code, postal abbreviation (e.g. SK), or \"canada\"."
    }
  },
  "additionalProperties": false
}

Traverse bounded, typed economic relationships from a resolved entity without treating missing edges as false.

{
  "type": "object",
  "properties": {
    "entity": {
      "type": "string",
      "description": "Exact name, slug, graph id, NOC code, SGC code, source id, or provider id."
    },
    "geography": {
      "type": "string",
      "description": "Optional exact municipality name, slug, or SGC code for geography-scoped facts."
    },
    "type": {
      "type": "string",
      "enum": [
        "occupation",
        "municipality",
        "geography",
        "sector",
        "training-program",
        "noc-unit-group",
        "data-source",
        "data-provider",
        "economic-region",
        "census-division",
        "trade-region",
        "naics-industry",
        "industrial-facility",
        "open-source-signal",
        "organization",
        "project",
        "procurement-notice",
        "product-or-service",
        "job-posting",
        "employer",
        "business-source-observation",
        "establishment",
        "business"
      ],
      "description": "Optional entity-type constraint."
    },
    "bundle": {
      "type": "string",
      "enum": [
        "municipal-economic-profile-v1"
      ],
      "description": "Bounded metric preset. municipal-economic-profile-v1 requires one municipality entity."
    },
    "metrics": {
      "type": "array",
      "maxItems": 20,
      "items": {
        "type": "string"
      },
      "description": "Fact metrics, e.g. population."
    },
    "predicates": {
      "type": "array",
      "maxItems": 20,
      "items": {
        "type": "string"
      },
      "description": "Relationship predicates, e.g. classified_as or serves."
    },
    "truthStates": {
      "type": "array",
      "maxItems": 7,
      "items": {
        "type": "string",
        "enum": [
          "live",
          "snapshot",
          "measured_aggregate",
          "derived",
          "mixed",
          "metadata",
          "unavailable"
        ]
      }
    },
    "minimumConfidence": {
      "type": "string",
      "enum": [
        "A",
        "B",
        "C",
        "D"
      ]
    },
    "referencePeriodStart": {
      "type": "string",
      "description": "Inclusive ISO-8601 lower bound for fact reference periods."
    },
    "referencePeriodEnd": {
      "type": "string",
      "description": "Inclusive ISO-8601 upper bound for fact reference periods."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "description": "Maximum facts, relationships, or listed entities; default 25."
    },
    "depth": {
      "type": "integer",
      "minimum": 1,
      "maximum": 3,
      "description": "Hops to expand outward from entity; default 1. Above 1 adds an expansion block of nodes and edges annotated with the hop that reached them, so a containment chain such as municipality -> census-division -> economic-region can be fetched in one call instead of three. Requires entity."
    },
    "maxNodes": {
      "type": "integer",
      "minimum": 1,
      "maximum": 500,
      "description": "Ceiling on entities across the whole expansion; default 200. Distinct from limit, which bounds one level — without it a depth of 2 from a municipality would pull every business in it."
    }
  },
  "additionalProperties": false
}

Find entities connected through governed graph predicates, with source, truth state, confidence, and hop annotations.

{
  "type": "object",
  "properties": {
    "entity": {
      "type": "string",
      "description": "Exact name, slug, graph id, NOC code, SGC code, source id, or provider id."
    },
    "geography": {
      "type": "string",
      "description": "Optional exact municipality name, slug, or SGC code for geography-scoped facts."
    },
    "type": {
      "type": "string",
      "enum": [
        "occupation",
        "municipality",
        "geography",
        "sector",
        "training-program",
        "noc-unit-group",
        "data-source",
        "data-provider",
        "economic-region",
        "census-division",
        "trade-region",
        "naics-industry",
        "industrial-facility",
        "open-source-signal",
        "organization",
        "project",
        "procurement-notice",
        "product-or-service",
        "job-posting",
        "employer",
        "business-source-observation",
        "establishment",
        "business"
      ],
      "description": "Optional entity-type constraint."
    },
    "bundle": {
      "type": "string",
      "enum": [
        "municipal-economic-profile-v1"
      ],
      "description": "Bounded metric preset. municipal-economic-profile-v1 requires one municipality entity."
    },
    "metrics": {
      "type": "array",
      "maxItems": 20,
      "items": {
        "type": "string"
      },
      "description": "Fact metrics, e.g. population."
    },
    "predicates": {
      "type": "array",
      "maxItems": 20,
      "items": {
        "type": "string"
      },
      "description": "Relationship predicates, e.g. classified_as or serves."
    },
    "truthStates": {
      "type": "array",
      "maxItems": 7,
      "items": {
        "type": "string",
        "enum": [
          "live",
          "snapshot",
          "measured_aggregate",
          "derived",
          "mixed",
          "metadata",
          "unavailable"
        ]
      }
    },
    "minimumConfidence": {
      "type": "string",
      "enum": [
        "A",
        "B",
        "C",
        "D"
      ]
    },
    "referencePeriodStart": {
      "type": "string",
      "description": "Inclusive ISO-8601 lower bound for fact reference periods."
    },
    "referencePeriodEnd": {
      "type": "string",
      "description": "Inclusive ISO-8601 upper bound for fact reference periods."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "description": "Maximum facts, relationships, or listed entities; default 25."
    },
    "depth": {
      "type": "integer",
      "minimum": 1,
      "maximum": 3,
      "description": "Hops to expand outward from entity; default 1. Above 1 adds an expansion block of nodes and edges annotated with the hop that reached them, so a containment chain such as municipality -> census-division -> economic-region can be fetched in one call instead of three. Requires entity."
    },
    "maxNodes": {
      "type": "integer",
      "minimum": 1,
      "maximum": 500,
      "description": "Ceiling on entities across the whole expansion; default 200. Distinct from limit, which bounds one level — without it a depth of 2 from a municipality would pull every business in it."
    }
  },
  "additionalProperties": false
}

Retrieve a governed upstream source or runtime provider and its lineage, licence boundary, releases, and serving status.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Optional registered source id from get_data_sources or provider id from get_data_providers."
    }
  },
  "additionalProperties": false
}

Explain the OEX A–D record-confidence vocabulary, its weakest-input rule for derived values, and the interpretation contract.

{
  "type": "object",
  "properties": {
    "confidence": {
      "type": "string",
      "enum": [
        "A",
        "B",
        "C",
        "D"
      ]
    }
  },
  "additionalProperties": false
}

Explain what an OEX truth state permits an agent to claim and return the complete interpretation contract.

{
  "type": "object",
  "properties": {
    "truthState": {
      "type": "string",
      "enum": [
        "preview",
        "snapshot",
        "measured_aggregate",
        "mixed",
        "live",
        "metadata"
      ]
    }
  },
  "additionalProperties": false
}

Check whether requested community observations share compatible concepts, units, geographic boundaries, and reference periods; return explicit reasons where they do not.

{
  "type": "object",
  "properties": {
    "entities": {
      "type": "array",
      "minItems": 2,
      "maxItems": 10,
      "uniqueItems": true,
      "items": {
        "type": "string"
      },
      "description": "Municipality names, local slugs, or SGC codes."
    },
    "bundle": {
      "type": "string",
      "enum": [
        "municipal-economic-profile-v1"
      ],
      "description": "Comparison metric preset; defaults to municipal-economic-profile-v1."
    },
    "metrics": {
      "type": "array",
      "maxItems": 20,
      "items": {
        "type": "string"
      },
      "description": "Optional additional fact metrics."
    }
  },
  "required": [
    "entities"
  ],
  "additionalProperties": false
}

Run Business Health on a real business from details you supply — the free public check. Use this when someone asks about *their own* business: it needs no account, stores nothing, and creates no record. Supply the website to unlock the nine checks that read the site. OEX asserts nothing about the business and holds no record of it; the report describes the details given and the site named. For experimenting with the workflow instead, use create_sandbox_business.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "The business name."
    },
    "website": {
      "type": "string",
      "description": "Domain or URL. Worth supplying — nine checks depend on it."
    },
    "address": {
      "type": "string"
    },
    "category": {
      "type": "string",
      "description": "What the business does."
    },
    "description": {
      "type": "string",
      "description": "How the business describes itself."
    },
    "phone": {
      "type": "string"
    }
  },
  "required": [
    "name"
  ]
}

What claiming a business on OEX involves, and how to start. Call this after check_business_health when the person wants to act on the findings inside OEX rather than only on their own website — claiming is what unlocks correcting the record, granting consent and verified rechecks. Read-only: it explains the process and returns the URL. You cannot claim a business on someone's behalf, and OEX will not accept an agent's word for who owns a business.

{
  "type": "object",
  "properties": {
    "businessName": {
      "type": "string",
      "description": "Optional — the business being asked about, echoed back for context."
    }
  }
}

What Business Health can actually inspect, fix, generate, verify and escalate — every check, what evidence it reads, what it needs before it will run, and what it offers as a fix. Read this before promising a business anything: it is the authoritative list of what OEX can do about a finding, and it distinguishes the checks that run for anyone from the ones that need a claim or a verified claim. Read-only, needs no account and no business, and answers even when the database is down.

{
  "type": "object",
  "properties": {}
}

Start here to try Business Health. Creates a synthetic business you may then operate, and returns its id. Sandbox businesses never appear in OEX search, the directory or any public count — they exist so the workflow can be walked end to end. Give it whatever characteristics the scenario you want to test needs; leaving fields out produces a business with gaps to find.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Trading name for the synthetic business."
    },
    "address": {
      "type": "string",
      "description": "Optional civic address."
    },
    "category": {
      "type": "string",
      "description": "Optional industry or category."
    },
    "description": {
      "type": "string",
      "description": "Optional description of what it does."
    },
    "phone": {
      "type": "string",
      "description": "Optional phone number."
    }
  },
  "required": [
    "name"
  ]
}

List the sandbox businesses that exist, so you can resume working on one.

{
  "type": "object",
  "properties": {}
}

The full health report for a sandbox business: the headline, findings worth attention with an action each, invitations, what passed, and what could not be evaluated. The headline is categorical — OEX publishes no numeric health score, in any cycle.

{
  "type": "object",
  "properties": {
    "businessId": {
      "type": "string"
    }
  },
  "required": [
    "businessId"
  ]
}

The same report as markdown — the form an owner would hand to whoever maintains their website.

{
  "type": "object",
  "properties": {
    "businessId": {
      "type": "string"
    }
  },
  "required": [
    "businessId"
  ]
}

Correct or complete the business's own record — the fix for most findings about missing or thin information. Supply only the fields you are changing; an omitted field is left alone, not cleared.

{
  "type": "object",
  "properties": {
    "businessId": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "address": {
      "type": "string"
    },
    "category": {
      "type": "string"
    },
    "phone": {
      "type": "string"
    }
  },
  "required": [
    "businessId"
  ]
}

Grant a purpose-scoped consent on behalf of the sandbox business. This is what an invitation in the report is asking for. The classes are separate on purpose: granting one never widens another.

{
  "type": "object",
  "properties": {
    "businessId": {
      "type": "string"
    },
    "consentClass": {
      "type": "string",
      "enum": [
        "listing",
        "operating_detail",
        "aggregate_use",
        "succession",
        "capability_profile",
        "purchasing_needs",
        "professional_escalation"
      ]
    }
  },
  "required": [
    "businessId",
    "consentClass"
  ]
}

Tell OEX the business's website so it can be inspected. Supplying a domain permits inspection; it does not assert that the business owns or controls it, and OEX will not publish the domain as the business's own on this basis alone.

{
  "type": "object",
  "properties": {
    "businessId": {
      "type": "string"
    },
    "domain": {
      "type": "string"
    }
  },
  "required": [
    "businessId",
    "domain"
  ]
}

Get an asset OEX generates from the business's own record: 'local-business-jsonld' or 'corrected-info-block'.

{
  "type": "object",
  "properties": {
    "businessId": {
      "type": "string"
    },
    "assetId": {
      "type": "string",
      "enum": [
        "local-business-jsonld",
        "corrected-info-block"
      ]
    }
  },
  "required": [
    "businessId",
    "assetId"
  ]
}

Record that work on a finding has begun — the owner opening the action. Moves the finding's action state, which is what makes its history readable later.

{
  "type": "object",
  "properties": {
    "businessId": {
      "type": "string"
    },
    "checkId": {
      "type": "string"
    }
  },
  "required": [
    "businessId",
    "checkId"
  ]
}

Record that the owner says a finding is fixed. This is their claim, not OEX's: nothing renders as resolved until a recheck runs and the check actually passes.

{
  "type": "object",
  "properties": {
    "businessId": {
      "type": "string"
    },
    "checkId": {
      "type": "string"
    }
  },
  "required": [
    "businessId",
    "checkId"
  ]
}

Ask OEX to look again — what a business does after fixing something. Inspects the website if one is supplied. Rate-limited, and a check that could not run is reported as unable-to-verify rather than as fixed.

{
  "type": "object",
  "properties": {
    "businessId": {
      "type": "string"
    },
    "checkId": {
      "type": "string",
      "description": "Optional: recheck one finding rather than all."
    }
  },
  "required": [
    "businessId"
  ]
}

The event history for a sandbox business: what was detected, what the owner reported, and what a recheck verified — with the timestamps that make the sequence auditable.

{
  "type": "object",
  "properties": {
    "businessId": {
      "type": "string"
    },
    "checkId": {
      "type": "string"
    }
  },
  "required": [
    "businessId"
  ]
}

For each public procurement notice whose requested categories overlap what this business has published, what about the business's OEX representation is in order and what is not. Every gap names the Business Health check that owns it, so the fix is the same one the health report already offers. Establishes category compatibility only: never qualification, eligibility, a supplier relationship, competitiveness, or any likelihood of award. There is no fit score and no probability, and asking for one will not produce one.

{
  "type": "object",
  "properties": {
    "businessId": {
      "type": "string"
    },
    "limit": {
      "type": "number",
      "description": "Optional, default 5. How many overlapping notices to assess."
    }
  },
  "required": [
    "businessId"
  ]
}

Run the Guided Business Study on a sandbox business: Business Health plus the three analytical instruments — Negative Space (what would be expected here and is not observed), Boundary Fracture (values that exist on one of the business’s own surfaces and never crossed to the other), and Strategic Node Finder (the one intervention that addresses several findings at once) — composed into one lineage-preserving result. Reads only the evidence OEX already holds; this tool never fetches the website. Every conclusion cites the evidence behind it, insufficient evidence returns explicit unknowns rather than guesses, and zero strategic nodes is a real answer.

{
  "type": "object",
  "properties": {
    "businessId": {
      "type": "string"
    },
    "objective": {
      "type": "string",
      "description": "Optional: what the business is trying to accomplish, in its own words. Carried into the study."
    },
    "inspectWebsite": {
      "type": "boolean",
      "description": "Optional, default false. Inspect the website on record before running, so the stages that compare the site against the record can actually look. Costs one bounded fetch of the claimed domain; without it those stages honestly report that nothing was inspected."
    }
  },
  "required": [
    "businessId"
  ]
}

The same Guided Business Study as a markdown document — the form a study is handed over in, with each stage’s findings beside its own evidence table.

{
  "type": "object",
  "properties": {
    "businessId": {
      "type": "string"
    },
    "objective": {
      "type": "string",
      "description": "Optional: the business’s stated objective."
    },
    "inspectWebsite": {
      "type": "boolean",
      "description": "Optional, default false. Inspect the website on record before running, so the stages comparing the site against the record can look. Costs one bounded fetch."
    }
  },
  "required": [
    "businessId"
  ]
}