DEV Community: Marco Arras

How I Got 1,600 Weekly npm Downloads with MCP Tools

Marco Arras — Thu, 09 Apr 2026 13:44:49 +0000

In January 2025, I published a package called Agent Toolbelt to npm. It's an MCP server — a collection of developer utility tools that Claude can use. UUID generation, base64 encoding, JSON formatting, timestamp conversion. Nothing groundbreaking. The kind of tools every developer reaches for daily.

Within weeks, it was getting over 1,600 weekly downloads.

npx agent-toolbelt

One command. Claude sees the tools. Developers use them. That's the entire distribution story.

I'm not telling you this to brag about download numbers — 1,600 is modest by npm standards. I'm telling you because it illustrates something about where we are in the MCP ecosystem: the bar for impact is low, and the surface area for opportunity is massive.

The ecosystem right now

Search npm for MCP servers. You'll find a few hundred packages. Now think about every category of software tool that exists: DevOps, databases, APIs, file management, cloud infrastructure, communication, analytics, CRM, project management, design, security, monitoring.

Most of these verticals have zero or one MCP tool package. Many have none.

Compare that to npm overall — over 2 million packages — and you see the gap. The MCP tool ecosystem is where the broader npm ecosystem was in 2012. Early. Wide open. Growing fast.

Where the gaps are

Verticals where MCP tools are either nonexistent or severely underbuilt:

Developer tools

Git operations beyond basic commits
Docker and container management
CI/CD pipeline interaction
Cloud provider CLIs (AWS, GCP, Azure)
Database query and migration tools

Business operations

CRM integration (Salesforce, HubSpot)
Project management (Jira, Linear, Asana)
Communication (Slack, Discord, email)
Document generation (contracts, reports, invoices)

Data and analytics

Database querying and visualization
Spreadsheet operations
Data pipeline management
Business intelligence dashboards

Domain-specific

Healthcare data (FHIR, HL7)
Legal document analysis
Financial compliance checking
Real estate listing management
E-commerce inventory and pricing

Each of these is a potential MCP server. Each could be a published npm package. Some of them could be products.

Three levels of opportunity

Not every MCP tool needs to be a business. There's a spectrum:

Level 1: Open source package

Publish a free tool to npm. Build reputation. Get downloads.

Example: Agent Toolbelt. Free, open source, 1,600+ weekly downloads. It established credibility, led to a course, and serves as a working reference implementation.

Time investment: A weekend to build, an hour to publish, minimal maintenance.

Returns: Reputation, GitHub stars, npm downloads, proof of expertise. Career assets that compound.

Level 2: Hosted MCP server

Take your tools and host them as a remote service. Users connect over HTTP instead of running locally. Add authentication, usage tracking, and premium features.

Example: A hosted stock analysis server. Free tier gives 10 queries/day. Paid tier ($19/month) gives unlimited access plus premium data sources.

Time investment: A few evenings to add HTTP transport, auth, and deploy.

Returns: Recurring revenue. 50 subscribers at $19/month is nearly $1,000/month.

Level 3: Full product

A complete application powered by your MCP tools. Web UI, user accounts, billing. Your tools become the backend engine.

Example: A financial analysis platform. Users interact through chat. Behind the scenes, Claude calls your MCP tools to fetch data, run calculations, generate reports.

Time investment: Weeks to months.

Returns: A real product business.

Start at Level 1. Validate the idea. Move up the stack if demand is there.

The revenue math

Let's get concrete about what a side-project MCP tool business looks like.

Scenario: Hosted MCP server for a niche vertical

Build time: 2-3 weekends
Hosting cost: ~$5/month
Pricing: $19/month per user
Marketing: 1 Dev.to post + npm package as funnel

Subscribers	Monthly	Annual
10	$190	$2,280
25	$475	$5,700
50	$950	$11,400
100	$1,900	$22,800

These are small numbers compared to a VC-funded startup. They're meaningful numbers for a side project built in a few weekends.

And the distribution advantage is real: your free npm package funnels users to your hosted offering. Every npx your-tool is a potential conversion.

Why now

Three things converging:

1. The protocol is stable enough. MCP has been through enough iterations that tools you build today won't break tomorrow. Anthropic is actively developing it. Other companies are adopting it.

2. The clients are ready. Claude Desktop supports MCP natively. VS Code extensions are adding support. More clients are coming. Your tools work everywhere.

3. The ecosystem is early. In a mature ecosystem, you're competing with established players. Right now, you're planting a flag in unclaimed territory. First-mover advantage is real when total MCP packages are in the hundreds, not millions.

If you wait a year, the landscape will look different. The verticals will have incumbents. The easy wins will be taken. The window for outsized impact relative to effort is right now.

What I'd build if I were starting today

If I were picking a vertical to build MCP tools for right now, here's how I'd think about it:

Pick a domain you know. Your industry knowledge is the moat, not the code.
Find the API. Almost every vertical has REST APIs you can wrap. That's all an MCP tool is — a function that calls an API and returns structured data.
Start with 3-5 tools. Not 50. A small, focused toolkit that does one job well.
Publish to npm. Get the feedback loop going. See if people use it.
Write about it. One Dev.to post about what you built gets more distribution than any other marketing effort at this stage.

The developer who builds the definitive MCP toolkit for [your vertical] is going to be in a very good position. That developer could be you.

This is Part 3 of a free 3-part series on MCP.

