CLAUDE.md

Agent Tool Repository

This repository contains your organization's custom agent tools. The package manager is pnpm.

Tool Structure

tools/<tool-name>/
  tool.json             # Tool metadata with UUID
  index.ts              # Tool implementation
  src/clients/          # Auto-generated resource clients
  resources.json        # Auto-generated resource registry

tool.json Format

{
  "id": "<uuid>",
  "name": "tool-name",
  "description": "What this tool does",
  "inputSchema": {
    "type": "object",
    "properties": {
      "param1": { "type": "string", "description": "..." }
    },
    "required": ["param1"]
  }
}

index.ts Format

Every tool's index.ts default-exports a handler that receives two arguments: the tool input and a context object injected per-request by the MCP server. Never read auth values from process.env.

import { createOrdersDbClient } from "./src/clients";

interface ToolInput {
  userId: string;
}

interface ToolContext {
  resourceApiUrl: string;
  majorJwtToken: string;
}

export default async function(input: ToolInput, context: ToolContext) {
  const db = createOrdersDbClient(context);
  const result = await db.invoke(
    "SELECT * FROM orders WHERE user_id = $1",
    [input.userId],
    "get-user-orders"
  );

  if (!result.ok) {
    throw new Error(result.error.message);
  }

  return result.result;
}

Resource Clients

Generate resource clients using the add-tool-resource-client MCP tool.

Resource clients are factory functions that accept context. Create a client instance inside the handler on every call -- do not cache globally. If the tool's UUID changes, regenerate all resource clients.

Rules

• Never push to main -- always create a branch
• Always use generated resource clients -- never construct clients manually
• Always pass context to resource client factory functions -- never read from process.env
• Tool names should be kebab-case
• Each tool should do one thing well

Examples of good tools:

• Return the number of users who signed up between start and end
• Deactivate's a user - performs functions across all resources to deactivate a user
• Returns sales statstics for all the BDRs across the company