Search or list documents
frappe_search_docsSearch or list documents of a single DocType with filters, selected fields, ordering, and pagination to find records by field value or browse matching entries.
Instructions
Search or list documents of one DocType, with optional filters, field selection, ordering and pagination.
Use to find documents by field value or to browse a DocType. Use frappe_get_doc instead when the exact document name is known and every field is wanted; use frappe_run_method for aggregates, totals or report output, which this tool cannot compute.
Behavior: read-only and idempotent, with no side effects. Only documents the API user's role permissions allow are returned, so a short result may mean restricted access rather than no matches. An unknown doctype raises a not-found error, and an unknown fieldname in filters, fields or order_by raises a Frappe error rather than being silently ignored.
Parameters: filters entries are ANDed together — there is no OR — and each is a [field, operator, value] triple; in/not in take a list as the value and between takes a two-element list. fields should name only what is needed, since omitting it returns every field of every row and can be very large. limit defaults to 20 and Frappe caps it at 200; there is no offset parameter, so page by ordering on creation and filtering past the last value already seen.
Returns: {"data": [...]} — an array of documents, empty when nothing matches.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"doctype": "<doctype>"
},
"name": "frappe_search_docs"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of results to return (default: 20, maximum: 200). Frappe caps results at 200 per request; there is no offset parameter, so paginate by narrowing `filters` rather than by increasing this. | |
| fields | No | Optional list of fieldnames to return. Limits the response to only the specified fields, which keeps large result sets manageable. Example: ['name', 'status', 'grand_total', 'posting_date']. When omitted, all fields are returned. Child-table fields are not expanded here — fetch the full document with frappe_get_doc for those. | |
| doctype | Yes | The DocType to search within (e.g. 'Sales Invoice', 'Customer', 'Item', 'ToDo', 'Contact'). Case-sensitive; exactly one DocType per call, as this tool cannot search across DocTypes. | |
| filters | No | Optional list of filter conditions, all ANDed together. Each filter is a triple [field, operator, value]. Supported operators: =, !=, >, <, >=, <=, like, not like, in, not in, between. Example: [['status','=','Open'], ['grand_total','>','1000']]. Dates are compared as 'YYYY-MM-DD' strings. | |
| order_by | No | Field to sort by with direction, formatted as 'fieldname direction'. Examples: 'creation desc' (newest first), 'modified asc' (oldest updated first), 'name asc' (alphabetical). The direction is required. Defaults to 'creation desc' when omitted. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| data | Yes | Matching documents, in the requested order. Empty when nothing matched. Each row carries only the requested `fields`, or every field when `fields` was omitted. |