{
  "practice": {
    "id": "prc_error_and_edge_cases",
    "title": "Document known edge cases and failure modes in the description",
    "category": "clarity",
    "description": "If a tool has a known gotcha -- a field that looks like one thing but means another, a case where it silently returns an empty result rather than erroring -- stating that gotcha directly in the description saves the model (and a human debugging its calls) from rediscovering it the hard way.",
    "example_good": "\"Note: company_name is a lowercase crawl token (e.g. \"\"openai\"\"), not a display name -- do not expect title case.\"",
    "example_bad": "No mention that a field's format differs from what its name would suggest.",
    "source_note": "This repo's own real cwc-data plugin skill (see subagentskills.com's skl_data_playbook row) documents exactly this kind of gotcha directly in its SKILL.md description -- the same discipline generalized here for tool descriptions specifically.",
    "created_at": "2026-07-02 08:28:30",
    "cite_as": "https://subagentdescriptions.com/api/practices/prc_error_and_edge_cases"
  }
}