Skip to main content
Glama

Brapi Federated Find

brapi_federated_find
Read-only

Find studies, germplasm, or observations across BrAPI connection aliases. Reuses each finder’s filters, dialect handling, and read limits. Rows retain their source alias and DbId. Only an unambiguous exact germplasm PUI can group records across aliases. Returns per-alias coverage and stages the merged collection when the inline limit is reached.

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": {
      "aliases": "<aliases>",
      "query": "<query>"
    },
    "name": "brapi_federated_find"
  }
}

Input Schema

NameRequiredDescriptionDefault
queryYesEntity and its finder-specific filters.
aliasesYesSource aliases to query in the order given.
loadLimitNoCap on rows returned inline in results[]. Omit for the deployment default. results[] also stops at a 24,000-byte budget, whichever bound comes first, and keeps at least one row when any matched. When results[] holds fewer rows than matched, the matched rows are staged in a dataframe (marked truncated if the upstream walk stopped short); query it with brapi_dataframe_query (SQL) instead of paging row-by-row.

Output Schema

NameRequiredDescriptionDefault
capNoEffective inline row limit.
errorNoPresent when the call failed. Absent on success.
shownNoMerged rows delivered inline.
entityNoThe requested BrAPI entity.
noticeNoPreview bound and pointer to the merged dataframe.
resultsNoLeading merged rows with source provenance.
completeNoTrue when all source scans completed.
coverageNoCollection coverage in alias input order.
dataframeNoMerged table when the preview is cut.
truncatedNoTrue when the merged inline preview was cut.
mergedCountNoMerged rows, including staged rows.
collectedCountNoSource rows collected before merging.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / query / oneOf
      Previous value: -[
      -  {
      -    "additionalProperties": false,
      -    "description": "Study query.",
      -    "properties": {
      -      "entity": {
      -        "const": "studies",
      -        "description": "Search study records.",
      -        "type": "string"
      -      },
      -      "filters": {
      -        "additionalProperties": false,
      -        "description": "Filters accepted by brapi_find_studies.",
      -        "properties": {
      -          "active": {
      -            "description": "Restrict to active / inactive studies.",
      -            "type": "boolean"
      -          },
      -          "crop": {
      -            "description": "Filter by common crop name (single value).",
      -            "pattern": "\\S",
      -            "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"
      -          },
      -          "locations": {
      -            "description": "Filter by locationDbIds (server-side identifiers, not display names). On servers that ignore this filter on /studies, it is applied client-side over the scanned studies, and a study with no locationDbId never matches.",
      -            "items": {
      -              "pattern": "\\S",
      -              "type": "string"
      -            },
      -            "type": "array"
      -          },
      -          "programs": {
      -            "description": "Filter by programDbIds.",
      -            "items": {
      -              "pattern": "\\S",
      -              "type": "string"
      -            },
      -            "type": "array"
      -          },
      -          "seasons": {
      -            "description": "Filter by seasons (e.g. \"2022\").",
      -            "items": {
      -              "pattern": "\\S",
      -              "type": "string"
      -            },
      -            "type": "array"
      -          },
      -          "studyNames": {
      -            "description": "Filter by study display name.",
      -            "items": {
      -              "pattern": "\\S",
      -              "type": "string"
      -            },
      -            "type": "array"
      -          },
      -          "trialTypes": {
      -            "description": "Filter by study types.",
      -            "items": {
      -              "pattern": "\\S",
      -              "type": "string"
      -            },
      -            "type": "array"
      -          },
      -          "trials": {
      -            "description": "Filter by trialDbIds.",
      -            "items": {
      -              "pattern": "\\S",
      -              "type": "string"
      -            },
      -            "type": "array"
      -          }
      -        },
      -        "type": "object"
      -      }
      -    },
      -    "required": [
      -      "entity",
      -      "filters"
      -    ],
      -    "type": "object"
      -  },
      -  {
      -    "additionalProperties": false,
      -    "description": "Germplasm query.",
      -    "properties": {
      -      "entity": {
      -        "const": "germplasm",
      -        "description": "Search germplasm records.",
      -        "type": "string"
      -      },
      -      "filters": {
      -        "additionalProperties": false,
      -        "description": "Filters accepted by brapi_find_germplasm.",
      -        "properties": {
      -          "accessionNumbers": {
      -            "description": "Filter by accession numbers (gene-bank catalog codes).",
      -            "items": {
      -              "pattern": "\\S",
      -              "type": "string"
      -            },
      -            "type": "array"
      -          },
      -          "collections": {
      -            "description": "Filter by germplasm collection names.",
      -            "items": {
      -              "pattern": "\\S",
      -              "type": "string"
      -            },
      -            "type": "array"
      -          },
      -          "crops": {
      -            "description": "Filter by common crop names.",
      -            "items": {
      -              "pattern": "\\S",
      -              "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.",
      -            "pattern": "\\S",
      -            "type": "string"
      -          },
      -          "germplasmDbIds": {
      -            "description": "Filter by DbIds.",
      -            "items": {
      -              "pattern": "\\S",
      -              "type": "string"
      -            },
      -            "type": "array"
      -          },
      -          "germplasmPUIs": {
      -            "description": "Persistent unique identifiers.",
      -            "items": {
      -              "pattern": "\\S",
      -              "type": "string"
      -            },
      -            "type": "array"
      -          },
      -          "names": {
      -            "description": "Filter by germplasm display names.",
      -            "items": {
      -              "pattern": "\\S",
      -              "type": "string"
      -            },
      -            "type": "array"
      -          },
      -          "programs": {
      -            "description": "Scope germplasm by program DbIds.",
      -            "items": {
      -              "pattern": "\\S",
      -              "type": "string"
      -            },
      -            "type": "array"
      -          },
      -          "species": {
      -            "description": "Botanical species.",
      -            "pattern": "\\S",
      -            "type": "string"
      -          },
      -          "studies": {
      -            "description": "Scope germplasm by study DbIds.",
      -            "items": {
      -              "pattern": "\\S",
      -              "type": "string"
      -            },
      -            "type": "array"
      -          },
      -          "synonyms": {
      -            "description": "Match registered synonyms.",
      -            "items": {
      -              "pattern": "\\S",
      -              "type": "string"
      -            },
      -            "type": "array"
      -          },
      -          "text": {
      -            "description": "Free-text query. Applied client-side as a case-insensitive substring match on germplasmName, germplasmPUI, accessionNumber, defaultDisplayName, and registered synonyms — no BrAPI server reliably supports a server-side free-text filter. Every upstream row is scanned when the filtered set fits one dataframe walk; above that, a miss on the first page stops the scan, and the warnings report how many rows were checked. Combine with `crops` / `genus` / etc. to narrow the upstream pull first.",
      -            "pattern": "^$|\\S",
      -            "type": "string"
      -          },
      -          "trials": {
      -            "description": "Scope germplasm by trial DbIds.",
      -            "items": {
      -              "pattern": "\\S",
      -              "type": "string"
      -            },
      -            "type": "array"
      -          }
      -        },
      -        "type": "object"
      -      }
      -    },
      -    "required": [
      -      "entity",
      -      "filters"
      -    ],
      -    "type": "object"
      -  },
      -  {
      -    "additionalProperties": false,
      -    "description": "Observation query.",
      -    "properties": {
      -      "entity": {
      -        "const": "observations",
      -        "description": "Search observation records.",
      -        "type": "string"
      -      },
      -      "filters": {
      -        "additionalProperties": false,
      -        "description": "Filters accepted by brapi_find_observations.",
      -        "properties": {
      -          "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": {
      -              "pattern": "\\S",
      -              "type": "string"
      -            },
      -            "type": "array"
      -          },
      -          "observationLevels": {
      -            "description": "Observation unit level (plot, plant, field, etc.).",
      -            "items": {
      -              "pattern": "\\S",
      -              "type": "string"
      -            },
      -            "type": "array"
      -          },
      -          "observationUnits": {
      -            "description": "Filter by observationUnitDbIds.",
      -            "items": {
      -              "pattern": "\\S",
      -              "type": "string"
      -            },
      -            "type": "array"
      -          },
      -          "observations": {
      -            "description": "Filter by observationDbIds.",
      -            "items": {
      -              "pattern": "\\S",
      -              "type": "string"
      -            },
      -            "type": "array"
      -          },
      -          "programs": {
      -            "description": "Filter by programDbIds.",
      -            "items": {
      -              "pattern": "\\S",
      -              "type": "string"
      -            },
      -            "type": "array"
      -          },
      -          "seasons": {
      -            "description": "Filter by seasonDbIds (e.g. \"2022\").",
      -            "items": {
      -              "pattern": "\\S",
      -              "type": "string"
      -            },
      -            "type": "array"
      -          },
      -          "studies": {
      -            "description": "Filter by studyDbIds.",
      -            "items": {
      -              "pattern": "\\S",
      -              "type": "string"
      -            },
      -            "type": "array"
      -          },
      -          "timestampFrom": {
      -            "description": "ISO 8601 start of the observation-time window.",
      -            "pattern": "\\S",
      -            "type": "string"
      -          },
      -          "timestampTo": {
      -            "description": "ISO 8601 end of the observation-time window.",
      -            "pattern": "\\S",
      -            "type": "string"
      -          },
      -          "trials": {
      -            "description": "Filter by trialDbIds.",
      -            "items": {
      -              "pattern": "\\S",
      -              "type": "string"
      -            },
      -            "type": "array"
      -          },
      -          "variables": {
      -            "description": "Filter by observationVariableDbIds.",
      -            "items": {
      -              "pattern": "\\S",
      -              "type": "string"
      -            },
      -            "type": "array"
      -          }
      -        },
      -        "type": "object"
      -      }
      -    },
      -    "required": [
      -      "entity",
      -      "filters"
      -    ],
      -    "type": "object"
      -  }
      -]New value: +[
      +  {
      +    "additionalProperties": false,
      +    "description": "Study query.",
      +    "properties": {
      +      "entity": {
      +        "const": "studies",
      +        "description": "Search study records.",
      +        "type": "string"
      +      },
      +      "filters": {
      +        "additionalProperties": false,
      +        "description": "Filters accepted by brapi_find_studies.",
      +        "properties": {
      +          "active": {
      +            "description": "Restrict to active / inactive studies.",
      +            "type": "boolean"
      +          },
      +          "crop": {
      +            "description": "Filter by common crop name (single value).",
      +            "pattern": "\\S",
      +            "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"
      +          },
      +          "locations": {
      +            "description": "Filter by locationDbIds (server-side identifiers, not display names). On servers that ignore this filter on /studies, it is applied client-side over the scanned studies, and a study with no locationDbId never matches.",
      +            "items": {
      +              "pattern": "\\S",
      +              "type": "string"
      +            },
      +            "type": "array"
      +          },
      +          "programs": {
      +            "description": "Filter by programDbIds.",
      +            "items": {
      +              "pattern": "\\S",
      +              "type": "string"
      +            },
      +            "type": "array"
      +          },
      +          "seasons": {
      +            "description": "Filter by seasons (e.g. \"2022\").",
      +            "items": {
      +              "pattern": "\\S",
      +              "type": "string"
      +            },
      +            "type": "array"
      +          },
      +          "studyNames": {
      +            "description": "Filter by study display name.",
      +            "items": {
      +              "pattern": "\\S",
      +              "type": "string"
      +            },
      +            "type": "array"
      +          },
      +          "trialTypes": {
      +            "description": "Filter by study types.",
      +            "items": {
      +              "pattern": "\\S",
      +              "type": "string"
      +            },
      +            "type": "array"
      +          },
      +          "trials": {
      +            "description": "Filter by trialDbIds.",
      +            "items": {
      +              "pattern": "\\S",
      +              "type": "string"
      +            },
      +            "type": "array"
      +          },
      +          "variables": {
      +            "description": "Filter by observationVariableDbIds — studies that recorded these variables. Get IDs from brapi_find_variables.",
      +            "items": {
      +              "pattern": "\\S",
      +              "type": "string"
      +            },
      +            "type": "array"
      +          }
      +        },
      +        "type": "object"
      +      }
      +    },
      +    "required": [
      +      "entity",
      +      "filters"
      +    ],
      +    "type": "object"
      +  },
      +  {
      +    "additionalProperties": false,
      +    "description": "Germplasm query.",
      +    "properties": {
      +      "entity": {
      +        "const": "germplasm",
      +        "description": "Search germplasm records.",
      +        "type": "string"
      +      },
      +      "filters": {
      +        "additionalProperties": false,
      +        "description": "Filters accepted by brapi_find_germplasm.",
      +        "properties": {
      +          "accessionNumbers": {
      +            "description": "Filter by accession numbers (gene-bank catalog codes).",
      +            "items": {
      +              "pattern": "\\S",
      +              "type": "string"
      +            },
      +            "type": "array"
      +          },
      +          "collections": {
      +            "description": "Filter by germplasm collection names.",
      +            "items": {
      +              "pattern": "\\S",
      +              "type": "string"
      +            },
      +            "type": "array"
      +          },
      +          "crops": {
      +            "description": "Filter by common crop names.",
      +            "items": {
      +              "pattern": "\\S",
      +              "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.",
      +            "pattern": "\\S",
      +            "type": "string"
      +          },
      +          "germplasmDbIds": {
      +            "description": "Filter by DbIds.",
      +            "items": {
      +              "pattern": "\\S",
      +              "type": "string"
      +            },
      +            "type": "array"
      +          },
      +          "germplasmPUIs": {
      +            "description": "Persistent unique identifiers.",
      +            "items": {
      +              "pattern": "\\S",
      +              "type": "string"
      +            },
      +            "type": "array"
      +          },
      +          "names": {
      +            "description": "Filter by germplasm display names.",
      +            "items": {
      +              "pattern": "\\S",
      +              "type": "string"
      +            },
      +            "type": "array"
      +          },
      +          "programs": {
      +            "description": "Scope germplasm by program DbIds.",
      +            "items": {
      +              "pattern": "\\S",
      +              "type": "string"
      +            },
      +            "type": "array"
      +          },
      +          "species": {
      +            "description": "Botanical species.",
      +            "pattern": "\\S",
      +            "type": "string"
      +          },
      +          "studies": {
      +            "description": "Scope germplasm by study DbIds.",
      +            "items": {
      +              "pattern": "\\S",
      +              "type": "string"
      +            },
      +            "type": "array"
      +          },
      +          "synonyms": {
      +            "description": "Match registered synonyms.",
      +            "items": {
      +              "pattern": "\\S",
      +              "type": "string"
      +            },
      +            "type": "array"
      +          },
      +          "text": {
      +            "description": "Free-text query. Applied client-side as a case-insensitive substring match on germplasmName, germplasmPUI, accessionNumber, defaultDisplayName, and registered synonyms — no BrAPI server reliably supports a server-side free-text filter. Every upstream row is scanned when the filtered set fits one dataframe walk; above that, a miss on the first page stops the scan, and the warnings report how many rows were checked. Combine with `crops` / `genus` / etc. to narrow the upstream pull first.",
      +            "pattern": "^$|\\S",
      +            "type": "string"
      +          },
      +          "trials": {
      +            "description": "Scope germplasm by trial DbIds.",
      +            "items": {
      +              "pattern": "\\S",
      +              "type": "string"
      +            },
      +            "type": "array"
      +          }
      +        },
      +        "type": "object"
      +      }
      +    },
      +    "required": [
      +      "entity",
      +      "filters"
      +    ],
      +    "type": "object"
      +  },
      +  {
      +    "additionalProperties": false,
      +    "description": "Observation query.",
      +    "properties": {
      +      "entity": {
      +        "const": "observations",
      +        "description": "Search observation records.",
      +        "type": "string"
      +      },
      +      "filters": {
      +        "additionalProperties": false,
      +        "description": "Filters accepted by brapi_find_observations.",
      +        "properties": {
      +          "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": {
      +              "pattern": "\\S",
      +              "type": "string"
      +            },
      +            "type": "array"
      +          },
      +          "observationLevels": {
      +            "description": "Observation unit level (plot, plant, field, etc.).",
      +            "items": {
      +              "pattern": "\\S",
      +              "type": "string"
      +            },
      +            "type": "array"
      +          },
      +          "observationUnits": {
      +            "description": "Filter by observationUnitDbIds.",
      +            "items": {
      +              "pattern": "\\S",
      +              "type": "string"
      +            },
      +            "type": "array"
      +          },
      +          "observations": {
      +            "description": "Filter by observationDbIds.",
      +            "items": {
      +              "pattern": "\\S",
      +              "type": "string"
      +            },
      +            "type": "array"
      +          },
      +          "programs": {
      +            "description": "Filter by programDbIds.",
      +            "items": {
      +              "pattern": "\\S",
      +              "type": "string"
      +            },
      +            "type": "array"
      +          },
      +          "seasons": {
      +            "description": "Filter by seasonDbIds (e.g. \"2022\").",
      +            "items": {
      +              "pattern": "\\S",
      +              "type": "string"
      +            },
      +            "type": "array"
      +          },
      +          "studies": {
      +            "description": "Filter by studyDbIds.",
      +            "items": {
      +              "pattern": "\\S",
      +              "type": "string"
      +            },
      +            "type": "array"
      +          },
      +          "timestampFrom": {
      +            "description": "ISO 8601 start of the observation-time window.",
      +            "pattern": "\\S",
      +            "type": "string"
      +          },
      +          "timestampTo": {
      +            "description": "ISO 8601 end of the observation-time window.",
      +            "pattern": "\\S",
      +            "type": "string"
      +          },
      +          "trials": {
      +            "description": "Filter by trialDbIds.",
      +            "items": {
      +              "pattern": "\\S",
      +              "type": "string"
      +            },
      +            "type": "array"
      +          },
      +          "variables": {
      +            "description": "Filter by observationVariableDbIds.",
      +            "items": {
      +              "pattern": "\\S",
      +              "type": "string"
      +            },
      +            "type": "array"
      +          }
      +        },
      +        "type": "object"
      +      }
      +    },
      +    "required": [
      +      "entity",
      +      "filters"
      +    ],
      +    "type": "object"
      +  }
      +]
  2. Added

