find_records
Retrieve records from a sift by applying a Mongo-subset filter, optional sort, limit, and pagination cursor for precise data querying.
Instructions
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}Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sift_id | Yes | ||
| filter | Yes | ||
| sort | No | ||
| limit | No | ||
| cursor | No |
Implementation Reference
- Direct database handler for find_records used by the chat agent loop. Transforms filter keys to 'extracted_data.' prefix and runs a MongoDB aggregation pipeline.
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/mcp/sifter_mcp/server.py:263-291 (handler)MCP tool handler for find_records. Uses AsyncSifter SDK client to filter records in a sift with structured criteria (Mongo-subset filter). Decorated with @mcp.tool().
@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} - JSON Schema definition for the find_records tool function used in the agent tool list (OpenAI-compatible function calling schema).
{ "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/mcp/sifter_mcp/server.py:263-291 (registration)Registration via @mcp.tool() decorator on the find_records async function in the FastMCP server.
@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/zapier/index.js:263-287 (helper)Zapier integration: defines 'find_records' as a search with input fields (sift_id, filter JSON, limit) and an HTTP perform function calling the backend 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: {} }, }, };