If you want to go from "I understand the opportunity" to "I shipped a real MCP package," that's exactly what the full course covers:

Module 1: Build your first MCP server and connect it to Claude
Module 2: Build real tools that call APIs and chain together
Module 3: Production patterns — error handling, caching, testing
Module 4: Package and publish to npm with CI/CD
Module 5: Turn your tools into a hosted product
Module 6: Advanced patterns — resources, prompts, multi-server

7 modules. 33 lessons. Ship a real npm package by the end.

Build & Ship MCP Tools — Get early access for $29

What is MCP? A Developer's Guide with Working Code

Marco Arras — Wed, 08 Apr 2026 13:58:30 +0000

MCP stands for Model Context Protocol. It's an open standard that defines how AI models connect to external tools and data sources.

Before MCP, every AI platform had its own way of doing tool integration. OpenAI had function calling. LangChain had its own tool format. Every agent framework invented its own interface. Build a tool for one system, it didn't work anywhere else.

MCP fixes this. One protocol. Any client. Any tool server. Build once, work everywhere.

The architecture in 30 seconds

┌─────────┐     MCP Protocol     ┌─────────────┐     Your Code     ┌──────────┐
│  Client  │ ◄──────────────────► │  MCP Server  │ ◄────────────────► │  APIs /   │
│ (Claude) │                      │  (your code) │                    │  Data     │
└─────────┘                       └─────────────┘                    └──────────┘

Client — The AI application. Claude Desktop, an IDE with AI, or any app that speaks MCP.

Server — Your code. A program that exposes tools, resources, and prompts to the client.

Transport — How they talk. stdio (local, stdin/stdout) or HTTP/SSE (remote, over the network).

The client discovers what your server offers, then calls your tools when the model decides it needs them.

What a tool looks like

A tool is a function with a name, a description, an input schema, and a handler:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

const server = new McpServer({
  name: "my-tools",
  version: "1.0.0",
});

server.tool(
  "generate_uuid",
  "Generate a random UUID",
  {},
  async () => ({
    content: [{ type: "text", text: crypto.randomUUID() }],
  })
);

15 lines. When Claude connects to this server, it sees a tool called generate_uuid. When a user asks for a unique ID, Claude calls this tool and returns the result.

The description matters more than you'd think. It's how the model decides when to use your tool. Write it for Claude, not for humans. Be specific about what the tool does and when it's useful.

Input schemas with Zod

Most tools need input. MCP uses JSON Schema to define inputs, and the SDK uses Zod to generate it from TypeScript:

server.tool(
  "get_stock_quote",
  "Get the latest stock price for a given ticker symbol",
  {
    ticker: z.string().describe("Stock ticker symbol, e.g. AAPL"),
  },
  async ({ ticker }) => {
    const res = await fetch(
      `https://api.polygon.io/v2/aggs/ticker/${ticker}/prev?apiKey=${process.env.POLYGON_API_KEY}`
    );
    const data = await res.json();
    const result = data.results[0];

    return {
      content: [{
        type: "text",
        text: [
          `${ticker} — Previous Close`,
          `Open: $${result.o}`,
          `High: $${result.h}`,
          `Low: $${result.l}`,
          `Close: $${result.c}`,
          `Volume: ${result.v.toLocaleString()}`,
        ].join("\n"),
      }],
    };
  }
);

Claude sees: "This server has a tool called get_stock_quote that takes a ticker string and returns stock price data."

User says: "What's Apple's stock price?"

Claude calls get_stock_quote with ticker: "AAPL".

The Zod schema does double duty: validates input at runtime (Claude can't send garbage) and generates JSON Schema so the model knows what format to use.

The connection flow

Here's what happens when Claude Desktop connects to your MCP server:

Launch — Claude starts your server as a subprocess
Initialize — Your server sends capabilities: name, version, available tools
Discovery — Claude reads the tool list and descriptions
Conversation — User talks to Claude. Claude decides when to call your tools.
Tool call — Claude sends: { tool: "get_stock_quote", input: { ticker: "AAPL" } }
Response — Your handler runs, returns content. Claude uses it in its response.

Steps 4–6 repeat as needed. Claude might call one tool or chain five together.

How MCP compares to function calling

If you've used OpenAI's function calling, MCP might seem familiar. Key differences:

	Function Calling	MCP
Scope	Single API provider	Universal protocol
Discovery	Defined per request	Server advertises capabilities
Transport	HTTP only	stdio, HTTP, SSE
Packaging	Not standardized	npm packages, shared configs
Ecosystem	Locked to one provider	Works with any MCP client

Function calling is "here are the tools for this conversation." MCP is "here's a server full of capabilities that any client can discover and use."

The complete 40-line server

Here's a complete, working MCP server. This is real — you can run this today:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({
  name: "starter-tools",
  version: "0.1.0",
});

server.tool(
  "generate_uuid",
  "Generate a random UUID",
  {},
  async () => ({
    content: [{ type: "text", text: crypto.randomUUID() }],
  })
);

server.tool(
  "timestamp",
  "Get the current time in multiple formats",
  {},
  async () => {
    const now = new Date();
    return {
      content: [{
        type: "text",
        text: [
          `ISO: ${now.toISOString()}`,
          `Unix: ${Math.floor(now.getTime() / 1000)}`,
          `Human: ${now.toLocaleString()}`,
        ].join("\n"),
      }],
    };
  }
);

