The check passed
now ask how much it actually looked at

A green result has two parts and people read one of them. There's the verdict, and there's the population the verdict covers. A pass over three percent of your code is not a smaller version of a pass over all of it. It's a different statement, and printed on its own it's indistinguishable from the stronger one.

Links validated: two

On 6 August 2026, on tapps-mcp version 3.12.69, I ran docs_check_links with a file filter: two specific documents, docs/LINKEDIN-PUBLISH-AUTOMATION.md and docs/LINKEDIN-POST-AGENT-DESIGN.md. It came back reporting total_links: 2.

Those two documents contain twelve external URLs between them, plus a number of internal references. So the count was off by an order of magnitude against the thing a reader would assume it was counting. The reason turned out to be structural rather than a miscount: external URLs are never checked at all. Not attempted and failed. Not in scope. The tool's idea of a link is narrower than mine, and the response had no field that said so.

links validated is therefore true and much smaller than it sounds. That gap is the entire defect, and it survives any amount of re-running.

217 warnings about files I don't own

The same run was generous in the other direction. It produced 217 warnings, and most of them were about LICENSE.txt and top_level.txt files inside .venv-3d/lib/python3.12/site-packages/. Installed third-party packages. Not my code, not my documentation, not anything I could act on.

The response reported excluded_paths_count: 3, and the virtualenv wasn't among the three. So the tool was simultaneously too narrow where it mattered, checking two links out of a dozen or more, and far too wide where it didn't, raising two hundred warnings from a directory nobody had written a line of.

Those two behaviours look unrelated. They're the same thing. Neither the narrowing nor the widening appeared in the verdict, because the verdict only ever described the outcome, never the population.

Why a noisy pass is worse than a quiet one

Two hundred and seventeen warnings train you to stop reading warnings. That's not a discipline failure, it's an entirely reasonable response to a signal with a terrible ratio. Once the warning stream is background noise, the six real findings buried in it are functionally invisible, and the tool has made the problem worse than not running it would have.

A check with a bad denominator does damage in both directions. It understates coverage, and it overstates the cost of paying attention.

Say the denominator out loud

The habit I keep coming back to is simple: no measurement without its population. Six broken links out of how many checked, out of how many exist. Two links validated out of twelve URLs present. Coverage eighty percent of what set of files. A number without its population isn't a measurement, it's a mood.

That's true of tools and it's equally true of the sentence a person writes underneath one. Most of the times I've misled myself with a metric, the metric was accurate and I'd silently attached it to a bigger set than it covered.

What I ask a tool to print now

Three things next to the verdict. What was examined, as a count and a scope. What was deliberately excluded, as a list rather than a number. And what the tool cannot check at all, stated plainly, so nobody infers coverage from silence.

If a tool won't print those, I can still get there by hand. Count what's in the directory, count what the tool says it saw, and put the two numbers side by side. When they don't match, the mismatch is the finding, and it's usually more interesting than whatever the check was nominally about.

Sources: All figures here (total_links: 2 under a two-file filter, twelve external URLs in those two documents, external URLs never checked, 217 warnings originating in .venv-3d/lib/python3.12/site-packages/, excluded_paths_count: 3) are recorded under Defect 1, "Three further problems in the same tool", in docs/UPSTREAM-TOOL-DEFECTS.md in this repo. Run against tapps-mcp 3.12.69 on 6 August 2026.