Skip to main content
Glama

Brapi Find Variables

brapi_find_variables
Read-only

Find observation variables (traits) by name, trait class, ontology term, or free-text query. Free-text queries are ranked against every fetched row by PUI, name, synonym, and trait text; every match leads results[] with its textMatchRank, and a candidate carries the ontology PUI of its row as termId when the row has one. results[] holds the leading rows 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_variables"
  }
}

Input Schema

NameRequiredDescriptionDefault
cropNoFilter by common crop name (single value).
textNoFree-text query. Ranks **every row the call fetched** (the whole dataframe walk, not just the first page) via the ontology resolver: each match carries textMatchRank in results[] and the dataframe, textMatchCount counts them, and results[] — up to loadLimit and the 24,000-byte budget — lists every match first in rank order, then unmatched rows for context. Use exact filters (`variables`, `variableNames`, `variablePUIs`, `traitClasses`, `ontologies`) to actually narrow the upstream pull. Differs from `brapi_find_germplasm.text`, which drops unmatched rows.
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.
scalesNoFilter by scaleDbIds.
methodsNoFilter by methodDbIds.
studiesNoFilter by studyDbId. Multiple distinct studies are collected under shared page, row and time budgets and unioned by variable ID with studyDbIds provenance; studyCoverage reports incomplete studies.
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.
variablesNoFilter by observationVariableDbIds.
ontologiesNoFilter by ontologyDbIds.
extraFiltersNoExtra BrAPI filters forwarded verbatim. Valid keys vary by endpoint; brapi_describe_filters enumerates them. Named params on this tool take precedence on conflict.
traitClassesNoFilter by trait class.
variablePUIsNoFilter by persistent ontology URIs.
variableNamesNoFilter by exact observationVariableNames.

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 variables, capped by loadLimit and 24,000 bytes. Text matches lead by textMatchRank; nested objects with no non-empty field are omitted.
warningsNoAdvisory messages (filter overrides, partial data, capability gaps).
dataframeNoMatched rows, staged when results[] holds fewer.
truncatedNoTrue when results[] holds fewer rows than matched because loadLimit or the inline byte budget bound.
totalCountNoTotal rows reported by the server, else the rows scanned.
distributionsNoValue frequency per field across every matched row fetched.
returnedCountNoLength of results[].
studyCoverageNoMulti-study coverage; incomplete studies may omit variables.
appliedFiltersNoFilter map sent upstream (named filters plus extraFilters).
refinementHintNoSuggested refinement when the result set is large.
textMatchCountNoFetched rows the free text matched (a partial scan counts fetched rows only); absent without text.
ontologyCandidatesNoTop 10 text matches by textMatchRank; empty without text.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed11 schema fields changed
    • changedInput schema / properties / text / description
      Previous value: -"Free-text query. Ranks **every row the call fetched** (the whole dataframe walk, not just the first page) via the ontology resolver, then fills results[] — up to loadLimit and the 24,000-byte budget — with matches first and unmatched rows for context. Use exact filters (`variables`, `variableNames`, `variablePUIs`, `traitClasses`, `ontologies`) to actually narrow the upstream pull. Differs from `brapi_find_germplasm.text`, which drops unmatched rows."New value: +"Free-text query. Ranks **every row the call fetched** (the whole dataframe walk, not just the first page) via the ontology resolver: each match carries textMatchRank in results[] and the dataframe, textMatchCount counts them, and results[] — up to loadLimit and the 24,000-byte budget — lists every match first in rank order, then unmatched rows for context. Use exact filters (`variables`, `variableNames`, `variablePUIs`, `traitClasses`, `ontologies`) to actually narrow the upstream pull. Differs from `brapi_find_germplasm.text`, which drops unmatched rows."
    • changedOutput schema / properties / ontologyCandidates / description
      Previous value: -"Ranked free-text candidates; empty without text."New value: +"Top 10 text matches by textMatchRank; empty without text."
    • changedOutput schema / properties / ontologyCandidates / items / properties / observationVariableDbId / description
      Previous value: -"Server-side variable DbId of the source row, when present."New value: +"Variable DbId of the source row."
    • changedOutput schema / properties / ontologyCandidates / items / properties / source / description
      Previous value: -"How the candidate was ranked — PUI exact / name / synonym / trait-class."New value: +"Which field the text matched."
    • changedOutput schema / properties / results / description
      Previous value: -"Leading variables, capped by loadLimit and 24,000 bytes. Text candidates lead; nested objects with no non-empty field are omitted."New value: +"Leading variables, capped by loadLimit and 24,000 bytes. Text matches lead by textMatchRank; nested objects with no non-empty field are omitted."
    • changedOutput schema / properties / results / items / properties / commonCropName / description
      Previous value: -"Common crop name this variable is scoped to."New value: +"Common crop name."
    • changedOutput schema / properties / results / items / properties / method / description
      Previous value: -"Measurement method or protocol used to collect this variable."New value: +"Measurement method or protocol."
    • changedOutput schema / properties / results / items / properties / observationVariablePUI / description
      Previous value: -"Persistent unique identifier — typically an ontology term URI."New value: +"Persistent ID, typically an ontology term URI."
    • changedOutput schema / properties / results / items / properties / scale / description
      Previous value: -"Scale used to record this variable (units / type / range)."New value: +"Measurement scale (units, type, range)."
    • addedOutput schema / properties / results / items / properties / textMatchRank
      Added value: +{
      +  "description": "Free-text rank among fetched rows, from 1; absent on unmatched rows.",
      +  "exclusiveMinimum": 0,
      +  "maximum": 9007199254740991,
      +  "type": "integer"
      +}
    • addedOutput schema / properties / textMatchCount
      Added value: +{
      +  "description": "Fetched rows the free text matched (a partial scan counts fetched rows only); absent without text.",
      +  "maximum": 9007199254740991,
      +  "minimum": 0,
      +  "type": "integer"
      +}
  2. 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"
      +]
  3. 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."
  4. Changed8 schema fields changed
    • changedInput schema / properties / studies / description
      Previous value: -"Filter by studyDbId. /variables takes one, so only the first value is sent."New value: +"Filter by studyDbId. Multiple distinct studies are collected under shared page, row and time budgets and unioned by variable ID with studyDbIds provenance; studyCoverage reports incomplete studies."
    • changedOutput schema / properties / dataframe / description
      Previous value: -"The matched rows, staged as a dataframe when results[] holds fewer."New value: +"Matched rows, staged when results[] holds fewer."
    • 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"
      +]
    • changedOutput schema / properties / ontologyCandidates / description
      Previous value: -"Top ranked candidates from the free-text query (if any). Empty when `text` was not supplied."New value: +"Ranked free-text candidates; empty without text."
    • changedOutput schema / properties / results / description
      Previous value: -"Leading observation variable rows, up to loadLimit and a 24,000-byte budget, whichever binds first. Rows matching `text` are promoted to the top when the free-text query produces candidates; nested objects with no non-empty field are omitted."New value: +"Leading variables, capped by loadLimit and 24,000 bytes. Text candidates lead; nested objects with no non-empty field are omitted."
    • addedOutput schema / properties / results / items / properties / studyDbIds
      Added value: +{
      +  "anyOf": [
      +    {
      +      "items": {
      +        "description": "Study ID.",
      +        "type": "string"
      +      },
      +      "type": "array"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "description": "Requested studies containing this union row."
      +}
    • addedOutput schema / properties / studyCoverage
      Added value: +{
      +  "description": "Multi-study coverage; incomplete studies may omit variables.",
      +  "items": {
      +    "additionalProperties": false,
      +    "description": "One study.",
      +    "properties": {
      +      "id": {
      +        "description": "Requested study ID.",
      +        "type": "string"
      +      },
      +      "pagesFetched": {
      +        "description": "Successful pages.",
      +        "maximum": 9007199254740991,
      +        "minimum": 0,
      +        "type": "integer"
      +      },
      +      "reason": {
      +        "description": "Stop/failure reason.",
      +        "type": "string"
      +      },
      +      "rowsScanned": {
      +        "description": "Rows examined.",
      +        "maximum": 9007199254740991,
      +        "minimum": 0,
      +        "type": "integer"
      +      },
      +      "status": {
      +        "description": "Scan outcome.",
      +        "enum": [
      +          "complete",
      +          "partial",
      +          "failed",
      +          "unprocessed"
      +        ],
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "id",
      +      "status",
      +      "rowsScanned",
      +      "pagesFetched"
      +    ],
      +    "type": "object"
      +  },
      +  "type": "array"
      +}
  5. Changed37 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."
    • addedInput schema / properties / crop / pattern
      Added value: +"\\S"
    • 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 / methods / items / pattern
      Added value: +"\\S"
    • addedInput schema / properties / ontologies / items / pattern
      Added value: +"\\S"
    • addedInput schema / properties / scales / items / pattern
      Added value: +"\\S"
    • changedInput schema / properties / studies / description
      Previous value: -"Filter by studyDbIds."New value: +"Filter by studyDbId. /variables takes one, so only the first value is sent."
    • addedInput schema / properties / studies / items / pattern
      Added value: +"\\S"
    • changedInput schema / properties / text / description
      Previous value: -"Free-text query. Ranks the **full upstream union** (the spilled dataframe when one is produced, otherwise the first page) via the ontology resolver, then fills the in-context window up to loadLimit with matches first and unmatched rows for context. Use exact filters (`variables`, `variableNames`, `variablePUIs`, `traitClasses`, `ontologies`) to actually narrow the upstream pull. Differs from `brapi_find_germplasm.text`, which drops unmatched rows."New value: +"Free-text query. Ranks **every row the call fetched** (the whole dataframe walk, not just the first page) via the ontology resolver, then fills results[] — up to loadLimit and the 24,000-byte budget — with matches first and unmatched rows for context. Use exact filters (`variables`, `variableNames`, `variablePUIs`, `traitClasses`, `ontologies`) to actually narrow the upstream pull. Differs from `brapi_find_germplasm.text`, which drops unmatched rows."
    • addedInput schema / properties / text / pattern
      Added value: +"^$|\\S"
    • addedInput schema / properties / traitClasses / items / pattern
      Added value: +"\\S"
    • addedInput schema / properties / variableNames / items / pattern
      Added value: +"\\S"
    • addedInput schema / properties / variablePUIs / items / pattern
      Added value: +"\\S"
    • addedInput schema / properties / variables / 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: -"Observation variable rows returned in-context (up to loadLimit). Rows matching `text` are promoted to the top when the free-text query produces candidates."New value: +"Leading observation variable rows, up to loadLimit and a 24,000-byte budget, whichever binds first. Rows matching `text` are promoted to the top when the free-text query produces candidates; nested objects with no non-empty field are omitted."
    • 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"
      +}
  6. First observed

TDQS

A4.1/5.0
Behavior5/5

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

Annotations only declare readOnlyHint and openWorldHint; the description goes well beyond them by disclosing ranking behavior (PUI, name, synonym, trait text), the textMatchRank/termId fields, the loadLimit plus 24,000-byte budget, and the fallback where the matched set is materialized as a dataframe. These are non-obvious consequences an agent could not infer from annotations or schema.

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?

Purpose is front-loaded in one line, followed by two dense sentences on ranking and on result budgeting/staging. The em-dash clause in the final sentence is long but every element (budget, truncation, dataframe handoff) is load-bearing.

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 13-parameter, zero-required tool with nested extraFilters and an output schema, the description covers the behaviors an output schema cannot: ranking semantics, inline-vs-dataframe split, and the follow-up tools to use. Nothing needed to invoke it correctly 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 baseline is 3. The description does clarify that free-text ranking applies to every fetched row rather than a single page and how loadLimit interacts with the byte budget, but the per-parameter meaning of text, studies, alias, and extraFilters is carried by the schema.

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 gives a specific verb and resource ("Find observation variables (traits)") plus the four query axes: name, trait class, ontology term, free-text. It does not name a sibling it is not (e.g. brapi_find_observations) inside the description, so differentiation from other find_* tools rests on the resource noun alone.

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

Usage Guidelines4/5

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

The description explains what free-text search does and routes the agent to brapi_dataframe_describe and brapi_dataframe_query with SQL when results[] is truncated, which is a concrete condition-action handoff. It stops short of stating when to prefer this tool over sibling find tools or when to prefer exact filters over text, so guidance is clear but incomplete.

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.