Skip to main content
Glama

Brapi Raw Search

brapi_raw_search
Read-only

Passthrough to BrAPI POST /search/{noun}, polling async search IDs. Sends loadLimit as the initial pageSize unless body.page/pageSize drives explicit paging. List previews fit loadLimit and a 24,000-byte budget on each serialized row representation; an oversized first row returns no inline rows. Every fetched row omitted inline stays in a dataframe readable with brapi_dataframe_describe and brapi_dataframe_query. Explicit paging fetches only the requested page, staging it if trimmed. Non-list results and envelope siblings are preserved; no distributions or foreign-key resolution.

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": {
      "noun": "<noun>",
      "body": "<body>"
    },
    "name": "brapi_raw_search"
  }
}

Input Schema

NameRequiredDescriptionDefault
bodyYesFilter body passed verbatim to POST /search/{noun}.
nounYesSearch noun — e.g. "observations", "calls", "germplasm".
aliasNoConnection alias. Omit to use alias `default`. An alias registered via brapi_connect works, and so does one the server has a URL configured for (a built-in alias, an operator-configured alias, or `default` on a deployment with a default server), which connects on first use. Calls that used a non-default alias must pass that same alias here.
loadLimitNoCap on rows returned inline. Omit for the deployment default. Rows beyond the cap land in a dataframe; query with brapi_dataframe_query (SQL) instead of paging row-by-row.

Output Schema

