Building Your First Agent Tool in 5 Minutes

JarvisSDK is built for two types of users: agents that consume tools, and developers who build them. If you're in the second category—you have a utility, an API wrapper, or a workflow that you want AI agents to be able to use—this tutorial is for you.

We're going to go from zero to a working, executable module in five minutes. No fluff. Just the steps.

What You're Building

A custom module called url-shortener with one action: shorten. It takes a URL as input and returns a shortened version. Simple enough to follow, real enough to be useful.

By the end of this tutorial, you'll have:

• A module registered in your JarvisSDK catalog
• A working API endpoint that agents (or you) can call to execute it
• An understanding of the module schema, trust scoring, and self-equip flow

Prerequisites

• A JarvisSDK account (jarvissdk.com — free tier available)
• An API key from your dashboard
• Node.js 18+ (or just a terminal with curl)

That's it. You don't need to clone a repo or configure anything locally for the basic flow.

Step 1: Get Your API Key

Sign in at jarvissdk.com, navigate to Settings → API Keys, and create a new key. Copy it—you'll use it in every request.

export JARVIS_API_KEY="jsk_your_key_here"

Step 2: Install the Client (Optional)

If you prefer TypeScript over raw curl:

npm install @jarvis-sdk/client

The client wraps the REST API with full TypeScript types. You can do everything in this tutorial with either approach—we'll show both.

Step 3: Browse What's Already There

Before building something new, check if it already exists:

curl https://jarvissdk.com/api/v1/modules \
  -H "X-API-Key: $JARVIS_API_KEY" | jq '.modules[].name'

Or with the client:

import { JarvisClient } from '@jarvis-sdk/client';

const client = new JarvisClient({ apiKey: process.env.JARVIS_API_KEY });
const { modules } = await client.modules.list({ category: 'utilities' });
console.log(modules.map(m => m.name));

There are 695 modules in the catalog today. If what you need exists, skip to Step 6 and just execute it. If not, keep going.

Step 4: Register Your Module

A JarvisSDK module is defined by a JSON schema: what it's called, what it does, what actions it exposes, and what inputs/outputs those actions expect.

curl -X POST https://jarvissdk.com/api/v1/modules \
  -H "X-API-Key: $JARVIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "url-shortener",
    "displayName": "URL Shortener",
    "description": "Shortens URLs for use in agent-generated content",
    "category": "utilities",
    "version": "1.0.0",
    "actions": [
      {
        "name": "shorten",
        "description": "Shorten a URL",
        "inputSchema": {
          "type": "object",
          "properties": {
            "url": {
              "type": "string",
              "description": "The URL to shorten",
              "format": "uri"
            }
          },
          "required": ["url"]
        },
        "outputSchema": {
          "type": "object",
          "properties": {
            "shortUrl": { "type": "string" },
            "originalUrl": { "type": "string" }
          }
        }
      }
    ],
    "runtimeType": "http",
    "endpoint": "https://your-service.com/api/shorten"
  }'

The runtimeType field tells JarvisSDK how to execute this module. There are four options:

