{
  "id": 591499,
  "title": "Part 2: Pinning the Use Case and Writing Tool Contracts Like Specs",
  "url": "https://urgent.news/2026/08/11/part-2-pinning-the-use-case-and-writing-tool-contracts-like-specs",
  "topic": "finance",
  "section": "Finance & Markets",
  "published": "2026-08-11T18:43:46.000Z",
  "source": {
    "name": "Dev.to",
    "slug": "dev-to",
    "url": "https://dev.to/akashpal/part-2-pinning-the-use-case-and-writing-tool-contracts-like-specs-4462"
  },
  "original_language": "en",
  "account": "Step 1: Pinning the Use Case\n\nBefore writing any code, two essential documents must be created: docs/use-case.md and docs/tool-contracts.md. Skipping this step is the most common reason teams end up with an agent nobody trusts. Four gates must be filled in before any coding begins:\n\n1. Bounded Input: A single support ticket containing { subject, body, customer_id, order_id? }.\n2. Bounded Output: Exactly one of the following: resolved, refund_proposed (pending approval), or escalated (with a reason).\n3. Tool Count: Limited to 5 tools to avoid cognitive overload and hallucinations.\n4. Success Metric: Resolution rate of 85% without escalation, and an escalation rate of 10%.\n\nThe limited tool count ensures the agent stays focused on three request types (order status, refunds, KB lookups), preventing it from ballooning into a system that requires multiple specialist agents.\n\nStep 2: Writing Tool Contracts\n\nTool contracts are schemas, not just documentation. The LLM reads these contracts to decide when to call the tools. Each tool's description field should be treated as a specification, not a comment for future developers. Here's an example of a refund_eligibility tool contract from src/tools/index.ts:\n\n{\nname: \"refund_eligibility\",\ndescription: \"Check whether an order is eligible for a refund BEFORE ever proposing one.\",\ngated: false,\ninput_schema: {\ntype: \"object\",\nproperties: {\norder_id: { type: \"string\" },\nreason: { type: \"string\", description: \"Customer's stated reason for the refund request\" },\n},\nrequired: [\"order_id\", \"reason\"],\n},\n}\n\nThe 30-day window for refund eligibility is explicitly stated in the tool description, not just mentioned in the system prompt. This ensures the policy logic lives load-bearing in the tool itself, preventing missed details under load.",
  "summary": "Part 2 of a series building a support-ticket agent with no framework. Part 1 covered why. This part covers Steps 1–2 of the build order: pinning the use case, and writing tool contracts. Repo: github.com/akash-pal/agent-from-scratch Before any code, two documents: docs/use-case.md and docs/tool-contracts.md . Skipping this step is the single most common reason teams end up with an agent nobody…",
  "key_points": [],
  "editors_take": null,
  "illustration": null,
  "coverage": {
    "outlets": 1,
    "also_reported_by": []
  },
  "ai_generated": true,
  "disclaimer": "Summaries, key points and the editor’s take are written by software from other outlets’ reporting and may contain errors — always check the linked original."
}