Entropy

Information content of an event with chance p is -log2(p) bits. Rare events are surprising and take more bits to name. A fair coin landing heads is 1 bit. A one-in-a-million incident is about 20 bits of surprise.

Entropy of a distribution is the expected surprise: H = -sum p_i log2(p_i). A certain outcome (p=1 for one item) has entropy 0. A uniform distribution over k labels has entropy log2(k), the maximum for that many labels.

Entropy is not “how wrong.” A model can be confidently wrong (entropy low, accuracy low) or uncertain and honest (entropy high). Calibration is the extra requirement that p matches frequencies. Entropy is only about spread.

A wrong picture

A wrong picture is: “high entropy means the model is wrong; low entropy means it is right.” Entropy 0 on the wrong tool is a disaster. Entropy high on a genuinely ambiguous ticket can be honest. You want low entropy on the right answer, which is a joint statement about entropy and accuracy.

Another wrong picture is using a different log base and comparing numbers. Bits use log base 2. Natural log gives nats. Same story, different unit. H_nats = H_bits * ln(2). Be consistent with your log. Dashboards that mix them look like a regression.

A third: including p = 0 as 0 * log(0) in a naive loop. Skip those terms: 0 log 0 is treated as 0. If you clip chances up from 0, you change entropy — be consistent.

The formula in words

Surprise of one outcome: minus log2 of its chance. Smaller p, larger surprise.

Entropy: chance-weighted average of those surprises. Same weighted-average idea as expectation, with surprise as the value.

Maximum for k labels: all chances 1/k, H = log2(k). Two labels uniform: 1 bit. Three labels uniform: about 1.585 bits. Eight labels uniform: 3 bits.

Tiny numeric. Peaked [0.90, 0.05, 0.05]: surprise of the big one is -log2(0.9) ≈ 0.152 bits; the two tails are about 4.32 bits each but they are rare. H lands well under 1 bit (about 0.57). Flat [1/3, 1/3, 1/3]: H ≈ 1.585. A coin [0.5, 0.5]: H = 1.

A next-token distribution with entropy 10 bits is as uncertain as a uniform choice among about 1024 tokens (2^10). The model does not “know” the next word.

Moving parts

You only need those four. Calibration (does 0.7 happen 70% of the time?) is a different check.

A second walkthrough (four tools)

Four tools with chances [0.70, 0.20, 0.08, 0.02] — search, sql, finish, wait.

Surprise of each, by hand:

• 0.70 → -log2(0.70) ≈ 0.515 bits
• 0.20 → -log2(0.20) = 2.322 bits
• 0.08 → -log2(0.08) ≈ 3.644 bits
• 0.02 → -log2(0.02) ≈ 5.644 bits

Entropy is the weighted average:

0.700.515 + 0.202.322 + 0.083.644 + 0.025.644

= 0.361 + 0.464 + 0.292 + 0.113 ≈ 1.230 bits.

Uniform four-way is log2(4) = 2 bits. This policy is peaked, not confused. A nearly flat four-way sits at 2 bits — almost a full extra bit of average surprise. That extra bit is extra samples and extra tool dithering.

Certain policy [1, 0, 0, 0]: skip the zeros, H = 0. Half-and-half with a dead tool [0.5, 0.5, 0, 0]: H = 1, same as a fair coin. Unused tools do not add surprise. A wrong certain policy (entropy 0 on the bad tool) is worse than a confused one: you will not even try the right hand.

Tokens and bits

Uncertain tokens are expensive because:

• You may need more samples (majority vote, rerank) to stabilize an action.
• Sequences wander; more tokens get spent repairing the plan.
• A high-entropy tool distribution means the policy does not know which hand to use; wasted calls follow.

Low entropy is not automatically good. Pair it with accuracy or with a gold tool label.

A Friday ticket

Friday 16:40. Support tickets started taking three tools instead of one. The prompt had not changed. Someone had added wait to the catalog with an empty description. Mean tool entropy jumped from about 0.75 bits (three labels, peaked on search) to about 1.55 bits (four labels, nearly flat). The incident title was “model quality.” The number was entropy: the policy no longer knew which hand to use.

The fix was not a longer system prompt. They logged tool_entropy_bits on every step, alerted when the hourly mean exceeded 0.6 * log2(n_tools), and wrote a one-line description for wait. Entropy fell. Search stopped sharing mass with wait. Same logits family, better constraint.

Run to execute this in your browser. Nothing is sent to a server.

Surprise of p=0.5 is 1.0 bit. Surprise of p=0.9 is about 0.152. H peaked is about 0.569. H flat is about 1.585. H coin is 1.0. Max for 8 labels is 3.0. Confident policy H is about 0.748 on search/sql/finish. Confused policy H is about 1.585 — the same as a flat 3-way choice, the maximum for three options. An agent that logs entropy of the tool distribution (when you have logits) gets a numeric “I don’t know” instead of a vibe.

Skip p = 0 terms. If your softmax produces exact zeros, that is fine. If you clip chances, you change entropy — be consistent.

What goes wrong

• Zeros: 0 * log(0) is treated as 0. Skip p == 0. If you clip every chance up to 1e-12 “to be safe,” you raise entropy a little. Pick a rule and keep it.
• List that does not sum to 1: H of [0.9, 0.9] is nonsense. Assert abs(sum(p) - 1) < 1e-6 before you log H.
• Bits vs nats: math.log vs math.log(..., 2). A chart that mixed them looked like a 30% regression. Label the unit on the series.
• Ties / flat top-k: retrieval scores [0.41, 0.40, 0.39] softmax to a high-H blob. Rank-1 is not destiny. Entropy of that list is the confusion number.
• Overflow into -inf: if a chance underflowed to 0 and you still take log, you get -inf. Same clip story as cross-entropy.

Production logs: tool_entropy_bits, mean_token_entropy_bits, n_tools (so a catalog change is visible), and the argmax tool next to its chance. Assert non-negative p_i, unit sum, and that you skipped zeros. A line like H=1.55 n=4 argmax=wait p=0.28 is a policy you can debug. H=1.55 alone is a vibe.

How agents use this

Production teams watch average entropy of generations. Spikes mean the prompt stopped constraining the model (new tool added, schema missing, temperature too high). Combined with temperature, entropy is a knob-and-gauge pair: temperature reshapes logits; entropy measures how flat the result became.

For ranking, a query whose top-k cosine scores are almost equal is high-entropy retrieval: the neighborhood is a blob, not a nearest neighbor. Do not pretend rank-1 is destiny.

• Tokens: log mean token entropy per reply. A jump after a prompt or temperature change is a constraint failure, not “creativity.” Pair it with exact-match or gold-tool accuracy so you do not celebrate a peaked wrong policy.
• Ranking: turn top-k scores into a softmax over documents; the entropy of that list is retrieval confusion. High H: refuse or clarify. Log the entropy and the top cosine.
• Loss: cross-entropy is at least the entropy of the true labels. You cannot beat H(p) on average. KL (next lessons) is the extra bits.
• Sampling: high T raises entropy. Low T lowers it. Greedy is entropy toward 0 given a unique max logit. If greedy still looks high-entropy, you have a tie in the logits, not a temperature bug.

Note:Bits use log base 2. Natural log gives nats. Same story, different unit. Be consistent with your log.