Skip to main content
Glama

Brapi Find Variants

brapi_find_variants
Read-only

Find variant records by variant set, reference sequence, or genomic region. Named reference and region filters are verified on each scanned row using exact reference names and overlap with the 0-based half-open window [start, end). results[] holds the leading matches up to loadLimit and a 24,000-byte budget; when it holds fewer rows than matched, the matched set is materialized as a dataframe — read it with brapi_dataframe_describe and brapi_dataframe_query (SQL).

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "brapi_find_variants"
  }
}

Input Schema

NameRequiredDescriptionDefault
endNoWindow end, 0-based exclusive.
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.
startNoWindow start, 0-based inclusive.
variantsNoFilter by variantDbIds.
loadLimitNoCap on rows returned inline in results[]. Omit for the deployment default. results[] also stops at a 24,000-byte budget, whichever bound comes first, and keeps at least one row when any matched. When results[] holds fewer rows than matched, the matched rows are staged in a dataframe (marked truncated if the upstream walk stopped short); query it with brapi_dataframe_query (SQL) instead of paging row-by-row.
referencesNoFilter by referenceDbIds.
variantSetsNoFilter by variantSetDbIds.
extraFiltersNoExtra BrAPI filters forwarded verbatim. Valid keys vary by endpoint; brapi_describe_filters enumerates them. Named params on this tool take precedence on conflict.
referenceNameNoReference display name (e.g. "chr01", "chr1").

Output Schema

