Tools API Reference

This page documents the checked-in tool registry used by Luna and the workflow-facing run_tool contract used by the Health AI Platform.

1. Luna’s real tool registry

The concrete registry in this repository lives in apps/luna/src/lib/tools/index.ts.


export const lunaTools = {
  'product-search': productSearchTool,
  'create-cart': createCartTool,
  'lookup-orders': lookupOrdersTool,
  'lookup-peptide': lookupPeptideTool,
  'search-peptides': searchPeptidesTool,
  'list-goals': listGoalsTool,
  'list-stacks': listStacksTool,
  'lookup-stack': lookupStackTool,
  'safety-info': safetyInfoTool,
  'update-customer-profile': updateCustomerProfileTool,
  'save-note': saveNoteTool,
  'suggest-resource': suggestResourceTool,
  'suggest-action': suggestActionTool,
  'create-support-ticket': createSupportTicketTool,
  'get-community-insights': getCommunityInsightsTool,
  'find-similar-users': findSimilarUsersTool,
};

2. Workflow `run_tool` contract

The workflow engine accepts tool calls through action params.


- id: invoke-risk-tool
  type: run_tool
  action:
    type: tool
    params:
      toolId: risk-calculator
      labPanel: advanced-metabolic

Today the executor validates toolId against context.tools and then returns a stub result.

Tool categories

The registry groups tools into five categories:

Category	Tool names
Product & Commerce	`product-search`, `create-cart`, `lookup-orders`
Peptide Knowledge	`lookup-peptide`, `search-peptides`, `list-goals`, `list-stacks`, `lookup-stack`, `safety-info`
Customer Management	`update-customer-profile`, `save-note`
UI/UX	`suggest-resource`, `suggest-action`
Support & Community	`create-support-ticket`, `get-community-insights`, `find-similar-users`


import { toolCategories } from '@/lib/tools';
 
console.log(toolCategories['Peptide Knowledge']);

Tool definition shape

Luna tools are built with the AI SDK tool() helper and normally provide:

a description
a Zod parameter schema
an async execute function

Example from product-search:


import { tool } from 'ai';
import { z } from 'zod';
 
export const productSearchTool = tool({
  description: 'Search the product catalog by name, category, or use-case.',
  parameters: z.object({
    category: z.enum(['supplements', 'treats', 'wellness', 'grooming', 'all']).optional(),
    productName: z.string().optional(),
    petType: z.enum(['dog', 'cat', 'horse', 'all']).optional(),
    healthGoal: z.string().optional(),
  }),
  execute: async ({ category, productName, petType, healthGoal }) => {
    // ...
  },
});

`run_tool` request contract

Workflow definition


- id: call-tool
  type: run_tool
  action:
    type: tool
    params:
      toolId: lookup-peptide
      query: BPC-157

Execution context


const result = await workflow.execute({
  patientId: 'patient-1',
  tools: ['lookup-peptide'],
});

Current output


{
  "executed": true,
  "toolId": "lookup-peptide",
  "params": {
    "toolId": "lookup-peptide",
    "query": "BPC-157"
  }
}

If the tool is not allowlisted:


{
  "stepId": "call-tool",
  "success": false,
  "error": "Tool \"lookup-peptide\" is not available in this workflow context"
}

Representative tool examples

`product-search`

Search the catalog by category, product name, or health goal.


const result = await productSearchTool.execute({
  productName: 'BPC-157',
  category: 'supplements',
});

`save-note`

Attach structured notes to customer-facing workflows.


const toolId = 'save-note';
 
const workflow = WorkflowEngine.load({
  id: 'note-capture-v1',
  name: 'Note Capture',
  version: '1.0.0',
  steps: [
    {
      id: 'save-follow-up',
      type: 'run_tool',
      action: {
        type: 'tool',
        params: { toolId, note: 'Follow up in 7 days' },
      },
    },
  ],
});

`create-support-ticket`

Escalate from an agent flow into support operations.


console.log(toolCategories['Support & Community']);
// ['create-support-ticket', 'get-community-insights', 'find-similar-users']

Design guidance

Use tool IDs as stable contracts

Tool IDs should be treated as external contracts between:

agent prompts
workflow definitions
runtime allowlists
future shared registry implementations

Keep parameters explicit

Prefer:


params:
  toolId: lookup-peptide
  query: BPC-157

over opaque blobs that hide the tool’s real inputs.

Separate workflow orchestration from tool implementation

The workflow should decide when a tool can run. The tool implementation should decide how it performs the work.

Known limitation

The workflow engine mentions a future @loop/tool-registry, but that shared package does not exist in this repository snapshot.

That means:

Luna’s tool registry is real
workflow run_tool is real as a contract
shared execution across apps is still future work