{
  "practices": [
    {
      "id": "prc_avoid_jargon_unclear_abbrev",
      "title": "Avoid unexplained jargon or abbreviations in descriptions",
      "category": "clarity",
      "description": "A tool description is read by the model with no additional context beyond what is written -- internal codenames, uncommon abbreviations, or jargon specific to one team should be spelled out or avoided, the same way a new team member would need it explained.",
      "example_good": "\"CSL (Citation Style Language) JSON\" spelled out on first use.",
      "example_bad": "\"Returns CSL data.\" with no expansion anywhere in the tool description or schema.",
      "source_note": "General clarity best practice, consistent with this repo's own style-citations skill spelling out CSL on first use.",
      "created_at": "2026-07-02 08:28:30",
      "cite_as": "https://subagentdescriptions.com/api/practices/prc_avoid_jargon_unclear_abbrev"
    },
    {
      "id": "prc_concise_but_complete",
      "title": "Keep descriptions concise, but not at the expense of completeness",
      "category": "clarity",
      "description": "Long descriptions cost context and can dilute the signal of what matters most; the goal is not the shortest possible description, but the shortest description that still unambiguously conveys behavior, required parameters, and edge cases. Cutting real information to save space is a false economy.",
      "example_good": "A 2-3 sentence description that states behavior, key parameters, and one caveat, with no filler words.",
      "example_bad": "A verbose description padded with generic phrases (\"This powerful and versatile tool can help you...\") that add length without adding information.",
      "source_note": "General best practice; consistent with subagentprompts.com's own catalog entries, which are written to be brief but information-dense rather than padded.",
      "created_at": "2026-07-02 08:28:30",
      "cite_as": "https://subagentdescriptions.com/api/practices/prc_concise_but_complete"
    },
    {
      "id": "prc_describe_return_shape",
      "title": "Describe what the tool returns, not just what it does",
      "category": "clarity",
      "description": "A tool description that only explains the action (e.g. \"searches for X\") without saying what shape the result takes leaves the model unable to reason correctly about how to use the output in a following step.",
      "example_good": "\"Returns a JSON array of {title, url, snippet} objects, most relevant first.\"",
      "example_bad": "\"Searches the web.\" (no mention that results come back as a list, or in what format)",
      "source_note": "General tool-use best practice.",
      "created_at": "2026-07-02 08:28:30",
      "cite_as": "https://subagentdescriptions.com/api/practices/prc_describe_return_shape"
    },
    {
      "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"
    },
    {
      "id": "prc_extremely_detailed",
      "title": "Write extremely detailed, unambiguous descriptions",
      "category": "clarity",
      "description": "A tool description should explain exactly what the tool does, what each parameter means, what the tool returns, and any important caveats -- err on the side of more detail rather than less, since the model has no other context about the tool beyond its name, description, and schema.",
      "example_good": "\"Get the current weather in a given location. Returns temperature in the unit specified. If no unit is given, defaults to the location's local convention (Celsius outside the US, Fahrenheit within it).\"",
      "example_bad": "\"Gets weather.\"",
      "source_note": "Anthropic's published tool-use / function-calling guidance on writing clear, complete tool descriptions.",
      "created_at": "2026-07-02 08:28:30",
      "cite_as": "https://subagentdescriptions.com/api/practices/prc_extremely_detailed"
    },
    {
      "id": "prc_required_vs_optional",
      "title": "Be explicit about which parameters are required vs. optional, and what defaults apply",
      "category": "clarity",
      "description": "If a parameter is optional, the description (or schema) should say so and state what happens when it is omitted -- silently assumed defaults are a common source of wrong tool calls.",
      "example_good": "\"unit (optional): \"\"celsius\"\" or \"\"fahrenheit\"\". If omitted, defaults to the location's local convention.\"",
      "example_bad": "An optional parameter with no default behavior documented anywhere.",
      "source_note": "General JSON Schema / function-calling best practice.",
      "created_at": "2026-07-02 08:28:30",
      "cite_as": "https://subagentdescriptions.com/api/practices/prc_required_vs_optional"
    }
  ]
}