search_records
Search records for a resource_id; search_type decides how the query is matched and defaults to hybrid. Use it when the request is in the user's own words; when the selection is an exact field condition, query_records filters without ranking. Long text fields may be shortened in results; a shortened record carries _sys.truncated. Where the resource lists get_one among its discover_resources capabilities, call get_record with that record's id for the full document. Returns 5 records unless limit says otherwise — enough to choose among hits and then fetch one. When the task is to enumerate or count, raise limit (up to 100) instead of paging through small pages: every page is resent on every later turn, so many small pages cost far more than one large one. In a files collection results are file metadata or chunk hits, read in full with get_record; a files collection connected without get_one answers access_denied.
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": {
"resource_id": "<resource_id>",
"query": "<query>"
},
"name": "search_records"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Records per call. Defaults to 5, which is enough to pick a hit and fetch it in full with get_record. Raise it (up to 100) when the task is to enumerate or count rather than to find. | |
| query | Yes | The text to search for. Whether it is matched by keyword, by meaning, or by both is decided by `search_type`. | |
| cursor | No | Pass back `page.next_cursor` from a previous response to get the following page. Reach for it only when a page really has to be continued: raising `limit` costs one call where paging costs one per page, and every page already fetched is re-sent on every later turn. | |
| filters | No | Field conditions, all of which must hold. `field` is a field path from the collection's describe_resource schema, `op` defaults to `eq`, and `value` follows the operator: a list for `in`/`not_in`, a two-element list for `between`, a single value otherwise. | |
| locales | No | Locale codes (`en`, `fr`, ...) to keep in localized fields. Omit it to get every locale the record carries, which is the right default unless one language was asked for. The codes are the keys of a localized field in any record of this collection; a code the environment does not use is not an error, it simply matches nothing. | |
| parents | No | Parent placeholders for nested resource_id templates. | |
| populate | No | Reference and relation fields come back as opaque record keys. Name those fields here and the records they point at are fetched and grafted in place of the key. Prefer it whenever a list result carries references the task needs: resolving them afterwards costs one call per record, and every earlier result is re-sent on every later turn, so ten resolved by hand cost far more than one populated call. Populated records obey the same text limit as the rest of this response; call get_record on a key for the unshortened record. | |
| resource_id | Yes | Resource identifier from discover_resources. | |
| search_type | No | How `query` is matched. `hybrid` (the default) ranks a union of keyword and meaning matches and is the right choice when in doubt. `text` matches keywords only — use it for identifiers, codes, names and exact phrases. `semantic` matches meaning only, so it can return records that share no word with the query, and it returns nothing at all on a collection with no embeddings. `vector_boosted` keeps `text`'s guarantee that every result really contains the query terms and only reorders them, lifting the closest few by meaning to the top; the rest keep the collection's default order and report `_sys.relevance` 0. | hybrid |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | Yes | ||
| items | Yes | The matching records, ranked, at most `limit` of them. | |
| truncation | No | Present when a text limit is in force for this collection. | |
| execution_info | No | Which search mode actually ran, which can differ from `search_type` when a mode is unavailable. |