Agent Toolboxes

The main aim of treeparse is to build toolboxes you can hand to agents. Instead of pasting a full tool schema into the agent's context, you give it a purpose-only stub. The agent pulls the command tree or the machine-readable schema itself, when and only when it needs it. This keeps agent context small and makes every treeparse CLI self-describing.

The stub

Every treeparse CLI has a built-in --stub flag:

$ toolbox --stub
toolbox — Creative toolbox.

This is a CLI toolbox. Discover its commands and
full schema on demand:
  toolbox -h   # command tree
  toolbox -j   # machine-readable JSON schema

The output is always plain text (no ANSI codes, even at a TTY), so it can be redirected straight into a skill or agent prompt file:

toolbox --stub > skill.md

That one paragraph is all the agent needs up front: the toolbox's name, its purpose, and how to learn more.

Schema discovery

Two channels, never mixed:

• Tree (human) — -h / --hv render a rich command tree (colors, soft-wrap, branch pruning). For terminals and people.
• JSON (machine) — -j / --json prints plain json.dumps only: no ANSI, no rich wrapping, parseable as-is by agents, jq, and scripts (including under a PTY).

When the agent decides to use the toolbox, it runs the discovery flags itself:

On parse failure

A wrong invoke (unknown flag, bad choice, missing argument) does not dump the schema. The error reminds the agent how to get the current one:

Error: unrecognized arguments: --stale-flag

Rediscover the current schema, then retry from that output:
  toolbox -j   # machine-readable JSON schema
  toolbox ink new -h   # command tree for this path

Retry from that output, not from memory. After install or upgrade, rediscover the same way.

From Python

cli.stub_text() returns the same blurb as a string, for generating skill files programmatically:

from mytools import toolbox

with open("skill.md", "w") as f:
    f.write(toolbox.stub_text())

Why purpose-only

• Context economy — a toolbox with dozens of commands costs the agent one paragraph, not pages of schema.
• Always current — the agent reads the schema from the installed CLI at use time; a pasted schema goes stale.
• Progressive disclosure — humans use the tree (-h shape, --hv docstrings); machines use -j for the full model. Never mix rich into JSON.

Write good help= strings on the root cli and on every command — they are what the agent sees first (--stub, -h) and what -j carries as structured data.