Query Engine — Tool Reference

Use this tool FIRST to plan your query strategy before calling any data tool. Reason about which tools to call, in what order, and why. Identify if tools can run in parallel (no dependencies) or must be sequential (one tool needs another's output).

Search and filter compute infrastructure facilities (data centers, semiconductor fabs, packaging plants, HPC centers). Returns facility details including power capacity, GPU count, owner, status, and location.

Get complete details for a specific facility including all relationships, investments, nearby facilities, supply chain connections through owner org, and compute capacity timeline. Use when you need the full picture of a single facility.

Find facilities within a radius of a geographic point. Useful for geographic clustering analysis or finding what infrastructure exists near a specific facility.

Search for organizations (companies, governments, labs) in the AI compute ecosystem. Returns org profile including financials, type, country HQ, and description. Supports fuzzy name matching via aliases.

Get a complete organization profile: financials (revenue, capex, market cap), facility portfolio (count, total power, total GPUs), supply chain summary (top suppliers, top customers), and investment history. For deep dives on a single company.

Get ranked list of organizations by a metric. For competitive landscape analysis and identifying the biggest players.

Get upstream suppliers and/or downstream customers for an organization. Returns supply chain links with product/service, criticality score (1-10), value, sole-source status, and alternative suppliers.

Identify supply chain chokepoints: organizations that are sole-source suppliers in critical categories, have high criticality scores, or serve many customers with no alternatives. Essential for supply chain risk and exposure analysis.

Analyze a country's dependency on foreign suppliers in the AI compute supply chain. Returns total links, foreign dependency percentage, sole-source foreign dependencies, and critical foreign suppliers by category.

Get the complete supply chain graph with all edges. Returns supplier/customer org details, product/service, category, criticality, value, and sole-source status. Use sparingly — returns a large dataset.

Search investments in AI compute infrastructure: CHIPS Act grants, sovereign AI programs, hyperscaler capex, VC/PE rounds, government loans. Returns amounts, dates, programs, and linked facilities/orgs.

Get investment aggregations over time — monthly totals, counts, and breakdowns by type. For trend analysis of compute infrastructure spending patterns.

Get government AI investment programs including announced amounts, disbursed amounts, GPU details, key partners, and interdependence analysis. For analyzing sovereign AI capabilities and dependencies.

Get BIS Entity List entries and other export control designations. Returns entity names, countries, designation dates, grounds for listing, and Federal Register citations.

Cross-reference BIS Entity List designations against organizations in the Scrutica database. Uses 4-layer fuzzy matching (exact name, alias, Jaccard similarity, trigram). Returns matched organizations with facility count, supply chain connections, and match confidence score.

Get aggregated compute infrastructure statistics by country: facility count, total power MW, total GPU count, total FLOPS, organization count. For country-level comparisons and rankings.

Get high-level platform statistics: total facilities, total organizations, total investments, total power MW, total GPU count, countries covered. For overview and summary responses.

Get count and capacity breakdown by facility type (hyperscale DC, colocation, logic fab, memory fab, packaging, HPC, etc.). For understanding the composition of global compute infrastructure.

Side-by-side comparison of facilities, organizations, or countries. Returns a structured comparison with all relevant metrics aligned. For direct comparison queries.

Search the hardware catalog for GPU, TPU, ASIC, and interconnect specifications. Returns compute performance (FP16/FP32/BF16 TFLOPS), memory, TDP, process node, and export control status. For comparing chip specs or identifying which hardware is export-controlled.

Search compute deployments: GPU clusters, training runs, cloud regions. Returns hardware type, GPU count, cluster name, training FLOPS, organization, and linked facility. For understanding who is deploying what compute where.

Get cloud GPU pricing data by provider, hardware type, region, and pricing model. Returns price per GPU-hour for comparison across cloud providers.

Query bilateral semiconductor trade flows (HS 8542 integrated circuits). 397K records from UN Comtrade (25 reporters), CEPII BACI (231 reporters), Taiwan Customs, China GACC, and Japan e-Stat. Covers 2010-2026. Use this to answer: "How much did China import from Japan in 2023?", "Show US chip exports to China over time", "Which countries does Taiwan export the most ICs to?"

Query the PJM interconnection queue (6,093 entries). Shows planned and active power projects in PJM territory (Northern Virginia, Ohio, Maryland, Pennsylvania — the densest data center corridor in the world). Use this to answer: "How much power is queued in Virginia?", "What DC-region projects are active?", "Show PJM queue by state."

Get temporal compute capacity snapshots for facilities. Shows how capacity changed over time (GPU additions, power upgrades, new phases). Use this to answer: "When did xAI Colossus add GPUs?", "How has TSMC fab capacity changed?"

Look up compute-threshold regulatory compliance status. Three modes: (a) pass `model_name` to see which active regimes (EU AI Act 10²⁵, China CAC ~10²⁴, rescinded US EO 14110 10²⁶) a specific frontier model crosses; (b) pass `regime_id` to see the regime details and which models exceed it; (c) pass neither for a global summary (counts above each major threshold). Sources: Epoch AI Notable AI Models dataset (authority tier 2, all model FLOP estimates are estimates — `is_estimated: true`); regulation text and authority tiers per regime.

Rank facilities by nameplate power capacity within the jurisdictions affected by a regulatory regime. Use this for the structural question "which facilities have the physical compute capacity to support a model that triggers regulatory obligations under regime X" — the model-level question is `get_threshold_compliance`. Returns facilities with power_capacity_mw, total_gpu_count, owner country, and is_estimated flag. NOTE: this is capacity-listing, NOT a deterministic FLOP-capable claim — facility-level FLOP-capability requires the power-path methodology described in the system prompt (PUE, MFU, GPU fraction of IT, etc.). The LLM must reason from power capacity to FLOP plausibility itself, not assert "this facility CAN train a 10²⁵ model".

Get the Compute Visibility Index — a per-country capacity-weighted distribution of facility-operator transparency tiers (Tier 1 public-filing UBO; Tier 2 licensed-database-sourced; Tier 3 documented-but-secondary; Tier 4 operator named, chain opaque; Data_Gap operator not yet investigated). Pass `country` (ISO2) for one country's breakdown; omit for the global summary plus top-10 countries by capacity. The Index is the source of truth for "Compute Under Control" estimates by country. Backed by `mv_compute_visibility_by_country` and the `visibility_index_snapshots` table (snapshot citation handle: `scrutica:compute-visibility-index:YYYY-MM-DD`).

Per-facility tier breakdown for a given country — every facility with its assigned visibility tier (Tier_1 / Tier_2 / Tier_3 / Tier_4 / Data_Gap) and the tier_reason string explaining the classification. Use after `get_compute_visibility_index` to drill into the facilities driving a country's tier mix. Sorted by power_capacity_mw descending.

Walk an organization's ownership chain upward toward the documented ultimate beneficial owner (UBO). Returns the ordered hops (max 10) with per-hop provenance: data_source on the connecting edge, confidence (HIGH/MEDIUM/LOW), as_of_date, source_class (public_filing / private_database / other), and the opacity classification on termination (terminus_listed / terminus_government / terminus_self_reference / terminus_max_hops / terminus_cycle). Use this for "who ultimately owns X" questions and for tracing PE-fund chains to their LP base. Citation: cite each hop's edge_data_source individually — the chain itself is not a single source.

Search the Scrutica sovereign-execution procurement substrate (USAspending federal contracts, simpler.grants.gov federal solicitations, EU TED tenders, Korean MSIT awards, manual curations). One row per primary record; the record_type column distinguishes solicitation / award / subaward / modification / cancellation. Returns the per-record classifier breakdown (confidence + category + ai_relevance + reasoning) plus the per-component authority tiers (announced / committed / disbursed / deployed_chip / deployed_facility / deployed_utility) so the LLM can cite the MIN-of-inputs composite tier per the classifier methodology. Use for queries like "DoD AI contracts in Q4 2025", "EU Tier-1 frontier-AI tenders", "FedRAMP awards classified as training_compute", "awards over $10M with confidence above 0.9". The substrate is updated by the ingest crons (sovexec-usaspending weekly, sovexec-fed-solicitations daily, sovexec-eu-ted daily, manual MSIT) and resolves awardee names against organization_aliases at write time.

Per-country, per-stage rollup of sovereign procurement execution (announced → committed → disbursed → deployed). Backed by the executed_allocations denormalized table (trigger-maintained on procurement_records writes) plus a read-side accessor that re-derives mean classifier confidence and the SWF-pattern execution_stage_note narrative on read. Returns the disclosure_state classification (with_records / disclosed_zero / structurally_undisclosed / no_ingest_yet) so the LLM can frame Saudi PIF / UAE Mubadala / Singapore Temasek / Norway GPFG style structural-non-disclosure correctly rather than as data gap. Composite authority tier is computed MIN-of-inputs per the classifier methodology (a tier-1 facility-evidence claim does NOT inflate a tier-3 chip-allocation press report into a tier-1 deployed assertion). Use for queries like "Saudi sovereign AI execution by stage", "compare announced vs deployed for top sovereign programs", "Korean MSIT FY2024 disbursement". For per-record drill-down use search_procurement_records.

Read-only access to the admin classifier-review queue and its append-only audit log. Surfaces unresolved records (resolved_at IS NULL) flagged by the trigger for confidence_below_threshold (<0.7), category_unclassifiable, authority_tier_min_4, or operator manual_flag. Joined with procurement_records on the procurement_record_id PK. The audit log captures every admin action (approved / rejected / reclassified / manual_data_added / manual_flag) with prior_state + new_state JSONB diffs; pass include_audit_log=true to fetch the joined audit trail per record. NOT a mutation surface — write paths remain admin-UI-only at /admin/classifier-review. Use for "unresolved review-queue entries", "records flagged below confidence 0.5", "audit log for record X", "records re-classified in the last week".

Simulate the structural reach of a hypothetical BIS Entity List addition (or other designation type). Given a seed organization, computes the affiliate-graph closure (downward through SUBSIDIARY/JV/AFFILIATE edges, max 4 hops), the facilities operated/owned by entities in that closure, country distribution, sovereign-LP exposure breakdown (PIF, Mubadala, Temasek etc. with disclosed dollar amounts), and coordination-gap classifications. Returns an ImpactReport: closure size, affected facility count, total power MW + H100-equivalent GPUs, country rollups, sovereign-LP breakdown. NOT a legal interpretation — see caveats[] in the result. NOT a prediction of BIS behavior — structural reach only. Use this for "if BIS designated X, what would be caught" pre-decision analysis.

Run a supply-chain cascade-propagation simulation given a named perturbation (e.g., "TSMC Fab 18 offline 30 days", "ASML disrupted", "Tokyo earthquake"). Returns the propagated impact graph: affected nodes, weighted edge dynamics, inventory-buffer absorption, substitution paths, and historical-backtest comparison rows where the same shock pattern has resolved before. Wraps `src/lib/data/cascade-dynamics.ts` (`buildEdgeDynamics`, `getInventoryBufferDefs`, `getSubstitutionPathDefs`, `HISTORICAL_BACKTESTS`) + `src/lib/data/cascade.ts` (`getCascadeGraphData`). Provenance: cascade parameters carry `is_estimated: true`; the historical-backtest rows cite calibration events (Korea-Japan 2019, Renesas Naka 2021, Hsinchu 2024) with primary-source attribution.

Return the structured scenario data for one of Scrutica's five named scenario models. (1) tokyo-earthquake — `src/lib/data/tokyo-earthquake-data.ts` (memory-fab concentration, seismic intensity-MMI scoring, compound NankaiTrough/Mt-Fuji scenarios, historical-disruption table). (2) iran-threat — `src/lib/data/iran-threat-data.ts` (missile/drone systems, launch sites, air-defense profiles, strike impacts on Saudi DCs). (3) scs-cable — `src/lib/data/scs-cable-data.ts` (submarine cables, landing stations, incident-attribution status, rerouting scenarios, chokepoint zones). (4) taiwan-strait — `src/lib/data/taiwan-strait-data.ts` (TSMC fab facilities, substitution paths, Chinese pathway timelines, Korea-Japan 2019 calibration). (5) abqaiq — `src/lib/data/abqaiq-data.ts` (Saudi DC + petroleum-facility shared substations, attack scenarios, air-defense gaps). Each scenario carries source URLs at the underlying data-module level; cite the specific exported constant when summarising (e.g., "MEMORY_FABS at tokyo-earthquake-data.ts:12").

Compute EU AI Act 10²⁵ FLOP-threshold compliance for a facility or org, with the full power-path derivation transparent in the result. Walks: nameplate MW → PUE-adjusted IT load (default 1.15) → GPU fraction of IT (0.49) → MFU (0.40) → H100-equivalent count → days-to-threshold. Returns the input parameters, intermediate values, and threshold-crossing verdict. Wraps `src/lib/data/eu-threshold-data.ts` (`computeThresholdCrossings`, `THRESHOLD_MODELS`, `JURISDICTION_PROFILES`) + `src/lib/data/governance-thresholds.ts` (`GOVERNANCE_THRESHOLDS`). Distinct from `get_threshold_compliance` (which is model-centric and uses Epoch-seeded model FLOP estimates) — this is facility-centric and uses the nameplate-power-to-FLOP derivation methodology v1.3.0.

Return $/petaFLOP-day broken down by cloud provider, GPU type, region, and pricing model. Computes the normalisation across AWS, Azure, GCP, Oracle, CoreWeave, Lambda from `src/lib/data/pricing.ts:getCloudPricing()` (the cost-index data layer). On-prem TCO 3yr/5yr surfaces alongside as the build-vs-buy boundary. Source per row: provider pricing-page snapshot date + Epoch ML hardware spec (dense BF16 TFLOP/s; no 2:4 sparsity). Filter via params; omit all to return the global rollup. Distinct from `get_compute_pricing` (which returns raw $/GPU-hour cells) — this returns the petaFLOP-day-normalised, throughput-aware rollup.

Return the methodology block for a Scrutica page. Wraps `src/lib/data/page-descriptions.ts:getPageDescription(route)` (canonical per-page metadata: title, audience-block prose, methodology, source list, authority-tier breakdown). Use for "how does Scrutica calculate X?" — returns the actual current methodology text rendered on the page, not a paraphrase. Cite the route + the specific methodology section when summarising.

Return one labeled methodology subsection from the /methodology page. Wraps the methodology page's structured data layer + section anchors (e.g., "validation-6", "flop-estimation-bounds", "cascade-criticality-weighting", "threshold-derivation"). Distinct from `get_page_methodology` (which returns a single page's full methodology); this drills into a specific named subsection within /methodology.

