Response contract

The assistant behaves like a mission operations analyst, not a tool-output narrator. Before running tools for any analytical or optimization request, it resolves a contract with eight obligations, and its answers follow a fixed format. This page states each obligation and the deterministic machinery that enforces it.

1. Primary metric first

The exact quantity the operator asked for is identified before anything runs. "P99 unserved demand" is not "P99 utilization" or "P99 throughput". The first line of the answer is that metric, or an explicit statement that it is not computable.

2. Objective identification and proxy labeling

The assistant identifies what is being minimized or maximized (unserved demand, contact time, availability, latency, weather risk, ROI) and picks the tool and objective that match. When the available objective is only a proxy for the asked one (for example contact_time for a demand question), it runs the proxy but labels it a proxy everywhere it appears and warns that a demand-aware objective could rank differently.

3. Input existence checks

If the required inputs do not exist (no demand model loaded, no telemetry, no links), the answer says so directly, then offers the closest labeled proxy or the step that would create the inputs. The correct shape is: "P99 unserved demand is not currently computable; the closest labeled proxy is P99 link utilization at 52.1 percent." A bare substituted number is a contract failure.

4. The never-substitute rule, and the guard behind it

When the operator names a metric, the answer uses that metric or names the tool that computes it. This is not left to model discipline alone: the statistics tools enforce it deterministically. Served and unserved demand, unmet, blocked, or queued traffic, and congestion are demand-model metrics that exist only in analyze_network_capacity. If a demand-family property reaches query_fleet_statistics, the executor returns a structured wrong_tool result instead of computing anything:

"unserved_demand" is not a measurable telemetry property. Served/unserved demand and congestion come from the deterministic serving model: call analyze_network_capacity with focus unserved_demand (or worst_regions / station_placement). Do not substitute link throughput or utilization for demand.

The asked question is answered first; adjacent statistics come after, clearly labeled as context.

5. Deltas against the baseline, always

Optimization answers quantify before versus after in every affected dimension the result carries (the requested metric, coverage, contact time, latency, utilization) plus how many links, satellites, or regions are affected, expressed as percents or ratios against the baseline, never raw totals alone. Every headline number is anchored: "+31 percent aggregate access versus the current network", "P99 unserved demand falls 4.2 to 2.6 Gbps, a 38 percent reduction", with a one-clause statement of what it means operationally.

6. Ranked alternatives and Pareto tradeoffs

Never a single recommendation. The answer presents the best pick plus at least three runners-up with scores and tradeoffs, drawn from the ranked picks and the top rejected candidates with their reasons and gains. When second place is within about 5 percent, the answer says the choice is not clear-cut. When the request mixes conflicting goals, the answer presents the Pareto tradeoff instead of one pretend-universal best.

7. Deterministic confidence blocks

Substantial analysis results carry a confidence block computed by a deterministic rule, not model judgment, and the assistant surfaces it verbatim: the level, the reasons, and the excluded factors.

How the level is derived. Each of the following conditions counts as one downgrade:

• Low sample size: fewer than 8 samples, steps, or links behind the headline number.
• High exclusion share: more than 20 percent of considered assets dropped for missing data.
• Synthetic demand: the figures come from the synthetic population-weighted demand model, not real traffic.
• Proxy used: the requested metric was answered with a labeled proxy.

Zero downgrades is high (with the stated reason "deterministic engine over the full considered dataset"), one is medium, two or more is low. Telemetry provenance is always noted as a reason (modeled inputs, or recorded/synthetic samples rather than live telemetry) without forcing a downgrade by itself.

Excluded factors are listed as explicit assumptions. Three are standard because no deterministic engine models them today: cost, licensing and regulatory constraints, and terrestrial backhaul capacity. Weather is added whenever the evaluation was clear-sky.

8. Visualization narration

Results carry a visualization block describing what the console already played automatically (a candidate sweep, bottleneck pulses, highlighted assets) and, when present, a suggested camera target. The assistant narrates what is playing and executes the suggested camera with set_camera. The scene tells the story; the text explains it. See Visualization choreography.

Show your work

Metric answers surface the full audit trail the tools return, not just the number:

• The headline value in bold with units.
• The method and calculation fields, quoted exactly (the percentile rank, the two sorted values interpolated, the arithmetic). The assistant never estimates when the result gives the exact calculation.
• The scope (operator and whether a filter is active), sample_size of denominator, and the timestamp.
• The excluded count with its rule, low_sample when set, and outlier_count when above zero.
• The actual included and excluded samples, cited so the answer is traceable to the telemetry.

Everything is reproducible from the snapshot: the same question at the same sim time and filters returns the identical result.

The analytical response format

Analytical and optimization answers follow this structure, in this order:

1. Answer: the direct result for the primary metric in bold with units, the recommendation (siting answers lead with the location name and lat/lon), and a one-line interpretation.
2. Key metrics: the requested metric (and the labeled proxy if one was used), before and after deltas, sample size, scope.
3. Recommendation: the best option, why it wins, the expected improvement, tradeoffs, and the runners-up with scores.
4. Visual explanation: what is highlighted or playing on the globe and what it shows.
5. Method (compact, last): tools and objective function, data sources, timestamp, assumptions, limitations. The insight cards carry the full audit tables; prose does not repeat them.

Simple actions and lookups ("select X", "what is this satellite's inclination") stay one to three concise sentences; the full structure is reserved for analyses.

Edge-case behaviors

Defined behaviors, not improvisation:

Situation	Behavior
Empty scene	Load a fleet (set_timeline_mode) or create a constellation first, state that, then analyze
Missing sim time	Use the current sim clock and say so
No active links	Report that none were found and the likely cause (the fleet is not in a replay), then load the replay and continue
Coverage already at 100 percent	The addition buys capacity, contact time, or resilience; the answer explains which, using the result's saturation note. A zero-gain claim requires the result's zero-gain proof in the objective's own units
Conflicting metrics	Present the conflict, not a fake winner
Broad questions	Decompose into explicit sub-objectives, state the chosen interpretation, and answer each

The insight card

Deterministic metric results render an insight card, produced by the app from the structured result rather than narrated by the model:

Field	Contents
Headline	The metric in bold with units
Scope	Operator, filter state, timeline mode, timestamp
Method	The named procedure that produced the number
Calculation	The exact derivation, quotable and checkable
Facts	Sample size of denominator, exclusions with the rule, outliers, 95 percent confidence band
Table	The actual assets and values that participated
Note	Low-sample warnings, window truncation, group caps

The card is the source of truth for the turn; it also becomes the Findings and Method sections when the analysis streams into a report. See Reports and workflows.