Your API has forty-one operations, so every request your agent sends carries forty-one tool definitions before it has done any work. Replace them with one shell tool and the agent can write files, call other hosts, and read a progress meter mixed into the JSON it is trying to parse.
What you get
You will end up with one shell tool that runs only the programs you allow, four routes through it to the same API, and a task check that reads the API’s state. This is for you if your agent calls an API and you want to know what a CLI buys and costs.
Short answer
Give the agent one tool that starts an allowlisted CLI without a shell, with a fixed environment, a timeout, and stdout and stderr returned apart. Check each task against the API’s state, not against what the CLI printed. One shell tool and a help text cost a small fraction of the tokens of one definition per operation. The CLI’s own commands then decide which tasks the agent can finish.
You will need
Node 22 or later with curl and jq, a CLI over your API, and an agent loop that can run commands. The API here is a stand-in for JSONPlaceholder on 127.0.0.1. It answers with the real service’s routes, status codes, and record shapes, its records hold invented values, and it keeps writes.1
No model runs anywhere on this page. A scripted policy in policies.mjs issues the commands a
model would send, in order, and decides what to do with each result. The page therefore tests the
CLIs and the loop, not what a model would choose.
Approaches compared
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
cobra CLI on an ogen client | A Go team that wants JSON output and every operation it needs | A CLI to write and keep, because ogen generates a client and no command line | You would rather generate the CLI than own it |
| curl with jq | Any HTTP API, with nothing to build | Long commands, and a curl allowlist strict enough to stop file writes | The agent repeats the same calls and you want short ones |
| Swagger Codegen 2.4 Bash client | A Swagger 2.0 document and a machine with Bash and curl | Parameter values reach eval, and curl options pass straight through to curl | The document is OpenAPI 3, or the arguments come from a model |
| Voxgig SDK catalog Go CLI | A public API already in the catalog, read more than written | Three words only, boru notation instead of JSON, and keys in changing order | The agent must create or delete records |
Voxgig maintains the SDK catalog and its CLIs. The catalog CLI is one of four rows here, not the recommendation.
curl and jq reach every operation and need the strictest argument checks, because curl can do
almost anything. The ogen route gives clean JSON and exit codes, but someone writes and maintains
it. The two generated CLIs cost nothing to write, and each one limits or endangers the agent in
its own way.
Count what each route puts in every request
Each tool definition travels with every request the agent sends. tools.mjs turns each operation in the
catalog’s own JSONPlaceholder document into a tool definition, and measures it beside the one shell
tool the catalog route sent.
node tools.mjs
per-operation tools from the catalog's JSONPlaceholder document
41 tools, 15030 bytes, 3311 tokens in every request
one shell tool for the catalog CLI
1 tool, 585 bytes, 142 tokens in every request
plus --help, read once: 478 bytes, 114 tokens
what --help offers: list / load / update <query?> <entity>
The tokens are counted with the cl100k_base encoding of
js-tiktoken. For a model with another tokenizer the counts are
an estimate, so read them as an order of magnitude. The last line is the cost of the saving: the
catalog CLI’s help offers three words, where the document has 41 operations.
Give the agent one tool that runs no shell
The tool takes a pipeline of argument arrays, at most three stages, and starts each program itself.
Nothing reaches a shell, so there is no globbing, no $(...) and no redirection to refuse.
return async function run(input) {
const bad = checkInput(input)
if (bad) return { refused: bad }
for (const [name, ...args] of input.pipeline) {
if (!Object.hasOwn(programs, name)) return { refused: `${name} is not on the allowlist` }
const why = programs[name].check(args)
if (why) return { refused: `${name}: ${why}` }
}
const cwd = mkdtempSync(join(tmpdir(), 'agent-run-'))
try {
return await execute(input.pipeline, { programs, env, cwd, timeoutMs, maxBytes })
} finally {
rmSync(cwd, { recursive: true, force: true })
}
Each program has its own argument check in programs.mjs. curl accepts a few options and one URL
on the API’s origin, and jq accepts one filter and no filenames. The environment is a fixed
object, so nothing the agent’s host process holds leaks into a child:
// The whole environment the programs see. Nothing is inherited from this process.
const env = { PATH: SYSTEM_DIRS.join(':'), HOME: '/nonexistent', LANG: 'C', JSONPLACEHOLDER_BASE: base }
sandbox.mjs sends nine commands a model could send and prints what the tool did with each:
node sandbox.mjs
sh -c 'curl -s {base}/posts/1'
refused: sh is not on the allowlist
curl -s https://example.com/posts/1
refused: curl: "https://example.com/posts/1" does not start with the API's origin
curl -s '{base}\@example.com/posts/1'
refused: curl: "{base}\\@example.com/posts/1" holds a character curl reads differently
curl -s -o copy.json {base}/posts/1
refused: curl: option -o is not allowed
curl -s -d @/etc/passwd {base}/posts
refused: curl: reading request data from a file is not allowed
jp-bash --host https://example.com getPost id=1
refused: jp-bash: operation --host is not allowed
jp-bash createPost 'title==x'$(touch pwned)''
refused: jp-bash: parameter "title==x'$(touch pwned)'" is not allowed
curl -s {base}/posts/1 | jq . | jq . | jq .title
refused: pipeline must hold one to three stages
jq -n -c 'env | keys'
exit 0: ["HOME","JSONPLACEHOLDER_BASE","LANG","PATH"]
requests that reached the stand-in: 0
The tool runs on Node’s child_process.spawn with
shell: false. The allowlist is the security boundary, so test its neighbors. The sample’s tests
feed each check a URL with a user part, another scheme, a second URL, curl’s glob brackets, and an
unknown option. The backslash case matters because curl reads {base}\@example.com as a user part
and the host example.com, where Node’s URL sees the API.
Each program starts in a process group of its own, so the timeout reaches its children. At
the deadline the tool sends SIGTERM to the group, and SIGKILL to whatever is left a quarter second
later. It then returns exit 124 without waiting on a stream a child still holds open. The Bash
client runs curl through eval, so a stalled request would otherwise keep the tool waiting for as
long as curl waited.
Drive the four tasks and check the API
Four tasks run on every route: read a title, count open to-do items, rename a post and keep its body, and create a post. Each check reads the stand-in’s records afterwards. Every pass count on this page is a scripted policy against the stand-in, not a measure of what a model would do. curl and jq run live:
node agent.mjs curl-jq
route: curl + jq
load: What is the title of post 3?
run curl -s -f {base}/posts/3 | jq -r .title
exit 0
stdout "post 3 title"
answer "post 3 title" check: pass
count: How many open todos does user 2 have?
run curl -s -f '{base}/todos?userId=2&completed=false' | jq length
exit 0
stdout "13"
answer 13 check: pass
rename: Rename post 1 to "Shelved" and keep its body.
run curl -s -f -X PATCH -H 'content-type: application/json' -d '{"title":"Shelved"}' {base}/posts/1 | jq -c '{id, title}'
exit 0
stdout "{\"id\":1,\"title\":\"Shelved\"}"
answer {"id":1,"title":"Shelved"} check: pass
create: Create a post for user 2 titled "Draft".
run curl -s -f -X POST -H 'content-type: application/json' -d '{"userId":2,"title":"Draft","body":""}' {base}/posts | jq -c '{id, title}'
exit 0
stdout "{\"id\":101,\"title\":\"Draft\"}"
answer {"id":101,"title":"Draft"} check: pass
tasks passed: 4 of 4
The other three routes need binaries the gate cannot build offline, so record.sh built them,
drove the same tasks through the same tool once, and committed the runs. report.mjs reads them:
node report.mjs
route tasks tool calls failed
cobra CLI on an ogen client 4 of 4 5 none
curl + jq 4 of 4 4 none
Swagger Codegen 2.4 Bash client 4 of 4 5 none
Voxgig SDK catalog Go CLI 2 of 4 5 rename, create
Voxgig SDK catalog Go CLI, whole record 3 of 4 6 create
Voxgig SDK catalog Go CLI
update sent: PUT /posts/1 { "id": 1, "title": "Shelved" }
10 loads of one post: 3 distinct outputs, same keys every time: yes
--json: exit 1, error: [boru/undefined_word]: undefined word: --json
no arguments, stdin closed: exit 0, stdout "jsonplaceholder>"
Swagger Codegen 2.4 Bash client, called without the tool
a quote in a value: exit 0, the command inside it ran: yes
-o before the operation: exit 0, wrote copy.json: yes
a missing post: exit 0, stdout {}
cobra CLI on an ogen client
a missing post: exit 1, stderr {"error":"decode response: unexpected status code: 404","status":404}
--verbose: stderr "fetching post 3", stdout still parses: yes
The catalog CLI printed {id:1 title:'Shelved'} for the rename, which reads as success. Its
update is the document’s PUT, carrying only the fields it was given. The stand-in stores a PUT as
the whole record, as JSONPlaceholder’s answer to such a PUT shows, so the body was gone. The loss
happened on the stand-in, because the real service stores no write, and only the check against
the records caught it. The whole-record run loads the
post first and sends every field back; it passes the rename and still cannot create, because the
CLI has no create word.
Check it worked
node --test agent.test.mjs
1..14
# tests 14
# suites 0
# pass 14
# fail 0
# cancelled 0
# skipped 0
# todo 0
# duration_ms 2209.048911
The first test runs the curl route live and compares it with its recording, call for call. Others hold each recorded route to its task results, and the stand-in to the routes and status codes the real service answered with. The timeout tests check that no process a program started outlives the tool.
When it goes wrong
The JSON does not parse. curl writes its progress meter to stderr, and a tool that collects both streams into one string puts the meter in front of the body:
node progress.mjs
command exit stdout alone parses both streams parse first bytes of both
curl {base}/posts/1 0 yes no " % Total % Receive"
curl -s {base}/posts/1 0 yes yes "{\n \"userId\": 1,\n \"id"
Return stdout and stderr apart, and parse stdout only. The generated Bash client calls curl
without -s, so it shows the meter on every call, and only the split saved its route.
The parse works once and fails the next time. The catalog CLI prints boru notation, which
JSON.parse refuses, and ten loads of one post came back in more than one key order. Read fields
by name, as the catalog policy does with a pattern, and never compare its output as text.
A failed call looks like success. The Bash client exits 0 on a 404 and prints {}, so the exit
code tells the agent nothing. Check the body, or prefer a CLI that exits 1, as the ogen route does.
Drive a Swagger Codegen client and a Go CLI you write
ogen writes Go clients and servers. Its
configuration page lists clients, servers, webhooks and
telemetry as features. The full list in its repository’s gen/features.go at v1.24.0 has no
command line either, so a team on ogen writes the CLI itself. The
sample’s ogen-cli/main.go wraps the generated client in cobra commands, with
JSON on stdout, a JSON error on stderr, and exit 2 for bad usage. The scripted policy completed all four tasks through it. It
is the better choice when you need writes and stable output, and can afford to own the code.
Swagger Codegen’s 2.x line ships a bash client generator, and its 3.0.85 langs list has none.
The 2.4.53 client read the page’s Swagger 2.0 document, and the tool pins its --host for it. Two
things make its argument check necessary. A value holding a quote ran the command inside it, because
the script builds curl’s command line and passes it to eval. A curl option placed before the
operation reached curl, and -o wrote a file. Do not hand this client to an agent without the argument check programs.mjs puts in front of it,
which the tests hold to each of those inputs. With the check in place, the scripted policy completed
all four tasks through it. It is the better choice for a Swagger 2.0 API whose callers have only
Bash and curl.2
When not to do this
Do not hand an agent a shell with your credentials in its environment. Build the environment
yourself, as agent.mjs does, and give each program an argument check that refuses by default.
Do not trust a CLI’s output as proof that a task finished. The catalog CLI’s rename printed a plausible record while the post lost its body.
Skip the Voxgig SDK catalog CLI when the agent must create or delete: it offers list, load and
update only. Pick the cobra CLI on an ogen client when you need every operation as JSON and can
own the code. Keep per-operation tools when you have a handful of operations, because a few typed
schemas let the model’s own tool-calling check the arguments.
Related how-tos
Last verified
Verified 2026-11-22 against Node 22.23.5, curl 8.5.0, jq 1.7 and js-tiktoken 1.0.21. The curl
route, the sandbox, and the progress commands run live. record.sh built the catalog CLI at
a21ce5a97d8e with Go 1.24.7, generated the ogen v1.24.0 client and its cobra CLI with Go 1.25.0,
and generated the Bash client with Swagger Codegen 2.4.53. It drove each once against the same
stand-in, and report.mjs reads what it committed. No task run or probe sent a request beyond the loopback interface.
Footnotes
-
The JSONPlaceholder guide says of a created post that the resource is not really created on the server, “but the response is faked as if” in its place. A check that reads the records back has nothing to read on the real service, which is why the stand-in keeps what it is sent. ↩︎ Back to text
-
The Swagger Codegen 2.4.53 README lists its API clients alphabetically, so Bash sits between Apex and C#. The client it writes calls curl,
sed, andcolumn, checks for all three before it starts, and names the missing package whencolumnis absent: bsdmainutils. ↩︎ Back to text