Agent tools

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 as_anthropic_tools() / as_openai_tools() / as_json_schema() all derive from it, and a parity check fails the build if the served snapshot and the SDK’s registry disagree.

This is a reference endpoint rather than a CRUD resource, so there is one read call. Any role works.

Fetch the registry

The SDK builds the same payload locally with no HTTP round-trip; the CLI writes it to a file; the REST endpoint returns it over the wire.

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"])

pictograph agents export-tools --output tools.json

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

/api/v1/developer/tools returns identical content, for callers that prefer a path without the extension.

Response shape

{
  "tools": [
    {
      "name": "upload_dataset_from_directory",
      "description": "Use when the user asks to upload a directory of images …",
      "input_schema": {
        "type": "object",
        "properties": {
          "dataset_name": { "type": "string", "description": "…" },
          "directory":    { "type": "string", "description": "…" }
        },
        "required": ["dataset_name", "directory"],
        "additionalProperties": false
      },
      "required_role": "member",
      "cost_micro_usd": 0,
      "idempotent": false
    }
  ],
  "version": "1.0.0",
  "count": 37,
  "generated_at": "2026-08-02T06:06:11Z"
}

Field	Notes
name	Snake-case identifier. Stable across SDK versions.
description	“Use when X” framing. Agents read this to choose between tools.
input_schema	JSON Schema with additionalProperties: false.
required_role	Minimum org role on the calling API key. Re-enforced server-side.
cost_micro_usd	Approximate cost in micro-USD (0 for read-only and free ops). Agents may gate on it.
idempotent	When true, agents may safely retry on transient failures.

Tool list (v1.0.0)

37 tools. See the agents overview for the dispatch pattern.

Category	Tools
Pipelines	upload_dataset_from_directory, auto_annotate_dataset, augment_dataset, tile_dataset, train_pipeline
Datasets	list_datasets, get_dataset, create_dataset, delete_dataset
Images	upload_image, delete_image, review_image, set_image_split, rebalance_dataset_splits
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
Notifications	list_notifications
Credits	get_credit_balance, estimate_credit_cost
Connectors	validate_connector, import_from_connector

Provider-shaped tool lists

The registry is importable directly, and the toolkit emits tool lists already shaped for the Anthropic and OpenAI SDKs from that same source.

from pictograph.agents import REGISTRY, create_toolkit

for descriptor in REGISTRY:      # no client needed
    print(descriptor.name, descriptor.required_role, descriptor.cost_micro_usd)

toolkit = create_toolkit()
anthropic_tools = toolkit.as_anthropic_tools()   # name/description/input_schema
openai_tools = toolkit.as_openai_tools()         # OpenAI function-calling format

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.