AroFlo MCP

AroFlo: Get DocumentsAndPhotos

aroflo_get_documentsandphotos

Read-onlyIdempotent

Retrieve documents and photos from AroFlo by applying filters, sorting results, and joining related data to access specific files efficiently.

Instructions

Query the AroFlo DocumentsAndPhotos zone (GET). Use pipe-delimited WHERE clauses like "and|field|=|value", ORDER clauses like "field|asc", and JOIN areas like "lineitems". where/order/join accept either a single string or an array. mode: data|verbose|debug|raw (default: data). Set compact=true and optionally select=["field","nested.field"] to reduce payload size. See resource "aroflo://docs/api/" (example: "aroflo://docs/api/quotes") for valid fields/values.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`where`	No
`order`	No
`join`	No
`page`	No
`pageSize`	No
`autoPaginate`	No
`maxPages`	No
`maxResults`	No
`maxItemsTotal`	No
`validateWhere`	No
`mode`	No
`verbose`	No
`debug`	No
`raw`	No
`compact`	No
`select`	No
`maxItems`	No
`extra`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Implementation Reference

src/mcp/tools/get-zones.ts:77-270 (handler)

The tool handler is defined within `registerZoneGetTools` in `src/mcp/tools/get-zones.ts`. It iterates over `AROFLO_ZONES` and registers a tool for each zone, dynamically setting the tool name to `aroflo_get_${zoneToToolSuffix(zone)}`. For 'DocumentsAndPhotos', this results in `aroflo_get_documentsandphotos`.

async (args) => {
  const mode = resolveOutputMode(args);
  const envelopeRequested =
    typeof args.mode === 'string' || Boolean(args.raw) || Boolean(args.verbose);
  try {
    const where = normalizeWhereParam(args.where);
    const order = normalizeOrderParam(args.order);
    const join = normalizeJoinParam(args.join);

    if (args.validateWhere !== false) {
      await validateWhereOrThrow({ zone, where });
    }

    const autoPaginate = Boolean(args.autoPaginate);
    const startPage = args.page ?? 1;
    const pageSize = args.pageSize ?? (autoPaginate ? 200 : undefined);
    const maxResultsRaw =
      typeof args.maxItemsTotal === 'number' ? args.maxItemsTotal : args.maxResults;
    const maxResults =
      typeof args.maxResults === 'number' && typeof args.maxItemsTotal === 'number'
        ? Math.min(args.maxResults, args.maxItemsTotal)
        : maxResultsRaw;
    const maxPages = args.maxPages ?? (autoPaginate ? 25 : undefined);

    const debugInfo: Record<string, unknown> | undefined = args.debug
      ? {
          zone,
          normalized: {
            where,
            order,
            join,
            page: startPage,
            pageSize,
            extra: args.extra
          }
        }
      : undefined;

    let response = await client.get(zone, {
      where,
      order,
      join,
      page: startPage,
      pageSize,
      extra: args.extra
    });

    let pagesFetched = 1;
    let truncated = false;
    let truncatedReason: string | undefined;
    let nextPage: number | undefined;

    if (autoPaginate) {
      let currentPage = startPage;
      let lastPageCount = extractZoneItems(zone, response.data).items.length;
      while (true) {
        const total = extractZoneItems(zone, response.data).items.length;

        if (typeof maxResults === 'number' && total >= maxResults) {
          truncated = true;
          truncatedReason = 'maxResults';
          nextPage = currentPage + 1;
          break;
        }

        if (typeof maxPages === 'number' && pagesFetched >= maxPages) {
          truncated = true;
          truncatedReason = 'maxPages';
          nextPage = currentPage + 1;
          break;
        }

        if (typeof pageSize === 'number' && lastPageCount < pageSize) {
          break;
        }

        currentPage += 1;
        const next = await client.get(zone, {
          where,
          order,
          join,
          page: currentPage,
          pageSize,
          extra: args.extra
        });

        // If the next page contributes nothing, stop.
        const nextCount = extractZoneItems(zone, next.data).items.length;
        if (nextCount === 0) {
          break;
        }

        response = {
          ...response,
          data: mergeZoneResponseData(response.data, next.data).merged
        };
        pagesFetched += 1;
        lastPageCount = nextCount;

        // Stop if the last page was short.
        if (typeof pageSize === 'number' && nextCount < pageSize) {
          break;
        }
      }
    }

    if (typeof maxResults === 'number') {
      const total = extractZoneItems(zone, response.data).items.length;
      if (total > maxResults) {
        const { truncated: newData } = truncateZoneArrays(response.data, maxResults);
        response = { ...response, data: newData };
        truncated = true;
        truncatedReason = truncatedReason ?? 'maxResults';
      }
    }

    let compactApplied = false;
    let effectiveResponse = response;
    const defaultSelect =
      zone === 'Tasks' && args.compact && (!args.select || args.select.length === 0)
        ? [
            'taskid',
            'jobnumber',
            'status',
            'taskname',
            'daterequested',
            'createdutc',
            'clientid',
            'org.orgid',
            'org.orgname',
            'projectid',
            'stageid',
            'project.projectid',
            'project.projectname',
            'tasktotals.totalhrs'
          ]
        : undefined;
    const select = args.select ?? defaultSelect;

    if (args.compact || (select && select.length > 0) || args.maxItems) {
      compactApplied = true;
      const compactedData = compactZoneResponseData(response.data, {
        select,
        maxItems: args.maxItems
      });
      effectiveResponse = { ...response, data: compactedData };
    }

    // Backward compatible default: return the full AroFlo client response, optionally
    // annotated with pagination/debug metadata. The new minimal envelope is opt-in via
    // args.mode / args.verbose / args.raw.
    if (!envelopeRequested) {
      let finalData: unknown = effectiveResponse.data;
      if (autoPaginate || truncated) {
        finalData = withZoneResponseMeta(finalData, {
          pagesFetched,
          truncated,
          truncatedReason,
          nextPage
        });
      }
      if (debugInfo) {
        finalData = withDebug(finalData, debugInfo);
      }
      return successToolResult({ ...effectiveResponse, data: finalData });
    }

    const out = buildZoneDataEnvelope({
      zone,
      response: effectiveResponse,
      page: startPage,
      pageSize,
      mode,
      mcp:
        autoPaginate || truncated
          ? {
              autoPaginate,
              pagesFetched,
              truncated,
              truncatedReason,
              nextPage
            }
          : undefined,
      debug: debugInfo,
      compactApplied,
      select,
      maxItems: args.maxItems
    });

    return successToolResult(out);
  } catch (error) {
    return errorToolResult(error, { mode, debug: { zone } });
  }
}

