Agent-Compatible Tools: Interfaces for Humans and AI Systems
How to design CLIs, APIs, and MCP tools with discoverable capabilities, typed inputs, stable errors, dry runs, scoped credentials, approvals, and audit records.
Direct answer
Direct answer: Agent-compatible tools
A tool becomes agent-compatible when its capabilities and consequences are machine-readable without becoming less legible to people. It needs typed inputs, predictable structured output, stable error categories, runtime discovery, scoped credentials, redacted logs, rate-limit and retry metadata, dry-run or proposal modes, explicit approval before high-impact writes, and an audit record tied to the exact action. A pleasant human CLI is not automatically a safe agent interface.
Written for Developer-tool teams, platform engineers, API designers, MCP implementers, security engineers, and organisations exposing operational systems to agents.
Architecture
The operating principles
Make capabilities discoverable
An agent should be able to learn supported operations, schemas, authority requirements, and side-effect classes at runtime rather than infer them from prose.
Return structured success and failure
Stable JSON, exit codes, error categories, correlation IDs, and retry hints let agents distinguish malformed requests, missing authority, rate limits, and uncertain outcomes.
Design safe preview modes
Dry-run and proposal outputs should reveal the exact resources and effects without claiming that a downstream system has validated or reserved them.
Scope and isolate credentials
Tools should use the narrowest credential that fits the operation, keep secrets out of model context and logs, and separate read, propose, approve, and execute authority.
Test the uncertain state
The hardest case is not a clean failure; it is a timeout after a remote service may have committed the write. Give the caller a receipt or reconciliation route.
Evidence
What supports this view
hubspot-cli
A Rust CRM CLI with structured JSON, stable error and exit semantics, discovery, dry-run, profiles, MCP, and stated secret-handling controls. The repository has no published adoption record or security audit.
Inspect the source ↗apollo-io-cli
A Rust interface exposing human subcommands and JSON-in/JSON-out operations across a large API surface.
Inspect the source ↗dial-coder
A coding-agent design with risk-selected modes, multiple review roles, approvals, destructive-operation blocking, and optional container execution.
Inspect the source ↗Scope and limitations
Where the result applies
- —Repository design and README statements are not independent evidence of adoption or security effectiveness.
- —Examples and demonstrations should use mocks or disposable sandbox accounts, never production CRM or customer credentials.
- —MCP compatibility does not by itself make a tool safe; authority and side effects still require an application-specific control design.
Common questions
Answers in plain language
What makes a CLI safe for AI agents?+
Typed inputs, predictable machine-readable output, stable failures, discovery, scoped credentials, redacted logs, dry-run, explicit approval for high-impact writes, idempotency, receipts, and auditability.
Why are stable error codes important for agents?+
Without them, a model may treat missing permission, malformed input, rate limiting, and uncertain completion as interchangeable text and choose an unsafe retry or fallback.
Is an MCP server automatically agent-safe?+
No. MCP standardises how capabilities are exposed, not whether their credentials are scoped, their effects are authorised, or their failures and audit records are operationally safe.
How should a tool handle destructive actions?+
Classify them explicitly, show the exact proposed effect, require appropriate authority or human approval, use idempotency and receipts, and support reconciliation or compensation when possible.
Continue exploring