{
  "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_avoid_overlap",
      "title": "Avoid ambiguous, overlapping tool sets",
      "category": "scoping",
      "description": "If two tools could plausibly both apply to the same request, the model has to guess -- and guesses are where tool-use errors come from. Where possible, consolidate near-duplicate tools into one tool with a parameter, or make the boundary between them explicit in both descriptions.",
      "example_good": "One tool `search(source: \"docs\" | \"web\")` with a parameter, rather than two separately-described tools with fuzzy, overlapping \"search for information\" descriptions.",
      "example_bad": "Two tools, `search_docs` and `find_documents`, both described only as \"search for information\" with no distinguishing detail.",
      "source_note": "General best practice for multi-tool agent systems; consistent with this repo's own subagentcode.com AgentTool enum design, which keeps tool variants distinct rather than overlapping.",
      "created_at": "2026-07-02 08:28:30",
      "cite_as": "https://subagentdescriptions.com/api/practices/prc_avoid_overlap"
    },
    {
      "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_descriptive_param_names",
      "title": "Give parameters descriptive, self-explanatory names",
      "category": "naming",
      "description": "Parameter names are part of the model's only signal for what a field means -- prefer a clear, specific name (and a short description on the parameter itself, not just the top-level tool description) over a short but ambiguous one.",
      "example_good": "`ticker_symbol: string` with description \"e.g. AAPL, TSLA\"",
      "example_bad": "`t: string` with no description",
      "source_note": "General JSON Schema / function-calling best practice, applicable across MCP tool schemas and Anthropic tool_use blocks alike.",
      "created_at": "2026-07-02 08:28:30",
      "cite_as": "https://subagentdescriptions.com/api/practices/prc_descriptive_param_names"
    },
    {
      "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_examples_in_description",
      "title": "Include example usage directly in the description",
      "category": "examples",
      "description": "Concrete input/output examples embedded in a tool's description reduce ambiguity far more efficiently than more prose -- showing the model one or two realistic calls (and, where useful, one call that should NOT be made) often resolves edge cases prose alone leaves open.",
      "example_good": "\"Example: get_stock_price(ticker_symbol=\"\"AAPL\"\") returns the latest closing price in USD.\"",
      "example_bad": "A tool description that only states the parameter types with no example call shown.",
      "source_note": "General tool-description best practice; mirrors how this repo's own real skill descriptions (see subagentskills.com) fold trigger-phrase examples directly into the description field, not a separate doc.",
      "created_at": "2026-07-02 08:28:30",
      "cite_as": "https://subagentdescriptions.com/api/practices/prc_examples_in_description"
    },
    {
      "id": "prc_explain_when_to_use",
      "title": "Explain when to use the tool -- and when not to",
      "category": "scoping",
      "description": "Beyond describing what a tool does, a good description tells the model the situations that should trigger it, and explicitly calls out situations where a similar-looking tool should be used instead, to prevent the model from picking the wrong one of several overlapping tools.",
      "example_good": "\"Use this to search internal company documents. Do NOT use this for general web search -- use the web_search tool for that instead.\"",
      "example_bad": "\"Searches documents.\" (no guidance on which documents, or when to prefer a different search tool)",
      "source_note": "General best practice; several sites in this family (e.g. subagentskills.com's catalog) already apply an explicit \"do not use for X\" pattern in their own real skill descriptions.",
      "created_at": "2026-07-02 08:28:30",
      "cite_as": "https://subagentdescriptions.com/api/practices/prc_explain_when_to_use"
    },
    {
      "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"
    },
    {
      "id": "prc_single_responsibility",
      "title": "Prefer one tool, one clear responsibility",
      "category": "scoping",
      "description": "A tool that tries to do many unrelated things behind a single description and a large branching parameter set is harder for the model to invoke correctly than several smaller, single-purpose tools with tight, specific descriptions.",
      "example_good": "Separate `create_task`, `update_task`, `delete_task` tools, each with a narrow, specific description.",
      "example_bad": "One `manage_task(action: \"create\" | \"update\" | \"delete\" | \"archive\" | \"restore\" | ...)` tool whose description tries to explain all six behaviors in one dense paragraph.",
      "source_note": "General API/tool design best practice, echoed in this repo's own real TaskCreate/TaskUpdate/TaskList tool split (see subagenttasks.com) rather than one combined \"manage tasks\" tool.",
      "created_at": "2026-07-02 08:28:30",
      "cite_as": "https://subagentdescriptions.com/api/practices/prc_single_responsibility"
    },
    {
      "id": "prc_xml_or_delimiters_in_description",
      "title": "Use clear structure or delimiters inside a long description",
      "category": "structure",
      "description": "When a tool description needs to cover several distinct concerns -- what it does, when to use it, when not to, an example -- breaking it into clearly labeled or delimited sections (short paragraphs, a labeled \"Example:\" sentence, explicit \"Do NOT use this for...\" sentence) is easier for the model to parse reliably than one dense paragraph.",
      "example_good": "A description with clearly separated sentences: one describing behavior, one giving the trigger phrases, one giving an explicit \"do not use for\" exclusion, one giving an example.",
      "example_bad": "A single 300-word run-on paragraph mixing behavior, triggers, exclusions, and examples with no sentence-level separation.",
      "source_note": "General prompt-structuring best practice, consistent with Anthropic's broader guidance (mirrored on subagentprompts.com) that clear delimiters/structure improve reliability in long prompts generally, applied here specifically to tool descriptions.",
      "created_at": "2026-07-02 08:28:30",
      "cite_as": "https://subagentdescriptions.com/api/practices/prc_xml_or_delimiters_in_description"
    }
  ]
}