src/mcp/tools/get-zones.ts:56-271 (registration)

The tool registration happens inside a loop over `AROFLO_ZONES` in `src/mcp/tools/get-zones.ts`. `toolName` is constructed as `aroflo_get_${zoneToToolSuffix(zone)}`.

server.registerTool(
  toolName,
  {
    title: `AroFlo: Get ${zone}`,
    description:
      `Query the AroFlo ${zone} zone (GET). ` +
      `Use pipe-delimited WHERE clauses like "and|field|=|value", ORDER clauses like "field|asc", and JOIN areas like "lineitems". ` +
      `where/order/join accept either a single string or an array. ` +
      `mode: data|verbose|debug|raw (default: data). ` +
      `Set compact=true and optionally select=[\"field\",\"nested.field\"] to reduce payload size. ` +
      `See resource "aroflo://docs/api/<slug>" (example: "aroflo://docs/api/quotes") for valid fields/values.`,
    inputSchema,
    // MCP SDK expects output schemas to be object schemas (or raw object shapes).
    // `z.any()` causes output validation to crash under the current SDK.
    outputSchema: z.object({}).passthrough(),
    annotations: {
      readOnlyHint: true,
      idempotentHint: true,
      openWorldHint: true
    }
  },
  async (args) => {
    const mode = resolveOutputMode(args);
    const envelopeRequested =
      typeof args.mode === 'string' || Boolean(args.raw) || Boolean(args.verbose);
    try {
      const where = normalizeWhereParam(args.where);
      const order = normalizeOrderParam(args.order);
      const join = normalizeJoinParam(args.join);

      if (args.validateWhere !== false) {
        await validateWhereOrThrow({ zone, where });
      }

      const autoPaginate = Boolean(args.autoPaginate);
      const startPage = args.page ?? 1;
      const pageSize = args.pageSize ?? (autoPaginate ? 200 : undefined);
      const maxResultsRaw =
        typeof args.maxItemsTotal === 'number' ? args.maxItemsTotal : args.maxResults;
      const maxResults =
        typeof args.maxResults === 'number' && typeof args.maxItemsTotal === 'number'
          ? Math.min(args.maxResults, args.maxItemsTotal)
          : maxResultsRaw;
      const maxPages = args.maxPages ?? (autoPaginate ? 25 : undefined);

      const debugInfo: Record<string, unknown> | undefined = args.debug
        ? {
            zone,
            normalized: {
              where,
              order,
              join,
              page: startPage,
              pageSize,
              extra: args.extra
            }
          }
        : undefined;

      let response = await client.get(zone, {
        where,
        order,
        join,
        page: startPage,
        pageSize,
        extra: args.extra
      });

      let pagesFetched = 1;
      let truncated = false;
      let truncatedReason: string | undefined;
      let nextPage: number | undefined;

      if (autoPaginate) {
        let currentPage = startPage;
        let lastPageCount = extractZoneItems(zone, response.data).items.length;
        while (true) {
          const total = extractZoneItems(zone, response.data).items.length;

          if (typeof maxResults === 'number' && total >= maxResults) {
            truncated = true;
            truncatedReason = 'maxResults';
            nextPage = currentPage + 1;
            break;
          }

          if (typeof maxPages === 'number' && pagesFetched >= maxPages) {
            truncated = true;
            truncatedReason = 'maxPages';
            nextPage = currentPage + 1;
            break;
          }

          if (typeof pageSize === 'number' && lastPageCount < pageSize) {
            break;
          }

          currentPage += 1;
          const next = await client.get(zone, {
            where,
            order,
            join,
            page: currentPage,
            pageSize,
            extra: args.extra
          });

          // If the next page contributes nothing, stop.
          const nextCount = extractZoneItems(zone, next.data).items.length;
          if (nextCount === 0) {
            break;
          }

          response = {
            ...response,
            data: mergeZoneResponseData(response.data, next.data).merged
          };
          pagesFetched += 1;
          lastPageCount = nextCount;

          // Stop if the last page was short.
          if (typeof pageSize === 'number' && nextCount < pageSize) {
            break;
          }
        }
      }

      if (typeof maxResults === 'number') {
        const total = extractZoneItems(zone, response.data).items.length;
        if (total > maxResults) {
          const { truncated: newData } = truncateZoneArrays(response.data, maxResults);
          response = { ...response, data: newData };
          truncated = true;
          truncatedReason = truncatedReason ?? 'maxResults';
        }
      }

      let compactApplied = false;
      let effectiveResponse = response;
      const defaultSelect =
        zone === 'Tasks' && args.compact && (!args.select || args.select.length === 0)
          ? [
              'taskid',
              'jobnumber',
              'status',
              'taskname',
              'daterequested',
              'createdutc',
              'clientid',
              'org.orgid',
              'org.orgname',
              'projectid',
              'stageid',
              'project.projectid',
              'project.projectname',
              'tasktotals.totalhrs'
            ]
          : undefined;
      const select = args.select ?? defaultSelect;

      if (args.compact || (select && select.length > 0) || args.maxItems) {
        compactApplied = true;
        const compactedData = compactZoneResponseData(response.data, {
          select,
          maxItems: args.maxItems
        });
        effectiveResponse = { ...response, data: compactedData };
      }

      // Backward compatible default: return the full AroFlo client response, optionally
      // annotated with pagination/debug metadata. The new minimal envelope is opt-in via
      // args.mode / args.verbose / args.raw.
      if (!envelopeRequested) {
        let finalData: unknown = effectiveResponse.data;
        if (autoPaginate || truncated) {
          finalData = withZoneResponseMeta(finalData, {
            pagesFetched,
            truncated,
            truncatedReason,
            nextPage
          });
        }
        if (debugInfo) {
          finalData = withDebug(finalData, debugInfo);
        }
        return successToolResult({ ...effectiveResponse, data: finalData });
      }

      const out = buildZoneDataEnvelope({
        zone,
        response: effectiveResponse,
        page: startPage,
        pageSize,
        mode,
        mcp:
          autoPaginate || truncated
            ? {
                autoPaginate,
                pagesFetched,
                truncated,
                truncatedReason,
                nextPage
              }
            : undefined,
        debug: debugInfo,
        compactApplied,
        select,
        maxItems: args.maxItems
      });

      return successToolResult(out);
    } catch (error) {
      return errorToolResult(error, { mode, debug: { zone } });
    }
  }
);