const transport = new StdioServerTransport();
await server.connect(transport);

Save as src/index.ts. Add to your Claude Desktop config:

{
  "mcpServers": {
    "starter-tools": {
      "command": "npx",
      "args": ["tsx", "src/index.ts"]
    }
  }
}

Restart Claude. You have a working agent with two tools.

The rest is about making those tools useful, reliable, and shippable.

This is Part 2 of a free 3-part series on MCP.

Part 3 covers the opportunity — where the gaps are in the ecosystem, how to go from open source package to paid product, and the actual revenue math.

The full course — **Build & Ship MCP Tools* — takes you from your first tool to a published npm package. 7 modules, 33 lessons.*

Get early access for $29

The Agentic Shift — Why AI Developers Need to Learn MCP Now

Marco Arras — Tue, 07 Apr 2026 17:28:23 +0000

Six months ago, Claude could chat. It could write code, explain concepts, draft emails. But when the conversation ended, nothing happened. The AI lived inside a text box.

Today, Claude can read your GitHub repo, check open issues, write code, open a pull request, and message your team on Slack — in a single conversation. Not because Claude got smarter. Because someone built the tools that let it act.

That shift — from chatbot to agent — is the most important change happening in AI right now. And the developers building the tools that make it possible are in an incredibly valuable position.

Three eras of AI development

Era 1: Chat (2022–2023)
You type a prompt. The model responds. You copy-paste the output somewhere useful. The AI has no context beyond what you paste into the conversation. Every interaction starts from zero.

Era 2: RAG and retrieval (2023–2024)
Systems start feeding documents into the model's context. Vector databases, embeddings, retrieval pipelines. The AI can "know" things about your data — but it still can't do anything with that knowledge. It reads, but it doesn't write.

Era 3: Agentic (2024–now)
The model can call functions. It can read data, make decisions, and take actions. It can chain multiple steps together. It's not just answering questions — it's completing tasks.

We're in Era 3. The models are capable enough. The protocols exist. The infrastructure is being built right now. The bottleneck isn't intelligence — it's tooling.

What "agentic" actually means

An AI agent isn't a new kind of model. It's a regular language model with three additions:

Tools — functions the model can call (check weather, query a database, send an email)
A decision loop — the model looks at the result of each tool call and decides what to do next
Context — the model maintains state across multiple steps

Here's what that looks like in practice.

You say to Claude: "How does AAPL look today?"

Without tools, Claude says: "I don't have access to real-time stock data, but as of my last update..."

With tools, Claude:

Calls get_stock_quote("AAPL") — gets today's price
Calls get_stock_financials("AAPL") — gets P/E ratio, margins, revenue
Calls get_stock_news("AAPL") — gets recent headlines
Synthesizes everything into a clear analysis

Same model. Completely different capability. The difference is the tools.

The tool layer is where value accrues

Here's the thing most people miss: the model layer is commoditizing. GPT-4, Claude, Gemini, Llama — they're all getting better, faster, cheaper. You can't build a lasting advantage on which model you use.

But the tool layer? That's where the value is.

When you build a tool that connects Claude to a stock API, you're not just writing a function. You're creating a capability that didn't exist before. Every developer who installs your tool gives Claude (or any MCP-compatible agent) a new superpower.

Think about it like smartphone apps. The iPhone was powerful, but the App Store is what made it indispensable. The models are the phone. The tools are the apps. We're in the App Store moment for AI agents.

Why this matters for you

If you're a developer, you already have the skills to build these tools. They're TypeScript functions with a specific interface. The hard part isn't the code. It's understanding what to build and how to ship it.

The developers who move now have a real advantage:

The ecosystem is early. There are entire verticals with zero MCP tool coverage. DevOps, healthcare, legal, finance, education — wide open.
The protocol is stabilizing. MCP (Model Context Protocol) is emerging as the standard. Tools you build today will work tomorrow.
Distribution is built in. Publish an MCP tool to npm and every Claude Desktop user can install it with one line. No app store approval. No marketing budget required.

This isn't theoretical. In the next post, I'll show you exactly what MCP is — with working code.

This is Part 1 of a free 3-part series on MCP.

I'm building a full course — **Build & Ship MCP Tools* — that takes you from your first tool to a published npm package to a paid product. 7 modules, 33 lessons.*

Get early access for $29

I gave Claude real-time stock analysis. Here's how it works.

Marco Arras — Thu, 19 Mar 2026 15:17:56 +0000

Claude can reason about stocks brilliantly. But ask it about NVDA's current P/E ratio, whether insiders are buying, or what last quarter's earnings meant — and it has to guess. Its training data has a cutoff. It has no live market data.

I fixed that by building five tools that give Claude everything a Motley Fool analyst would reach for: live financials, earnings history, insider transactions, valuation metrics, and analyst consensus. Claude synthesizes the data. You get structured research.

Here's what it produces and how to use it.

What the tools return

A single call to stock-thesis with {"ticker": "NVDA"} pulls data from three sources in parallel — Polygon.io (company overview + price), Finnhub (metrics, analyst ratings, insider trades), and Financial Modeling Prep (income statements, key ratios) — and returns this:

