find_records

Instructions

Args:
    sift_id: The sift identifier
    filter: Mongo-subset filter dict e.g. {"total": {"$gt": 1000}}
    sort: Optional sort spec e.g. [["date", -1]]
    limit: Max records to return (default 50)
    cursor: Opaque pagination cursor from a previous call

Returns:
    {"records": [...], "next_cursor": "..." | null}

Implementation Reference

• code/mcp/sifter_mcp/server.py:263-291 (handler)

  MCP tool handler for 'find_records'. Uses @mcp.tool() decorator. Accepts sift_id, filter dict, optional sort, limit (default 50, max 200), and cursor for pagination. Calls client.get_sift().find() and returns records, next_cursor, and total.

  @mcp.tool()
  async def find_records(
      sift_id: str,
      filter: dict,
      sort: list = None,
      limit: int = 50,
      cursor: str = "",
  ) -> dict:
      """Filter records with structured criteria (no LLM roundtrip).
  
      Args:
          sift_id: The sift identifier
          filter: Mongo-subset filter dict e.g. {"total": {"$gt": 1000}}
          sort: Optional sort spec e.g. [["date", -1]]
          limit: Max records to return (default 50)
          cursor: Opaque pagination cursor from a previous call
  
      Returns:
          {"records": [...], "next_cursor": "..." | null}
      """
      async with _get_client() as client:
          handle = await client.get_sift(sift_id)
          page = await handle.find(
              filter=filter,
              sort=sort or None,
              limit=min(limit, 200),
              cursor=cursor or None,
          )
      return {"records": page.items, "next_cursor": page.next_cursor, "total": page.total}

• code/server/sifter/services/agent_tools.py:92-111 (schema)

  OpenAI-compatible tool schema for 'find_records' used by LLM agent tool-calling. Defines JSON schema with sift_id, filter (MongoDB-style), and optional limit parameters.

      {
          "type": "function",
          "function": {
              "name": "find_records",
              "description": "Filter records in a sift using structured criteria (no LLM round-trip). Field names map to extracted_data keys.",
              "parameters": {
                  "type": "object",
                  "properties": {
                      "sift_id": {"type": "string", "description": "The sift identifier"},
                      "filter": {
                          "type": "object",
                          "description": 'MongoDB-style filter on extracted fields, e.g. {"amount": {"$gt": 1000}}',
                      },
                      "limit": {"type": "integer", "description": "Max records (default 50, max 200)"},
                  },
                  "required": ["sift_id", "filter"],
              },
          },
      },
  ]

• code/server/sifter/services/agent_tools.py:192-198 (handler)

  Agent tool runner dispatch for 'find_records'. Builds a MongoDB $match pipeline on extracted_data fields with configurable limit (default 50, max 200), then calls execute_aggregation.

  if name == "find_records":
      limit = min(args.get("limit", 50), 200)
      raw_filter = args.get("filter", {})
      mongo_filter = {f"extracted_data.{k}": v for k, v in raw_filter.items()}
      pipeline = [{"$match": mongo_filter}, {"$limit": limit}]
      results = await self.results_svc.execute_aggregation(args["sift_id"], pipeline)
      return {"results": results, "count": len(results)}

• code/zapier/index.js:263-287 (registration)

  Zapier integration search definition for 'find_records'. Registered in the 'searches' export at line 353. Defines input fields (sift_id, filter JSON, limit) and performs HTTP GET against the API.

  const searchFindRecords = {
    key: "find_records",
    noun: "Record",
    display: {
      label: "Find Records",
      description: "Search records in a sift.",
    },
    operation: {
      inputFields: [
        { key: "sift_id", label: "Sift", dynamic: "sift_choices.id.name", required: true },
        { key: "filter", label: "Filter (JSON)", required: false, helpText: 'e.g. {"amount": {"$gt": 100}}' },
        { key: "limit", label: "Limit", required: false, default: "10" },
      ],
      perform: async (z, bundle) => {
        const params = new URLSearchParams({ limit: bundle.inputData.limit || "10" });
        if (bundle.inputData.filter) params.set("filter", bundle.inputData.filter);
        const resp = await z.request({
          url: `${apiUrl(bundle)}/api/sifts/${bundle.inputData.sift_id}/records?${params}`,
          headers: headers(bundle),
        });
        return (resp.data.items || []);
      },
      sample: { id: "sample-record-id", extracted_data: {} },
    },
  };

• code/zapier/index.js:352-355 (registration)

  Zapier searches registration block where 'find_records' is registered as a search action via the key 'searchFindRecords.key'.

  searches: {
    [searchFindRecords.key]: searchFindRecords,
    [searchGetRecord.key]: searchGetRecord,
  },