Describe symbols

Instructions

Implementation Reference

• src/tools/symbols/describeTool.ts:23-88 (handler)

  Main implementation of the describe-symbols tool. Registers the tool with input schema (ids, limit, offset), filters SYMBOLS by ids or returns all, then paginates via paginateSymbols.

  function describeSymbolsTool(server: HLMcpServer) {
    server.registerTool(
      'describe-symbols',
      {
        title: 'Describe symbols',
        description: DESCRIBE_TOOL_DESCRIPTION,
        inputSchema: {
          ids: z
            .array(z.string())
            .describe(
              'List of symbol IDs used to fetch detailed information for each symbol.'
            ),
          limit: z
            .number()
            .int()
            .optional()
            .default(25)
            .describe('Maximum number of symbols to return (default: 25).'),
          offset: z
            .number()
            .int()
            .optional()
            .default(0)
            .describe('Offset for pagination (default: 0).'),
        },
        outputSchema: {
          result: PaginatedSymbolSchema,
        },
      },
      async ({
        ids,
        limit,
        offset,
      }: {
        ids: string[];
        limit: number;
        offset: number;
      }) => {
        validatePaginationParams(limit, offset);
  
        const symbols: Array<Symbol> = [];
  
        SYMBOLS.forEach((symbol) => {
          if (ids.length > 0) {
            if (ids.includes(symbol.id)) {
              symbols.push(symbol);
            }
          } else {
            symbols.push(symbol); // return all symbols if no IDs are provided
          }
        });
  
        const content = { result: paginateSymbols(symbols, limit, offset) };
  
        return {
          content: [
            {
              type: 'text' as const,
              text: JSON.stringify(content),
            },
          ],
          structuredContent: content,
        };
      }
    );
  }

• src/tools/symbols/describeTool.ts:26-51 (schema)

  Input/output schema definitions for the describe-symbols tool. Input accepts ids (string array), limit (int, default 25), offset (int, default 0). Output uses PaginatedSymbolSchema.

  {
    title: 'Describe symbols',
    description: DESCRIBE_TOOL_DESCRIPTION,
    inputSchema: {
      ids: z
        .array(z.string())
        .describe(
          'List of symbol IDs used to fetch detailed information for each symbol.'
        ),
      limit: z
        .number()
        .int()
        .optional()
        .default(25)
        .describe('Maximum number of symbols to return (default: 25).'),
      offset: z
        .number()
        .int()
        .optional()
        .default(0)
        .describe('Offset for pagination (default: 0).'),
    },
    outputSchema: {
      result: PaginatedSymbolSchema,
    },
  },

• src/index.ts:32-36 (registration)

  Registration of describeSymbolsTool via server.modify() at the application entry point.

  server.modify(registerResources);
  server.modify(searchSymbolsTool);
  server.modify(describeSymbolsTool);
  server.modify(createExtendAppPrompt);

• src/tools/symbols/utils.ts:210-224 (helper)

  paginateSymbols helper used by the handler to slice results and return paginated data with total and next offset.

  function paginateSymbols(
    results: Array<Symbol>,
    limit: number,
    offset: number
  ): PaginatedSymbol {
    const end = Math.min(offset + limit, results.length);
    const next = end < results.length ? end : undefined;
    const data = results.slice(offset, end);
  
    return {
      data,
      total: results.length,
      next,
    };
  }

• src/tools/symbols/utils.ts:226-234 (helper)

  validatePaginationParams helper used by the handler to validate limit and offset inputs.

  function validatePaginationParams(
    limit: number,
    offset: number,
    maxLimit: number = 1000
  ): void {
    if (limit <= 0) throw new Error('limit must be positive');
    if (offset < 0) throw new Error('offset must be non-negative');
    if (limit > maxLimit) throw new Error(`limit cannot exceed ${maxLimit}`);
  }