Unix philosophy gave us a design principle half a century ago that software engineering repeatedly forgets and rediscovers every decade:
Write programs that do one thing and do it well. Write programs to work together. Write programs to handle text streams, because that is a universal interface.
In modern AI agent architecture, the prevailing instinct has been the exact opposite. Frameworks invite developers to wrap entire REST and GraphQL monoliths into monolithic JSON schemas, passing megabytes of parameter descriptions to an LLM on every single turn.
The result? Sluggish execution, hallucinated optional fields, high token bills, and fragile agents that get confused by their own capabilities.
The Problem with Schema Bloat
When an agent is handed 40 multi-nested tools:
- Context Saturation: 15,000 tokens of your prompt are eaten up just declaring what the tools might do before the user has even finished their sentence.
- Ambiguity Multipliers: When two tools overlap slightly in purpose, the model vacillates, guessing parameter nuances or retrying failed invocations.
- Debugging Nightmares: Tracing why a tool call failed requires sifting through hundreds of lines of serialized JSON rather than reading an exit code and a single stderr line.
Small, Composable CLI Primitives
Instead of building massive bespoke MCP wrappers for every internal database query, design your tools as sharp command-line utilities.
- A tool should accept standard arguments or flags.
- Output should default to concise, human-and-model-readable lines (or compact NDJSON if structured data is mandatory).
- Exit codes (
0for success, non-zero for failure) provide deterministic signaling that doesn't require probabilistic interpretation.
# Clean, deterministic, zero schema overhead
imail organize --account google --limit 100
wa contacts search "Alex"
bb pr list --repo core-api
When an agent needs to execute an operation, running a single concise command string with deterministic exit status is faster, cheaper, and vastly more reliable.
Return to first principles: build small, sharp tools that do one thing well, and let the agent compose them.