{
  "verdict": "bullish",
  "oneLiner": "Nvidia owns the essential infrastructure for the AI revolution with a defensible software moat, but the valuation demands flawless execution.",
  "thesis": "Nvidia is in a rare position: it supplies the picks and shovels for an industry-wide megatrend. The company has grown revenue at a staggering 10,005% CAGR over three years...",
  "keyStrengths": [
    "Dominant market position in AI chips with ~80%+ data center GPU market share",
    "CUDA software moat creates switching costs and customer lock-in",
    "42 buy / 5 hold / 1 sell analyst consensus shows street confidence"
  ],
  "keyRisks": [
    "36.9x P/E leaves no margin for error",
    "Intensifying competition from AMD, Intel, and hyperscaler custom silicon"
  ],
  "valuation": "Nvidia trades at 36.9x trailing earnings — premium to sector but justified by AI tailwinds. Fair value hinges entirely on sustained data center spending.",
  "insiderRead": "Mixed signals: two executives bought ~47k shares each in March (positive), offset by routine selling from others.",
  "watchFor": "Data center revenue growth rate and gross margin trends — deceleration below 30% YoY would signal the boom is maturing.",
  "dataSnapshot": {
    "marketCapBillions": 4452.2,
    "currentPrice": 180.4,
    "peRatio": 36.9,
    "analystConsensus": { "buy": 42, "hold": 5, "sell": 1 }
  }
}

That's not a data dump. That's analysis — the kind you'd get from a well-researched article, delivered as structured JSON in about 4 seconds.

The five tools

stock-thesis — Full investment thesis. Verdict (bullish/neutral/bearish), 2-3 paragraph analysis, strengths, risks, valuation read, insider interpretation, and the one thing to watch next earnings.

earnings-analysis — EPS beat/miss track record across the last 12 quarters. Revenue trend (accelerating/stable/decelerating). What the pattern means for a long-term holder.

insider-signal — Interprets Form 4 filings. Distinguishes meaningful open-market purchases from routine option exercises and tax-withholding sales. Returns signal strength: strong_buy → strong_sell.

valuation-snapshot — P/E, P/S, EV/EBITDA, FCF yield, ROE, net margin. Verdict (very_cheap/cheap/fair/expensive/very_expensive) plus a specific buy zone: "at what P/E would this become clearly attractive?"

bear-vs-bull — Steelmans both sides equally. Three bull arguments with specific data, three bear arguments with specific data, net verdict, and the single key question investors need to answer before buying.

Use it in Claude Desktop or Claude Code

One command:

claude mcp add agent-toolbelt \
  -e AGENT_TOOLBELT_KEY=atb_... \
  -- npx -y agent-toolbelt-mcp

Then in Claude:

"Give me a full analysis of AAPL — thesis, earnings quality, insider activity, and whether it's cheap or expensive right now."

Claude calls all four tools in parallel and synthesizes a complete research note. No switching between financial sites. No copy-pasting data into prompts.

Use it in a LangChain agent

import { AgentToolbelt } from "agent-toolbelt";
import { createLangChainTools } from "agent-toolbelt/langchain";
import { createReactAgent } from "@langchain/langgraph/prebuilt";
import { ChatAnthropic } from "@langchain/anthropic";

const client = new AgentToolbelt({ apiKey: process.env.AGENT_TOOLBELT_KEY! });
const tools = createLangChainTools(client);

// tools includes: stock_thesis, earnings_analysis, insider_signal,
//                 valuation_snapshot, bear_vs_bull (+ 20 utility tools)

const agent = createReactAgent({
  llm: new ChatAnthropic({ model: "claude-opus-4-6" }),
  tools,
});

const result = await agent.invoke({
  messages: [{
    role: "user",
    content: "Compare NVDA and AMD. Which has the stronger investment case right now?",
  }],
});

The agent will call stock-thesis and bear-vs-bull for both tickers, then synthesize a comparison. Real data, real analysis, in a few lines of code.

Or call the API directly

curl -X POST https://agent-toolbelt-production.up.railway.app/api/tools/bear-vs-bull \
  -H "Authorization: Bearer atb_..." \
  -H "Content-Type: application/json" \
  -d '{"ticker": "TSLA"}'

{
  "verdict": "too_close",
  "bullCase": [
    { "argument": "Energy business inflection", "detail": "..." },
    { "argument": "Full Self-Driving optionality", "detail": "..." },
    { "argument": "Brand and pricing power", "detail": "..." }
  ],
  "bearCase": [
    { "argument": "Auto margin compression", "detail": "..." },
    { "argument": "CEO distraction risk", "detail": "..." },
    { "argument": "Competition catching up", "detail": "..." }
  ],
  "keyDebate": "Is Tesla an auto company or an AI/energy company? The answer determines whether the multiple is justified.",
  "forInvestorsWho": "Suits investors who believe in long-duration optionality and can stomach high volatility."
}

Pricing

1,000 free calls/month. No credit card required.

Stock analysis tools are $0.05/call on the pay-as-you-go tier — prepaid credits, no subscription. A $10 pack covers 200 analyses.

Get your key: agent-toolbelt-production.up.railway.app

The raw data APIs (Polygon, Finnhub, FMP) are all freely available. What takes time is knowing which endpoints to call, normalizing the response formats, writing prompts that produce consistent structured output, and handling graceful degradation when a source is down. These tools handle all of that so you don't have to.

If you're building a stock research agent, portfolio monitor, or anything that needs live fundamental analysis — this is the fastest way to get there.

Three API Calls That Make Your LLM Workflow Dramatically Better

Marco Arras — Mon, 02 Mar 2026 15:20:38 +0000

