bubblyphone-agents

Instructions

Implementation Reference

• src/tools/calls.ts:72-80 (handler)

  The handler function for list_calls tool that builds a query object from optional filters (direction, status, phone_number_id, date_from, date_to) and calls client.get('/calls', query)

  async (params) => {
    const query: Record<string, string> = {};
    if (params.direction) query.direction = params.direction;
    if (params.status) query.status = params.status;
    if (params.phone_number_id) query.phone_number_id = params.phone_number_id;
    if (params.date_from) query.date_from = params.date_from;
    if (params.date_to) query.date_to = params.date_to;
    return callTool(() => client.get("/calls", query));
  }

• src/tools/calls.ts:61-71 (schema)

  The schema definition for list_calls including description, input schema with Zod validation for direction, status, phone_number_id, date_from, date_to filters, and read-only annotations

  {
    description: "List your calls with optional filtering by direction, status, phone number, and date range.",
    inputSchema: {
      direction: z.enum(["inbound", "outbound"]).optional().describe("Filter by call direction"),
      status: z.enum(["initiated", "ringing", "answered", "completed", "failed"]).optional().describe("Filter by call status"),
      phone_number_id: z.string().optional().describe("Filter by phone number ID"),
      date_from: z.string().optional().describe("Start date filter (YYYY-MM-DD)"),
      date_to: z.string().optional().describe("End date filter (YYYY-MM-DD)"),
    },
    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
  },

• src/tools/calls.ts:59-81 (registration)

  The registration of the list_calls tool with server.registerTool(), combining the tool name, schema configuration, and handler function

  server.registerTool(
    "list_calls",
    {
      description: "List your calls with optional filtering by direction, status, phone number, and date range.",
      inputSchema: {
        direction: z.enum(["inbound", "outbound"]).optional().describe("Filter by call direction"),
        status: z.enum(["initiated", "ringing", "answered", "completed", "failed"]).optional().describe("Filter by call status"),
        phone_number_id: z.string().optional().describe("Filter by phone number ID"),
        date_from: z.string().optional().describe("Start date filter (YYYY-MM-DD)"),
        date_to: z.string().optional().describe("End date filter (YYYY-MM-DD)"),
      },
      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
    },
    async (params) => {
      const query: Record<string, string> = {};
      if (params.direction) query.direction = params.direction;
      if (params.status) query.status = params.status;
      if (params.phone_number_id) query.phone_number_id = params.phone_number_id;
      if (params.date_from) query.date_from = params.date_from;
      if (params.date_to) query.date_to = params.date_to;
      return callTool(() => client.get("/calls", query));
    }
  );

• src/tools/calls.ts:13-20 (helper)

  Helper function callTool that wraps API calls with try-catch error handling, returning toolResult on success or toolError on API failure

  async function callTool<T>(fn: () => Promise<T>) {
    try {
      return toolResult(await fn());
    } catch (err) {
      const apiErr = err as ApiError;
      return toolError(`API error (${apiErr.status}): ${apiErr.message}`);
    }
  }

• src/tools/calls.ts:22-23 (registration)

  The registerCallTools function signature which contains all call-related tool registrations including list_calls

  export function registerCallTools(server: McpServer, client: BubblyPhoneClient) {
    server.registerTool(