Skip to main content
Glama

Brapi Germplasm Performance

brapi_germplasm_performance
Read-only

Aggregate a single germplasm's observations across studies, returning per-variable statistics (n, mean, median, sd, min, max), contributing studies, seasons, and collection coverage. SGN/Breedbase uses advertised germplasm-scoped observation units with embedded measurements, including zeros. Other servers discover up to 200 studies before pulling per study. Pass studyDbIds to skip discovery and restrict collection to known studies. Per-study observation limits, page limits, failures, and incomplete scans appear in coverage and warnings. For the underlying matrix, use brapi_build_phenotype_matrix.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "germplasmDbId": "<germplasmDbId>"
    },
    "name": "brapi_germplasm_performance"
  }
}

Input Schema

NameRequiredDescriptionDefault
aliasNoConnection alias. Omit to use alias `default`. An alias registered via brapi_connect works, and so does one the server has a URL configured for (a built-in alias, an operator-configured alias, or `default` on a deployment with a default server), which connects on first use. Calls that used a non-default alias must pass that same alias here.
loadLimitNoCap on matching observations collected per study, including during automatic discovery. Defaults to 50,000. A study that stops at it is reported as partial.
variablesNoOptional subset of observationVariableDbIds to aggregate. Omit to include every variable observed for the germplasm.
studyDbIdsNoOptional studyDbIds to restrict collection to known studies and skip automatic discovery. Omit to walk germplasm-scoped embedded units on SGN/Breedbase, or discover up to 200 studies on other servers. Find known study IDs with brapi_find_studies; some servers ignore its germplasm filter.
germplasmDbIdYesThe germplasmDbId to summarize performance for.

Output Schema

