Consumer
Understand This First
- Contract – the consumer relies on the promises an interface makes.
Context
Every interface exists to be used by someone or something. A consumer is the code, person, system, or agent on the other side of that interface: the party that calls the function, hits the API, reads the documentation, or invokes the tool. The concept operates at the architectural scale because the identity and needs of your consumers shape every structural decision you make.
Consumers are not always human. In modern systems, a consumer might be a frontend application calling a backend API, a microservice subscribing to an event stream, a CI/CD pipeline invoking a build tool, or an AI agent using a function it was given access to.
Problem
How do you design something when you don’t fully control, or even fully know, who will use it?
Forces
- Different consumers have different needs, capabilities, and expectations.
- Optimizing for one consumer may make things worse for another.
- You can’t anticipate every future consumer, but you can design for the likely ones.
- Consumers who are ignored or poorly served will work around your design in ways you didn’t intend.
Solution
Identify your consumers explicitly. Ask: who or what will use this interface? What do they need from it? What are their constraints? Then design the interface to serve those consumers well.
When the consumer is another piece of code, design for clarity and consistency. When the consumer is a human, design for discoverability and forgiveness. When the consumer is an AI agent, design for unambiguous descriptions and predictable behavior. Agents reason from descriptions and examples, not intuition.
Consumer-aware design doesn’t mean giving every consumer everything they want. It means understanding the contract from the consumer’s perspective and making sure the interface keeps its promises.
How It Plays Out
A team builds an internal API. Initially, the only consumer is their own frontend. Later, a partner team wants to integrate. The API was designed with clear documentation and stable versioning, not because the original team anticipated the partner, but because they treated “future unknown consumer” as a design constraint. The integration goes smoothly.
An AI agent is a consumer of the tools you give it. If you provide a search_codebase tool with a vague description (“searches code”), the agent will guess at the parameters and often guess wrong. If you describe it precisely (“searches file contents for a regex pattern; returns matching lines with file paths and line numbers”), the agent uses it correctly. Treating the agent as a first-class consumer improves results dramatically.
When designing tools for AI agents, write the tool description as if it were documentation for a capable but literal-minded new team member. Be explicit about what happens on success, on failure, and on edge cases.
“Write a clear description for the search_codebase tool: what it accepts (a regex pattern and optional file glob), what it returns (matching lines with file paths and line numbers), and what happens when there are no matches.”
Consequences
Thinking in terms of consumers shifts the design focus from “what does this thing do?” to “what does someone need from this thing?” That shift leads to better interfaces, clearer contracts, and fewer surprises.
The risk is over-accommodation. Trying to serve every possible consumer leads to bloated interfaces that serve none of them well. The principle of “minimum viable interface” applies: serve the known consumers well, and keep the door open for future ones without committing to them.
Related Patterns
- Uses: Interface — a consumer interacts through an interface.
- Depends on: Contract — the consumer relies on the promises an interface makes.
- Shapes: Abstraction — what to abstract depends on who the consumer is.
- Related to: Coupling — a consumer is coupled to what it consumes.