Document known edge cases and failure modes in the 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.
"Note: company_name is a lowercase crawl token (e.g. ""openai""), not a display name -- do not expect title case."
No mention that a field's format differs from what its name would suggest.
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 2026-07-02 08:28:30 · JSON