TDQS

A4.1/5.0
Behavior4/5

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

Annotations already declare readOnlyHint and openWorldHint, yet the description still adds real behavioral detail beyond them: rows keep their source alias and DbId, cross-alias grouping only happens on an unambiguous exact germplasm PUI, per-alias coverage is returned, and oversized result sets are staged into a dataframe. It stops short of saying how per-alias failures or partial coverage are signaled, which is the main remaining blind spot for a federated read.

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?

Five short sentences, front-loaded with the purpose, then grouping semantics, then the staging escape hatch — no filler. The phrasing is dense and jargon-heavy ('stages the merged collection'), which costs a little immediate readability without wasting words.

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

Completeness4/5

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

An output schema exists, so return-shape explanation is not owed, and the description still covers the non-obvious parts: cross-alias identity rules, coverage reporting, and the staging handoff to brapi_dataframe_query. What is missing is error/partial-failure behavior across aliases, which matters for a tool fanning out to multiple independent servers.

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

Parameters3/5

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

Schema description coverage is 100% and the nested query/filters/loadLimit semantics are already spelled out upstream (including the 24,000-byte budget and staging behavior), so the description has little left to add. 'Aliases are queried in the order given' is the only implicit nod to parameter behavior, and it is already in the schema; baseline 3 applies when the schema does the heavy lifting.

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 (Find) plus three concrete resources (studies, germplasm, observations) and a scope qualifier that separates it from the single-server finders: 'across BrAPI connection aliases'. An agent can tell this apart from brapi_find_studies / brapi_find_germplasm without opening either schema.

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

Usage Guidelines4/5

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

Gives clear operating context (multi-alias federation, finder filters reused, dialect and read limits inherited) and explicitly routes staged results to brapi_dataframe_query instead of row-by-row paging. It never states when to prefer the single-server finders over this one, so the exclusion side of the guidance is inferred rather than stated.

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.