fix: annotate throttler ratio with human-readable description#4
fix: annotate throttler ratio with human-readable description#4
Conversation
The PlanetScale throttler ratio is a brake (0 = full speed, 100 = paused), which is counter-intuitive. An LLM misread `ratio: 0` as "fully paused" during a production deploy request audit. Adding `ratio_description` to the response ensures the semantics are visible at interpretation time, not just in the tool schema. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
lorcan
force-pushed
the
lorcan/deploy-request-throttler-semantics
branch
from
3502fe3 to
44041be
Compare
| ? "no throttling — deployment runs at full speed" | ||
| : c.ratio === 100 | ||
| ? "fully throttled — deployment is paused" | ||
| : `${c.ratio}% throttled — deployment runs at ${100 - c.ratio}% capacity`, |
There was a problem hiding this comment.
This is VERY nitpik, but I think that I am get used to the Planetscale UI where 70% means that we a throttling more than half. I would keep the same for consistency instead of (1 - t). Even I think that (1-t) is clear, I would keep consistent with the UI.
There was a problem hiding this comment.
I dislike the use of the word "throttle", which is ambiguous and possibly backwards (the ratio is a brake not a throttle).
Claude gets very confused on what the throttle means. I had a bunch of back and forth about where the right place to put an explanation for what throttle/ratio means and Claude suggested it would be more likely to read it correctly if there was a description in the API response (a very human response).
I'm going to make this PR draft and let it sit for a while. I'm working on a throttling skill and if i can make it work reliably without this change I'll probably drop it.
2 participants
Why?
PlanetScale's throttler ratio uses brake semantics: 0 means "no braking" (full speed), 100 means "fully braked" (paused). This is counter-intuitive — a ratio of 0 looks like "zero work" or "fully paused" when read without context. An LLM consuming this tool's output misinterpreted
ratio: 0as "deployment is frozen" when it was actually running at maximum speed.How?
Adds a
ratio_descriptionfield alongside each numericratiovalue in the throttler configurations response, and updates the tool description to explain the brake model.Generated with Claude Code