• builtin: in-process TypeScript, compiled directly into the JarvisSDK runtime (for first-party modules)
• composio: delegates to the Composio API (for OAuth-based SaaS integrations)
• http: calls your external endpoint at execution time (what we're using here)
• mock: returns static test data (for development and testing)

For a custom module pointing to your own service, http is the right choice. JarvisSDK acts as the discovery and billing layer; your service handles the actual logic.

Step 5: Execute the Module

Once registered, your module is immediately executable:

curl -X POST https://jarvissdk.com/api/v1/modules/url-shortener/execute \
  -H "X-API-Key: $JARVIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "shorten", "input": {"url": "https://example.com/very/long/url"}}'

Response:

{
  "success": true,
  "result": {
    "shortUrl": "https://sho.rt/abc123",
    "originalUrl": "https://example.com/very/long/url"
  },
  "executionId": "exec_01HZ...",
  "durationMs": 142,
  "billedUnits": 1
}

With the TypeScript client:

const result = await client.modules.execute('url-shortener', {
  action: 'shorten',
  input: { url: 'https://example.com/very/long/url' }
});

console.log(result.result.shortUrl); // https://sho.rt/abc123

Every execution is logged with a unique executionId, duration, and billing units. You can query execution history from your dashboard or via the API.

Step 6: The Self-Equip Flow (How Agents Arm Themselves)

Here's where it gets interesting for agent use cases. Instead of an agent knowing in advance which tools it needs, JarvisSDK supports a self-equip pattern: the agent calls a single endpoint and receives back everything it needs to use a set of modules.

// An agent arming itself before starting a task
const { modules } = await client.agent.arm({
  modules: ['url-shortener', 'text-toolkit', 'email-toolkit'],
  format: 'openai-functions' // or 'mcp', 'anthropic-tools', 'raw'
});

// modules now contains tool definitions ready to inject into your LLM context

The format parameter tells JarvisSDK how to serialize the tool definitions. Pass openai-functions and you get back an array ready to drop into openai.chat.completions.create({ tools: modules }). Pass anthropic-tools and you get back the format Claude expects. Pass mcp and you get a list of MCP tool definitions.

This is the agent-native pattern: the agent decides what it needs, fetches the tool definitions at runtime, and passes them to the LLM. No configuration files. No hardcoded tool lists.

Step 7: Check Trust Score and Certification

Once your module is registered, you can view its trust status:

curl https://jarvissdk.com/api/v1/modules/url-shortener \
  -H "X-API-Key: $JARVIS_API_KEY" | jq '.trustScore, .certificationStatus'

A freshly registered http module starts at bronze tier. To move up, run the certification pipeline:

curl -X POST https://jarvissdk.com/api/v1/modules/url-shortener/certify \
  -H "X-API-Key: $JARVIS_API_KEY"

The pipeline runs 15 automated checks:

• Schema validation (input/output schemas are valid JSON Schema)
• Action completeness (every action has a description)
• Security scan (no obvious injection vectors in schema)
• Endpoint health (your HTTP endpoint responds)
• Response shape (output matches declared schema)
• And 10 more...

Pass all checks and your module moves to silver. Add usage history, good health metrics, and documentation and you can reach gold or platinum. Higher trust scores unlock higher rate limits and make your module more visible in discovery.

Putting It Together

Here's a complete example of an agent workflow that discovers, arms, and uses tools:

import { JarvisClient } from '@jarvis-sdk/client';

const client = new JarvisClient({ apiKey: process.env.JARVIS_API_KEY });

async function agentWorkflow(taskDescription: string) {
  // 1. Let the agent LLM figure out what tools it needs
  const { suggestedModules } = await client.agent.suggest({
    task: taskDescription
  });

  // 2. Arm with those modules
  const { modules } = await client.agent.arm({
    modules: suggestedModules,
    format: 'anthropic-tools'
  });

  // 3. Pass tool definitions to Claude (or any LLM)
  const response = await anthropic.messages.create({
    model: 'claude-opus-4-6',
    tools: modules,
    messages: [{ role: 'user', content: taskDescription }]
  });

  // 4. Execute any tool calls the LLM returned
  for (const toolUse of response.content.filter(c => c.type === 'tool_use')) {
    const result = await client.modules.execute(toolUse.name, {
      action: toolUse.input.action,
      input: toolUse.input.params
    });
    console.log(`Executed ${toolUse.name}:`, result.result);
  }
}

await agentWorkflow('Shorten this URL and post it to Slack: https://example.com/long-path');

Five lines of setup. The rest is just the agent doing its job.

What's Next

You've built and executed a module. Here's what to explore next:

• Module catalog — 695 modules across 14 categories. Probably has what you need.
• Composio integrations — GitHub, Slack, Gmail, Notion, Stripe, and 600+ more, all via OAuth.
• Orchestration modules — multi-step workflows like customer-onboarding, deploy-and-announce, incident-response.
• MCP bridge — connect the entire JarvisSDK catalog to Claude as a single MCP server.
• Module certification guide — path from bronze to platinum.

The catalog grows every day. If you build something useful, publishing it means every other agent developer (and every agent) can benefit from it immediately.

That's the npm model. That's what we're building.

Get your API key at jarvissdk.com.