Tools reference

The complete catalog of the tools the assistant can call, grouped by category. For each tool: what it does, the key parameters, what the result carries (the audit fields), and the honesty guards built into it. Defaults are always disclosed in answers when the assistant chooses them.

Scene control

Actions on the console UI. These are deterministic state changes, not calculations; every result reports exactly what changed, including when an action changed nothing or matched zero assets.

select_node

Highlights a satellite or ground station on the globe. Resolves node ids, labels, and NORAD ids across the operator fleet and any active catalog constellation. Parameters: node_id (id or label). Result: the resolved asset (id, label, type, constellation for catalog objects). Guards: a miss returns not_found with a sample of real, currently visible objects and an activation hint (turn on the right constellation with set_constellations, then retry) instead of a dead end.

select_link

Highlights a link between two nodes: a satellite-to-gateway fronthaul or an inter-satellite link. Parameters: source, target (endpoint ids or labels, order-independent). Result: the resolved link (source, target, link type), or not_found naming both queried endpoints.

clear_selection

Clears the globe selection. No parameters.

seek_time

Jumps the simulation to a UTC timestamp or an elapsed-seconds offset within the scenario window. Parameters: utc (ISO-8601) or elapsed_seconds. Result: the applied instant, the elapsed seconds, and a clamped flag when the request fell outside the scenario window and was clamped to it.

set_playback

Pauses, resumes, or changes the playback speed. Parameters: playing (boolean), speed (one of 1, 5, 10, 30, 60). Guards: unsupported speeds return an error listing the valid options; a call that requests nothing returns noop.

set_timeline_mode

Loads or replays a fleet: replay runs the deterministic replay window, live connects live telemetry, demo loads the bundled demo fleet. Activates the fleet if the globe is empty. This is the first step of any simulation, replay, or over-time request: without it there are no links and no timeline frames. Parameters: mode (replay, live, demo).

set_camera

Moves the globe camera. view=globe for a whole-earth overview, view=point to frame a location (lat, lon, optional altitude and camera range), view=region to frame a bounding box (minLat, maxLat, minLon, maxLon).

set_layers

Toggles globe layers and visual style: link lines, node labels, sky glow, earth style (realistic, operational, dark, tactical), and scene mode (2d, 3d). Only the passed fields change. Result: which layers changed and the resulting layer state.

open_panel

Opens a side panel (search, gallery, assets, settings, tips) or closes panels (close).

set_filter

Narrows the operator fleet by physical catalog attributes: NORAD ids, object types (payload, rocket body, debris, unknown), orbit classes (LEO, MEO, GEO, HEO), inclination and altitude ranges, countries, statuses, and tags. Only matching satellites stay visible. An empty object clears the filter. Result: honest match counts, matched of total ("142 of 648 match", "0 match"). Guards: the filter has no constellation field. Any request naming a constellation other than the operator fleet routes to set_constellations instead; filtering the operator fleet by a foreign constellation name would empty the globe.

set_constellations

Shows, isolates, or hides catalog constellation groups (Starlink, Kuiper, Iridium, GPS, Galileo, GEO comms, and others). mode is show (add alongside what is on), only (just these), or hide. Parameters: groups (names or catalog group ids), mode. Result: activated and deactivated groups, the active object count, groups that hit the display cap, and names that matched nothing. Guards: the operator fleet is always-on and is never passed here. Catalog objects carry orbital elements but no telemetry, links, or predictions, and reads on them say so.

Scene reads

Reads before actions. The assistant prefers reading over guessing, and entity reads return the asset's source, capabilities, and eligible analyses so the next step is grounded.

get_scene_state

The current globe scene: playback state, the scenario time window, asset counts by type, and the unified registry rollup scene_graph.assets_by_source (oneweb, gsaas, catalog, import, chat, synthetic) with the active catalog groups. satellites_visible is the total across every source and is the authoritative answer to "how many satellites are shown".

get_fleet_summary

