​
Metadata Fields

Version 0.9.8 This document provides a technical overview of the Metadata schema for tool/function definitions. The Metadata is a top-level object that describes each tool’s configuration, parameters, outputs, and related fields. Below is a structured breakdown of the fields that can appear, along with their types and meanings. An example of a real Metadata can be viewed here

​
Table: Metadata

FieldTypeDescription
idstring (optional)Unique identifier for the tool.
namestring (required)Human-readable name for the tool.
versionstring (optional)Version of the tool.
descriptionstring (optional)Short description explaining the tool’s purpose.
authorstring (optional)Author or maintainer of the tool.
homepagestring (optional)URL to the tool’s homepage or documentation.
keywordsarray of stringsList of keywords or tags associated with the tool.
tool_typestring (optional)Indicates the type of tool (e.g. “typescript”, “python”).
licensestring (optional)License for the tool (e.g. “MIT”).
configurationsConfigurationsTableConfiguration settings for the tool (see Configurations Table below).
parametersParametersTableThe input parameters accepted by the tool (see Parameters Table below).
resultResultTableThe shape of the tool’s output (see Result Table below).
sqlTablesarray of objectsOptional list of SQL table definitions (see SQL Tables section).
sqlQueriesarray of objectsOptional list of SQL queries or statements (see SQL Queries section).
toolsarrayOptional references to internal or external helper tools.
oautharray of objectsOAuth configuration objects if the tool requires authentication (see OAuth Table section).
Note: Any of these fields not marked “required” is optional. A specific metadata entry may include all, some, or none of these fields.

​
Configurations Table

The configurations field typically has the structure shown below. It is always an object with a type: "object" and a properties key that defines each possible configuration setting:
FieldTypeDescription
typestring (always “object”)Must be "object" for the top-level configurations schema.
propertiesPropertiesTableA collection of fields describing each configuration setting. Each property can have its own type, description, default, or enum.
requiredarray of stringsOptional. A list of property names that are required.

​
PropertiesTable for Configurations

Each property under configurations.properties can include:
  • type: "string", "number", "boolean", "array", or "object".
  • description: Explains the purpose of that configuration property.
  • default: Default value for the property (if any).
  • enum: A list of permitted values (if restricted).
  • nullable: If true, indicates that the value can be null (optional).
  • required: If present in the top-level configurations.required, that property must be provided.

​
Parameters Table

The parameters field describes the inputs a tool expects. It also always has the top-level shape:
FieldTypeDescription
typestring (always “object”)Must be "object" for the parameters schema.
propertiesPropertiesTableEach input parameter, with its own type, description, and optional attributes like default.
requiredarray of stringsOptional. Names of any parameters that must be supplied.

​
PropertiesTable for Parameters

Each property under parameters.properties can include:
  • type: "string", "number", "boolean", "array", or "object".
  • description: Explains that parameter’s purpose or usage.
  • default: Default value if not specified by the user.
  • enum: Possible fixed choices (e.g., ["high","low","urgent"]).
  • items: For an array type, describes the type or structure of each element (which can itself be string, number, object, etc.).
  • nullable: Indicates if the value can be null.

​
Result Table

The result field defines how the tool’s output is structured:
FieldTypeDescription
typestring (always “object”)Must be "object" for the result schema.
propertiesPropertiesTableDescribes the output fields the tool produces. Each field has its own type and other annotations.
requiredarray of stringsOptional. Lists the fields that will always appear in the result.

​
PropertiesTable for Result

As with configurations and parameters, each property can specify:
  • type: "string", "number", "boolean", "array", or "object".
  • description: Explains what that output field represents.
  • items: If the field is an array, describes each element.
  • nullable: If present, indicates the field can be null.

​
PropertiesTable

Below is a table describing the possible fields in PropertiesTable—used for configurations, parameters, or result. Each entry in a PropertiesTable can define one property with the following structure:
FieldType / Possible ValuesDescription
typestringIndicates the data type of the property. Common values are "string", "number", "boolean", "array", or "object".
descriptionstringExplains the purpose of this property or what it represents. Mandatory for Parameters and Configuration.
defaultany (optional)Default value. Only for reference it is NOT APPLIED, or passed to the LLM.
enumarray of strings (optional)Restricts the property to a specific set of string values (e.g., ["urgent", "high", "low"]). Only for reference, not enforced for LLM or verified. Only the description is passed to the LLM models.
itemsobject (only for arrays)For type: "array", describes the expected type of each element. This can itself be a nested structure (e.g., { "type": "object", "properties": ... }).
propertiesobject (only for objects)For type: "object", defines the keys and associated types within the nested object (a deeper PropertiesTable).
requiredarray of strings (optional)If present, lists which fields are mandatory in a nested object. This is usually specified at a higher level, but sometimes included in property definitions.
nullableboolean (optional)If true, indicates the property can be null. Only for reference, not enforced, passed to LLMs, or used in execution.

​
SQL Tables

The sqlTables array (if present) describes database tables used by the tool. Each entry is typically:
FieldTypeDescription
namestringThe table’s name.
definitionstringThe SQL statement to create or define the table.

​
SQL Queries

The sqlQueries array (if present) contains query definitions. Each entry often has:
FieldTypeDescription
namestringA short name or identifier for the query.
querystringThe SQL query or statement itself.

​
OAuth Table

If the tool requires OAuth authentication, oauth is an array of objects. Each object can include:
FieldTypeDescription
namestringCustom name of the OAuth service (e.g., “Github”, “Gmail”, etc.).
version”2.0”OAuth version.
authorizationUrlstringThe URL the user is redirected to for authorization.
redirectUrlstringThe callback/redirect URL after user grants authorization.
tokenUrlstringThe URL where the tool exchanges the code for an access token.
clientIdstringOAuth client ID.
clientSecretstringOAuth client Secret.
scopesstring[]List of permission scopes requested.
responseType”code”Type of an authorization code.
refreshToken”true” (optional)If the refresh token is requested, if the service returns or uses one.
pkceType”plain” or “S256” (optional)Defines PKCE usage (if set).
requestTokenContentType”application/x-www-form-urlencoded” (optional)By default query params are used to pass data to the authorizationUrl, this option changes the mechanism.
requestTokenAuthHeader”basic” (optional)Advanced field: The scheme for token exchange (“basic”) to send Authorization: Basic base64({client-id}:{client-secret}) in the headers.
The metadata JSON is structured to comprehensively describe a tool’s identity, configuration, and integration requirements. It includes basic information (like the name, description, and author), technical details (such as configurations, parameters, and results defined via JSON schemas), SQL interactions (through table definitions and queries), and external integrations (via OAuth settings). Understanding each field’s purpose is crucial for accurately generating documentation and ensuring that Shinkai’s tool platform can correctly interpret and utilize the tool’s function.