Skip to main content

Tool Results

All CTP tool functions return a standardized result object.

Result Structure

interface ToolResult<T = unknown> {
  // Required
  success: boolean;

  // On success
  data?: T;
  metadata?: ResultMetadata;

  // On failure
  error?: string;
  errorCode?: ErrorCode;
  suggestion?: string;
}

interface ResultMetadata {
  executionTime?: number;    // Milliseconds
  inputSize?: number;        // Bytes
  outputSize?: number;       // Bytes
  warnings?: string[];       // Non-fatal warnings
  [key: string]: unknown;    // Custom metadata
}

Success Response

return {
  success: true,
  data: {
    formatted: '{\n  "key": "value"\n}',
    lineCount: 3,
    valid: true,
  },
  metadata: {
    executionTime: 1.5,
    inputSize: 15,
    outputSize: 24,
  },
};

Error Response

return {
  success: false,
  error: 'Invalid JSON: Unexpected token at position 5',
  errorCode: 'INVALID_INPUT',
  suggestion: 'Check for missing quotes or commas',
};

Error Codes

CodeDescriptionHTTP Status
INVALID_INPUTInput failed validation400
MISSING_REQUIREDRequired parameter missing400
TYPE_ERRORParameter type mismatch400
CONSTRAINT_VIOLATIONValue outside allowed range400
EXECUTION_ERRORRuntime error during execution500
TIMEOUTExecution exceeded time limit504
RATE_LIMITEDToo many requests429
UNAUTHORIZEDAuthentication required401
NOT_FOUNDResource not found404
INTERNAL_ERRORUnexpected internal error500

Implementation Patterns

Basic Success/Error

export const myFn: ToolFunction = (params) => {
  const input = params.input as string;

  // Validate required parameter
  if (!input) {
    return {
      success: false,
      error: 'Input is required',
      errorCode: 'MISSING_REQUIRED',
    };
  }

  // Process and return
  return {
    success: true,
    data: { result: input.toUpperCase() },
  };
};

With Metadata

export const myFn: ToolFunction = (params) => {
  const startTime = performance.now();
  const input = params.input as string;

  const result = process(input);

  return {
    success: true,
    data: result,
    metadata: {
      executionTime: performance.now() - startTime,
      inputSize: input.length,
      outputSize: result.length,
    },
  };
};

With Warnings

export const hashFn: ToolFunction = (params) => {
  const algorithm = params.algorithm as string;

  const warnings: string[] = [];
  if (algorithm === 'SHA-1') {
    warnings.push('SHA-1 is deprecated for security purposes');
  }

  return {
    success: true,
    data: { hash: computeHash(params.input, algorithm) },
    metadata: {
      warnings: warnings.length > 0 ? warnings : undefined,
    },
  };
};

Try-Catch Pattern

export const myFn: ToolFunction = (params) => {
  try {
    const parsed = JSON.parse(params.json as string);
    return {
      success: true,
      data: { parsed, valid: true },
    };
  } catch (e) {
    return {
      success: false,
      error: `Parse error: ${(e as Error).message}`,
      errorCode: 'INVALID_INPUT',
      suggestion: 'Ensure the input is valid JSON',
    };
  }
};

Async with Timeout

export const myFn: ToolFunction = async (params, context) => {
  const controller = new AbortController();
  const timeout = context?.timeout ?? 30000;

  const timeoutId = setTimeout(() => controller.abort(), timeout);

  try {
    const result = await fetchWithAbort(params.url, controller.signal);
    clearTimeout(timeoutId);

    return { success: true, data: result };
  } catch (e) {
    clearTimeout(timeoutId);

    if ((e as Error).name === 'AbortError') {
      return {
        success: false,
        error: 'Request timed out',
        errorCode: 'TIMEOUT',
      };
    }

    return {
      success: false,
      error: (e as Error).message,
      errorCode: 'EXECUTION_ERROR',
    };
  }
};

Result Validation

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

const result = myFn(params);
const validation = validateToolResult(result);

if (!validation.valid) {
  console.error('Invalid result format:', validation.errors);
}

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "CTP Tool Result",
  "type": "object",
  "required": ["success"],
  "properties": {
    "success": { "type": "boolean" },
    "data": {},
    "error": { "type": "string" },
    "errorCode": {
      "type": "string",
      "enum": [
        "INVALID_INPUT", "MISSING_REQUIRED", "TYPE_ERROR",
        "CONSTRAINT_VIOLATION", "EXECUTION_ERROR", "TIMEOUT",
        "RATE_LIMITED", "UNAUTHORIZED", "NOT_FOUND", "INTERNAL_ERROR"
      ]
    },
    "suggestion": { "type": "string" },
    "metadata": {
      "type": "object",
      "properties": {
        "executionTime": { "type": "number" },
        "warnings": { "type": "array", "items": { "type": "string" } }
      }
    }
  }
}