Agent tool registry

GET /api/v1/developer/tools.json serves the agent tool registry as a JSON Schema array. Dynamic-discovery agent stacks (Vercel AI SDK, LangChain, raw OpenAI / Anthropic SDKs without the bundled adapters) fetch this once and have everything they need.

The registry is the single source of truth. The Python SDK’s Toolkit.as_anthropic_tools() / as_openai_tools() / as_json_schema() all derive from it, and the backend snapshot is regenerated on every SDK release via a CI parity check.

This page is a JSON Schema reference rather than a CRUD resource, so there is one read endpoint. The REST example authenticates with an X-API-Key header; set PICTOGRAPH_API_KEY in your shell to copy-and-run it.

Fetch the registry

The Python SDK builds the same payload locally (no HTTP round-trip), and the REST endpoint returns it over the wire. Any role works (the call is read-only).

from pictograph.agents import create_toolkit

toolkit = create_toolkit()           # reads PICTOGRAPH_API_KEY
schema = toolkit.as_json_schema()    # same payload the REST endpoint returns
for tool in schema:
    print(tool["name"], tool["required_role"])

curl -s "https://api.pictograph.io/api/v1/developer/tools.json" \
  -H "X-API-Key: $PICTOGRAPH_API_KEY"

Endpoints

URL	Notes
/api/v1/developer/tools	Trailing-slash-tolerant. Returns the full payload.
/api/v1/developer/tools.json	Same content. Matches the conventional *.json URL.

Response shape

{
  "tools": [
    {
      "name": "upload_dataset_from_folder",
      "description": "Use when the user asks to upload a folder of images …",
      "input_schema": {
        "type": "object",
        "properties": {
          "dataset_name": { "type": "string", "description": "…" },
          "folder":       { "type": "string", "description": "…" }
        },
        "required": ["dataset_name", "folder"],
        "additionalProperties": false
      },
      "required_role": "member",
      "credit_cost": 0,
      "idempotent": false
    }
  ],
  "version": "1.0.0",
  "count": 32,
  "generated_at": "2026-04-19T…Z"
}

Tool metadata

Field	Notes
name	Snake-case identifier. Stable across SDK versions.
description	Anthropic “use when X” framing. Agents read this to choose between tools.
input_schema	Pydantic-generated JSON Schema with extra: forbid.
required_role	Minimum org role on the calling API key. Backend re-enforces.
credit_cost	Approximate cost (0 for read-only / free ops). Agents may gate.
idempotent	When true, agents may safely retry on transient failures.

Tool list (v1.0.0)

32 tools across 12 categories. See the agents overview for details and the dispatch pattern.

Category	Tools
Workflows	upload_dataset_from_folder, auto_annotate_dataset, train_pipeline, full_pipeline
Datasets	list_datasets, get_dataset, create_dataset, delete_dataset
Images	upload_image, delete_image
Annotations	get_annotations, save_annotations
Auto-annotate	auto_annotate_point, auto_annotate_box, auto_annotate_text
Search	search_by_tag, search_by_similarity
Exports	create_export, list_exports, download_export
Training	get_training_status, cancel_training
Models	list_models, download_model
Deployments	list_deployments, get_deployment, create_deployment, delete_deployment
Credits	get_credit_balance, estimate_credit_cost
Connectors	validate_connector, import_from_connector

SDK equivalents

The registry is also importable directly, and the toolkit emits provider-shaped tool lists for the Anthropic and OpenAI SDKs.

from pictograph.agents import REGISTRY, create_toolkit

# Inspect the registry directly (no client needed):
for descriptor in REGISTRY:
    print(descriptor.name, descriptor.required_role, descriptor.credit_cost)

# Or build provider-shaped tool lists from the same source:
toolkit = create_toolkit()
schema = toolkit.as_json_schema()                # same payload, no HTTP round-trip
anthropic_tools = toolkit.as_anthropic_tools()   # name/description/input_schema only
openai_tools = toolkit.as_openai_tools()         # OpenAI function-calling format

The CLI also dumps the registry locally:

pictograph agents export-tools -o tools.json

Versioning

The version field tracks the SDK release that generated the snapshot. Tools may be added between minor versions; renames and removals only happen at major versions and are listed in the changelog.

Drift protection

The backend snapshot at routes/developer/_tools_snapshot.json is verified against the SDK’s live registry on every CI build (via scripts/generate_tools_snapshot.py --check). PRs that change one without the other fail.