Fleet-wide rollup for high-level questions: counts by type, health buckets, node and link utilization and latency percentiles, capacity totals, at-risk assets with reasons, and link-type and constellation breakdowns. Covers the operator fleet; the active catalog overlay groups and their object counts are reported separately so display-only objects are never conflated with fleet health.

get_entity_detail

Authoritative detail for one asset or link. Parameters: target (node id, label, or NORAD id; for a link, source__target). Result: for a satellite, orbital elements (classification, apogee, perigee, inclination, period, velocity, RAAN, anomalies), sunlit or eclipse state, live position, and connectivity; for a ground station or data center, telemetry, position, and connected links; for a link, the budget (SNR, margin, latency, capacity). Catalog objects carry full orbital detail from their TLEs but no telemetry or links, and the result says so. Guards: misses return not_found with a sample of valid objects and an activation hint.

Statistics, trends, and breakdowns

The deterministic analytics core. All three tools share one property vocabulary: link_latency_ms, link_utilization, link_snr_db, link_margin_db, link_capacity_gbps, link_throughput_gbps, link_reliability, node_utilization, node_capacity_gbps, node_queue_depth_gb, altitude_km, rain_rate_mm_hr (plain aliases like latency, snr, margin, throughput, altitude are accepted). All three honor the active filter, operator scope, the sim clock, and any active what-if scenario.

query_fleet_statistics

A deterministic statistic over the current fleet snapshot, for any "what is the stat of property" question. Parameters: property; operators, any of min, max, mean, median, p50, p90, p95, p99, stddev, sum, count, outliers, confidence (default mean plus percentiles). Result carries: the value(s), the exact scope (operator, filter state, timeline mode, timestamp), sample_size of denominator, excluded count with the exclusion rule, units, a low_sample flag (under 8 samples, percentiles unreliable), outlier_count (IQR rule), a 95 percent confidence band, a histogram, and the actual included and excluded samples so the answer is traceable to the telemetry. method and calculation quote the exact derivation, down to the two sorted values a percentile interpolated between. Guards: demand-family properties (anything matching unserved, demand, congestion, blocked) are refused with a deterministic wrong_tool result that redirects to analyze_network_capacity; throughput is never substituted for demand. Zero-sample scopes are reported with the reason, never papered over.

query_fleet_trend

The over-time version: the operator applied to the property at each replay or live frame, returned as a reproducible series plus a line chart. Parameters: property; operator (single, default p90); window_minutes (trailing window; omit for the whole timeline). Result carries: the exact window (start and end UTC, covered versus requested span, frame count, step), per-point sample sizes, and a summary (min, max, mean, latest, delta). Guards: a window that exceeds available data is flagged truncated with the real coverage, never padded. The demo replay window is about one hour, so a "last 24 hours" request truncates to what exists and the answer states that.

query_fleet_breakdown

A per-group breakdown: the statistic computed separately for each value of a grouping dimension, ranked worst-first, with a bar chart and a table of every group's value and sample size. Parameters: property; operator (single, default p90); dimension; optional groups to restrict to named segments for an A-versus-B comparison (for example Ka versus Ku, or two station names). Dimensions must match the metric's source: link metrics group by ground_station, satellite, link_type, spectrum; node metrics group by node_type, health, orbit_band, region. Result carries: each group with its value and sample size, total sample size, how many candidates lacked the value, and a truncation note when only the top groups are shown. Guards: a link-versus-node dimension mismatch is reported, not guessed. There is no geographic globe heatmap layer; "heatmap" requests get the ranked per-group breakdown and the answer says a map overlay is not available.

Charts

query_chart

Builds a chart from live fleet data (the preferred chart path). Picks nodes or links, a metric (utilization, latency_ms, capacity_gbps, altitude_km, count), grouping, top-N, and sorting. Parameters: title, chart_type (bar, horizontal_bar, stacked_bar, line, area, scatter, pie, donut, radar, histogram), source (nodes or links), metric, plus optional group_by, node_type, top_n (default 14), sort, stacked, value_format, axis labels. Guards: an empty result is reported as no_data, never as an empty chart.