Return the rendered prose content displayed on a Scrutica page. Wraps `src/lib/data/page-descriptions.ts:PAGE_DESCRIPTIONS[route]` — the canonical per-page metadata (title, short description, long description, audience-block variants for technical / policy users, OG image slug, category, source list). Use for "what does the [page] currently say about [topic]?" — the model retrieves the rendered prose then summarises against the user's question. Distinct from `get_page_methodology` (which returns just the methodology block); this returns the displayed body content.

Return the N most recent rows from the corrections log — Scrutica's public log of substantive data corrections (wrong-value fixes, methodology revisions, source-attribution corrections). Wraps `src/lib/data/corrections.ts:CORRECTIONS`. Each entry: id, correction_date, affected_path (route), prior_state, corrected_state, root_cause, source_url, authority_tier. Use this to answer "what's been corrected recently?" with verified post-correction values, NOT to surface uncorrected drafts. The corrections layer is the audit trail of the platform's "verify, never hedge" discipline.

Full-text search the corrections log. Wraps `src/lib/data/corrections.ts:CORRECTIONS`. Use for "has Scrutica corrected anything about [entity X]?" — searches across affected_path, prior_state, corrected_state, root_cause prose. Distinct from `recent_editorial_corrections` (chronological); this is keyword-driven.