NameRequiredDescriptionDefault
aliasNoConnection alias the call used.
errorNoPresent when the call failed. Absent on success.
coverageNoCollection coverage, independent of the number of contributing studies.
warningsNoAdvisory messages (study-discovery limits, dropped filters, fallback paths, per-study failures, partial study scans).
truncatedNoTrue when an observation scan stopped early; coverage records what was collected.
studyCountNoNumber of distinct studies that contributed any observation.
studyDbIdsNoDistinct studyDbIds that contributed observations.
perVariableNoPer-variable aggregates, sorted by observationVariableDbId.
germplasmDbIdNoThe germplasm that was analyzed.
germplasmNameNoDisplay name of the germplasm, when the server provides one.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `upstream_not_found`: An uncaught BrAPI data request answered HTTP 404. `upstream_rate_limited`: An uncaught BrAPI data request exhausted retries after HTTP 429. `unknown_alias`: No connection is registered under the requested alias, and the server has no base URL configured for it to connect on first use. `auth_token_exchange_failed`: Connecting the alias on first use, the SGN or OAuth token exchange against the BrAPI /token endpoint failed. `auth_no_access_token`: Connecting the alias on first use, the token endpoint answered without returning an access token. `capability_discovery_unavailable`: Neither /serverinfo nor /calls listed any call, and at least one of them timed out, was unreachable, or answered 429 or a 5xx other than 501, so nothing was cached. `upstream_unauthorized`: The BrAPI server answered HTTP 401: it requires credentials, or rejected the ones sent. `upstream_forbidden`: The BrAPI server answered HTTP 403: the credentials sent, or their absence, lack access. `alias_base_url_invalid`: The base URL configured on the server for this alias is not an absolute http(s) URL, or carries credentials. `private_address_blocked`: The base URL configured for this alias, or its token URL, is on a private or reserved address this server may not reach. `germplasm_not_found`: Upstream returned no germplasm record for the requested germplasmDbId. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `upstream_not_found`: An uncaught BrAPI data request answered HTTP 404. `upstream_rate_limited`: An uncaught BrAPI data request exhausted retries after HTTP 429. `unknown_alias`: No connection is registered under the requested alias, and the server has no base URL configured for it to connect on first use. `auth_token_exchange_failed`: Connecting the alias on first use, the SGN or OAuth token exchange against the BrAPI /token endpoint failed. `auth_no_access_token`: Connecting the alias on first use, the token endpoint answered without returning an access token. `capability_discovery_not_found`: Both /serverinfo and /calls return HTTP 404. `capability_discovery_unavailable`: Neither /serverinfo nor /calls listed any call, and at least one of them timed out, was unreachable, or answered 429 or a 5xx other than 501, so nothing was cached. `upstream_unauthorized`: The BrAPI server answered HTTP 401: it requires credentials, or rejected the ones sent. `upstream_forbidden`: The BrAPI server answered HTTP 403: the credentials sent, or their absence, lack access. `alias_base_url_invalid`: The base URL configured on the server for this alias is not an absolute http(s) URL, or carries credentials. `private_address_blocked`: The base URL configured for this alias, or its token URL, is on a private or reserved address this server may not reach. `germplasm_not_found`: Upstream returned no germplasm record for the requested germplasmDbId. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
      -  "upstream_not_found",
      -  "upstream_rate_limited",
      -  "unknown_alias",
      -  "auth_token_exchange_failed",
      -  "auth_no_access_token",
      -  "capability_discovery_unavailable",
      -  "upstream_unauthorized",
      -  "upstream_forbidden",
      -  "alias_base_url_invalid",
      -  "private_address_blocked",
      -  "germplasm_not_found"
      -]New value: +[
      +  "upstream_not_found",
      +  "upstream_rate_limited",
      +  "unknown_alias",
      +  "auth_token_exchange_failed",
      +  "auth_no_access_token",
      +  "capability_discovery_not_found",
      +  "capability_discovery_unavailable",
      +  "upstream_unauthorized",
      +  "upstream_forbidden",
      +  "alias_base_url_invalid",
      +  "private_address_blocked",
      +  "germplasm_not_found"
      +]
  2. Changed2 schema fields changed
    • addedInput schema / properties / loadLimit
      Added value: +{
      +  "description": "Cap on matching observations collected per study, including during automatic discovery. Defaults to 50,000. A study that stops at it is reported as partial.",
      +  "exclusiveMinimum": 0,
      +  "maximum": 9007199254740991,
      +  "type": "integer"
      +}
    • addedOutput schema / properties / truncated
      Added value: +{
      +  "description": "True when an observation scan stopped early; coverage records what was collected.",
      +  "type": "boolean"
      +}
  3. Changed2 schema fields changed
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `unknown_alias`: No connection is registered under the requested alias, and the server has no base URL configured for it to connect on first use. `auth_token_exchange_failed`: Connecting the alias on first use, the SGN or OAuth token exchange against the BrAPI /token endpoint failed. `auth_no_access_token`: Connecting the alias on first use, the token endpoint answered without returning an access token. `capability_discovery_unavailable`: Neither /serverinfo nor /calls listed any call, and at least one of them timed out, was unreachable, or answered 429 or a 5xx other than 501, so nothing was cached. `upstream_unauthorized`: The BrAPI server answered HTTP 401: it requires credentials, or rejected the ones sent. `upstream_forbidden`: The BrAPI server answered HTTP 403: the credentials sent, or their absence, lack access. `alias_base_url_invalid`: The base URL configured on the server for this alias is not an absolute http(s) URL, or carries credentials. `private_address_blocked`: The base URL configured for this alias, or its token URL, is on a private or reserved address this server may not reach. `germplasm_not_found`: Upstream returned no germplasm record for the requested germplasmDbId. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `upstream_not_found`: An uncaught BrAPI data request answered HTTP 404. `upstream_rate_limited`: An uncaught BrAPI data request exhausted retries after HTTP 429. `unknown_alias`: No connection is registered under the requested alias, and the server has no base URL configured for it to connect on first use. `auth_token_exchange_failed`: Connecting the alias on first use, the SGN or OAuth token exchange against the BrAPI /token endpoint failed. `auth_no_access_token`: Connecting the alias on first use, the token endpoint answered without returning an access token. `capability_discovery_unavailable`: Neither /serverinfo nor /calls listed any call, and at least one of them timed out, was unreachable, or answered 429 or a 5xx other than 501, so nothing was cached. `upstream_unauthorized`: The BrAPI server answered HTTP 401: it requires credentials, or rejected the ones sent. `upstream_forbidden`: The BrAPI server answered HTTP 403: the credentials sent, or their absence, lack access. `alias_base_url_invalid`: The base URL configured on the server for this alias is not an absolute http(s) URL, or carries credentials. `private_address_blocked`: The base URL configured for this alias, or its token URL, is on a private or reserved address this server may not reach. `germplasm_not_found`: Upstream returned no germplasm record for the requested germplasmDbId. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
      -  "unknown_alias",
      -  "auth_token_exchange_failed",
      -  "auth_no_access_token",
      -  "capability_discovery_unavailable",
      -  "upstream_unauthorized",
      -  "upstream_forbidden",
      -  "alias_base_url_invalid",
      -  "private_address_blocked",
      -  "germplasm_not_found"
      -]New value: +[
      +  "upstream_not_found",
      +  "upstream_rate_limited",
      +  "unknown_alias",
      +  "auth_token_exchange_failed",
      +  "auth_no_access_token",
      +  "capability_discovery_unavailable",
      +  "upstream_unauthorized",
      +  "upstream_forbidden",
      +  "alias_base_url_invalid",
      +  "private_address_blocked",
      +  "germplasm_not_found"
      +]
  4. Changed3 schema fields changed
    • changedInput schema / properties / studyDbIds / description
      Previous value: -"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."New value: +"Optional studyDbIds to restrict collection to known studies and skip automatic discovery. Omit to walk germplasm-scoped embedded units on SGN/Breedbase, or discover up to 200 studies on other servers. Find known study IDs with brapi_find_studies; some servers ignore its germplasm filter."
    • changedOutput schema / anyOf
      Previous value: -[
      -  {
      -    "not": {
      -      "required": [
      -        "error"
      -      ]
      -    },
      -    "required": [
      -      "alias",
      -      "germplasmDbId",
      -      "studyCount",
      -      "studyDbIds",
      -      "perVariable",
      -      "warnings"
      -    ]
      -  },
      -  {
      -    "required": [
      -      "error"
      -    ]
      -  }
      -]New value: +[
      +  {
      +    "not": {
      +      "required": [
      +        "error"
      +      ]
      +    },
      +    "required": [
      +      "alias",
      +      "germplasmDbId",
      +      "studyCount",
      +      "studyDbIds",
      +      "coverage",
      +      "perVariable",
      +      "warnings"
      +    ]
      +  },
      +  {
      +    "required": [
      +      "error"
      +    ]
      +  }
      +]
    • addedOutput schema / properties / coverage
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "Collection coverage, independent of the number of contributing studies.",
      +  "properties": {
      +    "discoveryLimited": {
      +      "description": "True when generic study discovery reached its bound; additional studies may exist.",
      +      "type": "boolean"
      +    },
      +    "partial": {
      +      "description": "True when failed, truncated, or unprocessed work leaves coverage incomplete.",
      +      "type": "boolean"
      +    },
      +    "scan": {
      +      "additionalProperties": false,
      +      "description": "Scoped-unit scan coverage; unseen studies are unknown after an incomplete walk.",
      +      "properties": {
      +        "complete": {
      +          "description": "Whether the scoped unit walk exhausted its authoritative total.",
      +          "type": "boolean"
      +        },
      +        "pagesFetched": {
      +          "description": "Unit pages returned before stopping.",
      +          "maximum": 9007199254740991,
      +          "minimum": 0,
      +          "type": "integer"
      +        },
      +        "reason": {
      +          "description": "Bound or failure that stopped the unit walk.",
      +          "type": "string"
      +        },
      +        "scannedUnits": {
      +          "description": "Raw upstream units examined, including repeated IDs.",
      +          "maximum": 9007199254740991,
      +          "minimum": 0,
      +          "type": "integer"
      +        },
      +        "totalUnits": {
      +          "description": "Upstream raw unit total, when reported.",
      +          "maximum": 9007199254740991,
      +          "minimum": 0,
      +          "type": "integer"
      +        }
      +      },
      +      "required": [
      +        "complete",
      +        "scannedUnits",
      +        "pagesFetched"
      +      ],
      +      "type": "object"
      +    },
      +    "studies": {
      +      "description": "Per-study outcomes in requested or encounter order.",
      +      "items": {
      +        "additionalProperties": false,
      +        "description": "One study collection outcome.",
      +        "properties": {
      +          "observationCount": {
      +            "description": "Matching observations collected for this study.",
      +            "maximum": 9007199254740991,
      +            "minimum": 0,
      +            "type": "integer"
      +          },
      +          "reason": {
      +            "description": "Why collection failed or remained incomplete.",
      +            "type": "string"
      +          },
      +          "status": {
      +            "description": "Outcome of collecting this study; partial may contain observations.",
      +            "enum": [
      +              "contributed",
      +              "empty",
      +              "failed",
      +              "partial",
      +              "unprocessed"
      +            ],
      +            "type": "string"
      +          },
      +          "studyDbId": {
      +            "description": "Requested study, or a study encountered in scoped units.",
      +            "type": "string"
      +          }
      +        },
      +        "required": [
      +          "studyDbId",
      +          "status",
      +          "observationCount"
      +        ],
      +        "type": "object"
      +      },
      +      "type": "array"
      +    }
      +  },
      +  "required": [
      +    "partial",
      +    "studies"
      +  ],
      +  "type": "object"
      +}
  5. Changed10 schema fields changed
    • changedInput schema / properties / alias / description
      Previous value: -"Connection alias registered via brapi_connect. Omit to read the connection registered under alias `default` — i.e. a prior brapi_connect call that did not specify an alias. Calls that used a non-default alias must pass that same alias here."New value: +"Connection alias. Omit to use alias `default`. An alias registered via brapi_connect works, and so does one the server has a URL configured for (a built-in alias, an operator-configured alias, or `default` on a deployment with a default server), which connects on first use. Calls that used a non-default alias must pass that same alias here."
    • removedInput schema / properties / germplasmDbId / minLength
      Removed value: -1
    • addedInput schema / properties / germplasmDbId / pattern
      Added value: +"\\S"
    • removedInput schema / properties / studyDbIds / items / minLength
      Removed value: -1
    • addedInput schema / properties / studyDbIds / items / pattern
      Added value: +"\\S"
    • addedInput schema / properties / variables / items / pattern
      Added value: +"\\S"
    • changedOutput schema / properties / alias / description
      Previous value: -"Alias of the registered BrAPI connection used."New value: +"Connection alias the call used."
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `unknown_alias`: No connection has been registered under the requested alias. `germplasm_not_found`: Upstream returned no germplasm record for the requested germplasmDbId. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `unknown_alias`: No connection is registered under the requested alias, and the server has no base URL configured for it to connect on first use. `auth_token_exchange_failed`: Connecting the alias on first use, the SGN or OAuth token exchange against the BrAPI /token endpoint failed. `auth_no_access_token`: Connecting the alias on first use, the token endpoint answered without returning an access token. `capability_discovery_unavailable`: Neither /serverinfo nor /calls listed any call, and at least one of them timed out, was unreachable, or answered 429 or a 5xx other than 501, so nothing was cached. `upstream_unauthorized`: The BrAPI server answered HTTP 401: it requires credentials, or rejected the ones sent. `upstream_forbidden`: The BrAPI server answered HTTP 403: the credentials sent, or their absence, lack access. `alias_base_url_invalid`: The base URL configured on the server for this alias is not an absolute http(s) URL, or carries credentials. `private_address_blocked`: The base URL configured for this alias, or its token URL, is on a private or reserved address this server may not reach. `germplasm_not_found`: Upstream returned no germplasm record for the requested germplasmDbId. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
      -  "unknown_alias",
      -  "germplasm_not_found"
      -]New value: +[
      +  "unknown_alias",
      +  "auth_token_exchange_failed",
      +  "auth_no_access_token",
      +  "capability_discovery_unavailable",
      +  "upstream_unauthorized",
      +  "upstream_forbidden",
      +  "alias_base_url_invalid",
      +  "private_address_blocked",
      +  "germplasm_not_found"
      +]
    • changedOutput schema / properties / warnings / description
      Previous value: -"Advisory messages (study-discovery limits, dropped filters, fallback paths, per-study failures)."New value: +"Advisory messages (study-discovery limits, dropped filters, fallback paths, per-study failures, partial study scans)."
  6. First observed

