TPMJS Specification

The open standard for AI tool discovery and integration

What is TPMJS?

TPMJS (Tool Package Manager for JavaScript) is an open standard and registry for AI tool discovery and integration. It solves the problem of fragmented AI tool ecosystems by providing:

Automatic Discovery - Tools are automatically indexed from NPM based on keywords
Standardized Metadata - A unified specification for describing tool capabilities
Quality Scoring - Algorithmic ranking based on documentation completeness and community adoption
AI Agent Integration - Structured metadata optimized for LLM tool selection

How it Works

📦

1. Publish to NPM

Add the tpmjs-tool keyword and a tpmjs metadata field to your package.json

🔍

2. Automatic Discovery

TPMJS monitors NPM every 2 minutes for new tools and updates the registry automatically

⚡

3. Instant Availability

Your tool appears on tpmjs.com within 15 minutes, searchable by AI agents and developers

The Specification

The TPMJS specification defines a tpmjs field in package.json with three tiers of metadata. Higher tiers receive better visibility and quality scores.

Tier 1: Minimal

Required fields only

`category` *

Tool category for organization. Must be one of the following:

web-scraping

data-processing

file-operations

communication

database

api-integration

image-processing

text-analysis

automation

ai-ml

security

monitoring

`description` *

Clear description of what the tool does. Must be 20-500 characters. This appears in search results and tool listings.

Example:

{
  "tpmjs": {
    "category": "text-analysis",
    "description": "Analyzes sentiment in text and returns positive/negative/neutral classification"
  }
}

Tier 2: Basic

+ Parameter and return type documentation

`parameters`

Array of parameter objects describing function inputs. Each parameter has:

name - Parameter name
type - TypeScript type
description - What it does
required - Boolean
default - Default value (optional)

`returns`

Object describing the return value:

type - Return type
description - What is returned

Example:

{
  "tpmjs": {
    "category": "text-analysis",
    "description": "Analyzes sentiment in text",
    "parameters": [
      {
        "name": "text",
        "type": "string",
        "description": "The text to analyze",
        "required": true
      },
      {
        "name": "language",
        "type": "string",
        "description": "Language code (e.g., 'en', 'es')",
        "required": false,
        "default": "en"
      }
    ],
    "returns": {
      "type": "SentimentResult",
      "description": "Object with score (-1 to 1) and label (positive/negative/neutral)"
    }
  }
}

Tier 3: Rich

+ Complete metadata for maximum visibility

`env`

Array of environment variables required by the tool. Each variable has:

name - Environment variable name (e.g., "OPENAI_API_KEY")
description - What the variable is used for
required - Boolean (defaults to true)
default - Default value if not provided (optional)

`frameworks`

Array of compatible AI frameworks. Supported values:

vercel-ai

langchain

llamaindex

haystack

semantic-kernel

`aiAgent`

AI agent integration guidance. Helps LLMs understand when and how to use your tool:

useCase - When to use this tool (min 10 chars, required)
limitations - Known constraints (optional)
examples - Array of example use cases (optional)

Complete Example:

{
  "tpmjs": {
    "category": "text-analysis",
    "description": "Advanced sentiment analysis with emotion detection",
    "parameters": [...],
    "returns": {...},
    "env": [
      {
        "name": "SENTIMENT_API_KEY",
        "description": "API key for sentiment analysis service",
        "required": true
      }
    ],
    "frameworks": ["vercel-ai", "langchain"],
    "aiAgent": {
      "useCase": "Use when users need to analyze sentiment or detect emotions in text",
      "limitations": "English and Spanish only. Max 10,000 characters per request.",
      "examples": [
        "Analyze customer review sentiment",
        "Detect emotions in user feedback"
      ]
    }
  }
}

Field Reference

Field	Type	Tier	Required	Description
`category`	string	Minimal	Yes	Tool category from predefined list
`description`	string	Minimal	Yes	Tool description (20-500 chars)
`parameters`	array	Basic	No	Function parameter definitions
`returns`	object	Basic	No	Return type definition
`env`	array	Rich	No	Required environment variables
`frameworks`	array	Rich	No	Compatible AI frameworks
`aiAgent`	object	Rich	No	AI agent integration guidance

Quality Score

Tools are ranked by quality score, calculated from three factors:

Tier Multiplier

Rich: 4x multiplier
Basic: 2x multiplier
Minimal: 1x multiplier

NPM Downloads

Logarithmic scale based on monthly downloads. More downloads = higher score.

GitHub Stars

Logarithmic scale based on repository stars. Community validation boosts visibility.

Formula:

function calculateQualityScore(params: {
  tier: 'minimal' | 'basic' | 'rich';
  downloads: number;
  githubStars: number;
}): number {
  const tierScore = tier === 'rich' ? 0.6 : tier === 'basic' ? 0.4 : 0.2;
  const downloadsScore = Math.min(0.3, Math.log10(downloads + 1) / 10);
  const starsScore = Math.min(0.1, Math.log10(githubStars + 1) / 10);

  return Math.min(1.0, tierScore + downloadsScore + starsScore);
}

Discovery & Sync

TPMJS automatically discovers and updates tools using three strategies:

Changes Feed

Monitors NPM's real-time changes feed every 2 minutes

Real-time

Keyword Search

Searches for tpmjs-tool keyword every 15 minutes

Every 15 min

Metrics Update

Updates download stats and quality scores hourly

Hourly

Validation

The TPMJS specification is validated using Zod schemas. The validation logic is available in the @tpmjs/types package.

Common Validation Errors:

Invalid category: Category must be one of the 12 predefined values
Description too short/long: Description must be 20-500 characters
Invalid env: Each environment variable must have a name and description

Publishing Your Tool

Publishing a tool to TPMJS is simple:

1️⃣

Add tpmjs-tool keyword

2️⃣

Add tpmjs field

3️⃣

Publish to NPM

✅

Appears on tpmjs.com in 15 min

Support & Resources

Documentation

→ Publishing Guide → GitHub Repository → TypeScript Types Package

Examples

→ Browse All Tools → Try the Playground → Report Issues or Ask Questions

TPMJS Specification

What is TPMJS?

How it Works

1. Publish to NPM

2. Automatic Discovery

3. Instant Availability

The Specification

category *

description *

Example:

parameters

returns

Example:

env

frameworks

aiAgent

Complete Example:

Field Reference

Quality Score

Tier Multiplier

NPM Downloads

GitHub Stars

Formula:

Discovery & Sync

Changes Feed

Keyword Search

Metrics Update

Validation

Common Validation Errors:

Publishing Your Tool

Support & Resources

Documentation

Examples

`category` *

`description` *

`parameters`

`returns`

`env`

`frameworks`

`aiAgent`