Wire a tool into the schema-driven AI Tools panel

The “AI Tools” panel in saas-2.0 is not hand-authored. There is no per-tool React component, no form JSX, no config file you have to edit. The panel is built at runtime from each tool’s registered Pydantic JSON Schema — the same input_schema_json the agent plans against. Ship a tool worker with a typed input model and it shows up in the panel with a working form. That is the whole integration: there is no frontend step.

Prerequisite: you already did the work

If you followed Add a new generation tool worker, your input model’s model_json_schema() is already registered. This page explains how that turns into a form so you know what to expect — and the handful of traps that make a tool render badly (or not at all).

The contract chain: schema in, form out

The schema makes six hops from your Python model to a rendered control. Every link is a committed, verifiable path — nothing is inferred or guessed:

#	Where	What happens
1	Worker	BaseTool.input_schema_json() returns json.dumps(self.input_model.model_json_schema()) and rides RegisterTool on boot.
2	generation.tools row	Stored as the input_schema jsonb column (Tool.input_schema_json, field 7). Re-register upserts ON CONFLICT (environment, model, operation).
3	GetActiveTools	The Go data service returns active rows for the environment, cached under tools:active:{environment}. RegisterTool invalidates that key, so a reboot refreshes the panel.
4	Gateway ListTools	core-gateway-consumer projects each internal Tool down to a consumer-safe ToolView and forwards input_schema_json verbatim.
5	BFF GET /api/tools	The Next.js route proxies GenerationService.ListTools and returns the ToolView rows as JSON.
6	Panel	parseToolSchema() turns the JSON Schema into panel controls; buildPayload() coerces the entered values back to the Pydantic-typed payload for createGeneration.

The two protos that define the contract:

• Registry side — GenerationToolDataService in generation/tool/v1/tool.proto. Tool carries input_schema_json (field 7, db_column "input_schema") and output_schema_json (field 8). GetActiveTools is require_internal_auth, target_db = "prod", cached 3600s under tools:active:{environment}.
• Consumer side — GenerationService.ListTools in consumer/v1/consumer.proto. ToolView exposes only id, name, operation, model, description, cost_unit, input_schema_json — no credentials, pricing, or rate-limit internals. The response is a flat repeated list; grouping is a UI concern, never in the proto.

The gateway projection is a one-liner — mappers.py::tool_view copies input_schema_json=tool.input_schema_json, and servicers/generation.py::ListTools calls GetActiveTools with the gateway’s own environment.

How the form is built

src/panels/schema.ts (parseToolSchema) walks the schema’s properties and maps each one to a control. It resolves $ref / allOf / anyOf (so X | None optionals and Pydantic $defs enums work), then applies these rules:

JSON Schema shape	Rendered control
x-sv-file-input marker (single or list item)	Library file picker (submits the picked file id)
enum	Select (numeric enums coerced back to numbers)
boolean	Toggle
integer / number with minimum and maximum	Slider (else a number input)
object (or nested properties)	JSON textarea
array of enum	Tag multi-select
array of objects	JSON-array textarea
string whose name/description hints at a media file	Upload
long / prompt-named string (prompt, lyrics, description, …)	Multi-line prompt
any other string	Text input

buildPayload() is the inverse: it coerces each entered value back to the Pydantic-expected JSON type before createGeneration — numbers to numbers, JSON textareas parsed, file pickers reduced to file id(s), empty optionals dropped.

The file-field marker beats the name heuristic

A field is treated as a real library file only when it carries the x-sv-file-input marker that a soundverse-py FileInput field stamps into its schema — that is the authoritative signal, and it makes the picker draw from the user’s real library and submit a file id the tool resolves server-side. The older name/description heuristic (audio, url, melody, .wav, …) is only a fallback that emits a plain upload control. If you want a proper file input, declare a FileInput field on your input model — don’t rely on the field name. See Add durable per-file metadata for the file/attributes model.

Grouping and submit

1. One card per operation. libraryScript.js::loadTools() fetches the registry via listToolsCached() (GET /api/tools) and groups the flat list by operation into a backendOps map — operation → { label, description, models[] }. Each operation becomes one card.

2. Models become a dropdown. Tools that share an operation but differ by model (e.g. several song-gen versions) become the selectable Model dropdown inside DynamicToolPanel.tsx. Switching the model rebuilds the form from that tool’s schema.

3. Submit runs a real generation. On submit, buildPayload produces the payload and the panel calls createGeneration({ toolId, projectId, workspaceId, payloadJson, license }), then dispatches a sv:generation-started event the app shell can open a live stream from.

Traps

Registry-only — no curated fallback

The grid lists only tools returned by ListTools. If the registry is unreachable (or no worker has ever registered), backendTools is [] and the grid shows an empty state — there is no demo/curated fallback. A missing tool is almost always a registration problem: no worker booted, or an ENVIRONMENT mismatch between the worker and the gateway (the panel is scoped per environment via tools:active:{environment}).

Agent sub-tools are hidden on purpose

Some tools register as consumer tools (so the agent can call them) but must not appear as standalone panel cards. loadTools() skips an _INTERNAL_OPS set — currently name_song, wait_for_task, generate_album_art. If you add an agent-orchestrated helper tool, add its operation there so the card grid doesn’t try to render it. If it becomes a real user-facing tool, remove it from that set.

The panel does NOT need a core-mcp restart

Adding a tool worker tells you to restart core-mcp after a schema change — that is for the agent’s in-memory schema cache. The panel reads a different path: RegisterTool invalidates tools:active:{environment}, so the panel picks up a changed schema on the next worker reboot with no gateway or core-mcp restart. (Absent a re-register, the 3600s cache TTL eventually refreshes it anyway.)

Optional enrichment overrides

Hand-authored configs under src/panels/configs/ are only optional enrichment — richer copy, icons, ordering. enrichmentConfigFor() matches one to a live registry tool by id/slug/name/operation and prefers it over the generated form. You never need one; the generated form always works from the schema alone.

A new ToolView field needs the proto to be republished

input_schema_json reaches the browser only because it is generated into the published web and Python stubs (soundverse-proto-web, soundverse-proto-python) that the saas app and gateway depend on. If you add a new field to ToolView, it will not flow until the proto is regenerated and republished and both consumers bump their dependency — see the proto → deploy cascade. Existing ToolView fields are already published, so ordinary new tools need no proto change at all.

Related

• Add a new generation tool worker — where the input model (and thus the form) is written
• Add pricing to a tool — the other must-do so the tool isn’t rejected at call time
• core-gateway-consumer — the ListTools / ToolView projection
• The contract: proto as source of truth — why the schema is authoritative end to end
• BFF routes → RPC map — GET /api/tools and the rest of the BFF surface
• Tool catalog — every operation and model currently registered