Tool Definition Quality

B3.2/5.0

Behavior3/5

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

Annotations cover read-only/idempotent safety. Description adds GET method confirmation and query DSL syntax. However, doesn't explain pagination behavior (offset vs cursor), the relationship between 'mode' enum and separate boolean flags (verbose/debug/raw), or the implication of openWorldHint.

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

Conciseness4/5

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

Information-dense with six focused sentences. Examples are concrete. Structure flows logically from purpose → syntax → options → documentation reference. Minor deduction for cramming multiple clause types into one sentence without visual separation.

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?

References external documentation resource for field validation, which is helpful given 18 undocumented schema properties. Output schema existence excuses return value documentation. However, incomplete given complexity: pagination model unexplained, validation behavior (validateWhere) unclear, and maxItems vs maxResults distinction missing.

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?

With 0% schema coverage, description compensates well for complex parameters (where/order/join syntax, mode options, compact/select usage). However, completely omits explanation of six pagination-related parameters (page, maxPages, etc.) and the 'extra' object, which are critical for a query tool with 5K result limits.

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

Purpose4/5

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

States specific action 'Query' and resource 'DocumentsAndPhotos zone' clearly. However, lacks distinction from generic query tools (e.g., aroflo_query_zone) present in siblings, and doesn't clarify if this returns metadata, file content, or both.

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

Usage Guidelines2/5

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

Provides excellent syntax examples for WHERE/ORDER/JOIN clauses, but fails to specify when to use this specific endpoint versus the generic 'aroflo_query_zone' or 'aroflo_get_record' siblings. No guidance on pagination strategies despite having six pagination parameters.

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

Tool Definition Quality Score (TDQS)
By punkpeye on April 3, 2026.
mcp
The Hackers Who Tracked My Sleep Cycle
By punkpeye on March 26, 2026.
security
Open Source Has a Bot Problem
By punkpeye on March 19, 2026.
open source

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/0x1NotMe/aroflo-mcp'

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