get_subscribe_link

Instructions

Implementation Reference

• src/server.ts:19-42 (registration)

  Tools are registered in a loop in server.ts. 'get_subscribe_link' is registered via the ALL_TOOLS array.

  for (const tool of ALL_TOOLS) {
    server.tool(
      tool.name,
      tool.description,
      tool.schema.shape,
      tool.annotations,
      async (args: Record<string, unknown>) => {
        try {
          const result = await tool.handler(args);
          return {
            content: [
              { type: 'text' as const, text: JSON.stringify(result, null, 2) },
            ],
          };
        } catch (err: unknown) {
          const message = err instanceof Error ? err.message : String(err);
          return {
            content: [{ type: 'text' as const, text: `Error: ${message}` }],
            isError: true,
          };
        }
      },
    );
  }

• src/tools.ts:713-733 (registration)

  'getSubscribeLink' is included in the ALL_TOOLS array which is used by server.ts to register all tools.

  export const ALL_TOOLS: ToolDef[] = [
    cbmCalculator,
    chargeableWeightCalculator,
    ldmCalculator,
    adrLookup,
    adrExemptionCalculator,
    adrLqEqCheck,
    airlineLookup,
    containerLookup,
    hsCodeLookup,
    incotermsLookup,
    palletFittingCalculator,
    unitConverter,
    consignmentCalculator,
    unlocodeLookup,
    ukDutyCalculator,
    shipmentSummary,
    uldLookup,
    vehicleLookup,
    getSubscribeLink,
  ];

• src/tools.ts:680-707 (handler)

  Full tool definition including the handler that returns a static subscription URL (no API call).

  const getSubscribeLink: ToolDef = {
    name: 'get_subscribe_link',
    description: `Get the URL where the user can subscribe to FreightUtils Pro for higher API limits.
  
  Use this tool when:
  - The user asks how to upgrade or subscribe
  - The user hits a rate limit and asks how to get more requests
  - The user asks about pricing
  
  Returns the subscription URL plus the tier/limit/price metadata. Agents must hand this URL to the user — DO NOT attempt to complete the subscription on the user's behalf.`,
  
    schema: z.object({
      tier: z.enum(['pro']).optional().describe('Tier to surface (only "pro" supported today)'),
    }).strict(),
  
    annotations: readOnlyAnnotations('FreightUtils Subscribe Link'),
  
    // Pure static response — no upstream API call. The pricing page is the
    // canonical surface for subscription; this tool just hands the URL back.
    handler: async () => ({
      url: 'https://www.freightutils.com/pricing',
      tier: 'pro',
      monthly_limit: 50000,
      monthly_price: '£19',
      currency: 'GBP',
      note: 'Open the URL in a browser to subscribe. Agents must not attempt to complete checkout themselves.',
    }),
  };

• src/tools.ts:691-693 (schema)

  Zod schema defining the optional 'tier' input parameter (only 'pro' is supported).

  schema: z.object({
    tier: z.enum(['pro']).optional().describe('Tier to surface (only "pro" supported today)'),
  }).strict(),

• src/tools.ts:28-34 (helper)

  Helper used by the tool to generate annotation metadata marking it as read-only and idempotent.

  const readOnlyAnnotations = (title: string): ToolAnnotationShape => ({
    title,
    readOnlyHint: true,
    destructiveHint: false,
    idempotentHint: true,
    openWorldHint: false,
  });