An agent is only as useful as the tools around it. A broad tool that can “manage the system” sounds convenient, but it creates a large permission boundary and makes mistakes difficult to inspect. I have had better results building small interfaces around the operations people actually need.
One tool, one useful decision
A good tool gives the agent enough context to make one decision and enough structure to make the result predictable. Searching a documentation system, listing an issue, reading a file, or querying a known data source are all easier to reason about than a single endpoint with dozens of unrelated modes.
The tool description is part of the interface. Names, parameters, return shapes, and failure messages affect what the agent will attempt. Ambiguity in the schema becomes ambiguity in the operation.
Read and write should feel different
Read operations are easier to test and safer to expose. Writes need stronger boundaries: explicit authorization, useful previews, validation before mutation, and a result that says what changed. Making write access opt-in is not friction for its own sake; it gives the operator a deliberate control point.
Compact results improve judgment
Returning an entire object graph is rarely helpful. It consumes context while hiding the fields that matter. Compact responses with stable identifiers and links let the agent decide what to inspect next without turning every request into a data-export job.
Transport changes the threat model
A local process and a shared HTTP service are not interchangeable deployments. The latter needs authentication, host and origin controls, request limits, and a clear model for whose credentials are being used. The transport is part of the security design, not a packaging detail.
Make failure ordinary
Tools should fail with messages that explain the next safe action. A missing permission, invalid identifier, unavailable service, and validation failure are different conditions. When they look the same, an agent may retry the wrong thing or invent a workaround.
The practical pattern is simple: narrow tools, explicit permissions, small responses, and failures that remain legible. That gives an agent room to be useful without asking the operator to trust an opaque automation layer.
Current as of September 2026. Examples use placeholders and omit private endpoints, credentials, and deployment details.
Leave a Reply