{
  "practices": [
    {
      "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_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_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"
    }
  ]
}