Building on top of LLMs is mostly a problem of plumbing. The model itself is capable. The hard part is everything around it: managing context, crafting prompts that reliably produce good output, and dealing with all the unstructured text that needs to become structured data.

Three tools in my stack handle the most common versions of these problems. Here's how I use them.

Problem 1: Context Overflows — Token Counter

If you're building any agent that processes documents, maintains conversation history, or chains multiple LLM calls, you've hit this error:

openai.BadRequestError: This model's maximum context length is 128000 tokens.
However, your messages resulted in 134521 tokens.

The naive fix is to truncate blindly. The real fix is to count tokens before you make the call and make a decision.

The problem is token counting is model-specific, non-obvious, and the libraries that do it (tiktoken, @dqbd/tiktoken) have quirks around special tokens, system prompts, and multi-turn conversations that make "just add it to your project" more involved than it sounds.

The API approach

curl -X POST https://agent-toolbelt-production.up.railway.app/api/tools/token-counter \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "{{ full conversation history + document here }}",
    "model": "gpt-4o"
  }'

{
  "tokens": 89432,
  "model": "gpt-4o",
  "limit": 128000,
  "remaining": 38568,
  "percentUsed": 69.87
}

The percentUsed and remaining fields let you make branching decisions without calculating anything:

import { AgentToolbelt } from "agent-toolbelt";

const toolbelt = new AgentToolbelt({ apiKey: process.env.TOOLBELT_KEY });

async function prepareContext(history: Message[], document: string) {
  const fullContext = buildContextString(history, document);

  const { percentUsed, remaining } = await toolbelt.tokenCounter({
    text: fullContext,
    model: "gpt-4o",
  });

  if (percentUsed > 80) {
    // Summarize old history before proceeding
    return await summarizeHistory(history, remaining);
  }

  if (percentUsed > 95) {
    // Chunk the document instead of including the full thing
    return await chunkAndProcess(document);
  }

  return fullContext;
}

This pattern — count first, decide, then call — prevents runtime failures and makes context management explicit rather than a guessing game.

I check token counts at three points in any agent that handles variable-length input:

Before appending to conversation history
Before adding a retrieved document to the context
Before the final LLM call, as a sanity check

Problem 2: Weak Prompts — Prompt Optimizer

Here's an uncomfortable truth: most prompts in production agents are not good. Not because the developer is bad at writing prompts, but because:

Prompt engineering is a craft that takes iteration to get right
The first draft usually works "well enough" and never gets revisited
What "well enough" means becomes clear only when edge cases fail

The prompt optimizer is powered by Claude and takes your prompt plus a description of your goal and returns a better version with an explanation of what changed.

What this looks like in practice

Original prompt:

Analyze this customer feedback and tell me what's wrong.

Goal: "Categorize issues by type and severity so a product manager can prioritize fixes"

curl -X POST https://agent-toolbelt-production.up.railway.app/api/tools/prompt-optimizer \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Analyze this customer feedback and tell me what what'\''s wrong.",
    "goal": "Categorize issues by type and severity so a product manager can prioritize fixes"
  }'

Optimized prompt:

You are a product analyst reviewing customer feedback. Analyze the following feedback and categorize every issue you find.

For each issue, provide:
- **Category**: Bug / UX Problem / Missing Feature / Performance / Other
- **Severity**: Critical (blocks usage) / High (significant friction) / Medium (noticeable but workaround exists) / Low (minor inconvenience)
- **Description**: One sentence describing the specific issue
- **Quote**: The exact phrase from the feedback that indicates this issue

Format your response as a structured list. If no issues are present, say so explicitly.

Changes explained:

Added a clear analyst persona to orient the model's reasoning
Defined explicit categories and severity levels to remove ambiguity
Required a direct quote to keep the analysis grounded in the actual feedback
Specified format explicitly so the output is consistent and parseable

The changes array is the part I find most valuable long-term. It's effectively prompt engineering education inline with the work — you can see which principles are being applied and why, which improves your own prompts over time.

My workflow

Every new prompt I write for a production agent goes through the optimizer once before it ships. I treat the optimized version as a starting point, not a final answer — sometimes I override specific changes, sometimes I take it wholesale.

For A/B testing:

const { optimizedPrompt, changes } = await toolbelt.promptOptimizer({
  prompt: currentPrompt,
  goal: "Extract structured contact information from business card text",
});

// Run both in shadow mode, compare output quality
const [originalResult, optimizedResult] = await Promise.all([
  callLLM(currentPrompt, testInput),
  callLLM(optimizedPrompt, testInput),
]);

At $0.05/call, running every significant prompt through this once is the cheapest prompt engineering review you can get.

Problem 3: Meeting Notes to Action Items — meetings.elephanttortoise.com

This one isn't strictly an LLM-workflow problem — it's a general productivity problem. But it shows up constantly in agent builds because meeting notes are one of the most common forms of unstructured text that needs to become structured data.

The gap between "notes from a meeting" and "tasks in a project management tool" is always a human doing manual extraction. It shouldn't be.

The API

curl -X POST https://agent-toolbelt-production.up.railway.app/api/tools/meeting-action-items \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "notes": "Sprint planning with the team. Decided to delay the billing feature to next sprint — the payment gateway integration is taking longer than expected. Alex is going to refactor the auth module by Thursday. Need Jamie to write up the new onboarding flow specs before our next sync on Friday. I should review the Q4 metrics and send a report to leadership by EOW. Still undecided on whether to use Stripe or Braintree — Alex will evaluate both and report back."
  }'

