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…
Step 1: Pinning the Use Case
Before 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:
1. Bounded Input: A single support ticket containing { subject, body, customer_id, order_id? }.
2. Bounded Output: Exactly one of the following: resolved, refund_proposed (pending approval), or escalated (with a reason).
3. Tool Count: Limited to 5 tools to avoid cognitive overload and hallucinations.
4. Success Metric: Resolution rate of 85% without escalation, and an escalation rate of 10%.
The 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.
Step 2: Writing Tool Contracts
Tool 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:
{
name: "refund_eligibility",
description: "Check whether an order is eligible for a refund BEFORE ever proposing one.",
gated: false,
input_schema: {
type: "object",
properties: {
order_id: { type: "string" },
reason: { type: "string", description: "Customer's stated reason for the refund request" },
},
required: ["order_id", "reason"],
},
}
The 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.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
