Tool Schema

A tool’s parameter schema, rendered as something a person can read. Required, type and default get their own column, because those are the three questions anyone actually has about a parameter.

src/components/ui/tool-schema.tsx

About

From the component's own source, where it was written.

A tool's parameter schema, rendered as something a person can read.

Tool definitions are JSON Schema, and JSON Schema shown as JSON is a wall. The questions anyone actually has are "what must I pass", "what type is it" and "what happens if I leave it out" — so required, type and default are the three things given their own column, and everything else is prose.

Nesting is expanded one level by default and collapsible below that. A deeply nested schema rendered fully open is the wall again in a different font.

It reads a useful subset of JSON Schema — type, description, enum, default, required, properties, items — and ignores the rest rather than half-supporting it. $ref in particular is deliberately not resolved: following one means fetching or bundling a document this component cannot see, and silently rendering an unresolved ref as an empty object is worse than saying so.

Install

npx astralyx-ui add tool-schema

Usage

import { ToolSchema } from '@/components/ui/tool-schema'

<ToolSchema name="issue_refund" schema={tool.inputSchema} />

Composer

Change the props and the source below follows.

issue_refund

Refunds part or all of a payment.

customer_idstringrequired
The customer to refund. Must already exist.
amountobjectrequired
Integer minor units, never a float.
- valueintegerrequired
  Pennies. 19_99 is £19.99.
- currencystringrequired
  GBPUSDEUR
  default: "GBP"
reasonstringoptional
Recorded on the ledger entry.
duplicatefraudulentrequested_by_customer
notifybooleanoptional
Email the customer when the refund settles.
default: true

Props

defaultDepth

tsx

<ToolSchema
  name="issue_refund"
  schema={tool.inputSchema}
  defaultDepth={1}
/>

Examples

A nested schema

tsx

<ToolSchema name="issue_refund" schema={schema} />

No parameters

tsx

<ToolSchema name="list_open_tickets" schema={{ type: 'object' }} />

API

Generated from the source, so it cannot fall behind the code. One table per exported component, then hooks, functions and types.

`ToolSchema`

Extends Omit<ComponentProps<'div'>, 'title'>.

Prop	Type	Default	Description
schema	JsonSchema	required	Reads type, description, enum, default, required, properties and items. Other keywords are ignored rather than half-supported.
name	string	—	Heading above the parameters.
description	ReactNode	—	Heading above the parameters.
defaultDepth	number	1	Levels open on first render. A deep schema fully expanded is the same wall of JSON in a different font.
requiredLabel	string	'required'	Every string is a prop.
optionalLabel	string	'optional'	Every string is a prop.
expandLabel	string	'Expand'	Verbs for the nested-field toggles, used in its accessible name.
collapseLabel	string	'Collapse'	—
emptyLabel	string	'Takes no parameters.'	Every string is a prop.
unresolvedRefLabel	(ref: string) => string	(ref) => `unresolved reference: ${ref}`	Shown in place of a `$ref` this component will not resolve.

Functions

Function	Signature	Description
toolSchemaType	(schema: JsonSchema) => string	—

Types

`JsonSchema`

A tool's parameter schema, rendered as something a person can read.

Field	Type	Description
type?	string \| string[]	—
description?	string	—
enum?	unknown[]	—
default?	unknown	—
properties?	Record<string, JsonSchema>	—
items?	JsonSchema	—
required?	string[]	—
$ref?	string	Deliberately. Following one means fetching or bundling a document this component cannot see; rendering an unresolved ref as an empty object would be worse than saying so.