From 23b13ab1c6b843deb8f72af30d02237f30565b2f Mon Sep 17 00:00:00 2001 From: Chuck Meyer Date: Wed, 26 Aug 2026 21:02:47 -0400 Subject: [PATCH] docs: complete the searchControls parameter table MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The table listed five of the eight parameters the service returns and implied they share one shape. They do not: constraint appears only on the numeric parameters (hitsPerPage, page) and merge only on the list-valued ones (attributesToRetrieve, responseFields), while distinct and facets carry neither. Adds the three missing parameters, the per-parameter sub-fields, and a note that this was derived by inspecting live agents rather than from a published schema — query, custom and the meaning of merge are still unconfirmed. Also clarifies that applying one block to every index is a property of the friendly format; the service stores searchControls per index, and a native config from snapshot can differ index by index. Closes the documentation half of #16. Co-Authored-By: Claude Opus 5 (1M context) --- README.md | 37 ++++++++++++++++++++++++++----------- 1 file changed, 26 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 60176df..42da4be 100644 --- a/README.md +++ b/README.md @@ -209,17 +209,32 @@ and the instructions file in a single pass — missing vars are reported togethe } ``` -`searchControls` constrains what the LLM can do at query time. It is applied to every index (primary + replicas). Supported fields: - -| Field | What it does | -|---|---| -| `hitsPerPage` | Limit result count. Set `constraint.max` to cap it. | -| `page` | Limit pagination depth. Set `constraint.max` to cap it. | -| `attributesToRetrieve` | Restrict which attributes are returned in each hit. Useful for limiting the LLM payload to only the fields it needs. | -| `facets` | Control which facet attributes are returned in the response. | -| `responseFields` | Restrict which top-level response fields are returned. | - -Set `exposed: true` to let the LLM vary the value within the constraint; `exposed: false` to fix it. +`searchControls` constrains what the LLM can do at query time. In this friendly format +one block is applied to **every** index (primary + replicas); the service itself stores +them per index, so a native config from `snapshot` can differ index by index. + +Set `exposed: true` to let the LLM vary the value within its constraint; `exposed: false` +to fix it. + +The parameters do **not** share one shape — `constraint` appears only on the numeric +ones, `merge` only on the list-valued ones: + +| Parameter | Sub-fields | What it does | +|---|---|---| +| `hitsPerPage` | `exposed`, `default`, `constraint: {min, max}` | Limit result count. Set `constraint.max` to cap it. | +| `page` | `exposed`, `default`, `constraint: {min, max}` | Limit pagination depth. | +| `attributesToRetrieve` | `exposed`, `default: []`, `constraint`, `merge` | Restrict which attributes each hit returns — useful for trimming the LLM payload. | +| `responseFields` | `exposed`, `default: []`, `constraint`, `merge` | Restrict which top-level response fields are returned. | +| `distinct` | `exposed`, `default` (boolean) | De-duplicate results. No `constraint`. | +| `facets` | `exposed`, `default: []` | Control which facet attributes the response returns. No `constraint`. | +| `query` | — | Present in the API's representation but not observed carrying a value. | +| `custom` | — | Present in the API's representation but not observed carrying a value. | + +This table was derived by inspecting live agents rather than from a published schema, so +treat `query`, `custom` and the semantics of `merge` as unconfirmed. The service returns +all eight keys with `null` for anything unset, and it expands the ones you do send with +its own defaults — which is why `--dry-run` compares only the keys your config actually +specifies. ```bash algolia-agent create \