TDQS

A4.4/5.0
Behavior3/5

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

The annotations only declare readOnlyHint and openWorldHint, and the description goes well beyond them by disclosing server-dependent execution paths (SGN/Breedbase embedded units vs. other servers discovering up to 200 studies), the 50,000 default load limit with partial-study reporting, and that failures, page limits, and incomplete scans surface in coverage and warnings. This is genuinely useful behavioral context that the agent cannot see elsewhere.

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

Conciseness4/5

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

Front-loaded with the action and output shape, then cost/behavior caveats, then the sibling redirect last. Five dense sentences with little waste, though the two-sentence server-implementation digression is heavier than the rest and could be tightened.

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

Completeness5/5

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

For a read-only federated aggregation tool with a full input schema and an output schema, this covers everything an agent needs: what it returns, what it costs, how to avoid discovery, how partial results are signaled, and which sibling covers the alternative case.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the description adds consequence-level meaning rather than restating types: studyDbIds controls whether discovery runs at all, and loadLimit causes a study to be reported as partial. It does not explain the alias or variables semantics beyond the schema, so it stops short of a 5.

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

Purpose5/5

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

States a specific verb and resource ('aggregate a single germplasm's observations across studies') and enumerates what comes back (per-variable n/mean/median/sd/min/max, contributing studies, seasons, coverage). It also explicitly contrasts itself with brapi_build_phenotype_matrix, so an agent can pick it apart from the sibling that returns the raw matrix.

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

Usage Guidelines5/5

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

Gives concrete routing rules: pass studyDbIds to skip discovery and restrict to known studies, find those IDs with brapi_find_studies, and use brapi_build_phenotype_matrix if the underlying observation matrix is wanted. It also flags the caveat that some servers ignore brapi_find_studies' germplasm filter, which is the kind of edge condition an agent needs before committing.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.