Server definition
- Hash
- sha256:5cb4dc794450517e68a47aeaaab9717cf7203c4bb392092d047e17705cca2dec
- What it is
- What a remote MCP server returned when asked what it offers: 22 tools
The blob, as servednamed by its sha256
{
"instructions": "Bridges BrAPI v2 servers (Breeding API for plant/crop research). Call `brapi_connect` first to register a server under an alias and return the orientation envelope (capabilities, dialect, content summary, the finders the server supports). `brapi_find_*` tools page filtered lookups across studies, germplasm, observations, variables, locations, images, variants, and genotype calls; rows beyond the per-call cap spill to a canvas dataframe — query with `brapi_dataframe_query` (SELECT-only SQL). `brapi_get_*` fetch single records by `*DbId`. Use `brapi_raw_get` / `brapi_raw_search` only when no curated tool fits — responses route back to the right curated tool.",
"tools": [
{
"description": "Pull observations across one or more studies and pivot them into a germplasm × trait matrix materialized as a canvas dataframe. Returns a dataframe handle (query with brapi_dataframe_query) plus a summary of dimensions and aggregate method. Long-form output is suitable for downstream GROUP BY analysis by study, germplasm, or variable.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"aggregate": {
"default": "mean",
"description": "How to aggregate replicate observations (multiple readings of the same variable on the same germplasm). `mean` and `median` attempt numeric conversion and skip non-numeric values (e.g. categorical traits). `first` keeps the first value seen. `all` keeps every replicate as a separate row (produces long-form output even when shape is \"wide\"). Default: `mean`.",
"enum": [
"mean",
"median",
"first",
"all"
],
"type": "string"
},
"alias": {
"description": "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.",
"pattern": "^[a-zA-Z0-9_-]+$",
"type": "string"
},
"extraFilters": {
"additionalProperties": {},
"description": "Extra BrAPI filters forwarded verbatim. Valid keys vary by endpoint; brapi_describe_filters enumerates them. Named params on this tool take precedence on conflict.",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"germplasm": {
"description": "Optional subset of germplasmDbIds to include. Omit to include all germplasm found in the queried studies.",
"items": {
"type": "string"
},
"type": "array"
},
"loadLimit": {
"description": "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.",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"type": "integer"
},
"shape": {
"default": "wide",
"description": "Matrix shape. `wide` — one row per germplasm, one column per variable, cell = aggregated value. `long` — one row per observation with columns: germplasmDbId, observationVariableDbId, studyDbId, value, replicateIndex. When `aggregate:\"all\"` is combined with `shape:\"wide\"`, the output falls back to long form with a replicateIndex column.",
"enum": [
"wide",
"long"
],
"type": "string"
},
"studies": {
"description": "studyDbIds to include in the matrix. At least one is required — the tool is study-anchored to avoid full-table scans.",
"items": {
"type": "string"
},
"minItems": 1,
"type": "array"
},
"variables": {
"description": "Optional subset of observationVariableDbIds to include. Omit to include all variables found in the queried studies.",
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"studies"
],
"type": "object"
},
"name": "brapi_build_phenotype_matrix",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"alias",
"studies",
"shape",
"aggregate",
"observationCount",
"germplasmCount",
"variableCount",
"variableLegend",
"warnings"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"aggregate": {
"description": "Aggregation applied to replicate observations (wide shape only). `all` keeps one row per replicate.",
"enum": [
"mean",
"median",
"first",
"all"
],
"type": "string"
},
"alias": {
"description": "Alias of the registered BrAPI connection the call used.",
"type": "string"
},
"cap": {
"description": "Per-study observation cap that was applied.",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"type": "integer"
},
"dataframe": {
"additionalProperties": false,
"description": "Canvas dataframe handle for the materialized matrix. Omitted when no observations were found. Query with brapi_dataframe_query (SQL). Long-form columns: germplasmDbId, observationVariableDbId, studyDbId, value, replicateIndex. Wide-form columns: germplasmDbId, germplasmName, one column per variable (SQL-safe identifier derived from observationVariableDbId — see variableLegend).",
"properties": {
"columnLegend": {
"additionalProperties": {
"type": "string"
},
"description": "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.",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"columns": {
"description": "Full column list of the dataframe.",
"items": {
"description": "Column name from the materialized rows.",
"type": "string"
},
"type": "array"
},
"createdAt": {
"description": "ISO 8601 timestamp the dataframe was created.",
"type": "string"
},
"expiresAt": {
"description": "ISO 8601 timestamp after which the dataframe metadata will be purged. Re-run the find_* tool to refresh, or copy results out before expiry.",
"type": "string"
},
"maxRows": {
"description": "Cap that was applied at create time, when truncation occurred.",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"type": "integer"
},
"rowCount": {
"description": "Number of rows materialized in the dataframe.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"tableName": {
"description": "Dataframe name. Use with brapi_dataframe_describe (schema + provenance) and brapi_dataframe_query (SQL).",
"type": "string"
},
"totalCount": {
"description": "Total rows reported by the upstream server (may exceed rowCount when truncated).",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"truncated": {
"description": "True when the dataframe hit a row cap before exhausting upstream.",
"type": "boolean"
}
},
"required": [
"tableName",
"rowCount",
"columns",
"createdAt",
"expiresAt"
],
"type": "object"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "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 supplied — the call would silently widen to the unfiltered baseline. `no_observation_path`: Neither /observations nor /observationunits returned data for any requested study after probing both paths. Other values are possible when a failure originates below the handler.",
"examples": [
"unknown_alias",
"all_filters_dropped",
"no_observation_path"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"germplasmCount": {
"description": "Number of distinct germplasm in the matrix.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"notice": {
"description": "Guidance for reaching the observations this call left out.",
"type": "string"
},
"observationCount": {
"description": "Total raw observations collected before pivoting.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"shape": {
"description": "Matrix shape — wide (one row per germplasm, one column per variable) or long (one row per observation).",
"enum": [
"wide",
"long"
],
"type": "string"
},
"shown": {
"description": "Observations collected across all studies after filtering.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"studies": {
"description": "studyDbIds that were queried to build the matrix.",
"items": {
"type": "string"
},
"type": "array"
},
"truncated": {
"description": "True when at least one study saturated the per-study loadLimit.",
"type": "boolean"
},
"variableCount": {
"description": "Number of distinct observation variables in the matrix.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"variableLegend": {
"additionalProperties": {
"type": "string"
},
"description": "Mapping of safe column identifier → observationVariableName. Wide-matrix column names are SQL-safe identifiers derived from observationVariableDbId (sanitized for DuckDB); consult this map to resolve a column back to its variable display name.",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"warnings": {
"description": "Advisory messages (empty studies, non-numeric aggregation skips, fallback paths).",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
}
},
{
"description": "Open a connection to a BrAPI v2 server, authenticate, and return the full orientation envelope (server identity, capability profile, content summary, suggested next tools). Required handshake before other BrAPI tools. Supports multiple concurrent connections via named aliases. Credentials can be configured server-side and omitted from this call. When a request carries no MCP session on a deployment without per-user auth, aliases live in one namespace shared by every such caller: re-registering an alias re-points their later calls to it. Built-in known servers (callable with no `baseUrl` or `auth` — public BrAPI v2 endpoints): `bti-breedbase-demo`, `bti-cassava`, `bti-sweetpotato`. Operator-configured aliases on this deployment (credentials and/or baseUrl read from server env vars): `default`, `cassava`. Aliases are shortcuts only; any other BrAPI v2 server is reachable by passing `baseUrl` directly.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"alias": {
"default": "default",
"description": "Alias for this connection. Use distinct aliases to register multiple BrAPI servers in one session.",
"pattern": "^[a-zA-Z0-9_-]+$",
"type": "string"
},
"auth": {
"description": "Auth payload. Omit to use credentials configured server-side for this alias (or no auth when none are configured).",
"oneOf": [
{
"description": "No-auth variant — public BrAPI endpoints.",
"properties": {
"mode": {
"const": "none",
"description": "No authentication.",
"type": "string"
}
},
"required": [
"mode"
],
"type": "object"
},
{
"description": "Bearer-token variant — caller already has an access token.",
"properties": {
"mode": {
"const": "bearer",
"description": "Pre-obtained bearer token.",
"type": "string"
},
"token": {
"description": "Pre-obtained access token, sent verbatim with each BrAPI request.",
"minLength": 1,
"type": "string"
}
},
"required": [
"mode",
"token"
],
"type": "object"
},
{
"description": "API-key variant — static key sent in a configurable header.",
"properties": {
"apiKey": {
"description": "API key issued by the BrAPI server.",
"minLength": 1,
"type": "string"
},
"headerName": {
"description": "HTTP header to send the API key in. Defaults to `Authorization`.",
"type": "string"
},
"mode": {
"const": "api_key",
"description": "Static API key in a custom header.",
"type": "string"
}
},
"required": [
"mode",
"apiKey"
],
"type": "object"
},
{
"description": "SGN variant — username/password exchanged at /token for a session bearer.",
"properties": {
"mode": {
"const": "sgn",
"description": "Breedbase/SGN username+password; exchanged for a bearer token at /token.",
"type": "string"
},
"password": {
"description": "Password for the SGN/Breedbase username supplied above.",
"minLength": 1,
"type": "string"
},
"username": {
"description": "SGN account username.",
"minLength": 1,
"type": "string"
}
},
"required": [
"mode",
"username",
"password"
],
"type": "object"
},
{
"description": "OAuth2 client-credentials variant.",
"properties": {
"clientId": {
"description": "OAuth2 client identifier registered with the upstream IdP.",
"minLength": 1,
"type": "string"
},
"clientSecret": {
"description": "OAuth2 client secret paired with the clientId.",
"minLength": 1,
"type": "string"
},
"mode": {
"const": "oauth2",
"description": "OAuth2 client-credentials flow; exchanged for an access token at connect time.",
"type": "string"
},
"tokenUrl": {
"description": "OAuth2 token endpoint (absolute URL). Defaults derived from the base URL when omitted.",
"type": "string"
}
},
"required": [
"mode",
"clientId",
"clientSecret"
],
"type": "object"
}
]
},
"baseUrl": {
"description": "BrAPI v2 base URL (absolute URL) including any path prefix — e.g. https://test-server.brapi.org/brapi/v2. Omit to use the configured default for this alias.",
"type": "string"
}
},
"type": "object"
},
"name": "brapi_connect",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"alias",
"baseUrl",
"server",
"auth",
"capabilities",
"dialect",
"content",
"nextToolSuggestions",
"notes",
"fetchedAt"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"alias": {
"description": "Connection alias.",
"type": "string"
},
"attribution": {
"additionalProperties": false,
"description": "Attribution metadata for built-in known-server connections. Absent for custom (env-only) connections.",
"properties": {
"citation": {
"description": "Citation requested by the upstream when data is reused in publications.",
"type": "string"
},
"homepage": {
"description": "Public homepage of the upstream dataset.",
"type": "string"
},
"isDemo": {
"description": "True when this server hosts demo / sample data, not production records.",
"type": "boolean"
},
"license": {
"description": "License under which the upstream dataset is published (e.g. \"CC-BY\").",
"type": "string"
}
},
"required": [
"homepage",
"license",
"citation"
],
"type": "object"
},
"auth": {
"additionalProperties": false,
"description": "Auth summary for the active connection.",
"properties": {
"expiresAt": {
"description": "ISO 8601 token-expiry timestamp, when known.",
"type": "string"
},
"headerName": {
"description": "HTTP header carrying credentials.",
"type": "string"
},
"mode": {
"description": "Auth mode of the active connection.",
"enum": [
"none",
"sgn",
"oauth2",
"api_key",
"bearer"
],
"type": "string"
}
},
"required": [
"mode"
],
"type": "object"
},
"baseUrl": {
"description": "BrAPI v2 base URL for this connection.",
"type": "string"
},
"capabilities": {
"additionalProperties": false,
"description": "Capability profile derived from /serverinfo.",
"properties": {
"notableGaps": {
"description": "Common-floor services this server does NOT expose.",
"items": {
"description": "Common-floor service the server does not expose.",
"type": "string"
},
"type": "array"
},
"supported": {
"description": "Sorted list of supported service names.",
"items": {
"description": "BrAPI service name (e.g. \"studies\", \"search/germplasm\").",
"type": "string"
},
"type": "array"
},
"supportedCount": {
"description": "Total distinct services the server advertises in /calls.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
}
},
"required": [
"supportedCount",
"supported",
"notableGaps"
],
"type": "object"
},
"content": {
"additionalProperties": false,
"description": "Content summary (crops + optional totals).",
"properties": {
"crops": {
"description": "Crops the server declares via /commoncropnames.",
"items": {
"description": "Common crop name as returned by /commoncropnames.",
"type": "string"
},
"type": "array"
},
"germplasmCount": {
"description": "Total germplasm hosted, when the server exposes a cheap count.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"locationCount": {
"description": "Total locations hosted, when the server exposes a cheap count.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"programCount": {
"description": "Total programs hosted, when the server exposes a cheap count.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"studyCount": {
"description": "Total studies hosted, when the server exposes a cheap count.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
}
},
"required": [
"crops"
],
"type": "object"
},
"dialect": {
"additionalProperties": false,
"description": "Active dialect adapter — translates outbound filters and declares known-dead routes for this server.",
"properties": {
"disabledSearchEndpoints": {
"description": "POST /search nouns the active dialect treats as known-dead. Tools using these routes will refuse with a recovery hint.",
"items": {
"description": "A POST /search/{noun} route the dialect routes around.",
"type": "string"
},
"type": "array"
},
"envVar": {
"description": "Env var that pins the dialect for this alias (e.g. BRAPI_DEFAULT_DIALECT) when detection misfires.",
"type": "string"
},
"id": {
"description": "Active dialect id (e.g. \"spec\", \"cassavabase\"). Names a registered adapter that translates outbound filters and declares known-dead routes.",
"type": "string"
},
"inferredMappingCount": {
"description": "Number of filter translations inferred from naming conventions but not independently verified. A non-zero count means some result narrowing on this server may not fire as expected.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"notes": {
"description": "Dialect-level compatibility notes for this server family.",
"items": {
"description": "Verified compatibility note exposed by the active dialect.",
"type": "string"
},
"type": "array"
},
"source": {
"description": "Where the dialect id came from: env-var override, URL host match, /serverinfo serverName, organizationName, or the spec passthrough fallback.",
"enum": [
"env-override",
"url-pattern",
"server-name",
"organization-name",
"fallback"
],
"type": "string"
},
"verifiedMappingCount": {
"description": "Number of filter translations the dialect has empirically verified against a live server. Higher means more confidence in the translation table.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
}
},
"required": [
"id",
"source",
"envVar",
"disabledSearchEndpoints",
"notes"
],
"type": "object"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "Machine-readable failure mode. Declared by this tool: `auth_session_required`: Caller-supplied credentials on an HTTP deployment without per-user auth, from a request that carries no MCP session. `auth_base_url_mismatch`: The alias has server-configured credentials and the supplied baseUrl differs from the server configured for it. `alias_base_url_unset`: The alias has server-configured credentials but no base URL of its own (no BRAPI_<ALIAS>_BASE_URL and no enabled built-in), so they pair with no server. `auth_token_exchange_failed`: SGN or OAuth token exchange against the BrAPI /token endpoint failed. `auth_no_access_token`: Token endpoint responded but did not return an access_token. `upstream_unauthorized`: The server answered HTTP 401 on /serverinfo or /calls — it requires login for capability discovery. `upstream_forbidden`: The server answered HTTP 403 on /serverinfo or /calls — the request (anonymous or credentialed) lacks read access. Other values are possible when a failure originates below the handler.",
"examples": [
"auth_session_required",
"auth_base_url_mismatch",
"alias_base_url_unset",
"auth_token_exchange_failed",
"auth_no_access_token",
"upstream_unauthorized",
"upstream_forbidden"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"fetchedAt": {
"description": "ISO 8601 timestamp of when this envelope was composed.",
"type": "string"
},
"nextToolSuggestions": {
"description": "Entry-point finders (studies, germplasm, variables, locations — in that order) whose GET or POST /search route this server exposes under the active dialect. Empty when none apply.",
"items": {
"additionalProperties": false,
"description": "A finder the connected server supports, with the arguments to start it.",
"properties": {
"args": {
"additionalProperties": false,
"description": "Arguments to call the tool with. Alias only — narrow further with the tool filters.",
"properties": {
"alias": {
"description": "Connection alias to pass to the suggested tool.",
"type": "string"
}
},
"required": [
"alias"
],
"type": "object"
},
"reason": {
"description": "Why this tool applies to the connected server.",
"type": "string"
},
"toolName": {
"description": "Entry-point finder tool this server can serve.",
"enum": [
"brapi_find_studies",
"brapi_find_germplasm",
"brapi_find_variables",
"brapi_find_locations"
],
"type": "string"
}
},
"required": [
"toolName",
"reason",
"args"
],
"type": "object"
},
"type": "array"
},
"notes": {
"description": "Server-specific quirks or degradation notes.",
"items": {
"description": "Server-specific quirk or degradation note.",
"type": "string"
},
"type": "array"
},
"server": {
"additionalProperties": false,
"description": "Normalized server identity block.",
"properties": {
"brapiVersion": {
"description": "Highest BrAPI version the server reports.",
"type": "string"
},
"contactEmail": {
"description": "Contact email for the operator.",
"type": "string"
},
"description": {
"description": "Free-form server description.",
"type": "string"
},
"documentationURL": {
"description": "Documentation URL for this server.",
"type": "string"
},
"name": {
"description": "Server display name from /serverinfo.",
"type": "string"
},
"organizationName": {
"description": "Hosting organization.",
"type": "string"
},
"organizationURL": {
"description": "Organization website.",
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}
},
{
"description": "Start here after a spillover. Lists dataframes (or describes one) with columns, row counts, and originating-source provenance. The dataframe name appears inline on every find_* response that spilled (`result.dataframe.tableName`) — pass it as `dataframe` to inspect schema and provenance before writing the first brapi_dataframe_query. Listing without a name is unavailable when this server runs as a shared HTTP endpoint without per-caller auth; pass a known name instead.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"dataframe": {
"description": "When set, return only the named dataframe. Omit to list all dataframes.",
"minLength": 1,
"type": "string"
}
},
"type": "object"
},
"name": "brapi_dataframe_describe",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"tables"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "Machine-readable failure mode. Declared by this tool: `list_all_disabled_on_shared_http`: This server is running as a shared HTTP endpoint without per-caller auth — listing every dataframe would expose other concurrent clients' workspaces, since all callers resolve to one shared tenant. Other values are possible when a failure originates below the handler.",
"examples": [
"list_all_disabled_on_shared_http"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"tables": {
"description": "All described dataframes.",
"items": {
"additionalProperties": false,
"description": "Dataframe description.",
"properties": {
"approxSizeBytes": {
"description": "Approximate size in bytes.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"columns": {
"description": "Schema in declaration order.",
"items": {
"additionalProperties": false,
"description": "Column declaration.",
"properties": {
"name": {
"description": "Column name.",
"type": "string"
},
"nullable": {
"description": "True when NULL values are allowed.",
"type": "boolean"
},
"type": {
"description": "SQL column type (VARCHAR, INTEGER, DOUBLE, BOOLEAN, etc.).",
"type": "string"
}
},
"required": [
"name",
"type"
],
"type": "object"
},
"type": "array"
},
"name": {
"description": "Dataframe name. Use this in SQL queries.",
"type": "string"
},
"provenance": {
"additionalProperties": false,
"description": "Originating-source provenance — present only for auto-registered dataframes (`df_*`).",
"properties": {
"baseUrl": {
"description": "BrAPI base URL the rows were pulled from.",
"type": "string"
},
"createdAt": {
"description": "ISO 8601 dataframe creation time.",
"type": "string"
},
"expiresAt": {
"description": "ISO 8601 expiry — when the dataframe metadata will be evicted.",
"type": "string"
},
"query": {
"description": "Original filter map / search body."
},
"source": {
"description": "Tool/operation that produced the dataframe (e.g. find_observations).",
"type": "string"
}
},
"required": [
"source",
"baseUrl",
"query",
"createdAt",
"expiresAt"
],
"type": "object"
},
"rowCount": {
"description": "Rows currently registered.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
}
},
"required": [
"name",
"rowCount",
"columns"
],
"type": "object"
},
"type": "array"
}
},
"type": "object"
}
},
{
"description": "Run SQL across in-memory dataframes. Dataframes auto-populate when find_* tools spill (named `df_<uuid>`) — the dataframe name appears inline on every find_* response that spilled (`result.dataframe.tableName`), so the typical flow is find_* → read the name → query here. Use brapi_dataframe_describe to inspect schema and provenance for a known name. SELECT only — writes/DDL/COPY/PRAGMA/ATTACH/file-reads are rejected. Use SQL as the paging idiom: `LIMIT/OFFSET` to walk results, projection to trim columns, aggregation to summarize. Use `registerAs` to chain — the result lands as a new dataframe.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"preview": {
"description": "Cap the number of rows returned in this response (1–1000). When omitted, the deployment-wide response cap applies. Lower this with `registerAs` when you only need a sample to verify the query.",
"exclusiveMinimum": 0,
"maximum": 1000,
"type": "integer"
},
"registerAs": {
"description": "Persist the result as a new dataframe under this name. The response still returns at most `preview` rows; the full result remains queryable as a new dataframe. Conflicts with an existing dataframe name fail — drop first via brapi_dataframe_drop. Identifier rules: letters, digits, and underscores; must start with a letter or underscore; max 63 characters.",
"pattern": "^[A-Za-z_][A-Za-z0-9_]{0,62}$",
"type": "string"
},
"rowLimit": {
"description": "Hard cap on rows materialized into the response, bounded by the deployment-wide response cap. For larger result sets, use `registerAs` to keep the full result queryable instead of raising this.",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"type": "integer"
},
"sql": {
"description": "SELECT statement against dataframes. Single statement only — writes, DDL, file reads, and exports are rejected. Use brapi_dataframe_describe to discover available dataframes. SQL is the primary paging idiom: use `LIMIT/OFFSET` to walk a large dataframe, projection to trim columns, and aggregation (`COUNT`, `GROUP BY`, `AVG`) to summarize without materializing every row.",
"minLength": 1,
"type": "string"
}
},
"required": [
"sql"
],
"type": "object"
},
"name": "brapi_dataframe_query",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"rowCount",
"columns",
"rows"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"cap": {
"description": "Row ceiling that bound the response (the smaller of preview and rowLimit).",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"type": "integer"
},
"columns": {
"description": "Column metadata in projection order — name and SQL type. Use this to write follow-up queries without round-tripping through brapi_dataframe_describe.",
"items": {
"additionalProperties": false,
"description": "One column descriptor — name and SQL/DuckDB type.",
"properties": {
"name": {
"description": "Column name in projection order.",
"type": "string"
},
"type": {
"description": "SQL/DuckDB column type (e.g. VARCHAR, BIGINT, DOUBLE, BOOLEAN, JSON) sourced from DuckDB schema metadata. The same type appears whether or not `registerAs` was supplied — without it, the handler runs an internal probe to recover authoritative types that would otherwise be lost when DuckDB BigInts serialize to JSON strings.",
"type": "string"
}
},
"required": [
"name",
"type"
],
"type": "object"
},
"type": "array"
},
"dataframe": {
"description": "Name of the dataframe holding the full result, populated when `registerAs` was supplied. Reference this name in follow-up queries.",
"type": "string"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "Machine-readable failure mode. Declared by this tool: `sql_rejected`: SQL violated read-only rules (multi-statement, non-SELECT, or disallowed operation). Other values are possible when a failure originates below the handler.",
"examples": [
"sql_rejected"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"notice": {
"description": "Guidance for reaching the rows this response left out.",
"type": "string"
},
"rowCount": {
"description": "Total rows the query produced (may exceed `rows.length` when capped).",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"rows": {
"description": "Materialized rows, bounded by preview/rowLimit.",
"items": {
"additionalProperties": {},
"description": "One result row. Columns are projected from the SQL SELECT clause; call brapi_dataframe_describe to inspect source dataframe schemas.",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"type": "array"
},
"shown": {
"description": "Rows materialized into `rows`.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"truncated": {
"description": "True when the response carries fewer rows than the query produced.",
"type": "boolean"
}
},
"type": "object"
}
},
{
"description": "List the valid filter names for a BrAPI endpoint (studies, germplasm, observations, variables, images, variants, locations) — companion lookup for the `extraFilters` passthrough on any `find_*` tool. Entries reflect the BrAPI v2.1 spec; individual servers may implement subsets.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"endpoint": {
"description": "BrAPI endpoint to describe filters for.",
"enum": [
"germplasm",
"images",
"locations",
"observations",
"studies",
"variables",
"variants"
],
"type": "string"
}
},
"required": [
"endpoint"
],
"type": "object"
},
"name": "brapi_describe_filters",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"endpoint",
"filterCount",
"filters",
"availableEndpoints"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"availableEndpoints": {
"description": "Every endpoint this tool can describe — useful for discovery.",
"items": {
"type": "string"
},
"type": "array"
},
"endpoint": {
"description": "The endpoint the filters apply to.",
"type": "string"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "Machine-readable failure mode. Declared by this tool: `unknown_endpoint`: No filter catalog is registered for the requested endpoint. Other values are possible when a failure originates below the handler.",
"examples": [
"unknown_endpoint"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"filterCount": {
"description": "Number of filters in the catalog.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"filters": {
"description": "Filter catalog entries.",
"items": {
"additionalProperties": false,
"description": "One filter entry — name, type, description, and an example value.",
"properties": {
"description": {
"description": "Short description of what the filter does.",
"type": "string"
},
"example": {
"description": "Example value (stringified).",
"type": "string"
},
"name": {
"description": "Filter parameter name (as accepted by the BrAPI endpoint).",
"type": "string"
},
"type": {
"description": "Expected value type.",
"enum": [
"string",
"integer",
"number",
"boolean",
"date",
"string[]",
"integer[]"
],
"type": "string"
}
},
"required": [
"name",
"type",
"description",
"example"
],
"type": "object"
},
"type": "array"
},
"specReference": {
"description": "Pointer to the BrAPI v2 spec section for this endpoint.",
"type": "string"
}
},
"type": "object"
}
},
{
"description": "Pull genotype calls for a germplasm × variant set and pivot them into a matrix. `format` controls the output: `matrix-json` registers a wide germplasm × variant canvas dataframe for SQL analysis; `vcf-lite` returns VCF-subset text (in the `vcf` field) and also registers the dataframe; `plink` returns .ped/.map text (in the `ped`/`map` fields) and also registers the dataframe. vcf-lite/plink pull /variants metadata for CHROM/POS/REF/ALT (`.`/`0` when the server lacks them). Column names are SQL-safe identifiers; `variantColumnLegend` maps them back to original variant IDs.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"alias": {
"description": "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.",
"pattern": "^[a-zA-Z0-9_-]+$",
"type": "string"
},
"format": {
"description": "Output format. `matrix-json` registers a wide canvas dataframe only. `vcf-lite` returns VCF-subset text and registers the dataframe. `plink` returns .ped/.map text and registers the dataframe.",
"enum": [
"plink",
"vcf-lite",
"matrix-json"
],
"type": "string"
},
"germplasmDbIds": {
"description": "Restrict to these germplasm. Omit to pull all germplasm in the variant set (use with caution on large sets).",
"items": {
"type": "string"
},
"type": "array"
},
"maxCalls": {
"description": "Lower the pull cap for this call. Omit to use the deployment ceiling (BRAPI_GENOTYPE_CALLS_MAX_PULL). Cannot raise it: a value above the deployment ceiling is clamped down to it and the effective cap is reported in `warnings`.",
"exclusiveMinimum": 0,
"maximum": 500000,
"type": "integer"
},
"maxColumns": {
"description": "Lower the distinct-variant column cap for this call. Omit to use the deployment ceiling (BRAPI_GENOTYPE_MATRIX_MAX_COLUMNS). Cannot raise it: a value above the deployment ceiling is clamped down to it. When the variant set resolves more distinct variants than the effective cap, the matrix is capped at that many variant columns, `truncated` is set, and the effective cap is reported in `warnings`. Independent of `maxCalls`, which bounds the row (call) pull.",
"exclusiveMinimum": 0,
"maximum": 500000,
"type": "integer"
},
"variantSetDbId": {
"description": "Variant set to pull calls for. Required.",
"minLength": 1,
"type": "string"
}
},
"required": [
"variantSetDbId",
"format"
],
"type": "object"
},
"name": "brapi_export_genotype_matrix",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"alias",
"format",
"rowCount",
"columnCount",
"variantColumnLegend",
"callFormatting",
"dataframe",
"truncated",
"warnings"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"alias": {
"description": "Alias of the registered BrAPI connection used.",
"type": "string"
},
"callFormatting": {
"additionalProperties": false,
"description": "Genotype-encoding hints echoed by the server.",
"properties": {
"expandHomozygotes": {
"description": "Homozygous allele expansion flag.",
"type": [
"boolean",
"null"
]
},
"sepPhased": {
"description": "Phased allele separator.",
"type": [
"string",
"null"
]
},
"sepUnphased": {
"description": "Unphased allele separator.",
"type": [
"string",
"null"
]
},
"unknownString": {
"description": "String used for unknown/missing calls.",
"type": [
"string",
"null"
]
}
},
"type": "object"
},
"columnCount": {
"description": "Number of variant columns in the matrix (excluding the germplasm ID column).",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"dataframe": {
"additionalProperties": false,
"description": "Canvas dataframe handle for the wide germplasm × variant matrix (registered for every format). Query with brapi_dataframe_query (SQL); export with brapi_dataframe_export. The vcf/ped/map text fields are the format-specific serialization of the same data.",
"properties": {
"columnLegend": {
"additionalProperties": {
"type": "string"
},
"description": "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.",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"columns": {
"description": "Full column list of the dataframe.",
"items": {
"description": "Column name from the materialized rows.",
"type": "string"
},
"type": "array"
},
"createdAt": {
"description": "ISO 8601 timestamp the dataframe was created.",
"type": "string"
},
"expiresAt": {
"description": "ISO 8601 timestamp after which the dataframe metadata will be purged. Re-run the find_* tool to refresh, or copy results out before expiry.",
"type": "string"
},
"maxRows": {
"description": "Cap that was applied at create time, when truncation occurred.",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"type": "integer"
},
"rowCount": {
"description": "Number of rows materialized in the dataframe.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"tableName": {
"description": "Dataframe name. Use with brapi_dataframe_describe (schema + provenance) and brapi_dataframe_query (SQL).",
"type": "string"
},
"totalCount": {
"description": "Total rows reported by the upstream server (may exceed rowCount when truncated).",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"truncated": {
"description": "True when the dataframe hit a row cap before exhausting upstream.",
"type": "boolean"
}
},
"required": [
"tableName",
"rowCount",
"columns",
"createdAt",
"expiresAt"
],
"type": "object"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "Machine-readable failure mode. Declared by this tool: `unknown_alias`: No connection has been registered under the requested alias. `no_filters`: No variantSetDbId was provided. `search_endpoint_disabled`: The active dialect declares POST /search/calls as known-dead on this server. Other values are possible when a failure originates below the handler.",
"examples": [
"unknown_alias",
"no_filters",
"search_endpoint_disabled"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"format": {
"description": "The output format that was produced.",
"enum": [
"plink",
"vcf-lite",
"matrix-json"
],
"type": "string"
},
"map": {
"description": "PLINK .map text — chromosome, variant-id, genetic-distance (0 placeholder), base-pair position, one row per variant. Present only when format=\"plink\". Chromosome/position come from /variants metadata; `0` when absent.",
"type": "string"
},
"ped": {
"description": "PLINK .ped text — FID IID PAT MAT SEX PHENO placeholders (all 0) followed by biallelic genotype pairs per variant, one row per sample. Present only when format=\"plink\". Alleles are passed through verbatim; PLINK missing is `0`.",
"type": "string"
},
"rowCount": {
"description": "Number of call-set (germplasm) rows in the matrix.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"truncated": {
"description": "True when the matrix is not the complete upstream result — either the call pull hit the row ceiling (BRAPI_GENOTYPE_CALLS_MAX_PULL) or the distinct-variant count hit the column ceiling (BRAPI_GENOTYPE_MATRIX_MAX_COLUMNS). `warnings` names which ceiling fired.",
"type": "boolean"
},
"variantColumnLegend": {
"additionalProperties": {
"type": "string"
},
"description": "Map of sanitized column name → original variantDbId. Dataframe column names are SQL-safe identifiers; use this legend to correlate them back to the original variant IDs.",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"vcf": {
"description": "VCF-lite text — header `#CHROM POS ID REF ALT` plus one genotype column per sample, one row per variant. Present only when format=\"vcf-lite\". CHROM/POS/REF/ALT come from /variants metadata; \".\" when the server does not provide them.",
"type": "string"
},
"warnings": {
"description": "Advisory messages (truncation, missing fields, etc.).",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
}
},
{
"description": "Pull genotype calls for a germplasm × variant set. Filter to bound cost — at minimum, set `variantSetDbId` or `germplasmDbIds`. The upstream pull is capped by deployment policy; when the pull is truncated, narrow the filters or query the spilled dataframe. `loadLimit` bounds the rows returned inline; the full collected set is materialized as a dataframe — query it with brapi_dataframe_query (SQL) instead of paging row-by-row.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"alias": {
"description": "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.",
"pattern": "^[a-zA-Z0-9_-]+$",
"type": "string"
},
"callFormat": {
"description": "Requested call-encoding format, when the server honors it.",
"enum": [
"VCF",
"FLAPJACK",
"DARTSEQ",
"JSON"
],
"type": "string"
},
"callSetDbIds": {
"description": "Restrict to these call sets directly.",
"items": {
"type": "string"
},
"type": "array"
},
"germplasmDbIds": {
"description": "Restrict to these germplasm (call sets).",
"items": {
"type": "string"
},
"type": "array"
},
"loadLimit": {
"description": "Cap on rows returned inline. Omit for the deployment default. When the collected set exceeds this, the full result lands in a dataframe and only the first `loadLimit` rows return inline — query the dataframe with brapi_dataframe_query (SQL) for the rest. Upstream pageSize is fixed for genotype calls, so this knob only affects the inline preview here (no spillover capacity tradeoff).",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"type": "integer"
},
"variantDbIds": {
"description": "Restrict to specific variants.",
"items": {
"type": "string"
},
"type": "array"
},
"variantSetDbId": {
"description": "Scope calls to a single variant set. Strongly recommended.",
"minLength": 1,
"type": "string"
},
"variantSetDbIds": {
"description": "Alternative: multiple variant sets at once.",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"name": "brapi_find_genotype_calls",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"alias",
"results",
"hasMore",
"callFormatting",
"distributions",
"truncated",
"totalCount",
"returnedCount",
"appliedFilters",
"warnings"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"alias": {
"description": "Alias of the registered BrAPI connection the call used.",
"type": "string"
},
"appliedFilters": {
"additionalProperties": {},
"description": "The body sent to POST /search/calls (variant/germplasm/call-set scope plus pageSize).",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"callFormatting": {
"additionalProperties": false,
"description": "Genotype-encoding hints echoed by the server.",
"properties": {
"expandHomozygotes": {
"description": "When true, homozygous calls are expanded to both alleles.",
"type": [
"boolean",
"null"
]
},
"sepPhased": {
"description": "Separator between phased allele values (typically \"|\").",
"type": [
"string",
"null"
]
},
"sepUnphased": {
"description": "Separator between unphased allele values (typically \"/\").",
"type": [
"string",
"null"
]
},
"unknownString": {
"description": "String used for unknown / missing calls (often \".\" or \"N\").",
"type": [
"string",
"null"
]
}
},
"type": "object"
},
"dataframe": {
"additionalProperties": false,
"description": "Dataframe handle when the full collected calls exceed loadLimit and were materialized as a dataframe. Query it with brapi_dataframe_query (SQL).",
"properties": {
"columnLegend": {
"additionalProperties": {
"type": "string"
},
"description": "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.",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"columns": {
"description": "Full column list of the dataframe.",
"items": {
"description": "Column name from the materialized rows.",
"type": "string"
},
"type": "array"
},
"createdAt": {
"description": "ISO 8601 timestamp the dataframe was created.",
"type": "string"
},
"expiresAt": {
"description": "ISO 8601 timestamp after which the dataframe metadata will be purged. Re-run the find_* tool to refresh, or copy results out before expiry.",
"type": "string"
},
"maxRows": {
"description": "Cap that was applied at create time, when truncation occurred.",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"type": "integer"
},
"rowCount": {
"description": "Number of rows materialized in the dataframe.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"tableName": {
"description": "Dataframe name. Use with brapi_dataframe_describe (schema + provenance) and brapi_dataframe_query (SQL).",
"type": "string"
},
"totalCount": {
"description": "Total rows reported by the upstream server (may exceed rowCount when truncated).",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"truncated": {
"description": "True when the dataframe hit a row cap before exhausting upstream.",
"type": "boolean"
}
},
"required": [
"tableName",
"rowCount",
"columns",
"createdAt",
"expiresAt"
],
"type": "object"
},
"distributions": {
"additionalProperties": false,
"description": "Value frequency per field across the full collected call set.",
"properties": {
"callSetName": {
"additionalProperties": {
"type": "number"
},
"description": "Call set name → count of calls from that set.",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"variantName": {
"additionalProperties": {
"type": "number"
},
"description": "Variant name → count of calls for that variant.",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"variantSetDbId": {
"additionalProperties": {
"type": "number"
},
"description": "Variant set ID → count of calls from that set.",
"propertyNames": {
"type": "string"
},
"type": "object"
}
},
"required": [
"callSetName",
"variantName",
"variantSetDbId"
],
"type": "object"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "Machine-readable failure mode. Declared by this tool: `unknown_alias`: No connection has been registered under the requested alias. `no_filters`: No variant set, germplasm, call set, or variant filter was provided. `search_endpoint_disabled`: The active dialect declares POST /search/calls as known-dead on this server. Other values are possible when a failure originates below the handler.",
"examples": [
"unknown_alias",
"no_filters",
"search_endpoint_disabled"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"hasMore": {
"description": "True when the collection was truncated (equivalent to `truncated`).",
"type": "boolean"
},
"notice": {
"description": "Guidance when no calls were returned — how to broaden filters or verify IDs.",
"type": "string"
},
"results": {
"description": "Call rows returned in-context (up to loadLimit).",
"items": {
"additionalProperties": {},
"description": "One genotype call row.",
"properties": {
"callSetDbId": {
"description": "FK to the call set (one germplasm × one variant set = one call set).",
"type": [
"string",
"null"
]
},
"callSetName": {
"description": "Display name of the call set.",
"type": [
"string",
"null"
]
},
"genotype": {
"anyOf": [
{
"additionalProperties": {},
"properties": {
"values": {
"anyOf": [
{
"items": {
"description": "Per-allele value string.",
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"description": "Encoded allele values — interpret using top-level `callFormatting`."
}
},
"type": "object"
},
{
"type": "null"
}
],
"description": "Structured genotype payload (array of allele values plus server-specific fields)."
},
"genotypeValue": {
"description": "Legacy flat string form of the call (provided by some servers instead of `genotype`).",
"type": [
"string",
"null"
]
},
"phaseSet": {
"description": "Phase-set identifier linking calls that share a haplotype phase.",
"type": [
"string",
"null"
]
},
"variantDbId": {
"description": "FK to the variant being called.",
"type": [
"string",
"null"
]
},
"variantName": {
"description": "Display name / alias of the variant.",
"type": [
"string",
"null"
]
},
"variantSetDbId": {
"description": "FK to the variant set the call belongs to.",
"type": [
"string",
"null"
]
}
},
"type": "object"
},
"type": "array"
},
"returnedCount": {
"description": "Length of results[] — rows returned in-context (up to loadLimit).",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"totalCount": {
"description": "Total calls collected across all pages (may be capped by the deployment-wide pull limit; check `truncated`).",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"truncated": {
"description": "True when the deployment-wide pull limit was reached and more calls exist upstream. Narrow the filters and re-pull, or query the spilled dataframe.",
"type": "boolean"
},
"warnings": {
"description": "Advisory messages (truncation, capability gaps, partial pulls).",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
}
},
{
"description": "Find germplasm by name, synonym, accession number, PUI, crop, or free-text query. Matches across registered synonyms. When the upstream total exceeds loadLimit, the full result set is materialized as a dataframe — query it with brapi_dataframe_query (SQL) instead of paging row-by-row.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"accessionNumbers": {
"description": "Filter by accession numbers (gene-bank catalog codes).",
"items": {
"type": "string"
},
"type": "array"
},
"alias": {
"description": "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.",
"pattern": "^[a-zA-Z0-9_-]+$",
"type": "string"
},
"collections": {
"description": "Filter by germplasm collection names.",
"items": {
"type": "string"
},
"type": "array"
},
"crops": {
"description": "Filter by common crop names.",
"items": {
"type": "string"
},
"type": "array"
},
"extraFilters": {
"additionalProperties": {},
"description": "Extra BrAPI filters forwarded verbatim. Valid keys vary by endpoint; brapi_describe_filters enumerates them. Named params on this tool take precedence on conflict.",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"genus": {
"description": "Botanical genus.",
"type": "string"
},
"germplasmDbIds": {
"description": "Filter by DbIds.",
"items": {
"type": "string"
},
"type": "array"
},
"germplasmPUIs": {
"description": "Persistent unique identifiers.",
"items": {
"type": "string"
},
"type": "array"
},
"loadLimit": {
"description": "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.",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"type": "integer"
},
"names": {
"description": "Filter by germplasm display names.",
"items": {
"type": "string"
},
"type": "array"
},
"species": {
"description": "Botanical species.",
"type": "string"
},
"synonyms": {
"description": "Match registered synonyms.",
"items": {
"type": "string"
},
"type": "array"
},
"text": {
"description": "Free-text query. Applied client-side as a substring match on returned rows (germplasmName, accessionNumber, defaultDisplayName, registered synonyms) — no BrAPI server reliably supports a server-side free-text filter, so combine with `crops` / `genus` / etc. to narrow the upstream pull first.",
"type": "string"
}
},
"type": "object"
},
"name": "brapi_find_germplasm",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"alias",
"results",
"hasMore",
"distributions",
"totalCount",
"returnedCount",
"appliedFilters",
"warnings"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"alias": {
"description": "Alias of the registered BrAPI connection the call used.",
"type": "string"
},
"appliedFilters": {
"additionalProperties": {},
"description": "The final filter map sent to the server (named + extraFilters).",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"dataframe": {
"additionalProperties": false,
"description": "Dataframe handle when the full result set was materialized as a dataframe. Query it with brapi_dataframe_query (SQL).",
"properties": {
"columnLegend": {
"additionalProperties": {
"type": "string"
},
"description": "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.",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"columns": {
"description": "Full column list of the dataframe.",
"items": {
"description": "Column name from the materialized rows.",
"type": "string"
},
"type": "array"
},
"createdAt": {
"description": "ISO 8601 timestamp the dataframe was created.",
"type": "string"
},
"expiresAt": {
"description": "ISO 8601 timestamp after which the dataframe metadata will be purged. Re-run the find_* tool to refresh, or copy results out before expiry.",
"type": "string"
},
"maxRows": {
"description": "Cap that was applied at create time, when truncation occurred.",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"type": "integer"
},
"rowCount": {
"description": "Number of rows materialized in the dataframe.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"tableName": {
"description": "Dataframe name. Use with brapi_dataframe_describe (schema + provenance) and brapi_dataframe_query (SQL).",
"type": "string"
},
"totalCount": {
"description": "Total rows reported by the upstream server (may exceed rowCount when truncated).",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"truncated": {
"description": "True when the dataframe hit a row cap before exhausting upstream.",
"type": "boolean"
}
},
"required": [
"tableName",
"rowCount",
"columns",
"createdAt",
"expiresAt"
],
"type": "object"
},
"distributions": {
"additionalProperties": false,
"description": "Value frequency per field across the full result set.",
"properties": {
"collection": {
"additionalProperties": {
"type": "number"
},
"description": "Collection name → count of rows in that collection.",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"commonCropName": {
"additionalProperties": {
"type": "number"
},
"description": "Common crop name → count of rows for that crop.",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"countryOfOriginCode": {
"additionalProperties": {
"type": "number"
},
"description": "ISO country code → count of rows from that country.",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"genus": {
"additionalProperties": {
"type": "number"
},
"description": "Genus → count of rows with that genus.",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"species": {
"additionalProperties": {
"type": "number"
},
"description": "Species → count of rows with that species.",
"propertyNames": {
"type": "string"
},
"type": "object"
}
},
"required": [
"commonCropName",
"genus",
"species",
"collection",
"countryOfOriginCode"
],
"type": "object"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "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.",
"examples": [
"unknown_alias",
"all_filters_dropped"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"hasMore": {
"description": "True when more rows exist beyond the returned set.",
"type": "boolean"
},
"notice": {
"description": "Guidance when no rows were returned — how to broaden filters or retry.",
"type": "string"
},
"refinementHint": {
"description": "Suggested next-step query refinement when the result set is large.",
"type": "string"
},
"results": {
"description": "Germplasm rows returned in-context (up to loadLimit).",
"items": {
"additionalProperties": {},
"description": "One BrAPI germplasm record.",
"properties": {
"accessionNumber": {
"description": "Gene-bank catalog number.",
"type": [
"string",
"null"
]
},
"biologicalStatusOfAccessionDescription": {
"description": "MCPD biological-status label (wild / landrace / breeding / cultivar, etc.).",
"type": [
"string",
"null"
]
},
"collection": {
"description": "Collection name this accession belongs to.",
"type": [
"string",
"null"
]
},
"commonCropName": {
"description": "Common crop name (e.g. \"Maize\", \"Wheat\").",
"type": [
"string",
"null"
]
},
"countryOfOriginCode": {
"description": "ISO 3166-1 alpha-3 country code.",
"type": [
"string",
"null"
]
},
"defaultDisplayName": {
"description": "Preferred display label.",
"type": [
"string",
"null"
]
},
"genus": {
"description": "Botanical genus.",
"type": [
"string",
"null"
]
},
"germplasmDbId": {
"description": "Server-side identifier for the germplasm.",
"type": "string"
},
"germplasmName": {
"description": "Display name.",
"type": [
"string",
"null"
]
},
"germplasmOrigin": {
"anyOf": [
{
"items": {
"additionalProperties": {},
"description": "One origin record (collection coordinates and uncertainty per BrAPI v2).",
"properties": {},
"type": "object"
},
"type": "array"
},
{
"type": "null"
}
],
"description": "Origin records — array of collection-site objects per BrAPI v2."
},
"germplasmPUI": {
"description": "Persistent unique identifier (URI).",
"type": [
"string",
"null"
]
},
"instituteCode": {
"description": "FAO WIEWS institute code of the holding institute.",
"type": [
"string",
"null"
]
},
"instituteName": {
"description": "Display name of the holding institute.",
"type": [
"string",
"null"
]
},
"pedigree": {
"description": "Pedigree as a free-text string (e.g. \"A/B//C\").",
"type": [
"string",
"null"
]
},
"species": {
"description": "Botanical species.",
"type": [
"string",
"null"
]
},
"subtaxa": {
"description": "Botanical subtaxa (subspecies, variety, etc.).",
"type": [
"string",
"null"
]
},
"synonyms": {
"anyOf": [
{
"items": {
"additionalProperties": {},
"description": "Registered synonym for this germplasm.",
"properties": {
"synonym": {
"description": "Synonym value.",
"type": [
"string",
"null"
]
},
"type": {
"description": "Synonym type (e.g. \"COMMON\", \"SYNONYM\").",
"type": [
"string",
"null"
]
}
},
"type": "object"
},
"type": "array"
},
{
"type": "null"
}
],
"description": "All registered synonyms (alternative names)."
}
},
"required": [
"germplasmDbId"
],
"type": "object"
},
"type": "array"
},
"returnedCount": {
"description": "Length of results[].",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"totalCount": {
"description": "Total rows reported by the server.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"warnings": {
"description": "Advisory messages (filter overrides, partial data, capability gaps).",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
}
},
{
"description": "Filter images by observation unit, observation, study, descriptive ontology term, file name, or MIME type. Returns metadata only — use brapi_get_image to fetch bytes inline. When the upstream total exceeds loadLimit, the full result set is materialized as a dataframe — query it with brapi_dataframe_query (SQL).",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"alias": {
"description": "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.",
"pattern": "^[a-zA-Z0-9_-]+$",
"type": "string"
},
"descriptiveOntologyTerms": {
"description": "Filter by ontology tags (e.g. \"CO_334:plot\").",
"items": {
"type": "string"
},
"type": "array"
},
"extraFilters": {
"additionalProperties": {},
"description": "Extra BrAPI filters forwarded verbatim. Valid keys vary by endpoint; brapi_describe_filters enumerates them. Named params on this tool take precedence on conflict.",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"imageFileNames": {
"description": "Filter by uploaded file name.",
"items": {
"type": "string"
},
"type": "array"
},
"images": {
"description": "Filter by imageDbIds.",
"items": {
"type": "string"
},
"type": "array"
},
"loadLimit": {
"description": "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.",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"type": "integer"
},
"mimeTypes": {
"description": "Filter by MIME type — e.g. \"image/jpeg\", \"image/png\".",
"items": {
"type": "string"
},
"type": "array"
},
"observationUnits": {
"description": "Filter by observationUnitDbIds.",
"items": {
"type": "string"
},
"type": "array"
},
"observations": {
"description": "Filter by observationDbIds.",
"items": {
"type": "string"
},
"type": "array"
},
"studies": {
"description": "Filter by studyDbIds.",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"name": "brapi_find_images",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"alias",
"results",
"hasMore",
"distributions",
"totalCount",
"returnedCount",
"appliedFilters",
"warnings"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"alias": {
"description": "Alias of the registered BrAPI connection the call used.",
"type": "string"
},
"appliedFilters": {
"additionalProperties": {},
"description": "The final filter map sent to the server (named + extraFilters).",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"dataframe": {
"additionalProperties": false,
"description": "Dataframe handle when the full result set was materialized as a dataframe. Query it with brapi_dataframe_query (SQL).",
"properties": {
"columnLegend": {
"additionalProperties": {
"type": "string"
},
"description": "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.",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"columns": {
"description": "Full column list of the dataframe.",
"items": {
"description": "Column name from the materialized rows.",
"type": "string"
},
"type": "array"
},
"createdAt": {
"description": "ISO 8601 timestamp the dataframe was created.",
"type": "string"
},
"expiresAt": {
"description": "ISO 8601 timestamp after which the dataframe metadata will be purged. Re-run the find_* tool to refresh, or copy results out before expiry.",
"type": "string"
},
"maxRows": {
"description": "Cap that was applied at create time, when truncation occurred.",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"type": "integer"
},
"rowCount": {
"description": "Number of rows materialized in the dataframe.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"tableName": {
"description": "Dataframe name. Use with brapi_dataframe_describe (schema + provenance) and brapi_dataframe_query (SQL).",
"type": "string"
},
"totalCount": {
"description": "Total rows reported by the upstream server (may exceed rowCount when truncated).",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"truncated": {
"description": "True when the dataframe hit a row cap before exhausting upstream.",
"type": "boolean"
}
},
"required": [
"tableName",
"rowCount",
"columns",
"createdAt",
"expiresAt"
],
"type": "object"
},
"distributions": {
"additionalProperties": false,
"description": "Value frequency per field across the full result set.",
"properties": {
"descriptiveOntologyTerms": {
"additionalProperties": {
"type": "number"
},
"description": "Ontology term → count of images tagged with that term.",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"mimeType": {
"additionalProperties": {
"type": "number"
},
"description": "MIME type → count of images with that type.",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"observationUnitName": {
"additionalProperties": {
"type": "number"
},
"description": "Observation unit name → count of images tied to that unit.",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"studyName": {
"additionalProperties": {
"type": "number"
},
"description": "Study name → count of images in that study.",
"propertyNames": {
"type": "string"
},
"type": "object"
}
},
"required": [
"mimeType",
"studyName",
"observationUnitName",
"descriptiveOntologyTerms"
],
"type": "object"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "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.",
"examples": [
"unknown_alias",
"all_filters_dropped"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"hasMore": {
"description": "True when more rows exist beyond the returned set.",
"type": "boolean"
},
"notice": {
"description": "Guidance when no rows were returned — how to broaden filters or retry.",
"type": "string"
},
"refinementHint": {
"description": "Suggested next-step query refinement when the result set is large.",
"type": "string"
},
"results": {
"description": "Image metadata rows returned in-context (up to loadLimit).",
"items": {
"additionalProperties": {},
"description": "One BrAPI image metadata record.",
"properties": {
"copyright": {
"description": "Copyright or rights notice.",
"type": [
"string",
"null"
]
},
"description": {
"description": "Free-text description.",
"type": [
"string",
"null"
]
},
"descriptiveOntologyTerms": {
"anyOf": [
{
"items": {
"description": "Ontology term ID or label.",
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"description": "Descriptive ontology tags (e.g. \"CO_334:plot\")."
},
"imageDbId": {
"description": "Server-side identifier for the image.",
"type": "string"
},
"imageFileName": {
"description": "Original uploaded filename.",
"type": [
"string",
"null"
]
},
"imageFileSize": {
"description": "File size in bytes. Coerced from string when the upstream emits a numeric string.",
"type": [
"number",
"null"
]
},
"imageHeight": {
"description": "Pixel height. Coerced from string when the upstream emits a numeric string.",
"type": [
"number",
"null"
]
},
"imageName": {
"description": "Display name.",
"type": [
"string",
"null"
]
},
"imageTimeStamp": {
"description": "ISO 8601 capture timestamp.",
"type": [
"string",
"null"
]
},
"imageURL": {
"description": "URL where the bytes live (may be relative to baseUrl or absolute).",
"type": [
"string",
"null"
]
},
"imageWidth": {
"description": "Pixel width. Coerced from string when the upstream emits a numeric string.",
"type": [
"number",
"null"
]
},
"mimeType": {
"description": "MIME type (e.g. \"image/jpeg\").",
"type": [
"string",
"null"
]
},
"observationDbIds": {
"anyOf": [
{
"items": {
"description": "Observation identifier.",
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"description": "FKs to observations this image is evidence for."
},
"observationUnitDbId": {
"description": "FK to the observation unit this image depicts.",
"type": [
"string",
"null"
]
},
"observationUnitName": {
"description": "Display name of the observation unit.",
"type": [
"string",
"null"
]
},
"studyDbId": {
"description": "FK to the study the image belongs to.",
"type": [
"string",
"null"
]
},
"studyName": {
"description": "Display name of the study.",
"type": [
"string",
"null"
]
}
},
"required": [
"imageDbId"
],
"type": "object"
},
"type": "array"
},
"returnedCount": {
"description": "Length of results[].",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"totalCount": {
"description": "Total rows reported by the server.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"warnings": {
"description": "Advisory messages (filter overrides, partial data, capability gaps).",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
}
},
{
"description": "Find research stations / field sites by country, abbreviation, type, location ID, or free-text. Countries filter by ISO 3166-1 alpha-3 code via countryCodes, or by free-form English country name via countryNames (resolved client-side to alpha-3 — \"Uganda\" → \"UGA\"). Optional bbox parameter restricts rows to a latitude/longitude window. When the spec-correct GeoJSON [lon, lat, alt] reading produces zero matches and at least one row carries a Point geometry, the bbox filter retries once with axes swapped (handles non-conformant servers that store [lat, lon, alt]) and surfaces a warning + `coordinateAxisOrder: \"swapped\"`. When the upstream total exceeds loadLimit, the full result set is materialized as a dataframe — query it with brapi_dataframe_query (SQL).",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"abbreviations": {
"description": "Short location abbreviations.",
"items": {
"type": "string"
},
"type": "array"
},
"alias": {
"description": "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.",
"pattern": "^[a-zA-Z0-9_-]+$",
"type": "string"
},
"bbox": {
"description": "Optional post-fetch bounding box. All four corners must be set to activate the filter.",
"properties": {
"maxLat": {
"description": "Maximum latitude in WGS84 decimal degrees.",
"maximum": 90,
"minimum": -90,
"type": "number"
},
"maxLon": {
"description": "Maximum longitude in WGS84 decimal degrees.",
"maximum": 180,
"minimum": -180,
"type": "number"
},
"minLat": {
"description": "Minimum latitude in WGS84 decimal degrees.",
"maximum": 90,
"minimum": -90,
"type": "number"
},
"minLon": {
"description": "Minimum longitude in WGS84 decimal degrees.",
"maximum": 180,
"minimum": -180,
"type": "number"
}
},
"type": "object"
},
"countryCodes": {
"description": "ISO 3166-1 alpha-3 country codes.",
"items": {
"type": "string"
},
"type": "array"
},
"countryNames": {
"description": "Free-form English country names or aliases (e.g. \"Uganda\", \"United States\", \"USA\") resolved client-side to ISO 3166-1 alpha-3 codes and merged into countryCodes. Names that do not resolve surface as a warning. Prefer countryCodes when you already have alpha-3 codes.",
"items": {
"type": "string"
},
"type": "array"
},
"extraFilters": {
"additionalProperties": {},
"description": "Extra BrAPI filters forwarded verbatim. Valid keys vary by endpoint; brapi_describe_filters enumerates them. Named params on this tool take precedence on conflict.",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"loadLimit": {
"description": "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.",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"type": "integer"
},
"locationNames": {
"description": "Filter by display name.",
"items": {
"type": "string"
},
"type": "array"
},
"locationTypes": {
"description": "Location type — e.g. \"Research Station\", \"Field\".",
"items": {
"type": "string"
},
"type": "array"
},
"locations": {
"description": "Filter by locationDbIds.",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"name": "brapi_find_locations",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"alias",
"results",
"hasMore",
"distributions",
"coordinateAxisOrder",
"totalCount",
"returnedCount",
"appliedFilters",
"warnings"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"alias": {
"description": "Alias of the registered BrAPI connection the call used.",
"type": "string"
},
"appliedFilters": {
"additionalProperties": {},
"description": "The final filter map sent to the server (named + extraFilters).",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"coordinateAxisOrder": {
"description": "Axis interpretation used when reading GeoJSON Point coordinates. \"spec\" follows the GeoJSON RFC 7946 [lon, lat, alt?] convention. \"swapped\" indicates the upstream server stores [lat, lon, alt?] (non-conformant) and bbox + rendered coordinates were interpreted accordingly.",
"enum": [
"spec",
"swapped"
],
"type": "string"
},
"dataframe": {
"additionalProperties": false,
"description": "Dataframe handle when the full result set was materialized as a dataframe. Query it with brapi_dataframe_query (SQL).",
"properties": {
"columnLegend": {
"additionalProperties": {
"type": "string"
},
"description": "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.",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"columns": {
"description": "Full column list of the dataframe.",
"items": {
"description": "Column name from the materialized rows.",
"type": "string"
},
"type": "array"
},
"createdAt": {
"description": "ISO 8601 timestamp the dataframe was created.",
"type": "string"
},
"expiresAt": {
"description": "ISO 8601 timestamp after which the dataframe metadata will be purged. Re-run the find_* tool to refresh, or copy results out before expiry.",
"type": "string"
},
"maxRows": {
"description": "Cap that was applied at create time, when truncation occurred.",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"type": "integer"
},
"rowCount": {
"description": "Number of rows materialized in the dataframe.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"tableName": {
"description": "Dataframe name. Use with brapi_dataframe_describe (schema + provenance) and brapi_dataframe_query (SQL).",
"type": "string"
},
"totalCount": {
"description": "Total rows reported by the upstream server (may exceed rowCount when truncated).",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"truncated": {
"description": "True when the dataframe hit a row cap before exhausting upstream.",
"type": "boolean"
}
},
"required": [
"tableName",
"rowCount",
"columns",
"createdAt",
"expiresAt"
],
"type": "object"
},
"distributions": {
"additionalProperties": false,
"description": "Value frequency per field across the full result set.",
"properties": {
"countryCode": {
"additionalProperties": {
"type": "number"
},
"description": "ISO country code → count of locations in that country.",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"locationType": {
"additionalProperties": {
"type": "number"
},
"description": "Location type → count of locations of that type.",
"propertyNames": {
"type": "string"
},
"type": "object"
}
},
"required": [
"countryCode",
"locationType"
],
"type": "object"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "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.",
"examples": [
"unknown_alias",
"all_filters_dropped"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"hasMore": {
"description": "True when more rows exist beyond the returned set.",
"type": "boolean"
},
"notice": {
"description": "Guidance when no rows were returned — how to broaden filters or retry.",
"type": "string"
},
"refinementHint": {
"description": "Suggested next-step query refinement when the result set is large.",
"type": "string"
},
"results": {
"description": "Location rows returned in-context (up to loadLimit). Bbox filter is applied after the upstream fetch.",
"items": {
"additionalProperties": {},
"description": "One BrAPI location record.",
"properties": {
"abbreviation": {
"description": "Short abbreviation.",
"type": [
"string",
"null"
]
},
"altitude": {
"description": "Altitude in meters above sea level.",
"type": [
"number",
"null"
]
},
"coordinates": {
"anyOf": [
{
"additionalProperties": {},
"properties": {},
"type": "object"
},
{
"type": "null"
}
],
"description": "BrAPI v2 GeoJSON Feature carrying [lon, lat, alt?] in geometry.coordinates."
},
"countryCode": {
"description": "ISO 3166-1 alpha-3 country code.",
"type": [
"string",
"null"
]
},
"countryName": {
"description": "Display name of the country.",
"type": [
"string",
"null"
]
},
"documentationURL": {
"description": "URL pointing at extra documentation.",
"type": [
"string",
"null"
]
},
"instituteAddress": {
"description": "Postal address of the institute.",
"type": [
"string",
"null"
]
},
"instituteName": {
"description": "Owning institute display name.",
"type": [
"string",
"null"
]
},
"latitude": {
"description": "WGS84 latitude in decimal degrees (legacy field; modern servers use coordinates).",
"type": [
"number",
"null"
]
},
"locationDbId": {
"description": "Server-side identifier for the location.",
"type": "string"
},
"locationName": {
"description": "Display name.",
"type": [
"string",
"null"
]
},
"locationType": {
"description": "Type of location (e.g. \"Research Station\", \"Field\", \"Greenhouse\").",
"type": [
"string",
"null"
]
},
"longitude": {
"description": "WGS84 longitude in decimal degrees (legacy field; modern servers use coordinates).",
"type": [
"number",
"null"
]
}
},
"required": [
"locationDbId"
],
"type": "object"
},
"type": "array"
},
"returnedCount": {
"description": "Length of results[] after any bbox filtering.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"totalCount": {
"description": "Total rows reported by the server (or the post-bbox count when a bbox filter is active).",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"warnings": {
"description": "Advisory messages (bbox malformed, filter overrides, capability gaps).",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
}
},
{
"description": "Pull observation records filtered by study, germplasm, variable, season, or observation unit. When the upstream total exceeds loadLimit, the full result set is materialized as a dataframe — query it with brapi_dataframe_query (SQL).",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"alias": {
"description": "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.",
"pattern": "^[a-zA-Z0-9_-]+$",
"type": "string"
},
"extraFilters": {
"additionalProperties": {},
"description": "Extra BrAPI filters forwarded verbatim. Valid keys vary by endpoint; brapi_describe_filters enumerates them. Named params on this tool take precedence on conflict.",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"germplasm": {
"description": "Filter by germplasmDbIds.",
"items": {
"type": "string"
},
"type": "array"
},
"loadLimit": {
"description": "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.",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"type": "integer"
},
"observationLevels": {
"description": "Observation unit level (plot, plant, field, etc.).",
"items": {
"type": "string"
},
"type": "array"
},
"observationUnits": {
"description": "Filter by observationUnitDbIds.",
"items": {
"type": "string"
},
"type": "array"
},
"observations": {
"description": "Filter by observationDbIds.",
"items": {
"type": "string"
},
"type": "array"
},
"programs": {
"description": "Filter by programDbIds.",
"items": {
"type": "string"
},
"type": "array"
},
"seasons": {
"description": "Filter by seasonDbIds (e.g. \"2022\").",
"items": {
"type": "string"
},
"type": "array"
},
"studies": {
"description": "Filter by studyDbIds.",
"items": {
"type": "string"
},
"type": "array"
},
"timestampFrom": {
"description": "ISO 8601 start of the observation-time window.",
"type": "string"
},
"timestampTo": {
"description": "ISO 8601 end of the observation-time window.",
"type": "string"
},
"trials": {
"description": "Filter by trialDbIds.",
"items": {
"type": "string"
},
"type": "array"
},
"variables": {
"description": "Filter by observationVariableDbIds.",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"name": "brapi_find_observations",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"alias",
"results",
"hasMore",
"distributions",
"totalCount",
"returnedCount",
"appliedFilters",
"warnings"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"alias": {
"description": "Alias of the registered BrAPI connection the call used.",
"type": "string"
},
"appliedFilters": {
"additionalProperties": {},
"description": "The final filter map sent to the server (named + extraFilters).",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"dataframe": {
"additionalProperties": false,
"description": "Dataframe handle when the full result set was materialized as a dataframe. Query it with brapi_dataframe_query (SQL).",
"properties": {
"columnLegend": {
"additionalProperties": {
"type": "string"
},
"description": "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.",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"columns": {
"description": "Full column list of the dataframe.",
"items": {
"description": "Column name from the materialized rows.",
"type": "string"
},
"type": "array"
},
"createdAt": {
"description": "ISO 8601 timestamp the dataframe was created.",
"type": "string"
},
"expiresAt": {
"description": "ISO 8601 timestamp after which the dataframe metadata will be purged. Re-run the find_* tool to refresh, or copy results out before expiry.",
"type": "string"
},
"maxRows": {
"description": "Cap that was applied at create time, when truncation occurred.",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"type": "integer"
},
"rowCount": {
"description": "Number of rows materialized in the dataframe.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"tableName": {
"description": "Dataframe name. Use with brapi_dataframe_describe (schema + provenance) and brapi_dataframe_query (SQL).",
"type": "string"
},
"totalCount": {
"description": "Total rows reported by the upstream server (may exceed rowCount when truncated).",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"truncated": {
"description": "True when the dataframe hit a row cap before exhausting upstream.",
"type": "boolean"
}
},
"required": [
"tableName",
"rowCount",
"columns",
"createdAt",
"expiresAt"
],
"type": "object"
},
"distributions": {
"additionalProperties": false,
"description": "Value frequency per field across the full result set.",
"properties": {
"germplasmName": {
"additionalProperties": {
"type": "number"
},
"description": "Germplasm name → count of observations on that germplasm.",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"observationLevel": {
"additionalProperties": {
"type": "number"
},
"description": "Unit level (plot / plant / field) → count of observations at that level.",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"observationVariableName": {
"additionalProperties": {
"type": "number"
},
"description": "Variable name → count of observations for that trait.",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"season": {
"additionalProperties": {
"type": "number"
},
"description": "Season identifier → count of observations in that season.",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"studyName": {
"additionalProperties": {
"type": "number"
},
"description": "Study name → count of observations in that study.",
"propertyNames": {
"type": "string"
},
"type": "object"
}
},
"required": [
"observationVariableName",
"studyName",
"germplasmName",
"observationLevel",
"season"
],
"type": "object"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "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.",
"examples": [
"unknown_alias",
"all_filters_dropped"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"hasMore": {
"description": "True when more rows exist beyond the returned set.",
"type": "boolean"
},
"notice": {
"description": "Guidance when no rows were returned — how to broaden filters or retry.",
"type": "string"
},
"refinementHint": {
"description": "Suggested next-step query refinement when the result set is large.",
"type": "string"
},
"results": {
"description": "Observation rows returned in-context (up to loadLimit).",
"items": {
"additionalProperties": {},
"description": "One BrAPI observation record.",
"properties": {
"collector": {
"description": "Name or ID of the person who collected the value.",
"type": [
"string",
"null"
]
},
"germplasmDbId": {
"description": "FK to the germplasm the observation was taken on.",
"type": [
"string",
"null"
]
},
"germplasmName": {
"description": "Display name of the germplasm.",
"type": [
"string",
"null"
]
},
"observationDbId": {
"description": "Server-side identifier for the observation.",
"type": [
"string",
"null"
]
},
"observationLevel": {
"description": "Unit level — e.g. \"plot\", \"plant\", \"field\".",
"type": [
"string",
"null"
]
},
"observationTimeStamp": {
"description": "ISO 8601 timestamp of the observation.",
"type": [
"string",
"null"
]
},
"observationUnitDbId": {
"description": "FK to the observation unit (plot / plant / sample) that carries the measurement.",
"type": [
"string",
"null"
]
},
"observationUnitName": {
"description": "Display name of the observation unit.",
"type": [
"string",
"null"
]
},
"observationVariableDbId": {
"description": "FK to the observation variable (trait) measured.",
"type": [
"string",
"null"
]
},
"observationVariableName": {
"description": "Display name of the observation variable.",
"type": [
"string",
"null"
]
},
"season": {
"anyOf": [
{
"description": "Season identifier as a flat string (older BrAPI servers).",
"type": "string"
},
{
"additionalProperties": {},
"description": "Structured season block per BrAPI v2.1 — may carry seasonDbId, year, season, or seasonName. Fields vary by server; all pass through and are collapsed into a single label by format().",
"properties": {},
"type": "object"
},
{
"description": "Field present but null on the upstream.",
"type": "null"
}
],
"description": "Season — either a flat string or a structured object depending on the server. format() normalizes both into a single label."
},
"studyDbId": {
"description": "FK to the study the observation belongs to.",
"type": [
"string",
"null"
]
},
"studyName": {
"description": "Display name of the study.",
"type": [
"string",
"null"
]
},
"uploadedBy": {
"description": "Name or ID of the user who uploaded the record.",
"type": [
"string",
"null"
]
},
"value": {
"description": "Recorded measurement value (stringified per BrAPI spec).",
"type": [
"string",
"null"
]
}
},
"type": "object"
},
"type": "array"
},
"returnedCount": {
"description": "Length of results[].",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"totalCount": {
"description": "Total rows reported by the server.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"warnings": {
"description": "Advisory messages (filter overrides, partial data, capability gaps).",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
}
},
{
"description": "Locate studies matching crop, trial type, season, location, or program. Enriches results with program/trial/location context in one call. When the upstream total exceeds loadLimit, the full result set is materialized as a dataframe — query it with brapi_dataframe_query (SQL).",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"active": {
"description": "Restrict to active / inactive studies.",
"type": "boolean"
},
"alias": {
"description": "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.",
"pattern": "^[a-zA-Z0-9_-]+$",
"type": "string"
},
"crop": {
"description": "Filter by common crop name (single value).",
"type": "string"
},
"extraFilters": {
"additionalProperties": {},
"description": "Extra BrAPI filters forwarded verbatim. Valid keys vary by endpoint; brapi_describe_filters enumerates them. Named params on this tool take precedence on conflict.",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"loadLimit": {
"description": "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.",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"type": "integer"
},
"locations": {
"description": "Filter by locationDbIds (server-side identifiers, not display names).",
"items": {
"type": "string"
},
"type": "array"
},
"programs": {
"description": "Filter by programDbIds.",
"items": {
"type": "string"
},
"type": "array"
},
"seasons": {
"description": "Filter by seasons (e.g. \"2022\").",
"items": {
"type": "string"
},
"type": "array"
},
"studyNames": {
"description": "Filter by study display name.",
"items": {
"type": "string"
},
"type": "array"
},
"trialTypes": {
"description": "Filter by study types.",
"items": {
"type": "string"
},
"type": "array"
},
"trials": {
"description": "Filter by trialDbIds.",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"name": "brapi_find_studies",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"alias",
"results",
"hasMore",
"distributions",
"totalCount",
"returnedCount",
"appliedFilters",
"warnings"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"alias": {
"description": "Alias of the registered BrAPI connection the call used.",
"type": "string"
},
"appliedFilters": {
"additionalProperties": {},
"description": "The final filter map sent to the server (named + extraFilters).",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"dataframe": {
"additionalProperties": false,
"description": "Dataframe handle when the full result set was materialized as a dataframe. Query it with brapi_dataframe_query (SQL).",
"properties": {
"columnLegend": {
"additionalProperties": {
"type": "string"
},
"description": "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.",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"columns": {
"description": "Full column list of the dataframe.",
"items": {
"description": "Column name from the materialized rows.",
"type": "string"
},
"type": "array"
},
"createdAt": {
"description": "ISO 8601 timestamp the dataframe was created.",
"type": "string"
},
"expiresAt": {
"description": "ISO 8601 timestamp after which the dataframe metadata will be purged. Re-run the find_* tool to refresh, or copy results out before expiry.",
"type": "string"
},
"maxRows": {
"description": "Cap that was applied at create time, when truncation occurred.",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"type": "integer"
},
"rowCount": {
"description": "Number of rows materialized in the dataframe.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"tableName": {
"description": "Dataframe name. Use with brapi_dataframe_describe (schema + provenance) and brapi_dataframe_query (SQL).",
"type": "string"
},
"totalCount": {
"description": "Total rows reported by the upstream server (may exceed rowCount when truncated).",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"truncated": {
"description": "True when the dataframe hit a row cap before exhausting upstream.",
"type": "boolean"
}
},
"required": [
"tableName",
"rowCount",
"columns",
"createdAt",
"expiresAt"
],
"type": "object"
},
"distributions": {
"additionalProperties": false,
"description": "Value frequency per field across the full result set.",
"properties": {
"commonCropName": {
"additionalProperties": {
"type": "number"
},
"description": "Common crop name → count of rows for that crop.",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"locationName": {
"additionalProperties": {
"type": "number"
},
"description": "Location name → count of rows at that site.",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"programName": {
"additionalProperties": {
"type": "number"
},
"description": "Program name → count of rows with that program.",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"seasons": {
"additionalProperties": {
"type": "number"
},
"description": "Season identifier → count of rows in that season.",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"studyType": {
"additionalProperties": {
"type": "number"
},
"description": "Study type → count of rows with that type.",
"propertyNames": {
"type": "string"
},
"type": "object"
}
},
"required": [
"programName",
"studyType",
"seasons",
"locationName",
"commonCropName"
],
"type": "object"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "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.",
"examples": [
"unknown_alias",
"all_filters_dropped"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"hasMore": {
"description": "True when more rows exist beyond the returned set.",
"type": "boolean"
},
"notice": {
"description": "Guidance when no rows were returned — how to broaden filters or retry.",
"type": "string"
},
"refinementHint": {
"description": "Suggested next-step query refinement when the result set is large.",
"type": "string"
},
"results": {
"description": "Rows returned in-context (up to loadLimit).",
"items": {
"additionalProperties": {},
"description": "One BrAPI study record.",
"properties": {
"active": {
"description": "True while the study is open for data capture.",
"type": [
"boolean",
"null"
]
},
"commonCropName": {
"description": "Common crop name (e.g. \"Maize\", \"Wheat\").",
"type": [
"string",
"null"
]
},
"endDate": {
"description": "ISO 8601 end date.",
"type": [
"string",
"null"
]
},
"locationDbId": {
"description": "FK to location; resolve via `brapi_get_study`.",
"type": [
"string",
"null"
]
},
"locationName": {
"description": "Display name of the study site.",
"type": [
"string",
"null"
]
},
"programDbId": {
"description": "FK to program; resolve via `brapi_get_study`.",
"type": [
"string",
"null"
]
},
"programName": {
"description": "Display name of the owning program.",
"type": [
"string",
"null"
]
},
"seasons": {
"anyOf": [
{
"items": {
"description": "Season identifier — typically a year like \"2022\". Nullable: some Breedbase deployments emit a null entry when the study is missing a season.",
"type": [
"string",
"null"
]
},
"type": "array"
},
{
"type": "null"
}
],
"description": "Season identifiers this study spans."
},
"startDate": {
"description": "ISO 8601 start date.",
"type": [
"string",
"null"
]
},
"studyCode": {
"description": "Short code or alias for the study.",
"type": [
"string",
"null"
]
},
"studyDbId": {
"description": "Server-side identifier for the study.",
"type": "string"
},
"studyDescription": {
"description": "Free-form description.",
"type": [
"string",
"null"
]
},
"studyName": {
"description": "Display name.",
"type": [
"string",
"null"
]
},
"studyPUI": {
"description": "Persistent unique identifier (URI).",
"type": [
"string",
"null"
]
},
"studyType": {
"description": "E.g. \"Yield Trial\", \"Phenotyping\".",
"type": [
"string",
"null"
]
},
"trialDbId": {
"description": "FK to trial; resolve via `brapi_get_study`.",
"type": [
"string",
"null"
]
},
"trialName": {
"description": "Display name of the owning trial.",
"type": [
"string",
"null"
]
}
},
"required": [
"studyDbId"
],
"type": "object"
},
"type": "array"
},
"returnedCount": {
"description": "Length of results[].",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"totalCount": {
"description": "Total rows reported by the server.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"warnings": {
"description": "Advisory messages (filter overrides, partial data).",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
}
},
{
"description": "Find observation variables (traits) by name, trait class, ontology term, or free-text query. Free-text queries are ranked against the returned set and may resolve to ontology URIs when the server advertises them. When the upstream total exceeds loadLimit, the full result set is materialized as a dataframe — query it with brapi_dataframe_query (SQL).",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"alias": {
"description": "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.",
"pattern": "^[a-zA-Z0-9_-]+$",
"type": "string"
},
"crop": {
"description": "Filter by common crop name (single value).",
"type": "string"
},
"extraFilters": {
"additionalProperties": {},
"description": "Extra BrAPI filters forwarded verbatim. Valid keys vary by endpoint; brapi_describe_filters enumerates them. Named params on this tool take precedence on conflict.",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"loadLimit": {
"description": "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.",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"type": "integer"
},
"methods": {
"description": "Filter by methodDbIds.",
"items": {
"type": "string"
},
"type": "array"
},
"ontologies": {
"description": "Filter by ontologyDbIds.",
"items": {
"type": "string"
},
"type": "array"
},
"scales": {
"description": "Filter by scaleDbIds.",
"items": {
"type": "string"
},
"type": "array"
},
"studies": {
"description": "Filter by studyDbIds.",
"items": {
"type": "string"
},
"type": "array"
},
"text": {
"description": "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.",
"type": "string"
},
"traitClasses": {
"description": "Filter by trait class.",
"items": {
"type": "string"
},
"type": "array"
},
"variableNames": {
"description": "Filter by exact observationVariableNames.",
"items": {
"type": "string"
},
"type": "array"
},
"variablePUIs": {
"description": "Filter by persistent ontology URIs.",
"items": {
"type": "string"
},
"type": "array"
},
"variables": {
"description": "Filter by observationVariableDbIds.",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"name": "brapi_find_variables",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"alias",
"results",
"hasMore",
"distributions",
"ontologyCandidates",
"totalCount",
"returnedCount",
"appliedFilters",
"warnings"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"alias": {
"description": "Alias of the registered BrAPI connection the call used.",
"type": "string"
},
"appliedFilters": {
"additionalProperties": {},
"description": "The final filter map sent to the server (named + extraFilters).",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"dataframe": {
"additionalProperties": false,
"description": "Dataframe handle when the full result set was materialized as a dataframe. Query it with brapi_dataframe_query (SQL).",
"properties": {
"columnLegend": {
"additionalProperties": {
"type": "string"
},
"description": "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.",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"columns": {
"description": "Full column list of the dataframe.",
"items": {
"description": "Column name from the materialized rows.",
"type": "string"
},
"type": "array"
},
"createdAt": {
"description": "ISO 8601 timestamp the dataframe was created.",
"type": "string"
},
"expiresAt": {
"description": "ISO 8601 timestamp after which the dataframe metadata will be purged. Re-run the find_* tool to refresh, or copy results out before expiry.",
"type": "string"
},
"maxRows": {
"description": "Cap that was applied at create time, when truncation occurred.",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"type": "integer"
},
"rowCount": {
"description": "Number of rows materialized in the dataframe.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"tableName": {
"description": "Dataframe name. Use with brapi_dataframe_describe (schema + provenance) and brapi_dataframe_query (SQL).",
"type": "string"
},
"totalCount": {
"description": "Total rows reported by the upstream server (may exceed rowCount when truncated).",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"truncated": {
"description": "True when the dataframe hit a row cap before exhausting upstream.",
"type": "boolean"
}
},
"required": [
"tableName",
"rowCount",
"columns",
"createdAt",
"expiresAt"
],
"type": "object"
},
"distributions": {
"additionalProperties": false,
"description": "Value frequency per field across the full result set.",
"properties": {
"ontologyDbId": {
"additionalProperties": {
"type": "number"
},
"description": "Ontology ID → count of variables in that ontology.",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"scaleName": {
"additionalProperties": {
"type": "number"
},
"description": "Scale name → count of variables using that scale.",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"traitClass": {
"additionalProperties": {
"type": "number"
},
"description": "Trait class → count of variables in that class.",
"propertyNames": {
"type": "string"
},
"type": "object"
}
},
"required": [
"ontologyDbId",
"traitClass",
"scaleName"
],
"type": "object"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "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.",
"examples": [
"unknown_alias",
"all_filters_dropped"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"hasMore": {
"description": "True when more rows exist beyond the returned set.",
"type": "boolean"
},
"notice": {
"description": "Guidance when no rows were returned — how to broaden filters or retry.",
"type": "string"
},
"ontologyCandidates": {
"description": "Top ranked candidates from the free-text query (if any). Empty when `text` was not supplied.",
"items": {
"additionalProperties": false,
"description": "One ranked ontology candidate from a free-text query.",
"properties": {
"description": {
"description": "Trait description, when available.",
"type": "string"
},
"name": {
"description": "Display name of the candidate.",
"type": "string"
},
"observationVariableDbId": {
"description": "Server-side variable DbId of the source row, when present.",
"type": "string"
},
"ontologyDbId": {
"description": "Owning ontology ID.",
"type": "string"
},
"source": {
"description": "How the candidate was ranked — PUI exact / name / synonym / trait-class.",
"enum": [
"puiMatch",
"nameMatch",
"synonymMatch",
"traitClassMatch"
],
"type": "string"
},
"synonyms": {
"description": "Combined variable + trait synonyms.",
"items": {
"description": "Registered synonym.",
"type": "string"
},
"type": "array"
},
"termId": {
"description": "Ontology term ID / PUI when available (e.g. \"CO_334:0000013\").",
"type": "string"
}
},
"required": [
"source"
],
"type": "object"
},
"type": "array"
},
"refinementHint": {
"description": "Suggested next-step query refinement when the result set is large.",
"type": "string"
},
"results": {
"description": "Observation variable rows returned in-context (up to loadLimit). Rows matching `text` are promoted to the top when the free-text query produces candidates.",
"items": {
"additionalProperties": {},
"description": "One BrAPI observation variable record.",
"properties": {
"commonCropName": {
"description": "Common crop name this variable is scoped to.",
"type": [
"string",
"null"
]
},
"method": {
"anyOf": [
{
"additionalProperties": {},
"properties": {
"methodDbId": {
"description": "FK to the method.",
"type": [
"string",
"null"
]
},
"methodName": {
"description": "Display name of the method.",
"type": [
"string",
"null"
]
}
},
"type": "object"
},
{
"type": "null"
}
],
"description": "Measurement method or protocol used to collect this variable."
},
"observationVariableDbId": {
"description": "Server-side identifier for the observation variable.",
"type": "string"
},
"observationVariableName": {
"description": "Display name.",
"type": [
"string",
"null"
]
},
"observationVariablePUI": {
"description": "Persistent unique identifier — typically an ontology term URI.",
"type": [
"string",
"null"
]
},
"ontologyDbId": {
"description": "FK to the owning ontology.",
"type": [
"string",
"null"
]
},
"ontologyName": {
"description": "Display name of the owning ontology.",
"type": [
"string",
"null"
]
},
"scale": {
"anyOf": [
{
"additionalProperties": {},
"properties": {
"dataType": {
"description": "Scale data type (e.g. \"Numerical\", \"Categorical\", \"Date\", \"Text\").",
"type": [
"string",
"null"
]
},
"scaleDbId": {
"description": "FK to the scale.",
"type": [
"string",
"null"
]
},
"scaleName": {
"description": "Display name of the scale.",
"type": [
"string",
"null"
]
}
},
"type": "object"
},
{
"type": "null"
}
],
"description": "Scale used to record this variable (units / type / range)."
},
"trait": {
"anyOf": [
{
"additionalProperties": {},
"properties": {
"description": {
"description": "Free-text trait description.",
"type": [
"string",
"null"
]
},
"synonyms": {
"anyOf": [
{
"items": {
"description": "Trait synonym value.",
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"description": "Registered trait synonyms."
},
"traitClass": {
"description": "High-level trait grouping (e.g. \"agronomic\", \"morphological\").",
"type": [
"string",
"null"
]
},
"traitDbId": {
"description": "FK to the trait.",
"type": [
"string",
"null"
]
},
"traitName": {
"description": "Display name of the trait.",
"type": [
"string",
"null"
]
}
},
"type": "object"
},
{
"type": "null"
}
],
"description": "The biological trait this variable measures."
}
},
"required": [
"observationVariableDbId"
],
"type": "object"
},
"type": "array"
},
"returnedCount": {
"description": "Length of results[].",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"totalCount": {
"description": "Total rows reported by the server.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"warnings": {
"description": "Advisory messages (filter overrides, partial data, capability gaps).",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
}
},
{
"description": "Find variant records by variant set, reference sequence, or genomic region (start/end, 1-based inclusive / exclusive). When the upstream total exceeds loadLimit, the full result set is materialized as a dataframe — query it with brapi_dataframe_query (SQL).",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"alias": {
"description": "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.",
"pattern": "^[a-zA-Z0-9_-]+$",
"type": "string"
},
"end": {
"description": "Exclusive 1-based end.",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"type": "integer"
},
"extraFilters": {
"additionalProperties": {},
"description": "Extra BrAPI filters forwarded verbatim. Valid keys vary by endpoint; brapi_describe_filters enumerates them. Named params on this tool take precedence on conflict.",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"loadLimit": {
"description": "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.",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"type": "integer"
},
"referenceName": {
"description": "Reference display name (e.g. \"chr01\", \"chr1\").",
"type": "string"
},
"references": {
"description": "Filter by referenceDbIds.",
"items": {
"type": "string"
},
"type": "array"
},
"start": {
"description": "Inclusive 1-based start.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"variantSets": {
"description": "Filter by variantSetDbIds.",
"items": {
"type": "string"
},
"type": "array"
},
"variants": {
"description": "Filter by variantDbIds.",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"name": "brapi_find_variants",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"alias",
"results",
"hasMore",
"distributions",
"totalCount",
"returnedCount",
"appliedFilters",
"warnings"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"alias": {
"description": "Alias of the registered BrAPI connection the call used.",
"type": "string"
},
"appliedFilters": {
"additionalProperties": {},
"description": "The final filter map sent to the server (named + extraFilters).",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"dataframe": {
"additionalProperties": false,
"description": "Dataframe handle when the full result set was materialized as a dataframe. Query it with brapi_dataframe_query (SQL).",
"properties": {
"columnLegend": {
"additionalProperties": {
"type": "string"
},
"description": "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.",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"columns": {
"description": "Full column list of the dataframe.",
"items": {
"description": "Column name from the materialized rows.",
"type": "string"
},
"type": "array"
},
"createdAt": {
"description": "ISO 8601 timestamp the dataframe was created.",
"type": "string"
},
"expiresAt": {
"description": "ISO 8601 timestamp after which the dataframe metadata will be purged. Re-run the find_* tool to refresh, or copy results out before expiry.",
"type": "string"
},
"maxRows": {
"description": "Cap that was applied at create time, when truncation occurred.",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"type": "integer"
},
"rowCount": {
"description": "Number of rows materialized in the dataframe.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"tableName": {
"description": "Dataframe name. Use with brapi_dataframe_describe (schema + provenance) and brapi_dataframe_query (SQL).",
"type": "string"
},
"totalCount": {
"description": "Total rows reported by the upstream server (may exceed rowCount when truncated).",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"truncated": {
"description": "True when the dataframe hit a row cap before exhausting upstream.",
"type": "boolean"
}
},
"required": [
"tableName",
"rowCount",
"columns",
"createdAt",
"expiresAt"
],
"type": "object"
},
"distributions": {
"additionalProperties": false,
"description": "Value frequency per field across the full result set.",
"properties": {
"referenceName": {
"additionalProperties": {
"type": "number"
},
"description": "Reference sequence name → count of variants on that reference.",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"variantSetDbId": {
"additionalProperties": {
"type": "number"
},
"description": "Variant set ID → count of variants in that set.",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"variantType": {
"additionalProperties": {
"type": "number"
},
"description": "Variant type → count of variants of that type.",
"propertyNames": {
"type": "string"
},
"type": "object"
}
},
"required": [
"variantType",
"referenceName",
"variantSetDbId"
],
"type": "object"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "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.",
"examples": [
"unknown_alias",
"all_filters_dropped"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"hasMore": {
"description": "True when more rows exist beyond the returned set.",
"type": "boolean"
},
"notice": {
"description": "Guidance when no rows were returned — how to broaden filters or retry.",
"type": "string"
},
"refinementHint": {
"description": "Suggested next-step query refinement when the result set is large.",
"type": "string"
},
"results": {
"description": "Variant rows returned in-context (up to loadLimit).",
"items": {
"additionalProperties": {},
"description": "One BrAPI variant record.",
"properties": {
"alternateBases": {
"anyOf": [
{
"items": {
"description": "Alternate allele sequence.",
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"description": "Alternate alleles observed at this position."
},
"end": {
"description": "1-based exclusive end position.",
"type": [
"number",
"null"
]
},
"filtersApplied": {
"description": "True when QC filters were evaluated on this variant.",
"type": [
"boolean",
"null"
]
},
"filtersFailed": {
"anyOf": [
{
"items": {
"description": "Filter ID that failed.",
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"description": "IDs of QC filters this variant failed, when any."
},
"filtersPassed": {
"description": "True when the variant passed all QC filters.",
"type": [
"boolean",
"null"
]
},
"referenceBases": {
"description": "Reference allele sequence at the variant position.",
"type": [
"string",
"null"
]
},
"referenceName": {
"description": "Reference sequence name (e.g. \"chr01\").",
"type": [
"string",
"null"
]
},
"start": {
"description": "1-based inclusive start position.",
"type": [
"number",
"null"
]
},
"variantDbId": {
"description": "Server-side identifier for the variant.",
"type": "string"
},
"variantNames": {
"anyOf": [
{
"items": {
"description": "Variant name or alias.",
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"description": "Known names / aliases for this variant."
},
"variantSetDbId": {
"anyOf": [
{
"description": "Single variant-set FK (older BrAPI servers).",
"type": "string"
},
{
"description": "Variant-set FK array — a variant may belong to multiple sets.",
"items": {
"description": "One variant-set FK.",
"type": "string"
},
"type": "array"
},
{
"description": "Field present but null on the upstream.",
"type": "null"
}
],
"description": "FK to the variant set(s) this variant belongs to. May be a string or string[] depending on server."
},
"variantSetDbIds": {
"anyOf": [
{
"items": {
"description": "Variant-set FK.",
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"description": "Plural-form FK array per BrAPI v2.1 spec, when the server uses it."
},
"variantType": {
"description": "Variant type (e.g. \"SNP\", \"INDEL\", \"DUP\").",
"type": [
"string",
"null"
]
}
},
"required": [
"variantDbId"
],
"type": "object"
},
"type": "array"
},
"returnedCount": {
"description": "Length of results[].",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"totalCount": {
"description": "Total rows reported by the server.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"warnings": {
"description": "Advisory messages (filter overrides, partial data, capability gaps).",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
}
},
{
"description": "Aggregate a single germplasm's observations across every study it appears in, returning per-variable summary statistics (n, mean, median, sd, min, max), the contributing studies, and seasons. Study-anchored: discovers the germplasm's studies first (with a dialect-honor cross-check, capped at 200 studies), then pulls observations per study — avoids the unanchored germplasm-only pull that stalls on SGN/Breedbase. Pass an explicit studyDbIds set to skip discovery and its 200-study cap — e.g. process a chunk of the full study list retrieved via brapi_find_studies with extraFilters.germplasmDbIds. For the underlying observation matrix, use brapi_build_phenotype_matrix.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"alias": {
"description": "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.",
"pattern": "^[a-zA-Z0-9_-]+$",
"type": "string"
},
"germplasmDbId": {
"description": "The germplasmDbId to summarize performance for.",
"minLength": 1,
"type": "string"
},
"studyDbIds": {
"description": "Optional explicit set of studyDbIds to aggregate over. When supplied, skips automatic study discovery and its 200-study cap entirely — use it to process a specific slice of studies, e.g. the full germplasm-scoped study set retrieved via brapi_find_studies with extraFilters.germplasmDbIds. Omit to let the tool discover the germplasm’s studies automatically.",
"items": {
"minLength": 1,
"type": "string"
},
"type": "array"
},
"variables": {
"description": "Optional subset of observationVariableDbIds to aggregate. Omit to include every variable observed for the germplasm.",
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"germplasmDbId"
],
"type": "object"
},
"name": "brapi_germplasm_performance",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"alias",
"germplasmDbId",
"studyCount",
"studyDbIds",
"perVariable",
"warnings"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"alias": {
"description": "Alias of the registered BrAPI connection used.",
"type": "string"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "Machine-readable failure mode. Declared by this tool: `unknown_alias`: No connection has been registered under the requested alias. `germplasm_not_found`: Upstream returned no germplasm record for the requested germplasmDbId. Other values are possible when a failure originates below the handler.",
"examples": [
"unknown_alias",
"germplasm_not_found"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"germplasmDbId": {
"description": "The germplasm that was analyzed.",
"type": "string"
},
"germplasmName": {
"description": "Display name of the germplasm, when the server provides one.",
"type": "string"
},
"perVariable": {
"description": "Per-variable aggregates, sorted by observationVariableDbId.",
"items": {
"additionalProperties": false,
"description": "Aggregated statistics for one observation variable across the studies the germplasm appears in.",
"properties": {
"max": {
"description": "Maximum value — numeric max when numeric, else lexical max.",
"type": "string"
},
"mean": {
"description": "Arithmetic mean of numeric values (omitted for non-numeric traits).",
"type": "number"
},
"median": {
"description": "Median of numeric values (omitted for non-numeric traits).",
"type": "number"
},
"min": {
"description": "Minimum value — numeric min when numeric, else lexical min.",
"type": "string"
},
"n": {
"description": "Number of observations of this variable for the germplasm.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"observationVariableDbId": {
"description": "Observation variable identifier.",
"type": "string"
},
"observationVariableName": {
"description": "Display name of the variable.",
"type": "string"
},
"sd": {
"description": "Sample standard deviation (n−1) of numeric values; omitted when n < 2 or non-numeric.",
"type": "number"
},
"seasons": {
"description": "Distinct season labels across the observations (empty when the server carries no season).",
"items": {
"type": "string"
},
"type": "array"
},
"studyCount": {
"description": "Number of distinct studies contributing observations of this variable.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"studyDbIds": {
"description": "Distinct studyDbIds contributing observations of this variable.",
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"observationVariableDbId",
"n",
"studyCount",
"studyDbIds",
"seasons"
],
"type": "object"
},
"type": "array"
},
"studyCount": {
"description": "Number of distinct studies that contributed any observation.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"studyDbIds": {
"description": "Distinct studyDbIds that contributed observations.",
"items": {
"type": "string"
},
"type": "array"
},
"warnings": {
"description": "Advisory messages (study-discovery limits, dropped filters, fallback paths, per-study failures).",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
}
},
{
"description": "Fetch a single germplasm by DbId with attributes and direct parents. Response companions report study count, direct parent count, and direct descendant count — signals for pedigree depth and observation coverage.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"alias": {
"description": "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.",
"pattern": "^[a-zA-Z0-9_-]+$",
"type": "string"
},
"germplasmDbId": {
"description": "Germplasm identifier.",
"minLength": 1,
"type": "string"
}
},
"required": [
"germplasmDbId"
],
"type": "object"
},
"name": "brapi_get_germplasm",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"alias",
"germplasm",
"parents",
"attributes",
"directParentCount",
"warnings"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"alias": {
"description": "Alias of the registered BrAPI connection the call used.",
"type": "string"
},
"attributes": {
"description": "Germplasm attributes from /germplasm/{id}/attributes.",
"items": {
"additionalProperties": {},
"description": "One germplasm attribute record.",
"properties": {
"attributeDbId": {
"description": "Attribute identifier.",
"type": [
"string",
"null"
]
},
"attributeName": {
"description": "Attribute display name.",
"type": [
"string",
"null"
]
},
"attributeValue": {
"description": "Recorded value (stringified).",
"type": [
"string",
"null"
]
},
"determinedDate": {
"description": "ISO 8601 date the attribute was determined.",
"type": [
"string",
"null"
]
}
},
"type": "object"
},
"type": "array"
},
"directDescendantCount": {
"description": "Count of direct descendants from /germplasm/{id}/progeny.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"directParentCount": {
"description": "Count of direct parents.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "Machine-readable failure mode. Declared by this tool: `unknown_alias`: No connection has been registered under the requested alias. `germplasm_not_found`: Upstream returned no germplasm record for the requested DbId. Other values are possible when a failure originates below the handler.",
"examples": [
"unknown_alias",
"germplasm_not_found"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"germplasm": {
"additionalProperties": {},
"description": "Canonical germplasm record as returned by `/germplasm/{id}`.",
"properties": {
"accessionNumber": {
"description": "Gene-bank catalog number.",
"type": [
"string",
"null"
]
},
"biologicalStatusOfAccessionDescription": {
"description": "MCPD biological-status label.",
"type": [
"string",
"null"
]
},
"collection": {
"description": "Collection name.",
"type": [
"string",
"null"
]
},
"commonCropName": {
"description": "Common crop name.",
"type": [
"string",
"null"
]
},
"countryOfOriginCode": {
"description": "ISO 3166-1 alpha-3 country code.",
"type": [
"string",
"null"
]
},
"defaultDisplayName": {
"description": "Preferred display label.",
"type": [
"string",
"null"
]
},
"genus": {
"description": "Botanical genus.",
"type": [
"string",
"null"
]
},
"germplasmDbId": {
"description": "Server-side identifier for the germplasm.",
"type": "string"
},
"germplasmName": {
"description": "Display name.",
"type": [
"string",
"null"
]
},
"germplasmOrigin": {
"anyOf": [
{
"items": {
"additionalProperties": {},
"description": "One origin record (collection coordinates and uncertainty per BrAPI v2).",
"properties": {},
"type": "object"
},
"type": "array"
},
{
"type": "null"
}
],
"description": "Origin records — array of collection-site objects per BrAPI v2."
},
"germplasmPUI": {
"description": "Persistent unique identifier (URI).",
"type": [
"string",
"null"
]
},
"instituteCode": {
"description": "FAO WIEWS institute code.",
"type": [
"string",
"null"
]
},
"instituteName": {
"description": "Display name of the holding institute.",
"type": [
"string",
"null"
]
},
"pedigree": {
"description": "Pedigree as a free-text string.",
"type": [
"string",
"null"
]
},
"species": {
"description": "Botanical species.",
"type": [
"string",
"null"
]
},
"subtaxa": {
"description": "Botanical subtaxa.",
"type": [
"string",
"null"
]
},
"synonyms": {
"anyOf": [
{
"items": {
"additionalProperties": {},
"description": "Registered synonym for this germplasm.",
"properties": {
"synonym": {
"description": "Synonym value.",
"type": [
"string",
"null"
]
},
"type": {
"description": "Synonym type (e.g. \"COMMON\", \"SYNONYM\").",
"type": [
"string",
"null"
]
}
},
"type": "object"
},
"type": "array"
},
{
"type": "null"
}
],
"description": "All registered synonyms."
}
},
"required": [
"germplasmDbId"
],
"type": "object"
},
"parents": {
"description": "Direct parents from /germplasm/{id}/pedigree.",
"items": {
"additionalProperties": {},
"description": "One direct parent of the germplasm.",
"properties": {
"germplasmDbId": {
"description": "FK to the parent germplasm.",
"type": [
"string",
"null"
]
},
"germplasmName": {
"description": "Display name of the parent germplasm.",
"type": [
"string",
"null"
]
},
"parentType": {
"description": "E.g. \"MALE\", \"FEMALE\", \"SELF\".",
"type": [
"string",
"null"
]
}
},
"type": "object"
},
"type": "array"
},
"studyCount": {
"description": "How many studies this germplasm has appeared in.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"warnings": {
"description": "Advisory messages — failed sub-endpoint lookups, missing counts.",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
}
},
{
"description": "Fetch image bytes for up to 5 imageDbIds and return them inline as `type: image` content blocks. Falls back to the metadata `imageURL` when the server lacks dedicated image-content delivery. No filesystem side-effects.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"alias": {
"description": "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.",
"pattern": "^[a-zA-Z0-9_-]+$",
"type": "string"
},
"imageDbIds": {
"description": "1–5 image identifiers.",
"items": {
"minLength": 1,
"type": "string"
},
"maxItems": 5,
"minItems": 1,
"type": "array"
}
},
"required": [
"imageDbIds"
],
"type": "object"
},
"name": "brapi_get_image",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"alias",
"images",
"errors",
"warnings"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"alias": {
"description": "Alias of the registered BrAPI connection the call used.",
"type": "string"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "Machine-readable failure mode. Declared by this tool: `unknown_alias`: No connection has been registered under the requested alias. `images_unsupported`: BrAPI server does not advertise /images in /serverinfo. Other values are possible when a failure originates below the handler.",
"examples": [
"unknown_alias",
"images_unsupported"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"errors": {
"description": "Images that could not be loaded, one entry per id.",
"items": {
"additionalProperties": false,
"description": "Per-image error entry returned when a fetch fails.",
"properties": {
"error": {
"description": "Reason the image could not be loaded.",
"type": "string"
},
"imageDbId": {
"description": "Image identifier the error applies to.",
"type": "string"
}
},
"required": [
"imageDbId",
"error"
],
"type": "object"
},
"type": "array"
},
"images": {
"description": "Successfully loaded images.",
"items": {
"additionalProperties": false,
"description": "Successfully loaded image payload.",
"properties": {
"data": {
"description": "Base64-encoded image bytes.",
"type": "string"
},
"imageDbId": {
"description": "Server-side identifier for the image.",
"type": "string"
},
"metadata": {
"additionalProperties": {},
"description": "Upstream metadata for this image.",
"properties": {
"copyright": {
"description": "Copyright or rights notice.",
"type": "string"
},
"description": {
"description": "Free-text description.",
"type": "string"
},
"imageDbId": {
"description": "Server-side identifier for the image.",
"type": "string"
},
"imageFileName": {
"description": "Original uploaded filename.",
"type": "string"
},
"imageHeight": {
"description": "Pixel height. Coerced from string when the upstream emits a numeric string.",
"type": "number"
},
"imageName": {
"description": "Display name.",
"type": "string"
},
"imageTimeStamp": {
"description": "ISO 8601 capture timestamp.",
"type": "string"
},
"imageURL": {
"description": "URL where the bytes live.",
"type": "string"
},
"imageWidth": {
"description": "Pixel width. Coerced from string when the upstream emits a numeric string.",
"type": "number"
},
"mimeType": {
"description": "MIME type (e.g. \"image/jpeg\").",
"type": "string"
},
"observationUnitDbId": {
"description": "FK to the observation unit this image depicts.",
"type": "string"
},
"observationUnitName": {
"description": "Display name of the observation unit.",
"type": "string"
},
"studyDbId": {
"description": "FK to the study the image belongs to.",
"type": "string"
},
"studyName": {
"description": "Display name of the study.",
"type": "string"
}
},
"required": [
"imageDbId"
],
"type": "object"
},
"mimeType": {
"description": "Actual MIME type of the returned bytes.",
"type": "string"
},
"sizeBytes": {
"description": "Size of the returned byte payload.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"source": {
"description": "How the bytes were fetched.",
"enum": [
"imagecontent",
"imageURL"
],
"type": "string"
}
},
"required": [
"imageDbId",
"mimeType",
"sizeBytes",
"source",
"data",
"metadata"
],
"type": "object"
},
"type": "array"
},
"warnings": {
"description": "Per-image advisories for loaded payloads that appear suspect — e.g. the imageURL fallback returned a non-image MIME type, suggesting the upstream URL is broken.",
"items": {
"additionalProperties": false,
"description": "Per-image advisory for loaded-but-suspect content (e.g. non-image MIME).",
"properties": {
"imageDbId": {
"description": "Image identifier the warning applies to.",
"type": "string"
},
"warning": {
"description": "Advisory — bytes loaded but something is suspect.",
"type": "string"
}
},
"required": [
"imageDbId",
"warning"
],
"type": "object"
},
"type": "array"
}
},
"type": "object"
}
},
{
"description": "Fetch a single study by DbId with program, trial, and location fully resolved. Response includes cheap observation/observation-unit/variable counts as drill-down signals.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"alias": {
"description": "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.",
"pattern": "^[a-zA-Z0-9_-]+$",
"type": "string"
},
"studyDbId": {
"description": "Study identifier.",
"minLength": 1,
"type": "string"
}
},
"required": [
"studyDbId"
],
"type": "object"
},
"name": "brapi_get_study",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"alias",
"study",
"warnings"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"alias": {
"description": "Alias of the registered BrAPI connection the call used.",
"type": "string"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "Machine-readable failure mode. Declared by this tool: `unknown_alias`: No connection has been registered under the requested alias. `study_not_found`: Upstream returned no study record for the requested DbId. Other values are possible when a failure originates below the handler.",
"examples": [
"unknown_alias",
"study_not_found"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"location": {
"additionalProperties": {},
"description": "Resolved location record (when the study has a locationDbId and the FK lookup succeeded).",
"properties": {
"abbreviation": {
"description": "Short abbreviation.",
"type": [
"string",
"null"
]
},
"altitude": {
"description": "Altitude in meters above sea level.",
"type": [
"number",
"null"
]
},
"coordinates": {
"anyOf": [
{
"additionalProperties": {},
"properties": {},
"type": "object"
},
{
"type": "null"
}
],
"description": "BrAPI v2 GeoJSON Feature carrying [lon, lat, alt?] in geometry.coordinates."
},
"countryCode": {
"description": "ISO 3166-1 alpha-3 country code.",
"type": [
"string",
"null"
]
},
"countryName": {
"description": "Display name of the country.",
"type": [
"string",
"null"
]
},
"latitude": {
"description": "WGS84 latitude in decimal degrees (legacy field; modern servers use coordinates).",
"type": [
"number",
"null"
]
},
"locationDbId": {
"description": "Server-side identifier for the location.",
"type": "string"
},
"locationName": {
"description": "Display name.",
"type": [
"string",
"null"
]
},
"locationType": {
"description": "Type of location (e.g. \"Research Station\", \"Field\").",
"type": [
"string",
"null"
]
},
"longitude": {
"description": "WGS84 longitude in decimal degrees (legacy field; modern servers use coordinates).",
"type": [
"number",
"null"
]
}
},
"required": [
"locationDbId"
],
"type": "object"
},
"observationCount": {
"description": "Total observations recorded against this study. Omitted (with a warning) when the upstream server cannot scope the count to the study — never reported as the server-wide total.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"observationUnitCount": {
"description": "Total observation units (plots, plants, samples) in this study.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"program": {
"additionalProperties": {},
"description": "Resolved program record (when the study has a programDbId and the FK lookup succeeded).",
"properties": {
"abbreviation": {
"description": "Short abbreviation.",
"type": [
"string",
"null"
]
},
"commonCropName": {
"description": "Common crop name this program targets.",
"type": [
"string",
"null"
]
},
"documentationURL": {
"description": "URL pointing at program documentation.",
"type": [
"string",
"null"
]
},
"leadPersonName": {
"description": "Name of the program lead.",
"type": [
"string",
"null"
]
},
"programDbId": {
"description": "Server-side identifier for the program.",
"type": "string"
},
"programName": {
"description": "Display name.",
"type": [
"string",
"null"
]
}
},
"required": [
"programDbId"
],
"type": "object"
},
"study": {
"additionalProperties": {},
"description": "Canonical study record as returned by `/studies/{id}`.",
"properties": {
"active": {
"description": "True while the study is open for data capture.",
"type": [
"boolean",
"null"
]
},
"commonCropName": {
"description": "Common crop name (e.g. \"Maize\", \"Wheat\").",
"type": [
"string",
"null"
]
},
"endDate": {
"description": "ISO 8601 end date.",
"type": [
"string",
"null"
]
},
"locationDbId": {
"description": "FK to the study site.",
"type": [
"string",
"null"
]
},
"locationName": {
"description": "Display name of the study site.",
"type": [
"string",
"null"
]
},
"programDbId": {
"description": "FK to the owning program.",
"type": [
"string",
"null"
]
},
"programName": {
"description": "Display name of the owning program.",
"type": [
"string",
"null"
]
},
"seasons": {
"anyOf": [
{
"items": {
"description": "Season identifier — typically a year like \"2022\". Nullable: some Breedbase deployments emit a null entry when the study is missing a season.",
"type": [
"string",
"null"
]
},
"type": "array"
},
{
"type": "null"
}
],
"description": "Season identifiers this study spans."
},
"startDate": {
"description": "ISO 8601 start date.",
"type": [
"string",
"null"
]
},
"studyCode": {
"description": "Short code or alias for the study.",
"type": [
"string",
"null"
]
},
"studyDbId": {
"description": "Server-side identifier for the study.",
"type": "string"
},
"studyDescription": {
"description": "Free-form description.",
"type": [
"string",
"null"
]
},
"studyName": {
"description": "Display name.",
"type": [
"string",
"null"
]
},
"studyPUI": {
"description": "Persistent unique identifier (URI).",
"type": [
"string",
"null"
]
},
"studyType": {
"description": "E.g. \"Yield Trial\", \"Phenotyping\".",
"type": [
"string",
"null"
]
},
"trialDbId": {
"description": "FK to the owning trial.",
"type": [
"string",
"null"
]
},
"trialName": {
"description": "Display name of the owning trial.",
"type": [
"string",
"null"
]
}
},
"required": [
"studyDbId"
],
"type": "object"
},
"trial": {
"additionalProperties": {},
"description": "Resolved trial record (when the study has a trialDbId and the FK lookup succeeded).",
"properties": {
"active": {
"description": "True while the trial is ongoing.",
"type": [
"boolean",
"null"
]
},
"commonCropName": {
"description": "Common crop name.",
"type": [
"string",
"null"
]
},
"endDate": {
"description": "ISO 8601 end date.",
"type": [
"string",
"null"
]
},
"programDbId": {
"description": "FK to the owning program.",
"type": [
"string",
"null"
]
},
"programName": {
"description": "Display name of the owning program.",
"type": [
"string",
"null"
]
},
"startDate": {
"description": "ISO 8601 start date.",
"type": [
"string",
"null"
]
},
"trialDbId": {
"description": "Server-side identifier for the trial.",
"type": "string"
},
"trialDescription": {
"description": "Free-form description.",
"type": [
"string",
"null"
]
},
"trialName": {
"description": "Display name.",
"type": [
"string",
"null"
]
}
},
"required": [
"trialDbId"
],
"type": "object"
},
"variableCount": {
"description": "Total observation variables (traits) measured in this study. Omitted (with a warning) when the upstream server cannot scope the count to the study — never reported as the server-wide total.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"warnings": {
"description": "Advisory messages — failed FK lookups, missing counts.",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
}
},
{
"description": "Passthrough to any BrAPI GET /{path} endpoint. Returns the raw upstream envelope without enrichment or foreign-key resolution. Emits a `suggestion` field when a curated tool exists for the same data. Spills to a canvas dataframe when the upstream advertises more rows than `loadLimit` AND the result is a list shape (`result` array or `result.data` envelope); inline `result` is unchanged. Skips spillover when the caller drives paging via `params.page` / `params.pageSize`.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"alias": {
"description": "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.",
"pattern": "^[a-zA-Z0-9_-]+$",
"type": "string"
},
"loadLimit": {
"description": "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.",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"type": "integer"
},
"params": {
"additionalProperties": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"items": {
"type": [
"string",
"number"
]
},
"type": "array"
}
]
},
"description": "Query parameters to append. Arrays are repeated per BrAPI convention.",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"path": {
"description": "Endpoint path — e.g. \"/samples\", \"/methods\". Leading \"/\" is optional.",
"minLength": 1,
"type": "string"
}
},
"required": [
"path"
],
"type": "object"
},
"name": "brapi_raw_get",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"alias",
"url",
"path",
"metadata"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"alias": {
"description": "Alias of the registered BrAPI connection the call used.",
"type": "string"
},
"dataframe": {
"additionalProperties": false,
"description": "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.",
"properties": {
"columnLegend": {
"additionalProperties": {
"type": "string"
},
"description": "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.",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"columns": {
"description": "Full column list of the dataframe.",
"items": {
"description": "Column name from the materialized rows.",
"type": "string"
},
"type": "array"
},
"createdAt": {
"description": "ISO 8601 timestamp the dataframe was created.",
"type": "string"
},
"expiresAt": {
"description": "ISO 8601 timestamp after which the dataframe metadata will be purged. Re-run the find_* tool to refresh, or copy results out before expiry.",
"type": "string"
},
"maxRows": {
"description": "Cap that was applied at create time, when truncation occurred.",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"type": "integer"
},
"rowCount": {
"description": "Number of rows materialized in the dataframe.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"tableName": {
"description": "Dataframe name. Use with brapi_dataframe_describe (schema + provenance) and brapi_dataframe_query (SQL).",
"type": "string"
},
"totalCount": {
"description": "Total rows reported by the upstream server (may exceed rowCount when truncated).",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"truncated": {
"description": "True when the dataframe hit a row cap before exhausting upstream.",
"type": "boolean"
}
},
"required": [
"tableName",
"rowCount",
"columns",
"createdAt",
"expiresAt"
],
"type": "object"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "Machine-readable failure mode. Declared by this tool: `unknown_alias`: No connection has been registered under the requested alias. `cross_origin_path`: path argument was a full URL instead of a relative BrAPI route. Other values are possible when a failure originates below the handler.",
"examples": [
"unknown_alias",
"cross_origin_path"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"metadata": {
"additionalProperties": {},
"description": "BrAPI envelope metadata (pagination and any additional upstream fields).",
"properties": {
"pagination": {
"additionalProperties": {},
"description": "BrAPI pagination block. Absent when the endpoint does not paginate.",
"properties": {
"currentPage": {
"description": "0-indexed page number the server returned.",
"type": "number"
},
"pageSize": {
"description": "Rows per page.",
"type": "number"
},
"totalCount": {
"description": "Total rows matching the query across all pages.",
"type": "number"
},
"totalPages": {
"description": "Total pages at the current pageSize.",
"type": "number"
}
},
"required": [
"currentPage",
"pageSize",
"totalCount",
"totalPages"
],
"type": "object"
}
},
"type": "object"
},
"path": {
"description": "Normalized path (leading `/` preserved) that was appended to the baseUrl.",
"type": "string"
},
"result": {
"description": "Raw BrAPI `result` value — whatever shape the endpoint returns."
},
"suggestion": {
"description": "Emitted when a curated goal-shaped tool covers this endpoint.",
"type": "string"
},
"url": {
"description": "Fully resolved URL that was fetched (baseUrl + path + query string).",
"type": "string"
}
},
"type": "object"
}
},
{
"description": "Passthrough to any BrAPI POST /search/{noun} endpoint, returning the resolved envelope (async polling resolved upstream). Spills to a canvas dataframe when the upstream advertises more rows than `loadLimit` AND the result is a list shape; inline `result` is unchanged. Skips spillover when the caller drives paging via `body.page` / `body.pageSize`. No distributions or foreign-key resolution applied.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"alias": {
"description": "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.",
"pattern": "^[a-zA-Z0-9_-]+$",
"type": "string"
},
"body": {
"additionalProperties": {},
"description": "Filter body passed verbatim to POST /search/{noun}.",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"loadLimit": {
"description": "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.",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"type": "integer"
},
"noun": {
"description": "Search noun — e.g. \"observations\", \"calls\", \"germplasm\".",
"minLength": 1,
"pattern": "^[a-zA-Z0-9_-]+$",
"type": "string"
}
},
"required": [
"noun",
"body"
],
"type": "object"
},
"name": "brapi_raw_search",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"alias",
"noun",
"kind",
"metadata"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"alias": {
"description": "Alias of the registered BrAPI connection the call used.",
"type": "string"
},
"dataframe": {
"additionalProperties": false,
"description": "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.",
"properties": {
"columnLegend": {
"additionalProperties": {
"type": "string"
},
"description": "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.",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"columns": {
"description": "Full column list of the dataframe.",
"items": {
"description": "Column name from the materialized rows.",
"type": "string"
},
"type": "array"
},
"createdAt": {
"description": "ISO 8601 timestamp the dataframe was created.",
"type": "string"
},
"expiresAt": {
"description": "ISO 8601 timestamp after which the dataframe metadata will be purged. Re-run the find_* tool to refresh, or copy results out before expiry.",
"type": "string"
},
"maxRows": {
"description": "Cap that was applied at create time, when truncation occurred.",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"type": "integer"
},
"rowCount": {
"description": "Number of rows materialized in the dataframe.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"tableName": {
"description": "Dataframe name. Use with brapi_dataframe_describe (schema + provenance) and brapi_dataframe_query (SQL).",
"type": "string"
},
"totalCount": {
"description": "Total rows reported by the upstream server (may exceed rowCount when truncated).",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"truncated": {
"description": "True when the dataframe hit a row cap before exhausting upstream.",
"type": "boolean"
}
},
"required": [
"tableName",
"rowCount",
"columns",
"createdAt",
"expiresAt"
],
"type": "object"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "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.",
"examples": [
"unknown_alias",
"search_endpoint_disabled"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"kind": {
"description": "Whether the server returned inline results or we polled an async search.",
"enum": [
"sync",
"async"
],
"type": "string"
},
"metadata": {
"additionalProperties": {},
"description": "BrAPI envelope metadata (pagination and any additional upstream fields).",
"properties": {
"pagination": {
"additionalProperties": {},
"description": "BrAPI pagination block. Absent when the endpoint does not paginate.",
"properties": {
"currentPage": {
"description": "0-indexed page number the server returned.",
"type": "number"
},
"pageSize": {
"description": "Rows per page.",
"type": "number"
},
"totalCount": {
"description": "Total rows matching the query across all pages.",
"type": "number"
},
"totalPages": {
"description": "Total pages at the current pageSize.",
"type": "number"
}
},
"required": [
"currentPage",
"pageSize",
"totalCount",
"totalPages"
],
"type": "object"
}
},
"type": "object"
},
"noun": {
"description": "The `/search/{noun}` segment the body was posted to.",
"type": "string"
},
"result": {
"description": "Raw BrAPI `result` value — whatever shape the endpoint returns."
},
"searchResultsDbId": {
"description": "Populated when the server returned an async searchResultsDbId.",
"type": "string"
},
"suggestion": {
"description": "Emitted when a curated goal-shaped tool covers this search.",
"type": "string"
}
},
"type": "object"
}
},
{
"description": "Return the full orientation envelope for a registered BrAPI connection — server identity, capabilities, content counts, suggested finders, and notes. Re-running refreshes the cached capability scan; pass an alias to read a non-default connection.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"alias": {
"description": "Connection alias. 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.",
"pattern": "^[a-zA-Z0-9_-]+$",
"type": "string"
},
"forceRefresh": {
"default": false,
"description": "Bypass the cached capability profile and refetch from the server.",
"type": "boolean"
}
},
"type": "object"
},
"name": "brapi_server_info",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"alias",
"baseUrl",
"server",
"auth",
"capabilities",
"dialect",
"content",
"nextToolSuggestions",
"notes",
"fetchedAt"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"alias": {
"description": "Connection alias.",
"type": "string"
},
"attribution": {
"additionalProperties": false,
"description": "Attribution metadata for built-in known-server connections. Absent for custom (env-only) connections.",
"properties": {
"citation": {
"description": "Citation requested by the upstream when data is reused in publications.",
"type": "string"
},
"homepage": {
"description": "Public homepage of the upstream dataset.",
"type": "string"
},
"isDemo": {
"description": "True when this server hosts demo / sample data, not production records.",
"type": "boolean"
},
"license": {
"description": "License under which the upstream dataset is published (e.g. \"CC-BY\").",
"type": "string"
}
},
"required": [
"homepage",
"license",
"citation"
],
"type": "object"
},
"auth": {
"additionalProperties": false,
"description": "Auth summary for the active connection.",
"properties": {
"expiresAt": {
"description": "ISO 8601 token-expiry timestamp, when known.",
"type": "string"
},
"headerName": {
"description": "HTTP header carrying credentials.",
"type": "string"
},
"mode": {
"description": "Auth mode of the active connection.",
"enum": [
"none",
"sgn",
"oauth2",
"api_key",
"bearer"
],
"type": "string"
}
},
"required": [
"mode"
],
"type": "object"
},
"baseUrl": {
"description": "BrAPI v2 base URL for this connection.",
"type": "string"
},
"capabilities": {
"additionalProperties": false,
"description": "Capability profile derived from /serverinfo.",
"properties": {
"notableGaps": {
"description": "Common-floor services this server does NOT expose.",
"items": {
"description": "Common-floor service the server does not expose.",
"type": "string"
},
"type": "array"
},
"supported": {
"description": "Sorted list of supported service names.",
"items": {
"description": "BrAPI service name (e.g. \"studies\", \"search/germplasm\").",
"type": "string"
},
"type": "array"
},
"supportedCount": {
"description": "Total distinct services the server advertises in /calls.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
}
},
"required": [
"supportedCount",
"supported",
"notableGaps"
],
"type": "object"
},
"content": {
"additionalProperties": false,
"description": "Content summary (crops + optional totals).",
"properties": {
"crops": {
"description": "Crops the server declares via /commoncropnames.",
"items": {
"description": "Common crop name as returned by /commoncropnames.",
"type": "string"
},
"type": "array"
},
"germplasmCount": {
"description": "Total germplasm hosted, when the server exposes a cheap count.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"locationCount": {
"description": "Total locations hosted, when the server exposes a cheap count.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"programCount": {
"description": "Total programs hosted, when the server exposes a cheap count.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"studyCount": {
"description": "Total studies hosted, when the server exposes a cheap count.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
}
},
"required": [
"crops"
],
"type": "object"
},
"dialect": {
"additionalProperties": false,
"description": "Active dialect adapter — translates outbound filters and declares known-dead routes for this server.",
"properties": {
"disabledSearchEndpoints": {
"description": "POST /search nouns the active dialect treats as known-dead. Tools using these routes will refuse with a recovery hint.",
"items": {
"description": "A POST /search/{noun} route the dialect routes around.",
"type": "string"
},
"type": "array"
},
"envVar": {
"description": "Env var that pins the dialect for this alias (e.g. BRAPI_DEFAULT_DIALECT) when detection misfires.",
"type": "string"
},
"id": {
"description": "Active dialect id (e.g. \"spec\", \"cassavabase\"). Names a registered adapter that translates outbound filters and declares known-dead routes.",
"type": "string"
},
"inferredMappingCount": {
"description": "Number of filter translations inferred from naming conventions but not independently verified. A non-zero count means some result narrowing on this server may not fire as expected.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"notes": {
"description": "Dialect-level compatibility notes for this server family.",
"items": {
"description": "Verified compatibility note exposed by the active dialect.",
"type": "string"
},
"type": "array"
},
"source": {
"description": "Where the dialect id came from: env-var override, URL host match, /serverinfo serverName, organizationName, or the spec passthrough fallback.",
"enum": [
"env-override",
"url-pattern",
"server-name",
"organization-name",
"fallback"
],
"type": "string"
},
"verifiedMappingCount": {
"description": "Number of filter translations the dialect has empirically verified against a live server. Higher means more confidence in the translation table.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
}
},
"required": [
"id",
"source",
"envVar",
"disabledSearchEndpoints",
"notes"
],
"type": "object"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "Machine-readable failure mode. Declared by this tool: `unknown_alias`: No connection has been registered under the requested alias. Other values are possible when a failure originates below the handler.",
"examples": [
"unknown_alias"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"fetchedAt": {
"description": "ISO 8601 timestamp of when this envelope was composed.",
"type": "string"
},
"nextToolSuggestions": {
"description": "Entry-point finders (studies, germplasm, variables, locations — in that order) whose GET or POST /search route this server exposes under the active dialect. Empty when none apply.",
"items": {
"additionalProperties": false,
"description": "A finder the connected server supports, with the arguments to start it.",
"properties": {
"args": {
"additionalProperties": false,
"description": "Arguments to call the tool with. Alias only — narrow further with the tool filters.",
"properties": {
"alias": {
"description": "Connection alias to pass to the suggested tool.",
"type": "string"
}
},
"required": [
"alias"
],
"type": "object"
},
"reason": {
"description": "Why this tool applies to the connected server.",
"type": "string"
},
"toolName": {
"description": "Entry-point finder tool this server can serve.",
"enum": [
"brapi_find_studies",
"brapi_find_germplasm",
"brapi_find_variables",
"brapi_find_locations"
],
"type": "string"
}
},
"required": [
"toolName",
"reason",
"args"
],
"type": "object"
},
"type": "array"
},
"notes": {
"description": "Server-specific quirks or degradation notes.",
"items": {
"description": "Server-specific quirk or degradation note.",
"type": "string"
},
"type": "array"
},
"server": {
"additionalProperties": false,
"description": "Normalized server identity block.",
"properties": {
"brapiVersion": {
"description": "Highest BrAPI version the server reports.",
"type": "string"
},
"contactEmail": {
"description": "Contact email for the operator.",
"type": "string"
},
"description": {
"description": "Free-form server description.",
"type": "string"
},
"documentationURL": {
"description": "Documentation URL for this server.",
"type": "string"
},
"name": {
"description": "Server display name from /serverinfo.",
"type": "string"
},
"organizationName": {
"description": "Hosting organization.",
"type": "string"
},
"organizationURL": {
"description": "Organization website.",
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}
},
{
"description": "Walk germplasm ancestry or descendancy as a deduplicated DAG, with multi-generation traversal, cycle detection, and depth limits. Returns nodes + edges plus traversal stats (depthReached, rootCount, leafCount, cycleCount, deadEndCount).",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"alias": {
"description": "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.",
"pattern": "^[a-zA-Z0-9_-]+$",
"type": "string"
},
"direction": {
"default": "ancestors",
"description": "Which direction to walk: ancestors (parents), descendants (progeny), or both.",
"enum": [
"ancestors",
"descendants",
"both"
],
"type": "string"
},
"germplasmDbIds": {
"description": "Starting germplasm (1–20 roots). All roots are walked concurrently.",
"items": {
"minLength": 1,
"type": "string"
},
"maxItems": 20,
"minItems": 1,
"type": "array"
},
"loadLimit": {
"description": "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.",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"type": "integer"
},
"maxDepth": {
"default": 3,
"description": "Max generations to walk per direction (default 3, cap 10).",
"exclusiveMinimum": 0,
"maximum": 10,
"type": "integer"
}
},
"required": [
"germplasmDbIds"
],
"type": "object"
},
"name": "brapi_walk_pedigree",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"alias",
"direction",
"maxDepth",
"nodes",
"edges",
"depthReached",
"rootCount",
"leafCount",
"cycleCount",
"deadEndCount",
"truncated",
"warnings"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"alias": {
"description": "Alias of the registered BrAPI connection the call used.",
"type": "string"
},
"cycleCount": {
"description": "Number of times the walk revisited an already-registered node (cycles broken).",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"deadEndCount": {
"description": "Nodes whose upstream pedigree/progeny lookup failed.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"depthReached": {
"description": "Deepest BFS level that produced at least one new edge (0 if only roots were walked).",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"direction": {
"description": "The direction the walk expanded (echoed from the input).",
"enum": [
"ancestors",
"descendants",
"both"
],
"type": "string"
},
"edges": {
"description": "Deduplicated edge list. `relationship: \"parent\"` means `from` is a parent of `to`; `relationship: \"child\"` means `from` is a descendant of `to`.",
"items": {
"additionalProperties": false,
"description": "One deduplicated pedigree edge between two nodes.",
"properties": {
"from": {
"description": "germplasmDbId of the source of the relationship.",
"type": "string"
},
"parentType": {
"description": "E.g. MALE, FEMALE, SELF, when the upstream response supplies it.",
"type": "string"
},
"relationship": {
"description": "Direction: parent = from is a parent of to; child = from is a descendant of to.",
"enum": [
"parent",
"child"
],
"type": "string"
},
"to": {
"description": "germplasmDbId of the target.",
"type": "string"
}
},
"required": [
"from",
"to",
"relationship"
],
"type": "object"
},
"type": "array"
},
"edgesDataframe": {
"additionalProperties": false,
"description": "Canvas dataframe holding the full edge set, present when the walk exceeds loadLimit — edges[] is then a bounded preview. Any edge field that is a reserved SQL word (e.g. `from` → `from_`) is renamed to a SQL-safe identifier; columnLegend maps it back. Query with brapi_dataframe_query (SQL).",
"properties": {
"columnLegend": {
"additionalProperties": {
"type": "string"
},
"description": "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.",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"columns": {
"description": "Full column list of the dataframe.",
"items": {
"description": "Column name from the materialized rows.",
"type": "string"
},
"type": "array"
},
"createdAt": {
"description": "ISO 8601 timestamp the dataframe was created.",
"type": "string"
},
"expiresAt": {
"description": "ISO 8601 timestamp after which the dataframe metadata will be purged. Re-run the find_* tool to refresh, or copy results out before expiry.",
"type": "string"
},
"maxRows": {
"description": "Cap that was applied at create time, when truncation occurred.",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"type": "integer"
},
"rowCount": {
"description": "Number of rows materialized in the dataframe.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"tableName": {
"description": "Dataframe name. Use with brapi_dataframe_describe (schema + provenance) and brapi_dataframe_query (SQL).",
"type": "string"
},
"totalCount": {
"description": "Total rows reported by the upstream server (may exceed rowCount when truncated).",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"truncated": {
"description": "True when the dataframe hit a row cap before exhausting upstream.",
"type": "boolean"
}
},
"required": [
"tableName",
"rowCount",
"columns",
"createdAt",
"expiresAt"
],
"type": "object"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "Machine-readable failure mode. Declared by this tool: `unknown_alias`: No connection has been registered under the requested alias. Other values are possible when a failure originates below the handler.",
"examples": [
"unknown_alias"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"leafCount": {
"description": "Nodes that have no outgoing edges in the walked direction — terminal in the DAG.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"maxDepth": {
"description": "The maximum depth the walk was allowed to reach (echoed from the input).",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"type": "integer"
},
"nodes": {
"description": "Deduplicated node list — every germplasm reached by the walk, sorted by depth then DbId.",
"items": {
"additionalProperties": false,
"description": "One germplasm reached during the walk.",
"properties": {
"depth": {
"description": "Min distance from any root germplasm (0 for roots).",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"direction": {
"description": "Side of the root this node was reached from. `root` = the starting germplasm itself. `ancestor` = reached via /pedigree (a parent of the root or one of its parents). `descendant` = reached via /progeny. `both` = encountered as both an ancestor and a descendant in a bidirectional walk (rare — backcross or selfing chain).",
"enum": [
"root",
"ancestor",
"descendant",
"both"
],
"type": "string"
},
"germplasmDbId": {
"description": "Server-side identifier for the germplasm.",
"type": "string"
},
"germplasmName": {
"description": "Display name of the germplasm.",
"type": "string"
},
"isRoot": {
"description": "True when this node is one of the starting germplasm.",
"type": "boolean"
}
},
"required": [
"germplasmDbId",
"depth",
"isRoot",
"direction"
],
"type": "object"
},
"type": "array"
},
"nodesDataframe": {
"additionalProperties": false,
"description": "Canvas dataframe holding the full node set, present when the walk exceeds loadLimit — nodes[] is then a bounded preview. Query with brapi_dataframe_query (SQL); JOIN to the edges dataframe on germplasmDbId.",
"properties": {
"columnLegend": {
"additionalProperties": {
"type": "string"
},
"description": "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.",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"columns": {
"description": "Full column list of the dataframe.",
"items": {
"description": "Column name from the materialized rows.",
"type": "string"
},
"type": "array"
},
"createdAt": {
"description": "ISO 8601 timestamp the dataframe was created.",
"type": "string"
},
"expiresAt": {
"description": "ISO 8601 timestamp after which the dataframe metadata will be purged. Re-run the find_* tool to refresh, or copy results out before expiry.",
"type": "string"
},
"maxRows": {
"description": "Cap that was applied at create time, when truncation occurred.",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"type": "integer"
},
"rowCount": {
"description": "Number of rows materialized in the dataframe.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"tableName": {
"description": "Dataframe name. Use with brapi_dataframe_describe (schema + provenance) and brapi_dataframe_query (SQL).",
"type": "string"
},
"totalCount": {
"description": "Total rows reported by the upstream server (may exceed rowCount when truncated).",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"truncated": {
"description": "True when the dataframe hit a row cap before exhausting upstream.",
"type": "boolean"
}
},
"required": [
"tableName",
"rowCount",
"columns",
"createdAt",
"expiresAt"
],
"type": "object"
},
"rootCount": {
"description": "Number of starting germplasm roots.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"truncated": {
"description": "True when the walk hit the 1000-node safety cap before exhausting depth.",
"type": "boolean"
},
"warnings": {
"description": "Advisory messages (capability gaps, per-node expansion failures).",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
}
}
]
}Verify it yourself
curl -s https://api.teppi.xyz/v1/evidence/sha256:5cb4dc794450517e68a47aeaaab9717cf7203c4bb392092d047e17705cca2dec | sha256sum