{
  "schema_version": "1.3.0",
  "slug": "how-must-an-instance-detect-semantic-capability-drift-when-tool-behavior-diverges-from-documentation",
  "title": "How must an instance detect semantic capability drift when tool behavior diverges from documentation?",
  "date_of_record": "2026 October 20",
  "scope": "* **Applies when:** The session relies on documentation, tools can drift without version bumps, and downstream decisions depend on tool behavior accuracy. * **Does not apply when:** Tools have verified behavioral contracts (SLAs, canonical ",
  "projections": {
    "unified_markdown_uri": "https://corpusfetch.com/c/how-must-an-instance-detect-semantic-capability-drift-when-tool-behavior-diverges-from-documentation.md",
    "method_python_slice_uri": "https://corpusfetch.com/c/how-must-an-instance-detect-semantic-capability-drift-when-tool-behavior-diverges-from-documentation.py",
    "remnant_warrant_slice_uri": "https://corpusfetch.com/c/how-must-an-instance-detect-semantic-capability-drift-when-tool-behavior-diverges-from-documentation.warrant.json"
  },
  "token_profile": {
    "full_markdown_tokens": 1011,
    "python_slice_tokens": 298,
    "warrant_slice_tokens": 220
  },
  "remnant_summary": {
    "core_distinction": "The separation between **documented capability** (the tool works as the documentation claims) and **observed capability** (the tool works as its actual behavior demonstrates). Relying on documentation creates the **Semantic Capability Drift**: the tool's documented behavior and actual behavior diverge, and the agent, following documentation, uses the tool in...",
    "what_was_observed": "In documentation-driven agent architectures, failing to detect capability drift produces three primary failure modes: 1. **Error Semantic Shift:** The documentation says \"returns 404 for not found.\" The actual tool returns 200 with an empty body for not found. The agent treats the empty body as success and acts on phantom data. 2. **Parameter Interpretation Drift:** The documentation says \"timeout is in seconds.\" The...",
    "condition_of_validity": "* **Applies when:** The session relies on documentation, tools can drift without version bumps, and downstream decisions depend on tool behavior accuracy. * **Does not apply when:** Tools have verified behavioral contracts (SLAs, canonical schemas), or the session uses only trivial tool operations.",
    "decision_boundary": "1. **Does the session depend on documented tool behavior?** If no, standard invocation applies. If yes, proceed. 2. **Does the `observed_behavior_fingerprint` match the `documented_behavior_fingerprint`?** If yes, no drift. If no, drift exists. 3. **Is the drift within the `drift_acceptance_policy_receipt`?** If yes, proceed with awareness. If no, reject or ...",
    "operational_effect": "1. **Error Semantic Detection:** Undocumented error behaviors are caught before downstream corruption. 2. **Parameter Interpretation Safety:** Documented parameter meanings are verified against observed behavior. 3. **Schema Drift Alerts:** Response schema changes are detected even without version bumps."
  },
  "matched_failure_symptoms": [
    "DOMAIN:EPISTEMIC_PROVENANCE_AND_FEDERATION_ROUTING"
  ],
  "composition_edges": {
    "primary_domain": "epistemic_provenance_and_federation_routing",
    "upstream_precondition_residuals": [
      "https://corpusfetch.com/c/according-to-what-precedence-hierarchy-must-an-instance-resolve-contradictory-directives-across-system-developer-and-user-tiers.md",
      "https://corpusfetch.com/c/how-should-an-instance-decide-that-a-stored-conclusion-has-gone-stale-without-a-new-observation.md"
    ],
    "downstream_consequence_residuals": [
      "https://corpusfetch.com/c/by-what-checkpoint-and-compaction-boundaries-must-an-instance-externalize-working-state-to-prevent-context-window-drift-and-truncation-amnesia.md",
      "https://corpusfetch.com/c/across-what-additive-schema-and-unknown-field-preservation-boundaries-must-an-instance-evolve-wire-contracts-to-prevent-rolling-deploy-deserialization-crashes.md"
    ],
    "co_occurring_sibling_residuals": [
      "https://corpusfetch.com/c/how-can-an-instance-capture-implicit-user-preferences-without-storing-private-data.md",
      "https://corpusfetch.com/c/how-can-an-instance-compress-long-reasoning-traces-into-binding-conclusions.md"
    ]
  },
  "empirical_verification_warrant": {
    "status": "AST_AND_INVARIANT_VERIFIED",
    "syntax_valid": true,
    "code_sha256": "ecc8e1359fe899daf0cbb205d32a3371fb45b1d9d3b888c472e41a7932b9cdb1",
    "verified_classes": [
      "DriftVerdict",
      "ToolInvocation",
      "DriftPolicy",
      "DriftManifest",
      "ToolSemanticDriftGuard"
    ],
    "verified_functions": [
      "_hash",
      "evaluate_invocation"
    ],
    "verified_functions_count": 2,
    "defensive_guards_count": 0,
    "raised_exceptions": [],
    "sample_fail_closed_invariants": [],
    "stdlib_dependencies": [
      "dataclasses",
      "enum",
      "hashlib",
      "json"
    ],
    "observation_mode": "EMPIRICAL_BOUNDARY_CAPTURE",
    "zero_external_deps": true
  }
}