docs: complete the searchControls parameter table - #21
Merged
Conversation
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) <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
Updates the README’s searchControls documentation to reflect the observed API representation more accurately, including per-parameter shapes and the distinction between the CLI “friendly” format vs per-index storage in the service.
Changes:
- Expands the
searchControlstable to cover all observed parameters and their differing sub-field shapes. - Clarifies that “apply one block to every index” is a property of the friendly format, while the service stores
searchControlsper-index. - Adds provenance/uncertainty notes based on live inspection vs an out-of-sync published schema.
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+219
to
+220
| The parameters do **not** share one shape — `constraint` appears only on the numeric | ||
| ones, `merge` only on the list-valued ones: |
Comment on lines
+216
to
+217
| Set `exposed: true` to let the LLM vary the value within its constraint; `exposed: false` | ||
| to fix it. |
chuckmeyer
added a commit
that referenced
this pull request
Aug 27, 2026
Two contradictions introduced by #21, both found in review. The prose claimed constraint appears only on the numeric parameters while the table listed it for attributesToRetrieve and responseFields as well. That conflated "the key exists" with "it carries a {min, max} shape". Re-derived from 21 indices across the 12 live agents: four parameters carry a constraint key — hitsPerPage, page, attributesToRetrieve, responseFields — and only hitsPerPage was ever observed with one populated. merge was null in every record, so neither its purpose nor the constraint shape on those two parameters is known. `exposed: true` was described as varying the value "within its constraint", but distinct and facets have no constraint key at all. Reworded so the constraint is only mentioned where one is present. The unconfirmed list now covers merge and any constraint beyond hitsPerPage, rather than implying the rest is settled. Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #16 — the documentation half; the capability half shipped with the native config format in #19.
Problem
The
searchControlstable listed five of the eight parameters the service returns, and its single "What it does" column implied they all share one shape. They do not.Corrected
hitsPerPage,pageexposed,default,constraint: {min, max}attributesToRetrieve,responseFieldsexposed,default: [],constraint,mergedistinctexposed,default(boolean) — noconstraint, nomergefacetsexposed,default: []— noconstraint, nomergequery,customSo
constraintis numeric-only andmergeis list-only. Anything validating or generating these cannot assume a uniform shape.Also corrects a scoping statement: applying one block to every index is a property of the friendly format. The service stores
searchControlsper index, and a native config fromsnapshotcan differ index by index.Provenance
Derived by inspecting live agents, not from a published schema — the team reports the OpenAPI spec is out of sync. The README now says so, and flags
query,customand the semantics ofmergeas unconfirmed rather than implying completeness.Docs only; no code change.
🤖 Generated with Claude Code