Return per-data-source freshness state — when each substrate was last refreshed, the freshness-class TTL, and the current freshness color (fresh / aging / stale). Wraps `src/lib/freshness.ts` (`FreshnessClass`, `FRESHNESS_TTLS`, `computeFreshnessLevel`). Freshness classes: regulatory (4h TTL, e.g., BIS Federal Register feeds), market (24h, e.g., trade flows), structural (90d, e.g., facility ownership), narrative (365d, e.g., historical scenarios). Use for "how fresh is the [layer] data?" or "what's overdue for refresh?".

Return the authority-tier provenance metadata for a facility record: data_source, source_url, is_estimated, authority_tier, data_vintage, confidence_score (where applicable). Wraps `src/lib/data/data-quality-flags.ts:getDataQualityFlagsForFacility(facilityId)`. The Tier 1-4 hierarchy: Tier 1 = primary measurement / regulatory filing, Tier 2 = research database, Tier 3 = press / analyst, Tier 4 = inferred / estimated. The Citations Panel UI consumes this output to render per-claim provenance badges. The system prompt instructs the model to call this tool whenever a tool result lacks provenance fields needed to complete a citation.

Return the layer-by-layer anatomy of the AI compute supply-chain chokepoint structure — the "hourglass" shape (many AI labs and materials at the ends, extreme concentration in fab/packaging/equipment in the middle). Wraps `src/lib/data/market-shares.ts` (HBM_SHARES, ADVANCED_FOUNDRY_SHARES, OVERALL_FOUNDRY_SHARES, EUV_SHARES) plus the rendered concentration summary at /chokepoint-anatomy. Each layer carries: concentration_level (moderate / high / extreme), summary_text, vintage, source. Use for "show me the supply-chain concentration map" or "where is the system most exposed?".