render_chart

Renders a custom chart when exact labels and values are already computed (multi-series, scatter points, radar). Label count must match every dataset's value count; invalid specs are rejected.

render_fleet_chart

Fleet preset charts: link_latency_percentiles, link_latency_p90 (single-snapshot bar), link_latency_p90_over_time (line over sim time), link_latency_histogram, link_utilization_percentiles, node_utilization_percentiles.

Import and integration

import_fleet_assets

Parses CSV or JSON fleet or telemetry data (for example an attached file) into first-class user assets on the globe and in the asset browser. propagate_hours spreads single-point rows across the simulation window. Result: exactly how many assets were created, or the parse errors. Nothing is imported silently.

get_integration_bundle

Returns the operator API integration bundle for edge agents or IDE automation, as JSON, an IDE rule, or an install command. Guards: requires a signed-in account with an API token created under Settings; unavailable otherwise, with instructions. Not offered to guests.

What-if scenario mutation

simulate_gateway_outage

Deterministically models a gateway outage and how fronthaul traffic redistributes. Selects gateways by country name, region code, or explicit node ids; mode is disable (flag offline) or remove. Result carries: every affected satellite (re-homed to a surviving gateway, or orphaned with no coverage) plus before and after fleet statistics. While the scenario is active, all fleet analytics tools compute under it automatically. Guards: if zero gateways match the selector, the result says so plainly and the assistant stops; it never invents a hypothetical gateway or traffic figures. Results are modeled: fronthaul links are geometrically re-derived and may differ from replayed store links, and the globe is not re-rendered ("modeled under scenario, globe unchanged").

list_scenario

Lists the mutations currently stacked on the active what-if scenario.

reset_scenario

Clears the active what-if scenario so analytics compute against the unmodified fleet again. Returns how many mutations were removed.

Mission design: synthetic assets

create_orbit_scenario

