Part 2: Pinning the Use Case and Writing Tool Contracts Like Specs

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 trusts — not because the idea was bad, but because nothing downstream (evals, prompts, memory) had a fixed target to hit. Step 1: pin the use case Four gates, filled in before writing a line of code: Gate Definition Bounded input One support ticket: { subject, body, customer_id, order_id? } Bounded output Exactly one of: resolved , refund_proposed (pending approval), escalated (with a reason) Tool count 5 Success metric Resolution rate > 85% without escalation; escalation rate < 10% The tool count cap matters more than it looks. An agent given 10+ tools starts hallucinating tool names and picking the wrong one — a cognitive load problem, not a dependency problem. Keeping this agent to 5 tools, covering exactly three request types (order status, refunds, KB lookups), keeps every run in the healthy 3–8 tool-call range instead of ballooning into a system that needs to be split into multiple specialist agents. (Part 7 covers the actual cost math for when a split is worth it.) Bounded output matters too: resolved / refund_proposed / escalated isn't just documentation — it becomes a literal parseable prefix ( RESOLVED: , REFUND_PROPOSED: , ESCALATED: ) that the agent's final message must start with. Part 4 shows exactly how that gets parsed, and Part 5 shows why trusting that string alone turned out to be a real bug. Step 2: tool contracts are a schema, not a docstring This is the part that's easy to under-invest in. A tool's description field isn't a comment for future developers — it's the only thing the LLM reads to decide when to call the tool. Treat it as a specification. Here'