Curating the tool surface

Why curate

An OpenAPI spec built for humans is generous—hundreds of small, separate endpoints. Agents pay a real cost for every tool they see: more context, more chances to pick the wrong one. Converting every operation into a tool, 1:1, can leave agents with a bloated, confusing tool list.

Curation lets you decide what agents actually see.

By tag

Most specs group operations with OpenAPI tags. Use these to include or exclude by tag:

npx klaridian generate --spec ./api.yaml --out ./my-server \
  --exclude-tags internal,admin

npx klaridian generate --spec ./api.yaml --out ./my-server \
  --include-tags public

By operation ID

Exclude specific operations regardless of tag:

npx klaridian generate --spec ./api.yaml --out ./my-server \
  --exclude-operation-ids deleteAccount,purgeData

By path or method

Some specs don't use tags at all. --include-paths, --exclude-paths, --include-methods, and --exclude-methods work without them—they match on the operation's URL path (regex) or HTTP method:

npx klaridian generate --spec ./api.yaml --out ./my-server \
  --exclude-paths "^/internal/" \
  --exclude-methods delete

Path/method filters and tag filters can combine—an operation must pass both to be included.

Interactively

Prefer to pick tags by hand instead of writing flags? Use --interactive:

npx klaridian generate --spec ./api.yaml --out ./my-server --interactive

This prompts you for which tags to include before generating. It needs a real terminal—it fails with a clear error in CI or scripts, instead of silently generating with no tools.