{
  "actionItems": [
    {
      "task": "Refactor the auth module",
      "owner": "Alex",
      "deadline": "Thursday"
    },
    {
      "task": "Write up new onboarding flow specs",
      "owner": "Jamie",
      "deadline": "Before Friday sync"
    },
    {
      "task": "Review Q4 metrics and send report to leadership",
      "owner": "You",
      "deadline": "End of week"
    },
    {
      "task": "Evaluate Stripe vs Braintree and report back",
      "owner": "Alex",
      "deadline": null
    }
  ],
  "summary": "Billing feature delayed to next sprint. Four action items across three owners. Payment gateway decision pending Alex's evaluation."
}

The model correctly:

Identified the deferred billing feature as a decision, not an action item
Extracted the "I should" as belonging to "You"
Left deadline null when none was specified (rather than hallucinating one)

Where this gets interesting

The structured output is the point. With this response, you can:

// Auto-create Jira tickets
for (const item of actionItems) {
  await jira.createIssue({
    summary: item.task,
    assignee: resolveUser(item.owner),
    dueDate: parseDeadline(item.deadline),
  });
}

// Post to Slack
await slack.postMessage({
  channel: "#project-updates",
  text: summary,
  blocks: formatActionItemsAsBlocks(actionItems),
});

// Add to your project tracker
await notion.createTasks(actionItems);

One API call turns messy meeting notes into structured data that plugs into whatever system you're already using.

Putting It Together

These three tools address three different points in an LLM-based workflow:

Token Counter → Before the LLM call: is my context safe?
Prompt Optimizer → At deploy time: is my prompt good?
Meeting Action Items → After human collaboration: what needs to happen next?

None of them are complex to integrate. Each one is a POST request with a JSON body. But together they remove a significant amount of the manual work that surrounds LLM-based applications.

All three run on the same API key:

import { AgentToolbelt } from "agent-toolbelt";

const toolbelt = new AgentToolbelt({ apiKey: process.env.TOOLBELT_KEY });

// Everything from one client
await toolbelt.tokenCounter({ text, model: "gpt-4o" });
await toolbelt.promptOptimizer({ prompt, goal });
await toolbelt.meetingActionItems({ notes });

Get started: tokens.elephanttortoise.com · prompts.elephanttortoise.com · meetings.elephanttortoise.com

Agent Toolbelt is a collection of focused API tools for developers building on top of LLMs. Pricing is per-call. See all 14 tools →

I Stopped Writing JSON Schemas and Regex by Hand. Here's What I Do Instead.

Marco Arras — Mon, 02 Mar 2026 15:16:57 +0000

There are two types of code that every backend developer writes too much of: JSON schemas and regex patterns.

They're not hard. They're just tedious. And they have a way of taking 30 minutes when you expected 5. The schema you wrote by hand has a typo. The regex works for 90% of cases but misses the edge case you didn't think of. You open regex101 for the third time this week.

I solved this by turning both into API calls. Here's how.

The JSON Schema Problem — schema.elephanttortoise.com

If you're building APIs, validating LLM output, or defining TypeScript interfaces, you're writing JSON schemas. Manually. From example data that you already have.

This is the classic definition of a task that should not require a human.

The workflow before

Take your example JSON object
Open json-schema.org or remember the syntax
Manually map each field to its type
Add required, additionalProperties, format strings for dates
Test it, find the typo in "propeties", fix it
If you want a TypeScript interface too: do it all again

The workflow now

curl -X POST https://agent-toolbelt-production.up.railway.app/api/tools/schema-generator \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "orderId": "ord_abc123",
      "customer": {
        "id": "usr_456",
        "email": "jane@example.com"
      },
      "items": [
        { "sku": "WIDGET-001", "quantity": 2, "price": 19.99 }
      ],
      "total": 39.98,
      "status": "pending",
      "createdAt": "2024-03-01T14:22:00Z"
    },
    "format": "json-schema"
  }'

Response:

{
  "schema": {
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "properties": {
      "orderId": { "type": "string" },
      "customer": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "email": { "type": "string", "format": "email" }
        },
        "required": ["id", "email"]
      },
      "items": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "sku": { "type": "string" },
            "quantity": { "type": "integer" },
            "price": { "type": "number" }
          },
          "required": ["sku", "quantity", "price"]
        }
      },
      "total": { "type": "number" },
      "status": { "type": "string" },
      "createdAt": { "type": "string", "format": "date-time" }
    },
    "required": ["orderId", "customer", "items", "total", "status", "createdAt"]
  },
  "format": "json-schema"
}

Notice it:

Detected the nested object structure
Inferred email format from the value
Detected date-time format from the ISO string
Correctly typed quantity as integer and price as number
Populated required correctly

Switch "format" to "typescript" and you get:

interface Output {
  orderId: string;
  customer: {
    id: string;
    email: string;
  };
  items: Array<{
    sku: string;
    quantity: number;
    price: number;
  }>;
  total: number;
  status: string;
  createdAt: string;
}

Where I use this

Validating LLM output. When I ask a model to return structured data, I take an example of the output I want, run it through schema-generator, and use the result with Zod or Ajv for validation. This cuts the schema-writing step entirely.