Return concentration metrics (HHI, top-N share, severity, governance leverage) for a given product/service category. Wraps `src/lib/data/emerging-chokepoints-analysis.ts:getEmergingChokepointAnalysis()` (`getTopChokepoints`, `getChokepointsByTrajectory`, `getChokepointExportData`, `WEIGHT_SCHEMES`, `getWeightSensitivity`). Categories include: HBM, advanced foundry, EUV lithography, photomask, photoresist, lead-frame substrate, optical interconnect, etc. The Herfindahl-Hirschman Index quantifies market concentration on a 0-10000 scale; HHI > 2500 = high concentration; HHI > 5000 = near-monopoly. Use for "which product categories are most concentrated?" or "how concentrated is HBM3 supply?".

Return the aggregated country profile — facility count + total power MW + total GPUs + total estimated PFLOP, sovereign program count + announced + disbursed, supply-chain dependency vector (top foreign suppliers per critical category), governance reach metrics (export-control jurisdiction, regime memberships). Wraps `src/lib/data/country-profile.ts:getCountryProfile(countryCode)` + `getAllCountryStackScores`. Use for "what's [country]'s compute posture?" — returns a single dense summary instead of stitching together 4 separate tools. Distinct from `get_country_analytics` (which returns just the per-country stat rollup); this returns the qualitative profile + structural-vulnerability narrative.