NameRequiredDescriptionDefault
capNoThe effective loadLimit when truncated; shown is below it when the 24,000-byte inline budget bound first (notice says which).
aliasNoConnection alias the call used.
errorNoPresent when the call failed. Absent on success.
shownNoLength of results[] when truncated.
noticeNoWhy results[] is empty, or which bound cut it short and the dataframe holding the matched rows.
hasMoreNoTrue when more rows exist beyond the returned set.
resultsNoLeading matched variant rows, up to loadLimit and a 24,000-byte budget, whichever binds first.
warningsNoAdvisory messages (filter overrides, partial data, capability gaps).
dataframeNoThe matched rows, staged as a dataframe when results[] holds fewer.
truncatedNoTrue when results[] holds fewer rows than matched because loadLimit or the inline byte budget bound.
totalCountNoVerified matches among scanned rows when a named reference or window is set, else the upstream total or rows scanned.
distributionsNoValue frequency per field across every matched row fetched.
returnedCountNoLength of results[].
appliedFiltersNoFilter map sent upstream (named filters plus extraFilters).
refinementHintNoSuggested refinement when the result set is large.
upstreamTotalCountNoUpstream row count before local region verification, when reported.

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. `missing_find_route`: Neither the GET list nor a usable POST search route is advertised. `search_endpoint_disabled`: Only a POST search route marked unusable by the active dialect is advertised. `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. `all_filters_dropped`: The active dialect dropped every filter the agent supplied — the upstream server does not honor any of the requested scope filters on this endpoint, so the call would silently widen to the unfiltered baseline. 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. `missing_find_route`: Neither the GET list nor a usable POST search route is advertised. `search_endpoint_disabled`: Only a POST search route marked unusable by the active dialect is advertised. `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. `all_filters_dropped`: The active dialect dropped every filter the agent supplied — the upstream server does not honor any of the requested scope filters on this endpoint, so the call would silently widen to the unfiltered baseline. 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",
      -  "missing_find_route",
      -  "search_endpoint_disabled",
      -  "unknown_alias",
      -  "auth_token_exchange_failed",
      -  "auth_no_access_token",
      -  "capability_discovery_unavailable",
      -  "upstream_unauthorized",
      -  "upstream_forbidden",
      -  "alias_base_url_invalid",
      -  "private_address_blocked",
      -  "all_filters_dropped"
      -]New value: +[
      +  "upstream_not_found",
      +  "upstream_rate_limited",
      +  "missing_find_route",
      +  "search_endpoint_disabled",
      +  "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",
      +  "all_filters_dropped"
      +]
  2. Changed8 schema fields changed
    • removedInput schema / properties / end / exclusiveMinimum
      Removed value: -0
    • addedInput schema / properties / end / minimum
      Added value: +0
    • 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."
    • changedOutput schema / properties / totalCount / description
      Previous value: -"Total rows reported by the server, else the rows scanned."New value: +"Verified matches among scanned rows when a named reference or window is set, else the upstream total or rows scanned."
    • addedOutput schema / properties / upstreamTotalCount
      Added value: +{
      +  "description": "Upstream row count before local region verification, when reported.",
      +  "maximum": 9007199254740991,
      +  "minimum": 0,
      +  "type": "integer"
      +}
  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. `all_filters_dropped`: The active dialect dropped every filter the agent supplied — the upstream server does not honor any of the requested scope filters on this endpoint, so the call would silently widen to the unfiltered baseline. 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. `missing_find_route`: Neither the GET list nor a usable POST search route is advertised. `search_endpoint_disabled`: Only a POST search route marked unusable by the active dialect is advertised. `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. `all_filters_dropped`: The active dialect dropped every filter the agent supplied — the upstream server does not honor any of the requested scope filters on this endpoint, so the call would silently widen to the unfiltered baseline. 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",
      -  "all_filters_dropped"
      -]New value: +[
      +  "upstream_not_found",
      +  "upstream_rate_limited",
      +  "missing_find_route",
      +  "search_endpoint_disabled",
      +  "unknown_alias",
      +  "auth_token_exchange_failed",
      +  "auth_no_access_token",
      +  "capability_discovery_unavailable",
      +  "upstream_unauthorized",
      +  "upstream_forbidden",
      +  "alias_base_url_invalid",
      +  "private_address_blocked",
      +  "all_filters_dropped"
      +]
  4. Changed33 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."
    • changedInput schema / properties / end / description
      Previous value: -"Exclusive 1-based end."New value: +"Window end, 0-based exclusive."
    • changedInput schema / properties / loadLimit / description
      Previous value: -"Cap 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."New value: +"Cap on rows returned inline in results[]. Omit for the deployment default. results[] also stops at a 24,000-byte budget, whichever bound comes first, and keeps at least one row when any matched. When results[] holds fewer rows than matched, the matched rows are staged in a dataframe (marked truncated if the upstream walk stopped short); query it with brapi_dataframe_query (SQL) instead of paging row-by-row."
    • addedInput schema / properties / referenceName / pattern
      Added value: +"\\S"
    • addedInput schema / properties / references / items / pattern
      Added value: +"\\S"
    • changedInput schema / properties / start / description
      Previous value: -"Inclusive 1-based start."New value: +"Window start, 0-based inclusive."
    • addedInput schema / properties / variantSets / items / pattern
      Added value: +"\\S"
    • addedInput schema / properties / variants / items / pattern
      Added value: +"\\S"
    • 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 / appliedFilters / description
      Previous value: -"The final filter map sent to the server (named + extraFilters)."New value: +"Filter map sent upstream (named filters plus extraFilters)."
    • addedOutput schema / properties / cap
      Added value: +{
      +  "description": "The effective loadLimit when truncated; shown is below it when the 24,000-byte inline budget bound first (notice says which).",
      +  "exclusiveMinimum": 0,
      +  "maximum": 9007199254740991,
      +  "type": "integer"
      +}
    • changedOutput schema / properties / dataframe / description
      Previous value: -"Dataframe handle when the full result set was materialized as a dataframe. Query it with brapi_dataframe_query (SQL)."New value: +"The matched rows, staged as a dataframe when results[] holds fewer."
    • 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 / distributions / description
      Previous value: -"Value frequency per field across the full result set."New value: +"Value frequency per field across every matched row fetched."
    • 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. `all_filters_dropped`: The active dialect dropped every filter the agent supplied — the upstream server does not honor any of the requested scope filters on this endpoint, so the call would silently widen to the unfiltered baseline. 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. `all_filters_dropped`: The active dialect dropped every filter the agent supplied — the upstream server does not honor any of the requested scope filters on this endpoint, so the call would silently widen to the unfiltered baseline. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
      -  "unknown_alias",
      -  "all_filters_dropped"
      -]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",
      +  "all_filters_dropped"
      +]
    • changedOutput schema / properties / notice / description
      Previous value: -"Guidance when no rows were returned — how to broaden filters or retry."New value: +"Why results[] is empty, or which bound cut it short and the dataframe holding the matched rows."
    • changedOutput schema / properties / refinementHint / description
      Previous value: -"Suggested next-step query refinement when the result set is large."New value: +"Suggested refinement when the result set is large."
    • changedOutput schema / properties / results / description
      Previous value: -"Variant rows returned in-context (up to loadLimit)."New value: +"Leading matched variant rows, up to loadLimit and a 24,000-byte budget, whichever binds first."
    • changedOutput schema / properties / results / items / properties / end / description
      Previous value: -"1-based exclusive end position."New value: +"End position, 0-based exclusive per BrAPI."
    • changedOutput schema / properties / results / items / properties / start / description
      Previous value: -"1-based inclusive start position."New value: +"Start position, 0-based inclusive per BrAPI."
    • addedOutput schema / properties / shown
      Added value: +{
      +  "description": "Length of results[] when truncated.",
      +  "exclusiveMinimum": 0,
      +  "maximum": 9007199254740991,
      +  "type": "integer"
      +}
    • changedOutput schema / properties / totalCount / description
      Previous value: -"Total rows reported by the server."New value: +"Total rows reported by the server, else the rows scanned."
    • addedOutput schema / properties / truncated
      Added value: +{
      +  "description": "True when results[] holds fewer rows than matched because loadLimit or the inline byte budget bound.",
      +  "type": "boolean"
      +}
  5. First observed

TDQS

A3.7/5.0
Behavior4/5

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. Beyond that, the description discloses genuinely non-obvious behavior: named reference/region filters are re-verified row-by-row rather than pushed upstream, results[] is bounded by both loadLimit and a 24,000-byte budget, and overflow is materialized into a dataframe possibly marked truncated. That is real added context the annotations cannot convey.

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?

Two sentences, front-loaded with the core operation before the fallback mechanics. It is dense but every clause carries information; the only mild waste is restating the loadLimit/byte-budget rule that the schema parameter description already spells out.

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

Completeness4/5

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

With an output schema present, return structure need not be explained, yet the description still flags the truncation/overflow path an agent must handle, which is the main failure mode for this tool. Combined with the alias and filter notes in the schema, an agent has enough to call it correctly; only cross-tool selection guidance is missing.

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

Parameters3/5

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

Schema description coverage is 100%, so the baseline is 3. The description clarifies that reference matching uses exact display names and region matching means overlap with the half-open window, which reinforces rather than extends the schema's own wording ('0-based exclusive', '0-based inclusive'). It adds no meaning for the remaining parameters such as extraFilters beyond what the schema states.

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 first sentence names a specific verb ('Find') and resource ('variant records') and enumerates the three filter axes (variant set, reference sequence, genomic region). An agent can tell this apart from a generic raw query. It does not, however, explicitly contrast itself with siblings such as brapi_raw_search or brapi_federated_find, so it stops short of a 5.

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?

The description gives clear follow-up routing once results[] overflows: use brapi_dataframe_describe and brapi_dataframe_query. It gives no guidance on when to choose this tool over sibling lookup paths (e.g. raw_search, federated_find), and no prerequisites beyond the alias notes already in the schema.

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.