Small AI-Built Tools: Set the Boundary Before You Build

Give a coding agent one bounded job before asking it to replace a whole system. A useful small tool might prepare copies of selected files and produce a reviewable manifest. Its first specification should say what it accepts, what it creates and what it must leave alone, because an agent that is not told where the edge is may not find one on its own.

Small should describe the responsibility, not the number of screens or lines of code. A tiny application that silently becomes the only place important records are stored has already taken on a large obligation. This guide sets out the boundary worksheet, how to decide whether the finished tool needs a model at runtime, what “preserve the original” has to mean for files, how rejected cases keep a tool small, the ways a utility quietly becomes a system, and the ownership decision that has to happen after the first successful run.

Teams reach for “small tool” to mean low risk, and then measure smallness by the wrong thing. For example, a script of forty lines that is the only copy of a customer list is not small. A two-thousand-line utility that reads selected files and writes renamed copies to a new folder is. The difference is what happens if the tool is wrong or disappears: in the first case data is lost; in the second, someone deletes a folder and runs it again.

Framing smallness as responsibility changes the brief a coding agent receives. Instead of “build me a quick tool to tidy the asset library”, which has no edge, the brief becomes “build a tool that takes a list of files I give it, writes renamed copies to an output folder I name, and lists what it did”. The second brief has three nouns the agent cannot expand without asking, and that is what keeps the tool a tool.

The worksheet below describes a hypothetical file-preparation utility. It creates renamed copies of selected assets and lists the mapping for review. It does not edit the source library or publish anything. These are proposed requirements, not the report of a tool we tested, and the “Reason” column is there so that each boundary survives the moment someone asks the agent to relax it.

Four of the six rows are about what the tool refuses to do. That ratio is deliberate. A feature list tells the agent what to build; a boundary list tells it what to stop building, and the second only constrains the agent if it is written down.

An agent can write a deterministic utility: software that follows fixed rules once it is built. Renaming according to an agreed pattern does not necessarily require a model call at runtime. The agent’s role in creating the tool and the tool’s need for AI are different decisions, and conflating them produces tools that call a model to do what a regular expression would have done, with a review problem attached to every run.

Anthropic’s guidance on building agents recommends starting with the simplest adequate solution and adding complexity when needed. We apply that principle here as a design choice; the guidance does not measure the cost of the example utility. The simplest adequate solution for a rename is a rule; a model enters only when the rule cannot be written because the task requires interpretation.

Use a runtime model when the task actually requires interpretation, and specify how uncertain interpretations are reviewed. If a fixed rule is enough, write down the rule and ask the coding agent to implement it directly. That gives the reviewer a smaller set of behaviors to inspect, and it gives the tool the same output on the same input every time, which is the property that makes a manifest worth reading.

For files, “keep a copy” can mean more than preserving visible content. Filenames, timestamps, permissions and embedded metadata can affect how another application uses the result. Decide which properties matter for this job and verify them explicitly, because “the copy opened fine” tests the one property that was never in doubt.

The Python file-operation documentation warns that even high-level copying functions cannot preserve all file metadata. That is a concrete reason not to treat a successful copy operation as proof of complete preservation. The behavior depends on the operation and platform, and an agent that reaches for the convenient copy call can produce copies that match in content but differ in properties the next application reads.

Where metadata preservation is essential, verify the required properties or reject the unsupported transformation. A convenience copy should not be described as a backup system. The preservation row of the contract is satisfied when the original is untouched; whether the copy is a faithful copy is a separate requirement that has to be named if it matters.

A bounded utility should be allowed to say that an input is unsupported. That is often a better first release than adding a partial converter, background sync, account system and shared database because one file did not fit the rule. The rejection list is not a failure report; it is the tool telling you exactly where its edge is, in a form you can decide about.

Review the rejected cases after using the utility on a representative selection. If many legitimate inputs fall outside the contract, change the scope deliberately. If only a rare exception needs manual handling, document that route instead of making every user depend on a more complex application. Either way the decision is made by a person looking at a list, not by an agent looking at an error.

This differs from the system-replacement rollout pattern, which assumes an enduring application and a migration. A file utility can remain a separate, limited tool for its entire useful life.

Nobody decides to turn a rename script into the asset library of record. It happens one helpful step at a time, and each step is the kind an agent can take unprompted if the boundary was never written. The illustrative sequence below is the pattern the contract’s rows exist to interrupt.

The in-place edit: to save disk space the tool starts renaming originals instead of writing copies, and the preservation row is gone. The remembered state: to avoid reprocessing, the tool keeps a record of what it has seen, and now there is a database with no owner. The silent overwrite: two inputs map to one name and the tool picks the later one, and a file is gone with no entry in the manifest. The quiet dependency: another script starts reading the tool’s output folder as its input, and the disposable utility is now upstream of something that matters.

Each step was reasonable in isolation. Each one is a boundary row being crossed without a decision. The manifest and the rejection list are what make the crossing visible, because a tool that reports what it did and what it refused is much harder to drift silently.

For a disposable utility, keep the source and reproduction instructions until acceptance. For continued use, name a maintenance owner before it becomes a dependency. The moment to decide is the first successful run, because that is the last moment the tool has no users.

For a maintained utility, name who receives failure reports, how dependency changes are checked and what happens when the input format changes. A named owner need not create a large support process, but users should know where unresolved work goes; the same ownership rule that governs an agent handing off a task governs a tool handing off its future, and our guide to who owns unfinished work applies almost unchanged.

Use the file-output acceptance reference to inspect the deliverable. If the requirement expands into an enduring application, revisit the build-versus-buy framework with that larger scope. Teams that want the boundary contract and the ownership decision built into how they brief coding agents can work with our AI transformation practice.