Return Scrutica's active emerging-chokepoint feed — supply-chain constraints currently elevated to watch / elevated / high / critical severity, with deadline-bound risks (e.g., "CoWoS capacity shortfall through Q4 2026", "EU power grid pre-emption Phase 1 begins 2026-09-01"). Wraps `src/lib/data/emerging-chokepoints.ts:EMERGING_CHOKEPOINTS` (`getChokepointsBySeverity`, `getChokepointsByCategory`, `getChokepointsWithDeadline`). Each entry: id, severity, category, summary, evidence, deadline (where applicable), affected_orgs, governance_leverage. Use for "what supply-chain risks are active right now?" or "what's elevated to critical?".

Search BIS annual country-licensing data (Bureau of Industry & Security export license approvals/denials by destination country, ECCN code, and approval status). 2,587 rows covering CY2018-2022. Wraps `src/lib/data/bis-license-actions.ts:getBisOverlayData` + `getBisCountryEccnDetail`. Each row: country (ISO3), year, eccn_code, approval_count, denial_count, return-without-action count, total_value_usd, friction_pct (denial+RWA / total), friction_tier (low/elevated/anomalous). Use for "what was the friction rate for chip exports to [country] in [year]?" or "which countries had anomalous friction on AI hardware ECCNs?". Note: BIS publishes this data annually; CY2023+ pending.

