A person reading a report about an unfamiliar place applies an enormous amount of unconscious filtering. A number that seems too round gets a second look. A figure for a remote area gets discounted because the reader knows such places are poorly surveyed. A precision of four decimal places on an estimate reads as a warning rather than as rigour.
None of that filtering happens when the reader is a model. It receives a number, and a number is a fact. It will carry that figure into a calculation, compare it against another figure computed by an entirely different method, and present a conclusion in the same register whether the input was a direct measurement or a guess from sparse evidence.
This is not a reasoning defect that better models will grow out of. It is a consequence of the interface. If the response contains only a value, then only a value was communicated, and the scepticism a human would have supplied has nowhere to come from.
The reader who brings no priors
The gap is worth being specific about, because it determines what the response has to carry.
A human analyst knows that data density varies wildly by geography, and treats a figure for a well-surveyed city differently from the same figure for a rural district in a country with limited official statistics. A model has no such prior unless the response states it.
A human notices when precision exceeds plausibility. Three decimal places on a population estimate is a signal to a person and is invisible to a model, which will happily use every digit.
A human distinguishes a measurement from an inference by the vocabulary around it, by where it was published, by who produced it. Strip the surrounding context, which is exactly what an API response does, and the two are indistinguishable.
A human treats a suspiciously clean answer as a reason to check. A model treats a clean answer as a good answer, because cleanliness is not a signal it has any reason to distrust.
Every one of these is a form of context that a human supplies for free and that has to be made explicit for an automated consumer. Confidence marking is the compressed form of that context.
Three states, and why unknown is separate
Numeric confidence scores are tempting and mostly counterproductive. A figure of zero point seven three invites a consumer to do arithmetic with it, implies a calibration that almost never exists, and provides no guidance about what to actually do. The score becomes another number to propagate rather than a decision aid.
Three states carry most of the useful information and are far harder to misuse.
High confidence means the figure comes from a direct measurement or an authoritative record, and a consumer can use it as a fact. The evidence is sufficient that the remaining uncertainty is smaller than anything the decision turns on.
Low confidence means the figure is a real estimate with real support, but the evidence is thin, indirect, or old. A consumer may use it, and should say that it is an estimate, and should not build a precise conclusion on top of it.
Unknown means the system could not determine the quantity. Not that it is small. Not that it is zero. Not that it is average. The evidence does not support any estimate at all.
The third state is the one that gets collapsed, and collapsing it is the single most common way spatial and statistical APIs mislead automated consumers. Unknown and zero are opposite claims. Zero asserts a measurement: the thing was looked for and is not there. Unknown asserts an absence of measurement: nothing was determined either way. Representing both as the numeral zero destroys the distinction permanently, because no downstream consumer can recover it.
The spatial version of this has consequences that are easy to trace. A count of hospitals in an area returns zero. If that means the area was surveyed and has no hospital, it is a finding about healthcare access. If it means the area has no data coverage, it is a finding about the dataset. Coverage is worst precisely where infrastructure is sparsest, so the two get confused in exactly the places where the confusion does the most damage.
What happens downstream when unknown becomes a number
Coercion of unknown to zero is rarely a decision anyone makes. It happens by default, in a serialisation layer, in a database that stores a nullable column and reads it back with a default, in a client that treats a missing key as zero, in an aggregation that sums a column and skips nulls.
Trace it through a plausible chain. A model produces a per-district figure for some quantity, with unknown for the districts it could not determine. An aggregation step sums the districts to a regional total, treating unknown as zero. The regional total is now an undercount, and it is a valid-looking number with no marker on it. A comparison step ranks regions by that total. The regions with the worst data coverage rank lowest. A recommendation step reports that those regions have the least of the thing, which is a statement about data availability presented as a statement about the world.
At no point did any component fail. Every step did what it was written to do. The error entered at the first coercion and became untraceable one step later, because the type system was satisfied and the value was in range.
Averages behave worse than sums, because an average over a set containing coerced zeros is pulled towards zero without changing anything visible, and the result stays plausible. Ratios are worse again, since a coerced zero in a denominator produces either an exception or an infinity, and the exception handler frequently substitutes a default that has no meaning at all.
The defence is to make the coercion impossible rather than to catch it. If unknown is represented as a value of a different type, or as an explicit marker that arithmetic operations refuse to accept, then the coercion becomes a visible failure at the point it occurs instead of an invisible corruption that surfaces three steps later as a confident wrong answer.
A response shape that keeps confidence attached
The practical problem is that confidence gets separated from the figure it qualifies. A response carries a value in one place and a confidence summary somewhere else, and a consumer that extracts the value never sees the qualifier.
The structural fix is to make the value and its confidence the same object. Rather than a field holding a bare number, the field holds a small structure containing the value, its confidence state, and the provenance of the figure. A consumer that reads the field gets all three or none.
This has a property worth stating explicitly: a naive consumer that ignores the structure and tries to use it as a number gets a visible type error rather than a silently wrong result. That is the desired behaviour. Failing loudly at the point of misuse is much better than succeeding quietly with a number that has lost its qualification.
Several conventions make this work in practice. The confidence field should be present on every derived figure without exception, including the ones that are always high, because a field that is sometimes absent teaches consumers to treat absence as a default rather than as an error. When the state is unknown, the value slot should be absent or a null rather than a placeholder number, so that nothing numeric is available to grab. A response-level summary is fine as an addition and never as a replacement, since a consumer extracting one field will not read a summary elsewhere.
Aggregate figures need a rule for what confidence they inherit. The defensible default is the minimum across the inputs, since a total built from one unknown component is not high confidence regardless of how good the rest were. Where components were dropped, the aggregate should record how many, because a sum over four of nine districts is not comparable to a sum over all nine and nothing in the number says so.
Caveats that travel with the figure
Documentation is read by the developer who integrates the API, once, and it is not read at all by the automated consumer that will process ten thousand responses. Any qualification that lives only in documentation is a qualification that will not reach the point of use.
So the caveat has to travel in the response, attached to the specific figure it applies to. The ones that matter most are the ones that change how a number should be interpreted rather than merely describing where it came from.
Age is one. The response timestamp says when the API answered. What a consumer needs is when the underlying observation was made, because a figure derived from imagery captured two years ago is a claim about two years ago. Carry the acquisition date of the input, not the freshness of the cache.
Spatial and temporal unit is another, and it is routinely omitted. A density figure means nothing without the area it was computed over, and comparing a value computed per administrative district against one computed on a fine grid produces nonsense that looks like a finding. Attach the unit to the figure so that a consumer can refuse to compare incomparable things.
Provenance class matters more than provenance detail. A consumer does not need the full lineage on every call, but it does need to know whether a figure was observed, taken from an official record, or produced by a model. Those three carry different failure modes and a consumer that knows which one it has can weight accordingly.
Coverage is the caveat most specific to spatial work. A figure computed over an area with patchy input data should say so, because the alternative is that thin coverage reads as a real property of the place.
Each of these is small. Together they are the difference between a number a consumer can use responsibly and a number that will be used as though it were a measurement.
Refusing to answer is a feature
There is a natural pressure on any system to always return something. An empty response looks like a failure, a partial answer looks like a limitation, and the demo is more impressive when every query produces a result.
For an automated consumer, that pressure produces the worst possible outcome. An unqualified guess is indistinguishable from a measurement, and it will be used as a measurement. A refusal, by contrast, is information the consumer can act on: it can ask a different question, seek another source, or report to its own caller that the answer is not available.
Which means a refusal has to be modelled as a successful response carrying an unknown, not as an error. Errors invite retries. An agent that receives an error frequently tries again with adjusted arguments, on the theory that it asked badly, and a system that signals unknown as an error will generate repeated attempts at a question that has no answer. The same content returned as a successful response with an explicit unknown terminates the line of enquiry cleanly.
A refusal should also say what would change the answer. Whether the limitation is coverage, currency, or resolution tells a consumer whether to try a coarser question, a different area, or a different source. That is far more actionable than a bare unknown, and it costs one field.
The organisational difficulty is that refusal rate looks like a quality metric moving in the wrong direction. It is worth defining the metric the other way: the fraction of answers that were wrong and unqualified is the number that matters, and driving refusals to zero drives that number up.
The compounding problem
The failure that does the most damage is not a single low-confidence figure. It is several of them combined.
An agent answering a question of any complexity chains steps. It retrieves a figure, uses it to select a second query, combines that result with a third, and produces a conclusion. Each figure may be individually well qualified as low confidence. The conclusion frequently is not, because the qualification was consumed during the reasoning rather than propagated through it.
The mechanism is ordinary. Each intermediate step performs a small act of rounding or restatement. A figure marked as an estimate is described in the next step as a value. Two low-confidence figures are compared, and the comparison, which is a robust operation on shaky inputs, reads as more solid than either. By the third step the language has firmed up and no marker remains attached to anything.
The mathematical position is that combining uncertain quantities does not usually reduce uncertainty. A product of two uncertain factors has wider relative uncertainty than either. A difference between two uncertain quantities of similar size can be almost entirely uncertainty. A ratio where the denominator is uncertain and possibly small is unbounded. The intuition that combining several sources makes an answer more reliable holds only for independent measurements of the same quantity, which is almost never the situation in a chained analysis.
Three defences are worth building. Propagate confidence structurally so that any derived value inherits at minimum the lowest confidence among its inputs, applied by the composition mechanism rather than by whichever step happens to remember. Cap the number of low-confidence steps a chain may contain before it is required to report unknown rather than an answer, because beyond a small depth the output is dominated by accumulated uncertainty. And require that a final answer name its weakest input, since a conclusion that has to state which figure it rests on cannot present itself as more solid than that figure.
What confidence marking is really buying
The argument for all of this is not accuracy. Marking a figure as low confidence does not improve it. The estimate is exactly as wrong as it was before.
What it buys is the ability of everything downstream to behave correctly. A consumer that knows a figure is weak can seek corroboration, widen its own error band, decline to act, or escalate to a person. A consumer that receives the same figure bare has no option except to treat it as fact, and will.
The corollary is that confidence marking is only worth anything if it is honest in both directions. A system that marks everything low confidence to be safe teaches consumers to ignore the marker, which is the same outcome as not marking at all with extra fields. The marker has to be earned in both states: high should mean the evidence really is sufficient, and unknown should be used freely enough that consumers learn it appears when it is true.
That discipline is what makes the vocabulary load-bearing rather than decorative, and it has to hold on the boring endpoints as well as the interesting ones.