Documenting undocumented APIs. Hit the endpoint, grab the response, generate the schema. Done.

Starting TypeScript interfaces. I paste in a sample API response and get a starting interface. It's not always perfect (it can't infer discriminated unions or enums), but it's 80% of the work in one API call.

The Regex Problem — regex.elephanttortoise.com

Regex is write-once-debug-forever. The pattern that works in isolation fails in production because of a format variant you didn't consider. Then you're back in regex101, debugging character classes.

I'll be honest: I know regex well enough to write most patterns I need. But I've stopped doing it manually because there's no good reason to.

Describing what you want in English

curl -X POST https://agent-toolbelt-production.up.railway.app/api/tools/regex-builder \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Extract version numbers like 1.0.0, 2.13.4, or v3.0.0-beta.1 from a string",
    "testString": "Using express@4.18.2, react@18.2.0, and typescript@v5.0.0-beta.1"
  }'

Response:

{
  "pattern": "v?\\d+\\.\\d+\\.\\d+(?:-[\\w.]+)?",
  "flags": "g",
  "explanation": "Optionally matches a leading 'v', then three dot-separated numbers (major.minor.patch), followed by an optional pre-release suffix starting with a hyphen",
  "matches": ["4.18.2", "18.2.0", "v5.0.0-beta.1"]
}

The explanation field is what makes this useful beyond just getting the pattern. It tells you what the pattern does so you can verify it matches your mental model, and adjust the description if not.

The feedback loop

The real workflow isn't one-shot — it's iterative:

# First attempt
"description": "Match US phone numbers"
# → Too loose, matches 7-digit numbers

# Refined
"description": "Match 10-digit US phone numbers with optional country code +1, supporting formats: (555) 123-4567, 555-123-4567, 555.123.4567, +15551234567"
# → Gets exactly what you want with the edge cases handled

The description-based approach forces you to be precise about what you actually want, which surfaces edge cases earlier than writing the pattern directly would.

Where I use this

Data pipelines. Extracting structured data from unstructured text — dates, IDs, amounts, codes — without hand-crafting patterns for each format variant.

Input validation. Describe the valid format for your domain (order IDs, SKUs, reference numbers) and get the validation pattern.

AI agent tools. When an agent needs to extract something specific from a large document, I build the pattern with a description and hand it to the agent as a tool parameter.

Using Both Together

The combination becomes powerful when you're building data extraction pipelines. Example: processing invoice emails from multiple vendors with different formats.

import { AgentToolbelt } from "agent-toolbelt";

const toolbelt = new AgentToolbelt({ apiKey: process.env.TOOLBELT_KEY });

// Step 1: Build extraction patterns from a description
const { pattern: invoiceNumberPattern } = await toolbelt.regexBuilder({
  description: "Extract invoice numbers like INV-2024-001, #12345, or Invoice: 98765",
  testString: sampleInvoiceText,
});

const { pattern: amountPattern } = await toolbelt.regexBuilder({
  description: "Extract dollar amounts like $1,234.56 or USD 1234.56",
  testString: sampleInvoiceText,
});

// Step 2: Extract data using the patterns
const invoiceNumber = new RegExp(invoiceNumberPattern).exec(emailBody)?.[0];
const amount = new RegExp(amountPattern).exec(emailBody)?.[0];

// Step 3: Validate the structured output
const { schema } = await toolbelt.schemaGenerator({
  input: { invoiceNumber, amount, vendor: "...", date: "..." },
  format: "json-schema",
});

// Now you have validated, typed data from unstructured email text

Three API calls replaced what would have been a morning of work: designing the extraction logic, writing the patterns, defining the schema, wiring up validation.

The Broader Point

The best developer tools are the ones that handle the mechanics so you can think about the problem. JSON schemas and regex patterns are mechanics — the interesting part is what you do with the extracted data.

Both tools are available with the same API key. Pricing is fractions of a cent per call. No setup, no library to install (unless you want the TypeScript SDK), no configuration.

Get started: schema.elephanttortoise.com · regex.elephanttortoise.com

Agent Toolbelt is a collection of focused, pay-per-call API tools for developers and AI agents. See all 14 tools →

5 API Tools That Save AI Developers Hours of Boilerplate

Marco Arras — Mon, 02 Mar 2026 14:59:30 +0000

When I started building AI agents, I noticed a pattern: 80% of my time wasn't going into the agent logic — it was going into the infrastructure around the agent logic. Counting tokens before making API calls. Writing JSON schemas by hand. Debugging regex patterns. Cleaning up GPT output so it was actually useful.

None of this is interesting work. It's the tax you pay to build something interesting.

I built Agent Toolbelt to eliminate that tax. Each tool is a focused, pay-per-call API endpoint that does one thing well. Here are the five I reach for constantly.

1. Token Counter — Know Your Context Limits Before You Hit Them

If you've ever gotten a context_length_exceeded error mid-agent-run, you know the pain. Token counting feels like it should be trivial, but every model counts differently, and the tiktoken library has non-obvious behavior for different models.

The API:

curl -X POST https://agent-toolbelt-production.up.railway.app/api/tools/token-counter \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Analyze the following document and extract key action items...",
    "model": "gpt-4o"
  }'

Response:

{
  "tokens": 14,
  "model": "gpt-4o",
  "limit": 128000,
  "remaining": 127986,
  "percentUsed": 0.01
}

