Tool Design & the Tool Contract

Module 2 · Master Course — Harness Engineering

90 minutes · 4 sub-sections: Architecture · Writing Tools · Dispatch · Security

Where most security vulnerabilities live.

The tool surface

Module 1 gave you the loop's executeTool extension point. This module goes inside it. By the end: the five-part contract, the dispatch sequence, the three injection vectors, and the defenses Module 11 harvests.

2.1 Tool Architecture Patterns

The five-part tool contract

Every tool in every production harness has all five. Missing any degrades reliability or security.

Tool descriptions are prompts

The tool-count decision

The question isn't "how many tools?" It's: what's the minimum tool set that maximizes capability without decision noise? Most teams err on too many.

Registration patterns

2.2 Writing a Great Tool

Output formatting: the 67.6% rule

Module 0.3's anchor: tool outputs are 67.6% of context. Output formatting is the highest-leverage decision in tool design.

Idempotency

For non-idempotent tools: deduplicate via request ID, content-hash check, or "already sent" guard. Idempotency is a tool-design responsibility.

Error returns: never throw, always return

// WRONG — model gets generic "tool failed"
throw new Error("search failed");

// RIGHT — model knows what failed and whether to retry
return {
  ok: false,
  error: "search failed: timeout after 5000ms",
  retryable: true   // → model retries with backoff
};

Four categories (Module 7): transient (retry) · LLM-recoverable (self-correct) · user-fixable (interrupt) · fatal (halt). The tool provides the info; the loop categorizes.

2.3 Tool Routing and Dispatch

The 7-step dispatch sequence

Model emits tool_use
  │
  1. Parse (structured JSON or regex)
  │    └ parse failure → precise error to model
  2. Validate name against registry
  │    └ unknown → error
  3. Schema-validate inputs
  │    └ invalid → precise error ("pattern required, string; got number")
  4. Permission check (Module 6)
  │    └ denied → permission error
  5. Execute implementation
  6. Format result (truncate + structure)
  7. Return to model as tool result in context

Each step is a failure point AND an injection point. Structured output (JSON tool_use) eliminates step-1 parse failures.

MCP: external tool servers

MCP = ASI04 (Agentic Supply Chain) vulnerability if trusted blindly. Module 11.2 + Course 2 S12 cover tool-definition poisoning, evil-twin attacks, signed manifests.

2.4 Tool Security

The tool surface is the attack surface

Three injection vectors

Vector 1 is the most common and most dangerous. Module 11.3 implements the defense; the lab verifies it defeats a crafted payload.

Capability-based permissions

Defense in depth: tools declare required capabilities; harness checks before executing.

const tools = [
  { name: "read_file",  capabilities: ["fs:read"],  ... },
  { name: "write_file", capabilities: ["fs:write"], ... },
  { name: "bash",       capabilities: ["shell"],    ... },
  { name: "search_web", capabilities: ["network"],  ... }
];

function executeTool(tc, agentPerms) {
  const tool = registry[tc.name];
  const allowed = tool.capabilities.every(c => agentPerms.has(c));
  if (!allowed) return { ok: false, error: "permission denied" };
  return tool.execute(tc.input);
}

A subagent with {fs:read} cannot call bash — regardless of model requests. Permission at the dispatch boundary, not the prompt. Module 0.2's governance principle, at the tool layer.

Five anti-patterns

Takeaways

• Five-part contract: name, description, schema, implementation, error return.
• Descriptions are prompts. Precise inputs/outputs/when-to-use; no marketing.
• Fewer tools often wins. The Vercel finding. Decision noise is real.
• Never throw; always return. Structured errors let the model self-correct.
• Three injection vectors. Output (most common), definition (MCP), dispatch. Defenses previewed; Module 11 implements.

Next: Module 3 — Context Management. The hardest engineering problem in production harnesses.