Skip to main content

​
Tool Definition Schema

A Tool Definition is a JSON-serializable object that describes a tool’s metadata, parameters, and behavior.

​
Required Fields

FieldTypeDescription
idstringUnique identifier (lowercase, hyphen-separated)
namestringHuman-readable display name (max 50 chars)
descriptionstringDetailed description (max 500 chars)
categorystringPrimary category for organization
tagsstring[]Searchable tags (min 1, unique)
method"GET" | "POST"HTTP method when exposed as API
parametersParameter[]Array of parameter definitions
outputDescriptionstringDescription of tool output
exampleobjectExample input/output

​
Optional Fields

FieldTypeDefaultDescription
versionstring-Semantic version (e.g., “1.0.0”)
iconstring-Icon identifier or emoji
keywordsstring[]-Additional search keywords
relatedToolsstring[]-IDs of related tools
aiInstructionsstring-Special instructions for AI models
rateLimitobject-Rate limiting configuration
executionModestring"client"Where tool executes
requiresAuthbooleanfalseAuthentication required
deprecatedbooleanfalseDeprecation status
deprecationMessagestring-Deprecation explanation

​
Categories

Tools MUST belong to one of the following categories:
CategoryDescriptionExamples
formattersFormat and beautify dataJSON formatter, SQL formatter
encodersEncode and decode dataBase64, URL encoding
generatorsGenerate data or contentUUID, password, hash
convertersConvert between formatsUnit converter, color formats
validatorsValidate data formatsJSON validator, email checker
analyzersAnalyze and inspect dataJSON diff, regex tester
editorsEdit and transform dataText replacer, case converter
utilitiesGeneral utilitiesTimestamp converter

​
Execution Modes

ModeDescription
clientExecutes entirely in browser (default)
serverRequires server-side execution
hybridCan execute in either environment

​
Complete Example

import type { ToolDefinition } from '@conveniencepro/ctp-core';

export const jsonFormatterDefinition: ToolDefinition = {
  // Required fields
  id: 'json-formatter',
  name: 'JSON Formatter',
  description: 'Format, validate, and beautify JSON data with customizable indentation.',
  category: 'formatters',
  tags: ['json', 'format', 'beautify', 'validate', 'minify'],
  method: 'POST',
  parameters: [
    {
      name: 'json',
      type: 'textarea',
      label: 'JSON Input',
      description: 'The JSON string to format',
      required: true,
      placeholder: '{"name": "example"}',
      validation: { minLength: 1, maxLength: 1000000 },
    },
    {
      name: 'indent',
      type: 'select',
      label: 'Indentation',
      description: 'Number of spaces for indentation',
      required: false,
      defaultValue: '2',
      options: [
        { value: '0', label: 'Minified' },
        { value: '2', label: '2 spaces' },
        { value: '4', label: '4 spaces' },
        { value: 'tab', label: 'Tab' },
      ],
    },
    {
      name: 'sortKeys',
      type: 'boolean',
      label: 'Sort Keys',
      description: 'Sort object keys alphabetically',
      required: false,
      defaultValue: false,
    },
  ],
  outputDescription: 'Formatted JSON string',
  example: {
    input: { json: '{"b":2,"a":1}', indent: '2', sortKeys: true },
    output: {
      formatted: '{\n  "a": 1,\n  "b": 2\n}',
      valid: true,
      lineCount: 4,
    },
  },

  // Optional fields
  version: '1.0.0',
  icon: '📋',
  keywords: ['pretty print', 'beautifier'],
  relatedTools: ['json-validator', 'json-minifier'],
  aiInstructions: 'Use 2-space indentation by default. Enable sortKeys for consistent output.',
  executionMode: 'client',
};

​
JSON Schema

The complete JSON Schema for tool definitions is available at: 
https://conveniencepro.cc/schemas/tool-definition.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://conveniencepro.cc/schemas/tool-definition.schema.json",
  "title": "CTP Tool Definition",
  "type": "object",
  "required": [
    "id", "name", "description", "category", "tags",
    "method", "parameters", "outputDescription", "example"
  ],
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
      "minLength": 1,
      "maxLength": 100
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 50
    },
    "description": {
      "type": "string",
      "minLength": 1,
      "maxLength": 500
    },
    "category": {
      "type": "string",
      "enum": [
        "formatters", "encoders", "generators", "converters",
        "validators", "analyzers", "editors", "utilities"
      ]
    },
    "executionMode": {
      "type": "string",
      "enum": ["client", "server", "hybrid"],
      "default": "client"
    }
  }
}

​
Validation

import { validateToolDefinition } from '@conveniencepro/ctp-core';

const result = validateToolDefinition(myDefinition);

if (!result.valid) {
  result.errors.forEach(error => {
    console.error(`${error.path}: ${error.message}`);
  });
}