I use this before every LLM call in my agents to decide whether to summarize context, chunk documents, or proceed as-is. It's replaced about 200 lines of token management code across my projects.

2. Schema Generator — Stop Writing JSON Schemas by Hand

JSON Schema is powerful and absolutely miserable to write. TypeScript interfaces are better, but converting between them is a chore. This tool takes a sample JSON object and generates both.

The API:

curl -X POST https://agent-toolbelt-production.up.railway.app/api/tools/schema-generator \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "userId": "usr_123",
      "email": "user@example.com",
      "plan": "pro",
      "createdAt": "2024-01-15T10:30:00Z"
    },
    "format": "typescript"
  }'

Response:

{
  "schema": "interface Output {\n  userId: string;\n  email: string;\n  plan: string;\n  createdAt: string;\n}",
  "format": "typescript"
}

This is especially useful when you're working with undocumented APIs or extracting structured data from LLM output. Paste the example, get the schema, move on.

3. Regex Builder — Describe It in English, Get the Pattern

Regex is one of those things where the write-once-debug-forever rule really applies. ^[\w.]+@[\w]+\.[\w.]+$ is not readable. The regex builder lets you describe what you want in plain English and get a working pattern with an explanation.

The API:

curl -X POST https://agent-toolbelt-production.up.railway.app/api/tools/regex-builder \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Match US phone numbers in formats like (555) 123-4567, 555-123-4567, or 5551234567",
    "testString": "Call us at (555) 123-4567 or 555.987.6543"
  }'

Response:

{
  "pattern": "\\(?\\d{3}\\)?[\\s.\\-]?\\d{3}[\\s.\\-]?\\d{4}",
  "flags": "g",
  "explanation": "Matches US phone numbers with optional parentheses around area code, separated by spaces, dots, or hyphens",
  "matches": ["(555) 123-4567", "555.987.6543"]
}

In agent workflows, I use this for data extraction and validation. Tell the agent what format you want, get the regex, apply it to your pipeline.

4. Prompt Optimizer — Make Your Prompts Actually Work

This one is powered by Claude and it has saved my agents from a lot of mediocre output. You pass it a prompt and it returns an improved version with an explanation of what changed and why.

The API:

curl -X POST https://agent-toolbelt-production.up.railway.app/api/tools/prompt-optimizer \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Summarize this document",
    "goal": "Extract key decisions and action items for a project manager"
  }'

Response:

{
  "optimizedPrompt": "You are a project management assistant. Review the following document and produce a structured summary that includes: (1) Key decisions made, with context, (2) Action items with owner and deadline if mentioned, (3) Open questions requiring follow-up. Format your response as a bulleted list under each section.",
  "changes": [
    "Added a clear role/persona to orient the model",
    "Made the output format explicit with three specific sections",
    "Specified structured formatting to ensure consistent, parseable output"
  ],
  "estimatedImprovement": "High — original prompt was ambiguous about scope and format"
}

I run new prompts through this before adding them to production agents. The changes array is particularly useful for learning — it teaches you what prompt engineering principles are being applied.

5. Meeting Action Items — Turn Notes into Tasks Instantly

This is the one non-developers ask me about most. Paste raw meeting notes — however messy — and get back structured action items with owners and deadlines. Also Claude-powered.

The API:

curl -X POST https://agent-toolbelt-production.up.railway.app/api/tools/meeting-action-items \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "notes": "Sync call with Sarah and Mike. We agreed to push the launch to March 15. Mike needs to finish the billing integration by EOD Friday. Sarah will update the docs and send them to the team by Wednesday. We still need to decide on pricing — Mike will put together a proposal next week. Action: I need to email the investors by tomorrow."
  }'

Response:

{
  "actionItems": [
    { "task": "Finish billing integration", "owner": "Mike", "deadline": "Friday EOD" },
    { "task": "Update docs and send to team", "owner": "Sarah", "deadline": "Wednesday" },
    { "task": "Put together pricing proposal", "owner": "Mike", "deadline": "Next week" },
    { "task": "Email the investors", "owner": "You", "deadline": "Tomorrow" }
  ],
  "summary": "Launch pushed to March 15. Four action items assigned across three owners. Pricing decision pending Mike's proposal."
}

This integrates cleanly into any workflow automation — Zapier, Make, n8n, or directly in your agent.

Getting Started

All five tools are available under the same API key. The pricing is per-call: most tools are a fraction of a cent, the LLM-powered ones (prompt-optimizer and meeting-action-items) are $0.05/call.

# Get an API key
curl -X POST https://agent-toolbelt-production.up.railway.app/api/keys \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'

Or use the TypeScript SDK:

import { AgentToolbelt } from "agent-toolbelt";

const toolbelt = new AgentToolbelt({ apiKey: process.env.TOOLBELT_KEY });

const { tokens } = await toolbelt.tokenCounter({ text: myPrompt, model: "gpt-4o" });
const { optimizedPrompt } = await toolbelt.promptOptimizer({ prompt: myPrompt, goal: "..." });

The LangChain integration is also available if you're building with agents:

import { createLangChainTools } from "agent-toolbelt/langchain";

const tools = createLangChainTools({ apiKey: process.env.TOOLBELT_KEY });
// Drop into any LangChain agent executor

Stop paying the boilerplate tax. These five calls handle the tedious parts so you can focus on the parts that actually matter.

Agent Toolbelt is a collection of focused, pay-per-call API tools for AI developers. See all 14 tools →