Playground Tool Configuration#

The Playground uses a metadata-driven system to render, validate, and serialize tool definitions for LLM function-calling. The central UI component is PlaygroundTool, which wraps a JSON editor and exposes quick-edit inputs for the two most-used fields: function name and description.

Component: PlaygroundTool#

File: web/oss/src/components/Playground/Components/PlaygroundTool/index.tsx

The component holds three pieces of local state 1:

functionName and functionDescription are synced bidirectionally with toolString via useEffect hooks 2: editing either quick-edit field patches the JSON, and editing the JSON raw updates both fields. The parsed tool value is forwarded upstream via editorProps.handleChange 3.

The raw JSON editor is SharedEditor configured in codeOnly mode, with TOOL_SCHEMA passed as the live validation schema. Deletion is handled through the usePlayground mutate hook, which splices the tool out of its parent array 4.

Validation Schema: TOOL_SCHEMA#

File: web/oss/src/components/Playground/Components/PlaygroundTool/assets/index.ts

TOOL_SCHEMA is a plain JSON Schema object that mirrors the OpenAI function-calling convention 5:

{ type: "function", function: { name, description, parameters: { type, properties, required, additionalProperties } } }

Required at root: type, function. Required inside function: name, description, parameters. Required inside parameters: type, properties, required, additionalProperties 6.

Metadata Generation: ToolConfiguration#

File: web/oss/src/lib/shared/variant/genericTransformer/index.ts

When the generic transformer encounters an array property whose title is "Tools" and no itemMetadata is set, it auto-generates a ToolConfiguration metadata object 7. This metadata describes the shape of each tool item — type, function.name, function.description, function.parameters — and drives how the transformer processes each element.

Critically, when metadata.title === "Tools", the transformed object is stored as { value: item } (i.e., the raw item value) rather than being recursively decomposed 8. This means tool objects pass through as-is into the variant state.

The ConfigMetadata type union (StringMetadata | NumberMetadata | ArrayMetadata | ObjectMetadata | BooleanMetadata | CompoundMetadata) covers all metadata variants used by the transformer 9 — there is no PermissionMetadata or similar type in the schema.

Payload Construction: transformToRequestBody#

File: web/oss/src/lib/shared/variant/transformer/transformToRequestBody.ts

Tools flow into the request body as part of ag_config. The transformer builds ag_config by merging promptConfigs (extracted per prompt via extractValueByMetadata) and customConfigs 10. Any prompt whose llmConfig includes a tools array (typed as any[] in LLMConfig) contributes those tools to ag_config when extractValueByMetadata traverses the prompt structure.

The LLMConfig interface also exposes toolChoice?: "none" | "auto" | null 11 — this is serialized alongside tools in the prompt config.

Known Gap: Missing Permission Field#

The TOOL_SCHEMA and the auto-generated ToolConfiguration metadata define only the four fields from the OpenAI function-calling spec (type, name, description, parameters). There is no permission field in either the UI schema 5 or the auto-generated metadata 7.

If an Agent Template interface elsewhere in the system exposes a permission field on tools, the Playground UI will not render or preserve it — the field would be silently dropped during the metadata-driven round-trip unless the raw JSON editor is used directly.

Key Files at a Glance#