Return quarterly HBM (high-bandwidth memory) merchant market share by manufacturer. Wraps `src/lib/data/hbm-market-share.ts:getHbmMarketShareRows()` + `getHbmCanonicalShareByCell` (the per-quarter / per-product-tier / per-manufacturer share table). Manufacturers: SK Hynix, Samsung, Micron. Product tiers: HBM2E, HBM3, HBM3E. Sources: Astute Group, TrendForce, Yole Développement, manufacturer disclosures. Per-cell `is_estimated` + source_priority + data_vintage. Use for "what's the current HBM3E share split?" or "how have HBM shares moved since 2024?". Multi-source divergence is surfaced — the canonical-share-per-cell function applies the cn-source-priority resolution rule.

Return EU electricity grid capacity, HVDC interconnects, and per-country grid signal — the substrate behind sovereign-AI grid pre-emption analysis. Wraps `src/lib/data/eu-grid.ts:getEuGridChokepointData` (PyPSA-eur substations + transmission lines + HVDC interconnects). Per-country: nameplate generation MW, current draw MW, headroom MW, hyperscale-DC announcement count, announced power MW vs grid headroom, pre-emption-risk flag. Substrate: 16,564 records ingested 2026-05-09 from PyPSA-eur (TSO-disclosed network model). Sources: ENTSO-E, PyPSA-eur, per-country TSO disclosures. Use for "where is the EU grid being pre-empted by hyperscale buildout?" or "what's [country]'s grid headroom for AI compute?".

Return the recent-developments feed — Scrutica's timeline of substantive changes across the substrate (tenant changes, ownership transfers, capacity milestones, regulatory actions, incidents). Wraps `src/lib/data/recent-developments.ts:getRecentDevelopmentsForFacility` extended for global-feed access. Each entry: id, effective_date, title, body, data_source, source_url, confidence (high/medium/low), category (tenant_change / ownership_transfer / capacity_milestone / regulatory / incident / other), affected_facility_id (where applicable). Use for "what's changed in the last 30 days?" or "show me [country]'s most recent compute developments".

Return per-model training evidence — the multi-source per-model dataset Scrutica uses to cross-validate FLOP estimates against lab disclosures. Wraps `src/lib/data/training-evidence.ts` (`TrainingEvidencePageData`, `TrainingClaim`, `FacilityPowerEvidence`, `ChipAvailabilityEvidence`, `FinancialEvidence`, `SupplyChainEvidence`). Each model: training_claim (what the lab said), facility_power_evidence (where it ran, how much MW available), chip_availability_evidence (what hardware available + BIS export-control status), financial_evidence (capex / opex commitments), supply_chain_evidence (HBM / packaging / wafer availability), signal_status (consistent / insufficient / unknown). Use for "is [model]'s claimed FLOP budget consistent with the available facility / chip / supply-chain evidence?". Distinct from `get_threshold_compliance` (which returns regime-crossing verdict); this returns the underlying evidence chain.