List WhisperGraph Labels

Instructions

Implementation Reference

• src/tools/schema-tools.ts:60-62 (handler)

  listLabels() handler method in SchemaTools class — the core logic that executes the tool. Delegates to fetchLabelRows() which runs CALL db.labels() and caches results for 5 minutes.

  async listLabels(credential: Credential | null): Promise<{ labels: Row[] }> {
    return { labels: await this.fetchLabelRows(credential) };
  }

• src/tools/schema-tools.ts:93-109 (helper)

  fetchLabelRows() private helper — executes the backend Cypher query CALL db.labels(), caches results in TtlCache, and returns empty array on failure (best-effort).

  private async fetchLabelRows(credential: Credential | null): Promise<Row[]> {
    const cached = this.labelsCache.get(LABELS_KEY);
    if (cached) return cached;
  
    let rows: Row[];
    try {
      const raw = await this.backend.execute("CALL db.labels()", undefined, credential);
      rows = raw.rows ?? [];
    } catch (error) {
      // Schema introspection is best-effort: an unreachable backend yields an
      // empty list rather than failing the tool call.
      log.warn(`list_labels failed: ${describeError(error)}`);
      rows = [];
    }
    this.labelsCache.set(LABELS_KEY, rows);
    return rows;
  }

• src/server.ts:124-138 (registration)

  Tool registration via server.registerTool('list_labels', ...) — defines inputSchema (empty), outputSchema ({ labels: z.array(rowSchema) }), links to handler via schemaTools.listLabels().

  server.registerTool(
    "list_labels",
    {
      title: "List WhisperGraph Labels",
      description: LIST_LABELS_DESCRIPTION,
      inputSchema: {},
      outputSchema: { labels: z.array(rowSchema) },
      annotations: READ_ONLY_ANNOTATIONS,
    },
    async (_args, extra) => {
      const credential = resolveCredential(extra.requestInfo?.headers, config.apiKey);
      const result = await schemaTools.listLabels(credential);
      return toolResult(result);
    },
  );

• src/server.ts:130-131 (schema)

  Output schema definition for list_labels: { labels: z.array(rowSchema) } where rowSchema is z.record(z.string(), z.unknown()).

  outputSchema: { labels: z.array(rowSchema) },
  annotations: READ_ONLY_ANNOTATIONS,

• src/tools/descriptions.ts:39-45 (helper)

  LIST_LABELS_DESCRIPTION constant — the user-facing description used in the tool registration.

  export const LIST_LABELS_DESCRIPTION = `List all node labels in WhisperGraph with their counts.
  
  Use this BEFORE writing a query when you're not sure which label to anchor on. It rules out hallucinated labels (e.g. there is no DOMAIN or FQDN — only HOSTNAME) and tells you which labels are large (HOSTNAME, IPV4) vs small (RIR, COUNTRY).
  
  Returns: an array of {label, count} rows. Cached server-side for 5 minutes.
  
  Tip: pair with describe_label to verify which properties exist on a label before referencing them in WHERE clauses.`;