Skip to main content
Glama
HuntsDesk

Vibe Board VE

by HuntsDesk
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Hybrid

board_get_activity

Query the activity log to audit tasks, reconstruct sessions, or track agent actions. Filter by task ID, session ID, agent name, or action, with results capped at a customizable limit.

Instructions

Query the activity_log. Filter by task_id, session_id, agent_name, or action. Results are ordered newest-first and capped at limit (default 50, max 200). Useful for auditing what happened on a task, reconstructing a session, or following an agent's actions.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
task_idNoFilter by related task ID
session_idNoFilter by related session ID
agent_nameNoFilter by agent name
actionNoFilter by action type
limitNoMax entries to return (default 50, max 200)

Implementation Reference

  • src/tools/activity.ts:97-196 (handler)
    The async handler function for 'board_get_activity' tool. It queries Firestore 'activity_log' collection with optional filters (task_id, session_id, agent_name, action), paginates with a hard cap, applies remaining filters in JS to avoid composite indexes, and returns results ordered newest-first.
    async ({ task_id, session_id, agent_name, action, limit }) => {
  // Build query with single-field filter then order+limit. Firestore
  // requires a composite index for multi-field filter+order; to avoid
  // that, we pick the most selective filter as the query filter and
  // apply any remaining filters in JS.
  let query: FirebaseFirestore.Query = db.collection("activity_log");
  const jsFilters: Array<[string, unknown]> = [];

  // Pick one field to push to Firestore (ordered by selectivity for our
  // use cases). Remaining filters become JS predicates.
  if (task_id !== undefined) {
    query = query.where("task_id", "==", task_id);
    if (session_id !== undefined) jsFilters.push(["session_id", session_id]);
    if (agent_name !== undefined) jsFilters.push(["agent_name", agent_name]);
    if (action !== undefined) jsFilters.push(["action", action]);
  } else if (session_id !== undefined) {
    query = query.where("session_id", "==", session_id);
    if (agent_name !== undefined) jsFilters.push(["agent_name", agent_name]);
    if (action !== undefined) jsFilters.push(["action", action]);
  } else if (agent_name !== undefined) {
    query = query.where("agent_name", "==", agent_name);
    if (action !== undefined) jsFilters.push(["action", action]);
  } else if (action !== undefined) {
    query = query.where("action", "==", action);
  }
  // Else: unfiltered scan (bounded by limit).

  const effectiveLimit = Math.min(limit ?? 50, 200);
  // Order by created_at DESC directly in Firestore. Equality-filter +
  // order on a different field doesn't require a composite index for
  // our single-equality-filter cases (common composite-index requirement
  // only kicks in with range filters or multi-field equality + order).
  query = query.orderBy("created_at", "desc");

  // Cursor pagination. When JS filters apply, fetch pages until we fill
  // `effectiveLimit` or hit a hard scan cap (prevents runaway reads on
  // highly-selective filters against huge collections).
  const PAGE_SIZE = 200;
  const HARD_SCAN_CAP = 2000;
  const results: Array<Record<string, unknown>> = [];
  let scanned = 0;
  let lastDoc: FirebaseFirestore.QueryDocumentSnapshot | null = null;
  let hitCap = false;

  const toISO = (v: unknown) =>
    v && typeof v === "object" && "toDate" in (v as object)
      ? (v as { toDate(): Date }).toDate().toISOString()
      : null;

  while (results.length < effectiveLimit && scanned < HARD_SCAN_CAP) {
    let pageQuery = query.limit(
      Math.min(PAGE_SIZE, HARD_SCAN_CAP - scanned)
    );
    if (lastDoc) pageQuery = pageQuery.startAfter(lastDoc);
    const snap = await pageQuery.get();
    if (snap.empty) break;

    scanned += snap.size;
    for (const d of snap.docs) {
      const data = d.data();
      const passes = jsFilters.every(
        ([k, v]) => (data as Record<string, unknown>)[k] === v
      );
      if (!passes) continue;
      results.push({
        id: d.id,
        ...data,
        created_at: toISO(data.created_at),
      });
      if (results.length >= effectiveLimit) break;
    }

    if (snap.size < PAGE_SIZE) break; // reached end of collection
    lastDoc = snap.docs[snap.docs.length - 1];
  }

  if (scanned >= HARD_SCAN_CAP && results.length < effectiveLimit) {
    hitCap = true;
  }

  return {
    content: [
      {
        type: "text" as const,
        text: JSON.stringify(
          {
            entries: results,
            scanned,
            truncated: hitCap,
            note: hitCap
              ? `Scan cap ${HARD_SCAN_CAP} reached before filling limit ${effectiveLimit}. Results may be incomplete. Tighten filters or raise cap.`
              : undefined,
          },
          null,
          2
        ),
      },
    ],
  };
}
  • src/tools/activity.ts:64-96 (schema)
    Zod schema definitions for 'board_get_activity' tool, defining optional input parameters: task_id, session_id, agent_name, action (enum), limit (1-200, default 50).
    "Query the activity_log. Filter by task_id, session_id, agent_name, or action. Results are ordered newest-first and capped at `limit` (default 50, max 200). Useful for auditing what happened on a task, reconstructing a session, or following an agent's actions.",
{
  task_id: z.string().optional().describe("Filter by related task ID"),
  session_id: z
    .string()
    .optional()
    .describe("Filter by related session ID"),
  agent_name: z
    .string()
    .optional()
    .describe("Filter by agent name"),
  action: z
    .enum([
      "created",
      "updated",
      "claimed",
      "blocked",
      "completed",
      "commented",
      "mode_changed",
      "session_started",
      "session_ended",
    ])
    .optional()
    .describe("Filter by action type"),
  limit: z
    .number()
    .int()
    .min(1)
    .max(200)
    .optional()
    .describe("Max entries to return (default 50, max 200)"),
},
  • src/tools/activity.ts:62-197 (registration)
    Registration of 'board_get_activity' via server.tool() inside registerActivityTools(). The tool is registered with name, description, schema, and handler.
    server.tool(
  "board_get_activity",
  "Query the activity_log. Filter by task_id, session_id, agent_name, or action. Results are ordered newest-first and capped at `limit` (default 50, max 200). Useful for auditing what happened on a task, reconstructing a session, or following an agent's actions.",
  {
    task_id: z.string().optional().describe("Filter by related task ID"),
    session_id: z
      .string()
      .optional()
      .describe("Filter by related session ID"),
    agent_name: z
      .string()
      .optional()
      .describe("Filter by agent name"),
    action: z
      .enum([
        "created",
        "updated",
        "claimed",
        "blocked",
        "completed",
        "commented",
        "mode_changed",
        "session_started",
        "session_ended",
      ])
      .optional()
      .describe("Filter by action type"),
    limit: z
      .number()
      .int()
      .min(1)
      .max(200)
      .optional()
      .describe("Max entries to return (default 50, max 200)"),
  },
  async ({ task_id, session_id, agent_name, action, limit }) => {
    // Build query with single-field filter then order+limit. Firestore
    // requires a composite index for multi-field filter+order; to avoid
    // that, we pick the most selective filter as the query filter and
    // apply any remaining filters in JS.
    let query: FirebaseFirestore.Query = db.collection("activity_log");
    const jsFilters: Array<[string, unknown]> = [];

    // Pick one field to push to Firestore (ordered by selectivity for our
    // use cases). Remaining filters become JS predicates.
    if (task_id !== undefined) {
      query = query.where("task_id", "==", task_id);
      if (session_id !== undefined) jsFilters.push(["session_id", session_id]);
      if (agent_name !== undefined) jsFilters.push(["agent_name", agent_name]);
      if (action !== undefined) jsFilters.push(["action", action]);
    } else if (session_id !== undefined) {
      query = query.where("session_id", "==", session_id);
      if (agent_name !== undefined) jsFilters.push(["agent_name", agent_name]);
      if (action !== undefined) jsFilters.push(["action", action]);
    } else if (agent_name !== undefined) {
      query = query.where("agent_name", "==", agent_name);
      if (action !== undefined) jsFilters.push(["action", action]);
    } else if (action !== undefined) {
      query = query.where("action", "==", action);
    }
    // Else: unfiltered scan (bounded by limit).

    const effectiveLimit = Math.min(limit ?? 50, 200);
    // Order by created_at DESC directly in Firestore. Equality-filter +
    // order on a different field doesn't require a composite index for
    // our single-equality-filter cases (common composite-index requirement
    // only kicks in with range filters or multi-field equality + order).
    query = query.orderBy("created_at", "desc");

    // Cursor pagination. When JS filters apply, fetch pages until we fill
    // `effectiveLimit` or hit a hard scan cap (prevents runaway reads on
    // highly-selective filters against huge collections).
    const PAGE_SIZE = 200;
    const HARD_SCAN_CAP = 2000;
    const results: Array<Record<string, unknown>> = [];
    let scanned = 0;
    let lastDoc: FirebaseFirestore.QueryDocumentSnapshot | null = null;
    let hitCap = false;

    const toISO = (v: unknown) =>
      v && typeof v === "object" && "toDate" in (v as object)
        ? (v as { toDate(): Date }).toDate().toISOString()
        : null;

    while (results.length < effectiveLimit && scanned < HARD_SCAN_CAP) {
      let pageQuery = query.limit(
        Math.min(PAGE_SIZE, HARD_SCAN_CAP - scanned)
      );
      if (lastDoc) pageQuery = pageQuery.startAfter(lastDoc);
      const snap = await pageQuery.get();
      if (snap.empty) break;

      scanned += snap.size;
      for (const d of snap.docs) {
        const data = d.data();
        const passes = jsFilters.every(
          ([k, v]) => (data as Record<string, unknown>)[k] === v
        );
        if (!passes) continue;
        results.push({
          id: d.id,
          ...data,
          created_at: toISO(data.created_at),
        });
        if (results.length >= effectiveLimit) break;
      }

      if (snap.size < PAGE_SIZE) break; // reached end of collection
      lastDoc = snap.docs[snap.docs.length - 1];
    }

    if (scanned >= HARD_SCAN_CAP && results.length < effectiveLimit) {
      hitCap = true;
    }

    return {
      content: [
        {
          type: "text" as const,
          text: JSON.stringify(
            {
              entries: results,
              scanned,
              truncated: hitCap,
              note: hitCap
                ? `Scan cap ${HARD_SCAN_CAP} reached before filling limit ${effectiveLimit}. Results may be incomplete. Tighten filters or raise cap.`
                : undefined,
            },
            null,
            2
          ),
        },
      ],
    };
  }
);
  • src/index.ts:31-31 (registration)
    The call site where registerActivityTools(server, db) is invoked, which registers both board_log_activity and board_get_activity.
    registerActivityTools(server, db);
  • src/types.ts:57-74 (helper)
    ActivityLog interface type definition used by the activity tools, defining the shape of activity log entries (task_id, session_id, agent_name, action, details, metadata, created_at).
    export interface ActivityLog {
  task_id: string | null;
  session_id: string | null;
  agent_name: string;
  action:
    | "created"
    | "updated"
    | "claimed"
    | "blocked"
    | "completed"
    | "commented"
    | "mode_changed"
    | "session_started"
    | "session_ended";
  details: string | null;
  metadata: Record<string, unknown>;
  created_at: Timestamp;
}

Tool Definition Quality

A4.1/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description carries the burden. It discloses ordering (newest-first) and capping (default 50, max 200). It implies a read operation via 'Query', but could explicitly state it is read-only. Overall adequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with action, no wasted words. Each sentence adds value: what it does, filters, ordering, limit, use cases.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers filters, ordering, and limit. However, without an output schema, it lacks return structure details. For a query tool with 5 optional parameters, it is mostly complete but could mention return fields.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description groups the filters but adds little beyond schema descriptions, except for the limit default and max. The schema already specifies enum values for action.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'Query' and resource 'activity_log', and lists filter criteria and output characteristics. It clearly distinguishes itself from siblings like 'board_log_activity' and 'board_get_handoff'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit use cases: auditing, reconstructing sessions, following actions. It mentions ordering and capping but does not explicitly state when not to use it or alternatives. However, the use cases are clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server

Other Tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/HuntsDesk/ve-vibe-board'

If you have feedback or need assistance with the MCP directory API, please join our Discord server