Synthesizes temporary, clearly labeled SYNTHETIC satellites from a mission request, propagates them deterministically with SGP4 over a window, and scores coverage against the ground-station network. Parameters: orbit_type (sso or custom, default sso), altitude_km (default 700), inclination_deg (custom orbits only; SSO inclination is auto-derived from the sun-synchronous condition), window_hours (default 12), step_seconds (default 60), min_elevation_deg (default 10), region (score coverage against just that region's stations), label, and the constellation shape: count (default 1, max 48), planes, phasing (walker default, or even), raan_spread_deg (default 360), walker_f (default 1; adjacent-plane mean-anomaly offset is f times 360 divided by count). Optional deterministic weather (below). Result carries: coverage percent, pass intervals with ground station and max elevation, the stations used, the assumptions (chosen and derived orbital elements, per-plane RAANs, the applied phase offset), and the exact calculation. Constellation results add combined coverage (a sample is covered when any satellite sees any station), per-satellite coverage, the single-satellite baseline, and the coverage delta. Guards: never refuses for missing parameters; nominal defaults are chosen and stated. Satellites are injected as first-class synthetic assets through the same pipeline uploaded TLEs use; the only difference is provenance, always disclosed.

create_ground_station_scenario

Places a temporary, labeled SYNTHETIC ground station at a lat/lon and deterministically evaluates its utility against the currently enabled fleet. Parameters: lat, lon (required; for a named place the assistant picks representative coordinates and states them as an assumption), label, min_elevation_deg (default 10), window_hours (default 12), step_seconds (default 60), count_antennas (recorded as an assumption only). Optional deterministic weather. Result carries: contact percent (share of the window with at least one satellite in view above the mask), total contact minutes, per-satellite passes with max elevation, the longest idle gap, satellites evaluated versus excluded with the exclusion rule, and the calculation. Guards: satellites with no propagable TLE are excluded and counted, never fabricated. The station is injected through the same tabular import pipeline uploaded ground stations use (globe, detail panel, Ka fronthaul access links); the only difference is the SYNTHETIC provenance label.

Ground network optimization

optimize_ground_network

Goal-oriented site selection over the current scene satellites, with an explicit objective:

Objective	Maximizes	Units
contact_time (default)	Aggregate satellite-gateway access minutes; every simultaneous visible pair-minute counts	satellite-access minutes
access_availability	Share of the window with at least one satellite-gateway link (eliminating blackout)	percent of window
redundancy	Share of the window covered by at least two selected stations (one-gateway-outage survivability)	percent of window

Parameters: objective; picks (exact number of sites to return; overrides the target and gain floor, and the search is never cut short because some other metric is saturated); target_coverage_percent (default 95, percent objectives only); max_stations (default 8); window_hours (default 12); step_seconds (default 60); min_elevation_deg (default 10); include_grid (also evaluate a deterministic, land-agnostic lat/lon grid); use_existing_network_as_base (keep the scene's stations and optimize additions; default is a green-field network from zero). Optional deterministic weather. Candidates are real sites: the GSaaS provider catalog (KSAT, AWS Ground Station, Leaf Space, SSC, Atlas, Viasat, RBC Signals, Skynopy), the operator gateways, and the scene's uploaded or synthetic stations, plus the optional grid. Result carries: the objective in its own units; constraints; baselineMetrics versus finalMetrics (total access minutes, per-satellite min/median/mean access minutes, mean simultaneous links, access availability percent, redundancy-2 percent); every pick with its marginal gain in the objective's units plus unique-satellite-minutes so overlap is visible; every rejected candidate with its reason; the candidate ledger (pool by source, minus exclusions, equals evaluated, equals picked plus rejected); the scene-scope note; excluded satellites with the exclusion rule; assumptions; and the exact calculation. Weather runs add clear-sky versus degraded availability. Guards: saturationNote states when access availability is already saturated, and a zero-gain claim exists only when zeroGainProof proves it in the objective's own units. Grid candidates ignore land and infrastructure feasibility and every result repeats that caveat. Unreached percent targets are reported as not reached with the stop reason. The tool evaluates sites without injecting anything into the scene.

compare_candidate_sites

Deterministically compares 2 to 8 candidate sites against the same propagated satellite tracks and ranks them by contact percent. Parameters: sites (each label with optional lat/lon; a bare label resolves as an existing station against the scene, the operator gateways, and the GSaaS catalog), plus window, step, elevation mask, and optional weather. Result carries: the full ranked table (contact percent, contact minutes, passes, per-satellite utility, longest idle gap) scored with the same SGP4 and elevation-mask geometry as every coverage figure, the tiebreak rule, assumptions, and the calculation. Guards: unresolved names are reported, never guessed. Never a bare "pick A".

Beam planning and frequency reuse

Deterministic RF payload design over a satellite's visible footprint. All six tools share anchor resolution (a named satellite or NORAD id, the current selection, an explicit lat/lon plus altitude, or the first scene satellite, with the choice stated as an assumption) and all disclose two standing caveats: the demand surface is a synthetic population-weighted model, and the RF pattern math is an operational approximation (parabolic rolloff of 12 times the square of theta over theta3dB, DVB-S2X MODCOD efficiencies).

plan_beam_layout

Lays out hex-packed spot beams over the visible footprint, assigns a frequency-reuse coloring, computes per-beam SNR (center and edge), co-channel C/I, SINR, and DVB-S2X MODCOD capacity, then loads the beams against the demand surface. Parameters: anchor (satellite or lat/lon/altitude_km), beam_count (default 32), colors (3, 4, or 7; default 4), total_bandwidth_mhz (default 1250), layout (demand default, steering beam centers toward demand, or uniform), region, rain_rate_mm_hr. Result carries: served Gbps and the Jain fairness index versus the uniform layout, per-beam capacity range, the reuse coloring, assumptions, and the calculation.

compare_frequency_reuse

Compares two reuse plans (for example 4-color versus 7-color) on the same layout: total throughput, mean and worst co-channel C/I, edge-of-beam SNR, and per-beam bandwidth. More colors buy C/I isolation at the cost of per-beam spectrum; the result quantifies that tradeoff deterministically. Parameters: colors_a (default 4), colors_b (default 7), plus the shared anchor and RF parameters.

analyze_beam_load

Loads the beam plan against the demand surface and reports which beams are oversubscribed (offered above capacity) and which are underutilized (below 30 percent), with per-beam offered, served, and unserved Gbps, utilization, Jain fairness, and concrete recommendations: steer toward the demand centroid, split or narrow, merge adjacent underutilized beams, reallocate spectrum. Parameters: shared anchor parameters, layout (uniform default here so load imbalance is visible), region, rain_rate_mm_hr.

plan_beam_hopping

Schedules beam hopping across the footprint: largest-remainder apportionment of illumination slots proportional to per-beam offered demand, at most simultaneous_beams active per slot (default a quarter of the beam count), occurrences spread to minimize revisit gaps. Parameters: shared anchor parameters, simultaneous_beams, slots_per_frame (default 16), region. Result carries: dwell fraction and served Gbps per beam, total served versus offered, max revisit gap, and starved beams, never hidden.

scale_beam_count

Quantifies changing the spot-beam count (for example 32 to 64) at the same total transmit power: per-beam EIRP stays roughly constant (narrower beams gain directivity as per-beam power drops), so the change comes from reuse density, per-beam bandwidth, and edge SINR. Parameters: from_count (default 32), to_count (default 64), plus the shared anchor and RF parameters. Result carries: capacity, aggregate spectral efficiency (bps/Hz), coverage, and per-beam numbers for both counts, with the derivation.

reshape_beams_over_pass

Adaptive beamforming over the next orbital pass: propagates the anchor satellite forward, re-aims the pattern at the highest-demand cells in view at each step, and compares served demand against a static uniform pattern. Parameters: satellite (must be TLE-backed, any origin), window_minutes (default 100, one LEO revolution), step_seconds (default 120), plus beam parameters and region. Result carries: served Gbps-hours for both strategies, the improvement percent (a negative improvement is reported honestly), and per-step top cells. Long tracks are subsampled to a bounded step count, stated as an assumption.

Service availability and network capacity

Scene-scoped, deterministic, and engine-identical for fleet, uploaded, and synthetic satellites. Heavy runs execute off the main thread in the fleet worker.

analyze_service_availability

Service at a location for the current scene constellation: SGP4-propagates every satellite with usable elements over the window and reports service hours per day, coverage percent, the pass table, every gap with the longest and mean gap, and a per-hour 24 hour forecast (best SNR, estimated throughput via the DVB-S2X MODCOD table, propagation latency, outages). Parameters: location (a known city name resolved against the demand-model city table) or explicit lat/lon; window_hours (default 24); step_seconds (default 120); min_elevation_deg (user-terminal mask, default 25); rain_rate_mm_hr (default 0). Guards: the resolved coordinates and the elevation mask are stated as assumptions.

size_constellation_for_availability

Finds the smallest Walker constellation meeting an availability target over a location or region by sweeping candidate plane and satellite configurations deterministically (nothing is injected into the scene). Parameters: target_availability_percent (required), location or lat/lon, altitude_km (default 550), inclination_deg (default polar 90 for Arctic targets, else 53), max_satellites (sweep cap, default 48), window, step, elevation mask. Result carries: the minimal passing configuration with its margin, every candidate evaluated, and the remaining coverage risks. Guards: if no candidate within the sweep bounds meets the target, the result says so plainly with the best achieved.

analyze_network_capacity

Network-level capacity analysis of the current scene (satellites plus gateways) against the deterministic population-weighted demand surface. One serving model powers every focus: a demand cell is served at a sampled instant only when a satellite above the mask sees it and that satellite has a feasible gateway link; satellite and gateway capacities are hard caps; demand is assigned greedily. Parameters: focus (required), window_hours (default 6), step_seconds (default 120), demand_total_gbps (default 1000), region, max_picks (station placement, default 5), rain_rate_mm_hr, target_p95_latency_reduction_percent (latency focus).

Focus	What you get
unserved_demand	P50/P90/P95/P99 unserved Gbps with per-region cause attribution: coverage, gateway, or capacity
gateway_bottlenecks	Regions capacity-constrained by gateways rather than satellite coverage, with per-gateway utilization; the hottest gateways pulse on the globe
station_placement	Greedy ranking of real candidate ground stations by marginal unserved-demand reduction (congestion ROI); plays a candidate sweep on the globe
satellite_value	Leave-one-out marginal value per satellite, least valuable first, with the coverage, unserved, and latency deltas if removed
latency	The propagation-latency distribution over served cells and ranked levers to cut P95
sla_risk	Links most likely to violate margin over the next 6 hours under forecast rain, with rerouting suggestions
worst_regions	Worst served-versus-offered regions with root causes and the single highest-impact change

Result carries: the scope (epoch, satellites considered and excluded with the rule, gateway count), a deterministic confidence block, a visualization block when the console played something, the focus-specific analysis, assumptions, and the exact serving model. Guards: the demand surface is always disclosed as synthetic. satellite_value refuses scenes above 40 satellites (leave-one-out is quadratic) with instructions to scope down. Empty scenes return no_tracks or no_gateways with the fix, never a fabricated figure.

Saved scenarios

save_scenario

Persists the current mission sandbox as a named, reproducible scenario: the synthetic satellites and ground stations by their exact injection payloads (TLE text, station table content), the active what-if mutations, the current sim epoch, and the last-used evaluation config (window, step, elevation mask, weather). Saving an existing name overwrites it, and the result says so. Guards: synthetic assets that cannot be reconstructed into a payload are reported as skipped, never silently dropped.

load_scenario

Restores a saved scenario by name or id: removes the scene's current synthetic assets, resets the active what-if scenario, re-injects the saved payloads through the same import path, and re-applies the saved mutations. The result reports what was restored and the saved epoch; seeking the timeline there and re-running the saved evaluations reproduces identical numbers, because the engines are deterministic. Guards: unknown names come back with the available scenario names, never a guess.

list_scenarios

Lists saved scenarios: name, id, save time, saved epoch, and asset and mutation counts.

Deterministic weather (shared parameters)

create_orbit_scenario, create_ground_station_scenario, optimize_ground_network, and compare_candidate_sites accept optional deterministic weather; the beam and capacity tools accept a uniform rate.

• rain_rate_mm_hr: a uniform rain rate at every ground station.
• rain_regions: rain cells as lat/lon boxes, each with its own rate. Stations outside every box see 0 mm/h; overlapping boxes take the max rate.

Under weather, a sample only counts as covered when the Ka fronthaul link budget also closes under modeled rain attenuation (a P.618 approximation) at that sample's elevation, so low-elevation contacts are lost first. Results always report both clear-sky and degraded figures plus the samples lost to weather. There is no random weather: the rain field is exactly what was requested, and identical inputs reproduce identical results.

ML predictions

Production prediction backends, distinct from the deterministic engines. Availability and fidelity are plan-gated; see Safety and limits and /api/predictions.

Tool	Default tier	What it returns
predict_link_snr	bronze	Predicted SNR in dB, link margin, and confidence for a source-target pair at the current sim time
analyze_traffic_demand	bronze	Peak utilization, queue growth, and congested links over a horizon (horizon_minutes, default 60; link_type isl, fronthaul, backhaul, all)
forecast_weather_impact	silver	Rain rate, additional attenuation, and gateway availability for a ground station or gateway
detect_rf_jamming	silver	Interference classification, severity, bearing, and confidence, with an optional region hint
assess_collision_risk	gold	Conjunction probability, time to closest approach, and the recommended action for a satellite

Every tool accepts quality_tier (bronze, silver, gold, custom). Explicit requests are honored when the plan allows them; otherwise the tool's preferred tier is clamped down to the best tier the plan allows, and a request for an unavailable tier returns an explicit upgrade note rather than failing silently. Results render as forecast cards with the model tier and confidence stated.