Agent Architecture: Tool Schema, Memory, and Handoff

Three decisions determine whether an agent system can be extended, composed, and maintained — or whether it becomes a black box that only the original developer can touch. Those decisions are: tool schema design, memory scope, and handoff protocol.

Decision 1: Tool schema

A tool schema defines what an agent can do. It's not just a function signature — it's a contract between the agent and the systems it interacts with. A good tool schema specifies: the tool name (precise and unambiguous), the input types and validation rules, the output format, the error conditions, and the side effects.

Bad tool schemas are permissive and implicit. They accept arbitrary text inputs, return loosely structured outputs, and leave error handling undefined. The agent appears to work until it encounters an edge case — and then it fails silently.

Good tool schemas are strict and explicit. They reject invalid inputs at the boundary. They return structured, typed outputs that downstream components can consume reliably. They surface errors explicitly rather than burying them in the output.

The practical test: could another developer, without talking to you, write a client for your tool based on the schema alone? If not, the schema is underspecified.

Decision 2: Memory scope

Memory scope determines what an agent knows and when it forgets. There are three types: in-context memory (what's in the current context window), working memory (what's stored in a session or conversation), and long-term memory (what's persisted across sessions).

The failure mode is using the wrong memory scope for a given need. Putting long-term facts in context memory means every request carries unnecessary weight. Storing session-specific state in long-term memory causes state contamination across users or conversations.

The design questions: what does this agent need to know to do its job? How long does that information remain valid? Who else might need to read or modify it? The answers to those questions determine memory scope.

Decision 3: Handoff protocol

Handoff is the mechanism by which one agent transfers a task to another. Poor handoff is the primary reason multi-agent systems fail at scale.

The minimum handoff contract includes: what context is transferred, in what format, with what validity guarantees, and how the receiving agent signals completion or failure back to the sender. Without these four components, multi-agent systems degrade into message-passing chaos.

The pattern that works: handoff is a structured data transfer, not a natural language message. The sending agent produces a typed handoff payload. The receiving agent validates it before accepting the task. Completion is signaled through a defined callback, not inferred.

Why these three decisions compound

Each decision constrains the next. A permissive tool schema produces unstructured outputs that can't be stored in typed memory. Untyped memory can't support reliable handoff. The result is an agent system where each component works in isolation but can't be composed.

The inverse is also true. Precise tool schemas enable typed memory. Typed memory supports reliable handoff. A system designed with these three decisions made explicitly can be extended — new agents added, existing agents replaced — without breaking existing behavior.