NameRequiredDescriptionDefault
capNoEffective loadLimit row ceiling, even when the byte budget binds first.
kindNoWhether the server returned inline results or we polled an async search.
nounNoThe `/search/{noun}` segment the body was posted to.
aliasNoConnection alias the call used.
errorNoPresent when the call failed. Absent on success.
shownNoActual list rows returned inline.
noticeNoWhen a dataframe was staged, its name and the tools that read it.
resultNoRaw BrAPI `result` value — whatever shape the endpoint returns.
metadataNoBrAPI envelope metadata (pagination and any additional upstream fields).
warningsNoAdvisory messages — present when the dataframe walk stopped before the upstream total.
dataframeNoEvery fetched row of a list result, staged when the inline preview omits rows. Explicit paging stages only the requested page.
truncatedNoTrue when the inline list leaves fetched or matching rows out.
suggestionNoEmitted when a curated goal-shaped tool covers this search, or takes the IDs it lists.
searchResultsDbIdNoPopulated when the server returned an async searchResultsDbId.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `upstream_not_found`: An uncaught BrAPI data request answered HTTP 404. `upstream_rate_limited`: An uncaught BrAPI data request exhausted retries after HTTP 429. `unknown_alias`: No connection is registered under the requested alias, and the server has no base URL configured for it to connect on first use. `auth_token_exchange_failed`: Connecting the alias on first use, the SGN or OAuth token exchange against the BrAPI /token endpoint failed. `auth_no_access_token`: Connecting the alias on first use, the token endpoint answered without returning an access token. `capability_discovery_unavailable`: Neither /serverinfo nor /calls listed any call, and at least one of them timed out, was unreachable, or answered 429 or a 5xx other than 501, so nothing was cached. `upstream_unauthorized`: The BrAPI server answered HTTP 401: it requires credentials, or rejected the ones sent. `upstream_forbidden`: The BrAPI server answered HTTP 403: the credentials sent, or their absence, lack access. `alias_base_url_invalid`: The base URL configured on the server for this alias is not an absolute http(s) URL, or carries credentials. `private_address_blocked`: The base URL configured for this alias, or its token URL, is on a private or reserved address this server may not reach. `search_endpoint_disabled`: The active dialect declares this POST /search/{noun} route as known-dead on this server. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `upstream_not_found`: An uncaught BrAPI data request answered HTTP 404. `upstream_rate_limited`: An uncaught BrAPI data request exhausted retries after HTTP 429. `unknown_alias`: No connection is registered under the requested alias, and the server has no base URL configured for it to connect on first use. `auth_token_exchange_failed`: Connecting the alias on first use, the SGN or OAuth token exchange against the BrAPI /token endpoint failed. `auth_no_access_token`: Connecting the alias on first use, the token endpoint answered without returning an access token. `capability_discovery_not_found`: Both /serverinfo and /calls return HTTP 404. `capability_discovery_unavailable`: Neither /serverinfo nor /calls listed any call, and at least one of them timed out, was unreachable, or answered 429 or a 5xx other than 501, so nothing was cached. `upstream_unauthorized`: The BrAPI server answered HTTP 401: it requires credentials, or rejected the ones sent. `upstream_forbidden`: The BrAPI server answered HTTP 403: the credentials sent, or their absence, lack access. `alias_base_url_invalid`: The base URL configured on the server for this alias is not an absolute http(s) URL, or carries credentials. `private_address_blocked`: The base URL configured for this alias, or its token URL, is on a private or reserved address this server may not reach. `search_endpoint_disabled`: The active dialect declares this POST /search/{noun} route as known-dead on this server. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
      -  "upstream_not_found",
      -  "upstream_rate_limited",
      -  "unknown_alias",
      -  "auth_token_exchange_failed",
      -  "auth_no_access_token",
      -  "capability_discovery_unavailable",
      -  "upstream_unauthorized",
      -  "upstream_forbidden",
      -  "alias_base_url_invalid",
      -  "private_address_blocked",
      -  "search_endpoint_disabled"
      -]New value: +[
      +  "upstream_not_found",
      +  "upstream_rate_limited",
      +  "unknown_alias",
      +  "auth_token_exchange_failed",
      +  "auth_no_access_token",
      +  "capability_discovery_not_found",
      +  "capability_discovery_unavailable",
      +  "upstream_unauthorized",
      +  "upstream_forbidden",
      +  "alias_base_url_invalid",
      +  "private_address_blocked",
      +  "search_endpoint_disabled"
      +]
  2. Changed4 schema fields changed
    • changedOutput schema / properties / dataframe / properties / columnLegend / description
      Previous value: -"Sanitized column name → original upstream key, present only when a column was renamed to be SQL-safe (e.g. `end` → `end_`). SQL uses the sanitized names."New value: +"SQL-safe name → original upstream key for renamed columns. Use the safe names in SQL."
    • changedOutput schema / properties / dataframe / properties / expiresAt / description
      Previous value: -"ISO 8601 time the dataframe metadata is purged; copy rows out before, or re-run the producing tool."New value: +"ISO 8601 expiry of this dataframe’s provenance metadata."
    • changedOutput schema / properties / dataframe / properties / totalCount / description
      Previous value: -"Upstream-reported row total, when known; can exceed rowCount."New value: +"Matched total for complete local scans; else upstream total. Omitted for incomplete local scans or unknown totals."
    • changedOutput schema / properties / dataframe / properties / truncated / description
      Previous value: -"True when the dataframe holds less than the upstream reports: a cap, failed page, deadline, or short upstream ended the pull, or it was skipped. warnings says which. Absent otherwise."New value: +"True for a capped, failed, timed-out, incomplete, or skipped pull; warnings explains why."
  3. Changed2 schema fields changed
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `unknown_alias`: No connection is registered under the requested alias, and the server has no base URL configured for it to connect on first use. `auth_token_exchange_failed`: Connecting the alias on first use, the SGN or OAuth token exchange against the BrAPI /token endpoint failed. `auth_no_access_token`: Connecting the alias on first use, the token endpoint answered without returning an access token. `capability_discovery_unavailable`: Neither /serverinfo nor /calls listed any call, and at least one of them timed out, was unreachable, or answered 429 or a 5xx other than 501, so nothing was cached. `upstream_unauthorized`: The BrAPI server answered HTTP 401: it requires credentials, or rejected the ones sent. `upstream_forbidden`: The BrAPI server answered HTTP 403: the credentials sent, or their absence, lack access. `alias_base_url_invalid`: The base URL configured on the server for this alias is not an absolute http(s) URL, or carries credentials. `private_address_blocked`: The base URL configured for this alias, or its token URL, is on a private or reserved address this server may not reach. `search_endpoint_disabled`: The active dialect declares this POST /search/{noun} route as known-dead on this server. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `upstream_not_found`: An uncaught BrAPI data request answered HTTP 404. `upstream_rate_limited`: An uncaught BrAPI data request exhausted retries after HTTP 429. `unknown_alias`: No connection is registered under the requested alias, and the server has no base URL configured for it to connect on first use. `auth_token_exchange_failed`: Connecting the alias on first use, the SGN or OAuth token exchange against the BrAPI /token endpoint failed. `auth_no_access_token`: Connecting the alias on first use, the token endpoint answered without returning an access token. `capability_discovery_unavailable`: Neither /serverinfo nor /calls listed any call, and at least one of them timed out, was unreachable, or answered 429 or a 5xx other than 501, so nothing was cached. `upstream_unauthorized`: The BrAPI server answered HTTP 401: it requires credentials, or rejected the ones sent. `upstream_forbidden`: The BrAPI server answered HTTP 403: the credentials sent, or their absence, lack access. `alias_base_url_invalid`: The base URL configured on the server for this alias is not an absolute http(s) URL, or carries credentials. `private_address_blocked`: The base URL configured for this alias, or its token URL, is on a private or reserved address this server may not reach. `search_endpoint_disabled`: The active dialect declares this POST /search/{noun} route as known-dead on this server. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
      -  "unknown_alias",
      -  "auth_token_exchange_failed",
      -  "auth_no_access_token",
      -  "capability_discovery_unavailable",
      -  "upstream_unauthorized",
      -  "upstream_forbidden",
      -  "alias_base_url_invalid",
      -  "private_address_blocked",
      -  "search_endpoint_disabled"
      -]New value: +[
      +  "upstream_not_found",
      +  "upstream_rate_limited",
      +  "unknown_alias",
      +  "auth_token_exchange_failed",
      +  "auth_no_access_token",
      +  "capability_discovery_unavailable",
      +  "upstream_unauthorized",
      +  "upstream_forbidden",
      +  "alias_base_url_invalid",
      +  "private_address_blocked",
      +  "search_endpoint_disabled"
      +]
  4. Changed9 schema fields changed
    • addedOutput schema / properties / cap
      Added value: +{
      +  "description": "Effective loadLimit row ceiling, even when the byte budget binds first.",
      +  "exclusiveMinimum": 0,
      +  "maximum": 9007199254740991,
      +  "type": "integer"
      +}
    • changedOutput schema / properties / dataframe / description
      Previous value: -"Every fetched page of a list-shaped result, inline rows included, staged when the upstream advertised more rows than `loadLimit`. The inline `result` is unchanged."New value: +"Every fetched row of a list result, staged when the inline preview omits rows. Explicit paging stages only the requested page."
    • changedOutput schema / properties / metadata / properties / pagination / properties / currentPage / description
      Previous value: -"0-indexed page number the server returned."New value: +"0-indexed page number, when reported."
    • changedOutput schema / properties / metadata / properties / pagination / properties / pageSize / description
      Previous value: -"Rows per page."New value: +"Rows per page, when reported."
    • changedOutput schema / properties / metadata / properties / pagination / properties / totalCount / description
      Previous value: -"Total rows matching the query across all pages."New value: +"Total matching rows, when reported."
    • changedOutput schema / properties / metadata / properties / pagination / properties / totalPages / description
      Previous value: -"Total pages at the current pageSize."New value: +"Total pages, when reported."
    • removedOutput schema / properties / metadata / properties / pagination / required
      Removed value: -[
      -  "currentPage",
      -  "pageSize",
      -  "totalCount",
      -  "totalPages"
      -]
    • addedOutput schema / properties / shown
      Added value: +{
      +  "description": "Actual list rows returned inline.",
      +  "maximum": 9007199254740991,
      +  "minimum": 0,
      +  "type": "integer"
      +}
    • addedOutput schema / properties / truncated
      Added value: +{
      +  "description": "True when the inline list leaves fetched or matching rows out.",
      +  "type": "boolean"
      +}
  5. Changed18 schema fields changed
    • changedInput schema / properties / alias / description
      Previous value: -"Connection alias registered via brapi_connect. Omit to read the connection registered under alias `default` — i.e. a prior brapi_connect call that did not specify an alias. Calls that used a non-default alias must pass that same alias here."New value: +"Connection alias. Omit to use alias `default`. An alias registered via brapi_connect works, and so does one the server has a URL configured for (a built-in alias, an operator-configured alias, or `default` on a deployment with a default server), which connects on first use. Calls that used a non-default alias must pass that same alias here."
    • changedOutput schema / properties / alias / description
      Previous value: -"Alias of the registered BrAPI connection the call used."New value: +"Connection alias the call used."
    • changedOutput schema / properties / dataframe / description
      Previous value: -"Present when the upstream advertised more rows than `loadLimit` AND the result is a list shape. The inline `result` is unchanged; the dataframe carries the full union of pages — query with brapi_dataframe_query."New value: +"Every fetched page of a list-shaped result, inline rows included, staged when the upstream advertised more rows than `loadLimit`. The inline `result` is unchanged."
    • changedOutput schema / properties / dataframe / properties / columnLegend / description
      Previous value: -"Maps a sanitized column name back to its original upstream key, for columns renamed to clear the SQL-safe-identifier gate (e.g. `end` → `end_`). Present only when a column was renamed — write SQL against the sanitized (left-hand) names."New value: +"Sanitized column name → original upstream key, present only when a column was renamed to be SQL-safe (e.g. `end` → `end_`). SQL uses the sanitized names."
    • changedOutput schema / properties / dataframe / properties / columns / description
      Previous value: -"Full column list of the dataframe."New value: +"Every column name."
    • changedOutput schema / properties / dataframe / properties / columns / items / description
      Previous value: -"Column name from the materialized rows."New value: +"Column name."
    • changedOutput schema / properties / dataframe / properties / createdAt / description
      Previous value: -"ISO 8601 timestamp the dataframe was created."New value: +"ISO 8601 creation time."
    • changedOutput schema / properties / dataframe / properties / expiresAt / description
      Previous value: -"ISO 8601 timestamp after which the dataframe metadata will be purged. Re-run the find_* tool to refresh, or copy results out before expiry."New value: +"ISO 8601 time the dataframe metadata is purged; copy rows out before, or re-run the producing tool."
    • changedOutput schema / properties / dataframe / properties / maxRows / description
      Previous value: -"Cap that was applied at create time, when truncation occurred."New value: +"Row cap that ended the pull, present only when that cap fired."
    • changedOutput schema / properties / dataframe / properties / rowCount / description
      Previous value: -"Number of rows materialized in the dataframe."New value: +"Rows in the dataframe."
    • changedOutput schema / properties / dataframe / properties / tableName / description
      Previous value: -"Dataframe name. Use with brapi_dataframe_describe (schema + provenance) and brapi_dataframe_query (SQL)."New value: +"Table name for brapi_dataframe_describe and brapi_dataframe_query."
    • changedOutput schema / properties / dataframe / properties / totalCount / description
      Previous value: -"Total rows reported by the upstream server (may exceed rowCount when truncated)."New value: +"Upstream-reported row total, when known; can exceed rowCount."
    • changedOutput schema / properties / dataframe / properties / truncated / description
      Previous value: -"True when the dataframe hit a row cap before exhausting upstream."New value: +"True when the dataframe holds less than the upstream reports: a cap, failed page, deadline, or short upstream ended the pull, or it was skipped. warnings says which. Absent otherwise."
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `unknown_alias`: No connection has been registered under the requested alias. `search_endpoint_disabled`: The active dialect declares this POST /search/{noun} route as known-dead on this server. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `unknown_alias`: No connection is registered under the requested alias, and the server has no base URL configured for it to connect on first use. `auth_token_exchange_failed`: Connecting the alias on first use, the SGN or OAuth token exchange against the BrAPI /token endpoint failed. `auth_no_access_token`: Connecting the alias on first use, the token endpoint answered without returning an access token. `capability_discovery_unavailable`: Neither /serverinfo nor /calls listed any call, and at least one of them timed out, was unreachable, or answered 429 or a 5xx other than 501, so nothing was cached. `upstream_unauthorized`: The BrAPI server answered HTTP 401: it requires credentials, or rejected the ones sent. `upstream_forbidden`: The BrAPI server answered HTTP 403: the credentials sent, or their absence, lack access. `alias_base_url_invalid`: The base URL configured on the server for this alias is not an absolute http(s) URL, or carries credentials. `private_address_blocked`: The base URL configured for this alias, or its token URL, is on a private or reserved address this server may not reach. `search_endpoint_disabled`: The active dialect declares this POST /search/{noun} route as known-dead on this server. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
      -  "unknown_alias",
      -  "search_endpoint_disabled"
      -]New value: +[
      +  "unknown_alias",
      +  "auth_token_exchange_failed",
      +  "auth_no_access_token",
      +  "capability_discovery_unavailable",
      +  "upstream_unauthorized",
      +  "upstream_forbidden",
      +  "alias_base_url_invalid",
      +  "private_address_blocked",
      +  "search_endpoint_disabled"
      +]
    • addedOutput schema / properties / notice
      Added value: +{
      +  "description": "When a dataframe was staged, its name and the tools that read it.",
      +  "type": "string"
      +}
    • changedOutput schema / properties / suggestion / description
      Previous value: -"Emitted when a curated goal-shaped tool covers this search."New value: +"Emitted when a curated goal-shaped tool covers this search, or takes the IDs it lists."
    • addedOutput schema / properties / warnings
      Added value: +{
      +  "description": "Advisory messages — present when the dataframe walk stopped before the upstream total.",
      +  "items": {
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
  6. First observed

TDQS

A3.9/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare readOnlyHint and openWorldHint, and the description adds substantial behavior beyond that: async search-ID polling, loadLimit mapped to initial pageSize, a 24,000-byte per-row budget, the edge case where an oversized first row yields no inline rows, and staging of trimmed pages. It stops short of describing error or auth behavior, but the operational profile is unusually well disclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core identity, then paging, then budget, then dataframe fallback — a logical order with no filler sentences. It is dense and jargon-heavy ('serialized row representation', 'envelope siblings'), which costs some readability but not correctness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a raw passthrough with async polling, nested body, and an output schema already covering return shape, the description covers everything an agent needs: paging semantics, inline row limits, the dataframe escape hatch, and what is deliberately not resolved. Nothing material is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description genuinely adds meaning: loadLimit is applied as the initial pageSize only when body.page/pageSize does not drive explicit paging, and body is passed verbatim. That interaction between two parameters is not derivable from the schema alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource: a passthrough to BrAPI POST /search/{noun} with async polling. It implicitly separates itself from brapi_raw_get (POST vs GET) and from typed finders by noting 'no distributions or foreign-key resolution', but it never names a sibling outright, so an agent must infer the boundary.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives one clear routing rule — rows beyond loadLimit go to a dataframe, so use brapi_dataframe_query instead of paging row-by-row — and explains when explicit paging kicks in. It never states when to prefer this raw passthrough over the typed brapi_find_* tools, which is the main selection decision an agent faces.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.