brapi-mcp-server

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

With readOnlyHint and openWorldHint already in annotations, the description adds useful behavioral detail by disclosing that results are materialized as a dataframe, a handle is returned for brapi_dataframe_query, and output includes dimension/aggregate summary. No contradiction with annotations.

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

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

Three sentences, each carrying distinct useful information: the core transformation, the return handle/summary, and the downstream analysis suitability. The description is front-loaded with the main verb and resource.

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

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

For a tool with 8 parameters, full schema coverage, annotations, and an output schema, the description covers the essential call context and return shape. It could be more complete by naming sibling alternatives, but it does not leave the agent without enough to call the tool correctly.

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

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

Schema description coverage is 100%, so parameters are fully documented at the schema level; the description adds little parameter-specific meaning beyond the notion of pivoting observations across studies. Baseline of 3 is appropriate.

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

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

The description states a specific action (pull observations, pivot them into a germplasm × trait matrix) and names the concrete output (canvas dataframe handle plus summary). It differentiates from related siblings like brapi_find_observations by emphasizing the pivoted matrix form.

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

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

The description implies when to use the tool ('across one or more studies', 'long-form output suitable for GROUP BY analysis') but does not explicitly name alternatives or say when not to use it. Usage guidance is present but left largely to inference.

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

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

Beyond the annotations, the description adds meaningful behavioral context: concurrent named aliases, server-side credential resolution, the return of an orientation envelope, and the distinction between built-in known servers and operator-configured aliases. It aligns with openWorldHint and idempotentHint, and while it doesn't cover lifecycle details like disconnection, the extra context is valuable.

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

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

The description is front-loaded with the core purpose and prerequisite role, then proceeds through alias behavior, credential handling, and known servers with no filler. The longer enumeration of built-in servers and configured aliases is directly actionable, not padding.

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

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

Given that the schema is rich, the output schema is present, and annotations cover safety/idempotence, the description is complete enough for an agent to call this tool correctly. It covers connection intent, authentication modes, alias shortcuts, built-in endpoints, and how to reach arbitrary servers via baseUrl.

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

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

The schema already describes all three parameters thoroughly (100% coverage), but the description significantly extends that with deployment-specific alias names, built-in server identifiers, and guidance on when baseUrl and auth can be omitted. This is exactly the kind of practical parameter semantics that an agent cannot infer from the schema alone.

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

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

The description opens with a specific verb and resource combination: 'Open a connection to a BrAPI v2 server, authenticate, and return the full orientation envelope.' It also clearly positions the tool as the 'Required handshake before other BrAPI tools,' which differentiates it from the many data-access sibling tools in a single sentence.

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

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

The description gives clear when-to-use guidance ('Required handshake before other BrAPI tools') and practical context for omitting auth or baseUrl when using known servers or configured aliases. It stops short of explicitly naming alternatives or when-not scenarios, though for a connection-establishment tool the guidance is largely sufficient.

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

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

Annotations already indicate readOnly and idempotent, so the description doesn't repeat that. It adds context about provenance and the listing-unavailable behavior, which is useful, but doesn't detail error cases or output format beyond what annotations imply. No contradiction.

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

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

The description is reasonably concise, with the main use case front-loaded. The second sentence about auth limitation is somewhat lengthy but necessary. No redundant fluff.

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

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

Given the tool has a single optional parameter, complete schema coverage, an output schema, and read-only annotations, the description covers the important usage context: when to call it, how to obtain the parameter, and when listing is unavailable. Nothing critical is missing.

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

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

Schema coverage is 100%, with the dataframe parameter documented as optional and controlling list vs. describe. The description reinforces this by explaining how to obtain the name from spillover, but adds minimal new meaning beyond the schema.

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

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

The description clearly states the tool lists dataframes or describes one, with columns, row counts, and provenance. It distinguishes from siblings by focusing on schema/provenance inspection before queries, but could be more explicit about being a metadata-only tool compared to brapi_dataframe_query.

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

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

Explicitly instructs to use this tool after a spillover, before writing the first brapi_dataframe_query, and explains when listing is unavailable (shared HTTP endpoint without auth) with a fallback to pass a known name. This is strong guidance.

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

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

Annotations are uninformative (all three hints false), so the description carries the full burden — and it delivers. It discloses that dataframes auto-populate from find_* spills with a `df_<uuid>` naming convention, that non-SELECT statements are rejected, that responses are capped, and that registerAs creates a persistent side effect (the result lands as a new dataframe). No annotation contradiction: readOnlyHint=false is consistent with the registerAs persistence behavior described.

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

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

Six sentences but every clause earns its place: purpose, dataframe source and naming, lookup flow, sibling routing, query constraints, and chaining. Core purpose is front-loaded; the rest is dense with no filler or redundancy.

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

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

Given the output schema exists (return values need no explanation) and the annotations are uninformative, the description covers the full operational loop: how dataframes are created, how to discover their names, how to inspect them, what queries are legal, how to page, and how to chain results. Nothing an agent needs to invoke this tool correctly is missing.

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

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

Schema description coverage is 100% with detailed per-parameter explanations (row caps, conflict behavior for registerAs, identifier rules), so the baseline 3 applies. The description adds only marginal reinforcement — the SQL paging idiom and registerAs chaining — that largely restates what the schema already documents.

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

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

Opens with a specific verb+resource: 'Run SQL across in-memory dataframes.' It then distinguishes itself from siblings by explicitly naming brapi_dataframe_describe (use it to inspect schema/provenance) and the find_* tools (they produce the dataframes). An agent can tell this tool apart from its siblings without opening the schema.

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

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

States the canonical flow explicitly: find_* → read the inline `result.dataframe.tableName` → query here. It routes to the alternative (brapi_dataframe_describe) with the condition that selects it ('inspect schema and provenance for a known name'), and tells the agent when NOT to use it ('SELECT only — writes/DDL/COPY/PRAGMA/ATTACH/file-reads are rejected'). Nothing is left to inference.

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

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

Annotations already mark it read-only and idempotent, so the description only needs to add beyond that. It adds a meaningful caveat that entries reflect the BrAPI v2.1 spec and that individual servers may implement subsets, preventing agents from assuming server-specific support.

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

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

Two sentences: the first states scope and purpose, the second adds the spec/subset caveat. Every sentence earns its place and the main action is front-loaded.

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

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

For a low-complexity lookup with one enum-constrained parameter, read-only/idempotent annotations, and an output schema, the description conveys what the tool is, where it fits, and a key limitation. Nothing essential is missing.

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

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

The schema fully documents the single endpoint parameter with a 100% coverage enum list and its own description, so the description adds little parameter-level detail. The parenthetical endpoint list mirrors the enum values; the extraFilters context is useful but not necessary to understand the parameter.

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

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

The description opens with a specific verb ('List') and resource ('valid filter names for a BrAPI endpoint'), enumerates the supported endpoints, and positions itself as a companion to the find_* tools. This clearly distinguishes it from the query and retrieval tools in the sibling set.

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

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

It explicitly states the intended context: use it as a companion lookup for the extraFilters passthrough on any find_* tool. It does not provide explicit when-not-to-use guidance or compare it to an alternative tool, so it falls just short of a 5.

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

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

The description goes well beyond the minimal annotations (readOnlyHint, openWorldHint). It discloses side effects (registers a dataframe), format-specific behavior (vcf-lite/plink pull /variants metadata with fallback to '.'/'0'), edge cases (missing metadata, clamping of maxCalls/maxColumns, warnings), and naming conventions (SQL-safe identifiers, variantColumnLegend). This is rich behavioral context that helps an agent anticipate consequences.

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

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

The description is a single dense paragraph that front-loads the core purpose, then systematically covers formats and edge cases. Every sentence earns its place; there is no filler or repetition of schema text. It is structured logically (purpose → formats → metadata handling → naming) and remains readable despite the technical density.

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

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

For a tool with 6 parameters and a complex output schema, the description is remarkably complete. It covers all format-specific outputs, side effects, clamping behavior, warnings, and metadata fallbacks. The output schema is present, so return-value structure is not needed in the description. No critical information for correct invocation is missing.

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

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

The input schema already provides 100% descriptive coverage for all 6 parameters, including detailed explanations of maxCalls/maxColumns clamping and default behavior. The description adds context about how formats affect output but does not add parameter-specific semantics beyond what the schema states. With full schema coverage, a baseline of 3 is appropriate; the description does not need to compensate.

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

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

The description opens with a clear verb+resource: 'Pull genotype calls for a germplasm × variant set and pivot them into a matrix.' It explicitly names the three output formats and what each produces, distinguishing this export tool from siblings like brapi_find_genotype_calls (which presumably returns raw calls) and brapi_find_variants (metadata only). The purpose is unambiguous and specific.

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

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

The description implies when to use it (when a matrix/pivot is needed) and describes each format's behavior, but it does not explicitly contrast with alternatives or state when NOT to use it. For example, it doesn't say 'use brapi_find_genotype_calls for raw, unpivoted calls.' However, the purpose statement and format details give clear situational guidance, so it's just shy of an explicit routing rule.

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

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

Annotations already carry the safety profile (readOnlyHint=true, openWorldHint=true), and the description adds genuine behavioral context beyond them: the upstream pull is capped by deployment policy, truncation spills to a dataframe, and callFormat is honored 'when the server honors it.' These are non-obvious operational traits an agent could not infer from the schema alone; it loses a point only for not detailing spillover naming or the consequence of omitting both minimum filters.

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

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

Three sentences, each earning its place: purpose and mandatory filters up front, then truncation behavior, then the loadLimit semantics and dataframe routing. The most actionable constraint (minimum filters) is front-loaded before any behavioral detail, and there is zero filler or repetition of schema content.

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

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

For an 8-parameter tool with zero required params, the description covers the critical operational risks: cost bounding via minimum filters, truncation handling, the dataframe escape hatch, and the loadLimit tradeoff. Output schema exists so return values needn't be described, and annotations cover safety. It only omits interaction rules between the mutually related filters (variantSetDbId vs variantSetDbIds, germplasmDbIds vs callSetDbIds), which is a minor gap.

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

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

Schema coverage is 100%, so the baseline is 3. The description rises above it by explaining that variantSetDbId and germplasmDbIds serve as the cost-bounding minimum (a priority relationship not stated in the schema) and by framing the whole operation as 'germplasm × variant set,' which clarifies how the filter parameters combine. It doesn't add syntax details, but the schema already covers those.

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

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

The description states a specific verb and resource — 'Pull genotype calls for a germplasm × variant set' — which clearly differentiates it from siblings like brapi_find_variants (which finds variants, not calls) and brapi_export_genotype_matrix (which exports a matrix). The germplasm × variant scoping detail adds precision beyond the title.

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

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

The description gives explicit operating guidance: 'at minimum, set variantSetDbId or germplasmDbIds' tells the agent what filters are mandatory to bound cost. It also names a concrete alternative with a condition — 'query it with brapi_dataframe_query (SQL) instead of paging row-by-row' when the pull is truncated — leaving nothing to inference.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds meaningful behavior beyond that: it discloses that large result sets are materialized as a dataframe and that matching works across registered synonyms, which helps agents anticipate how queries behave at scale. No contradiction with annotations.

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

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

Two sentences, with the core purpose front-loaded and the large-result behavior attached as an important follow-up. Every word earns its place; there is no filler or repetition of schema content.

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

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

The tool has 13 optional parameters, a full output schema, and read-only/open-world annotations. The description covers the essential workflow, including the critical performance caveat about loadLimit and dataframe materialization, so an agent has what it needs to invoke the tool and interpret large results correctly.

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

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

Schema description coverage is 100%, so the schema already documents all 13 parameters in detail. The description's brief enumeration (name, synonym, accession number, PUI, crop, free-text) adds no meaning beyond that, but given full schema coverage, the baseline of 3 applies.

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

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

The description opens with a specific verb and resource — 'Find germplasm' — and enumerates the supported search facets: name, synonym, accession number, PUI, crop, and free-text query. It also adds a distinctive behavior, matching across registered synonyms, which clearly separates this search tool from direct retrieval tools like brapi_get_germplasm.

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

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

The description provides an explicit routing instruction: when the upstream total exceeds loadLimit, use brapi_dataframe_query instead of paging row-by-row. This gives clear context for a key decision point. It does not enumerate exclusions against every sibling (e.g., brapi_get_germplasm for direct ID lookups), but the main alternative is named with a trigger condition.

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

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

Annotations already cover readOnlyHint and openWorldHint, so the safety profile is known. The description adds genuinely non-obvious behavior: results are metadata-only, and exceeding loadLimit materializes the full result set as a dataframe in the session. This goes beyond what annotations convey and contradicts nothing.

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

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

Three sentences, each earning its place: filter dimensions, metadata-only scope plus the byte-fetching alternative, and the loadLimit/dataframe overflow behavior. Core filtering purpose is front-loaded before edge-case routing; no filler or redundancy.

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

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

With an output schema present and 100% parameter coverage, the description needn't restate return values or params. It covers the decisions an agent faces: when to call this vs brapi_get_image and what happens when results exceed loadLimit. Minor gap: no statement of how multiple filters compose (AND vs OR), which is a reasonable gap given the schema covers param mechanics.

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

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

Schema coverage is 100%, so the schema already documents all 10 parameters, including the loadLimit dataframe fallback and extraFilters precedence. The description restates filter dimensions but adds little nuance beyond the schema, so the baseline 3 applies.

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

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

States an explicit verb+resource ('Filter images') and enumerates six filter dimensions (observation unit, observation, study, ontology term, file name, MIME type). It distinguishes itself from brapi_get_image by explicitly limiting its scope to metadata, and the resource focus differentiates it from sibling brapi_find_* tools.

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

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

Gives two explicit routing rules with conditions: 'Returns metadata only — use brapi_get_image to fetch bytes inline' establishes a clear when-not-to-use boundary, and 'query it with brapi_dataframe_query (SQL)' routes the overflow case. The agent knows exactly when to leave this tool for an alternative.

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

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

Beyond the readOnlyHint and openWorldHint annotations, the description discloses several non-obvious behaviors: the client-side resolution of countryNames to alpha-3 codes, the retry with swapped coordinate axes when the spec-correct GeoJSON reading fails, the emission of a warning plus the 'coordinateAxisOrder: swapped' flag, and the materialization of large result sets as a dataframe. These are exactly the kind of behavioral traits an agent needs to predict tool behavior.

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

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

The description is long, but it is densely packed with necessary detail for a tool with 10 parameters and complex edge cases. It front-loads the core purpose and filters, then dives into the special behaviors. While a bit dense, no sentence is redundant, and the structure mirrors the tool's logical flow.

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

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

Given the complexity — 10 parameters, nested bbox object, an output schema, and intricate fallback logic — the description covers all essential aspects: filtering options, coordinate system handling, warnings, load limits, and dataframe access. An agent has everything needed to call the tool correctly and interpret results.

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

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 substantial meaning beyond the schema. For countryNames it explains the resolution process, alias handling, and merging into countryCodes; for loadLimit it clarifies the dataframe fallback and how to query it; for bbox it explains the axis-swap retry. These enrich each parameter beyond the raw property definitions.

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

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

The description opens with a specific verb+resource: 'Find research stations / field sites' and enumerates the filter dimensions (country, abbreviation, type, location ID, free-text). This clearly distinguishes it from sibling brapi_find_* tools, which target germplasm, studies, observations, etc., even without reading the schema.

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

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

The description gives concrete usage direction: it advises preferring countryCodes when alpha-3 codes are already available, explains how countryNames are resolved and merged, and tells the agent to query the resulting dataframe with brapi_dataframe_query when loadLimit is exceeded. It does not explicitly name an alternative location-finding tool, but none exists among siblings, so the guidance is sufficient.

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

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

With readOnlyHint and openWorldHint already supplied by annotations, the description adds non-obvious behavior: large result sets are materialized as a dataframe and queried via SQL through brapi_dataframe_query. This tells the agent what to expect and how to proceed after a large call, which goes beyond the annotations.

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

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

Two sentences with no filler: the first fronts the purpose and filters, the second delivers the critical overflow behavior and next-step tool. It earns every word and is immediately scannable.

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

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

Given 14 parameters, an output schema, and annotations already present, the description covers the main behavioral twist (dataframe overflow) and points to the right continuation tool. It does not enumerate every filter, but the schema already provides full per-parameter descriptions, so nothing essential is missing for invoking the tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's filter term list largely restates parameter names already defined in the schema, and the loadLimit dataframe behavior is already in the schema's loadLimit description. Thus the description adds no material parameter semantics beyond the structured schema.

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

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

The description opens with the specific operation "Pull observation records" and names the exact filter dimensions (study, germplasm, variable, season, observation unit), which makes the resource and scope unambiguous. This distinguishes it clearly from sibling tools like brapi_find_studies, brapi_find_germplasm, and brapi_find_variables without needing to open the schema.

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

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

The first sentence identifies the intended use case: retrieving observation records under BrAPI filters. It also gives a concrete handoff rule: when the upstream total exceeds loadLimit, the result is a dataframe and should be queried with brapi_dataframe_query rather than paged row-by-row. It does not explicitly list exclusions versus generic tools like brapi_raw_search, but the use context is clear enough.

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

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

Annotations already convey readOnlyHint and openWorldHint, so the bar is lower. The description adds meaningful behavioral context beyond annotations: it discloses that over-loadLimit results are materialized as a dataframe and that the caller should use SQL via brapi_dataframe_query rather than paging row-by-row. This is useful, non-obvious behavior.

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

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

Three sentences, each earning its place: purpose, enrichment value, and overflow behavior with an explicit alternative query path. The most important information is front-loaded and there is no filler or repetition of schema content.

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

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

For an 11-parameter tool with an output schema, no required parameters, and full schema descriptions, the description is complete enough. It covers the core discovery purpose, the enrichment behavior, and the important large-result-set fallback. The schema handles parameter-level detail, and the annotations cover safety and open-world semantics, so nothing critical is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description names a few high-level filter dimensions (crop, trial type, season, location, program) and mentions loadLimit behavior, but most parameter semantics are already fully documented in the schema. It adds minimal new meaning beyond what the property descriptions provide.

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

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

The description opens with a specific verb and resource: 'Locate studies matching crop, trial type, season, location, or program.' It further distinguishes the tool by noting it enriches results with program/trial/location context in one call, which clearly separates it from more generic raw-search or single-study getter siblings.

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

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

The description gives actionable usage context: use this tool to find studies with enriched context, and when the upstream total exceeds loadLimit, query the materialized dataframe with brapi_dataframe_query (SQL). It does not explicitly enumerate when to prefer brapi_get_study or brapi_raw_search, but the stated condition and enrichment benefit provide clear practical guidance.

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

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

The description goes well beyond the readOnlyHint/openWorldHint annotations by disclosing ranking semantics, ontology-URI resolution when advertised, and the dataframe materialization behavior for large result sets. This is exactly the kind of non-obvious runtime behavior an agent needs to predict before calling the tool.

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

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

The description is two sentences with no filler. The first sentence establishes the tool's purpose, and the second covers the most important behavioral caveat. It is front-loaded and every clause earns its place.

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

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

Given the tool's complexity (13 optional parameters, nested objects) and the existence of a full schema and output schema, the description covers the essential selection and invocation knowledge: search modes, overflow handling, and the post-query path. No critical behavioral gap remains for an agent to safely and correctly use the tool.

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

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 meaningful parameter-level meaning: free-text queries are ranked against the returned set, and loadLimit triggers spillover to a queryable dataframe. It does not restate the schema; it explains behavioral consequences that the schema alone does not convey.

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

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

The description names a specific resource ('observation variables (traits)') and the exact search dimensions: name, trait class, ontology term, and free-text query. This clearly distinguishes it from siblings like brapi_find_observations and brapi_find_germplasm without ambiguity.

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

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

The description gives concrete guidance on when free-text behavior differs from exact filters and instructs the agent to use brapi_dataframe_query when the result set spills beyond loadLimit. It does not explicitly list when not to use this tool relative to every sibling finder, but the conditional guidance is clear and actionable.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: the loadLimit materialization behavior, the 1-based inclusive/exclusive coordinate semantics, and the precedence rule for extraFilters vs named params. It does not detail pagination or error behavior, but the materialization disclosure is a meaningful addition.

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

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

Two sentences with no filler. The first sentence front-loads the core purpose and coordinate semantics; the second sentence explains the loadLimit behavior and routes to the dataframe query tool. Every clause earns its place.

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

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

The tool has 9 optional parameters, an output schema, and rich annotations. The description covers the key behavioral nuance (loadLimit materialization) and the main routing to brapi_dataframe_query. It doesn't enumerate all filter combinations or describe the output schema, but the output schema exists and the description is sufficient for an agent to call the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining the loadLimit behavior (rows beyond cap land in a dataframe) and the alias default behavior, which are not fully captured by the schema. It also clarifies the coordinate semantics (1-based inclusive/exclusive) that apply to start/end. Minor gap: it doesn't explain how multiple filter dimensions combine, but the schema already documents each parameter.

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

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

The description states a specific verb ('Find') and resource ('variant records') and enumerates the three filter dimensions (variant set, reference sequence, genomic region) with coordinate semantics. It also distinguishes itself from sibling tools by naming brapi_dataframe_query as the downstream consumer when results exceed loadLimit, so an agent can tell it apart from brapi_find_genotype_calls and brapi_raw_search.

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

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

The description explicitly explains when to use this tool versus brapi_dataframe_query: when the upstream total exceeds loadLimit, the full result set is materialized as a dataframe and should be queried with SQL. It also references brapi_describe_filters for extraFilters and brapi_connect for alias registration, giving clear routing to sibling tools.

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

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

Beyond the readOnlyHint/openWorldHint annotations, the description discloses the study-anchored execution order, the 200-study cap, the dialect-honor cross-check, and the performance rationale. No statement contradicts the annotations.

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

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

Four sentences with no filler: result, execution mechanism, optimization path, and sibling alternative each get exactly one sentence. The main outcome is front-loaded before implementation details.

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

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

Given a rich schema, an output schema, and read-only/open-world annotations, the description covers the core aggregation behavior, the study-discovery cap, the explicit-study shortcut, and how to get the raw matrix. An agent has everything needed to select and invoke it.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters thoroughly. The description's studyDbIds guidance largely duplicates the schema's own description, so it adds little per-parameter meaning beyond the baseline.

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

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

The description opens with a precise contract: 'Aggregate a single germplasm's observations across every study it appears in' and itemizes the output (n, mean, median, sd, min, max, studies, seasons). It also distinguishes the tool from the sibling raw-matrix tool by deferring to brapi_build_phenotype_matrix.

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

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

It gives an explicit alternative ('For the underlying observation matrix, use brapi_build_phenotype_matrix') and a concrete decision rule for studyDbIds: omit for automatic discovery, or pass an explicit set to skip discovery and the 200-study cap. It also advises against the unanchored germplasm-only pull that stalls on SGN/Breedbase.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, covering the safety profile. The description adds value beyond those by disclosing companion counts (study count, direct parent count, direct descendant count) and interpreting them as signals for pedigree depth and observation coverage — context an agent would not derive from the annotations or the schema.

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

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

Two sentences with no filler: the core purpose is front-loaded in the first clause, and the second sentence adds genuinely useful interpretive context about the response companions. Every clause earns its place.

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

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

For a simple 2-parameter read with full annotations, 100% schema coverage, and an output schema present, the description is nearly complete — it names the response contents and explains why those contents matter. The only real gap is the absence of explicit routing between this tool and its close siblings brapi_find_germplasm and brapi_walk_pedigree.

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

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

Schema description coverage is 100%, with both alias and germplasmDbId well documented in the schema, so the baseline of 3 applies. The description confirms germplasmDbId as the lookup key but contributes no additional format, constraint, or usage detail beyond what the schema already states.

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

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

The description names a specific verb and resource ('Fetch a single germplasm by DbId') and specifies what is included (attributes, direct parents), so an agent knows exactly what the tool does. The 'single... by DbId' phrasing signals a point lookup as opposed to the search-style brapi_find_germplasm sibling, though no sibling is named explicitly.

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

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

When to use is implied: an agent has a specific germplasmDbId and wants that one record with its attributes and parents. The second sentence hints at suitability for pedigree and observation-coverage questions, but there are no explicit alternatives, exclusions, or guidance about when to prefer brapi_walk_pedigree or brapi_find_germplasm.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, but the description adds valuable behavioral context beyond those: it returns inline image content blocks, falls back to imageURL when dedicated image delivery is unavailable, and has no filesystem side-effects. This meaningfully informs an agent about expected behavior.

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

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

The description is two sentences with no filler. It front-loads the primary purpose, then adds the fallback behavior and side-effect guarantee, each earning its place without redundancy.

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

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

For a tool with only two parameters, full schema coverage, an output schema, and safety annotations, the description covers the core operation, the response format, fallback behavior, and side-effects. Minor gaps remain around error handling and how missing or invalid imageDbIds are treated, but these are not critical given the output schema and annotations.

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

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

Schema description coverage is 100%, so the schema already fully documents both parameters. The description only restates that up to 5 imageDbIds are accepted, matching the schema's maxItems constraint, and does not add deeper parameter semantics such as format, lookup rules, or interaction between alias and imageDbIds.

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

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

The description states a specific verb and resource: 'Fetch image bytes for up to 5 imageDbIds and return them inline as `type: image` content blocks.' This clearly distinguishes the tool from siblings like brapi_find_images, which focus on discovering image metadata rather than retrieving image content.

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

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

The description implies when to use the tool: whenever image bytes are needed for known imageDbIds. It also mentions a fallback to metadata imageURL, which gives some context about server capabilities, but it does not explicitly say when to prefer this over sibling tools such as brapi_raw_get or brapi_find_images.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds value by disclosing that the response fully resolves program, trial, and location, and includes cheap observation/observation-unit/variable counts as drill-down signals—useful behavioral context beyond the annotations. No contradiction with annotations.

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

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

The description is two sentences with zero redundancy. It front-loads the primary action and key identifier, then adds the distinguishing resolved-fields and count-signal details. Every word earns its place.

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

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

An output schema exists (has_output_schema: true), so return value details are covered elsewhere. Annotations cover safety. The description covers the lookup key, resolved entities, and count signals—everything an agent needs to decide to use this tool and call it correctly. No material gaps remain.

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

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

Schema description coverage is 100% for both parameters, with alias and studyDbId already well documented. The description adds minimal parameter-specific meaning beyond confirming studyDbId is the lookup key and that related entities are resolved. Since the schema carries the full parameter semantics, a baseline of 3 is appropriate.

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

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

The description states a specific verb (Fetch), a specific resource (a single study), and the key identifier (DbId). It also mentions what is resolved (program, trial, location) and the count signals, which clearly distinguishes it from search-like siblings such as brapi_find_studies. The purpose is unambiguous and immediately actionable.

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

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

The description implies usage for a known study ID ('by DbId') but does not explicitly contrast with alternatives like brapi_find_studies or brapi_find_observations. It does not state when not to use it, leaving the agent to infer from the name and schema that this is a direct lookup tool rather than a search.

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

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

Well beyond the readOnlyHint/openWorldHint annotations, the description discloses the no-enrichment guarantee, `suggestion` field emission, and the precise spillover contract: spill happens only when rows exceed `loadLimit` AND the result is a list shape (`result` array or `result.data` envelope), inline results are unchanged, and caller-driven paging via `params.page`/`params.pageSize` skips spillover. This is unusually rich behavioral disclosure.

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

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

Four sentences, all information-dense, with the core purpose front-loaded in the first sentence. Each subsequent sentence covers a distinct behavior — return fidelity, suggestion signal, spillover rules, and the paging exception. For a generic passthrough with dynamic behavior, this length is fully earned with no filler.

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

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

Despite the tool's complexity (arbitrary endpoint, dynamic spill behavior), the description covers purpose, transformations, the spillover edge cases, and alternatives. An output schema exists so return-value details are covered elsewhere, and the description handles exactly the non-obvious behaviors an agent needs to predict the tool's output shape.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds genuine cross-parameter meaning the schema lacks: the interaction between `loadLimit` and `params.page`/`params.pageSize` (paging skips spillover), and the list-shape condition that activates `loadLimit`'s dataframe behavior. This goes beyond any single parameter's schema description.

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

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

"Passthrough to any BrAPI GET /{path} endpoint" names a specific verb, resource, and scope. "Returns the raw upstream envelope without enrichment or foreign-key resolution" precisely defines what it does and does not do, and the `suggestion` field mechanism clearly separates it from the curated brapi_find_*/brapi_get_* siblings.

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

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

The description gives actionable routing guidance: the `suggestion` field tells the caller when a curated tool exists, and the spillover clause directs the agent to "query with brapi_dataframe_query (SQL) instead of paging row-by-row." It does not explicitly state when to prefer brapi_raw_search over brapi_raw_get or enumerate exclusions, but the context is clear enough for correct selection.

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

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

Annotations only declare readOnlyHint and openWorldHint; the description adds substantial non-obvious behavior: async polling resolved upstream, spillover to a canvas dataframe under a precise condition, unchanged inline result, the paging exception via body.page/body.pageSize, and the lack of distributions/FK resolution. This is rich, accurate behavioral disclosure beyond what annotations or schema provide.

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

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

The description is four dense sentences, each carrying a distinct and non-redundant rule: core passthrough, spillover condition, paging exception, and scope limitation. It is front-loaded with the central verb and resource, and every sentence earns its place without fluff.

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

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

For a generic passthrough tool with four parameters and an existing output schema, the description covers all essential call-time behavior: request mechanics, optional parameters, spillover behavior, paging interaction, and what transformations are not applied. Nothing an agent needs to invoke it correctly appears to be missing.

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

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

Schema description coverage is 100%, so the baseline is 3, and this description adds extra semantic value: it explains what loadLimit actually controls (rows beyond the cap land in a dataframe) and how body.page/body.pageSize changes the behavior. Those details are not fully evident from the property names or schema descriptions alone.

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

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

The opening sentence states the exact mechanism ('Passthrough to any BrAPI POST /search/{noun} endpoint') and scope ('any'), making the generic nature immediately clear. The closing clause ('No distributions or foreign-key resolution applied') and the 'raw' in the name differentiate it from the brapi_find_* typed search siblings. This is a specific verb+resource description that enables correct tool selection.

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

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

The description provides operational guidance for specific cases: when spillover occurs, when it is skipped, and it explicitly routes querying of spilled data to brapi_dataframe_query. It also explains the alias default behavior. However, it never explicitly states when to prefer this generic raw search over the typed brapi_find_* tools or brapi_raw_get, so usage selection guidance is partially left to inference.

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

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

Annotations already mark the tool as readOnly and idempotent. The description adds value beyond those by disclosing that re-running refreshes the cached capability scan and clarifying how force_refresh relates to that cache. This is useful behavioral context without contradicting the annotations.

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

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

Two dense sentences front-load the core purpose, then add the cache-refresh behavior and the alias nuance. There is no filler, and each clause contributes to correct invocation.

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

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

With a rich output schema, strong annotations, and fully documented optional parameters, the description covers the essential invocation context: what the tool returns, when cache is refreshed, and how to handle non-default aliases. Nothing critical is missing for an agent to select and call it correctly.

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

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

Schema coverage is 100%, with both 'alias' and 'forceRefresh' already well described in the input schema. The description only lightly reinforces the alias behavior and cache refresh; it does not add substantial new parameter meaning beyond what the schema already provides.

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

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

The description clearly states the verb ('Return') and resource ('full orientation envelope for a registered BrAPI connection') and unpacks what that envelope contains: server identity, capabilities, content counts, and notes. This distinguishes it from data-querying siblings like brapi_raw_get or brapi_find_studies, since it is specifically about connection metadata.

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

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

The description implies the tool is for inspecting an existing BrAPI connection and notes when to pass an alias ('pass an alias to read a non-default connection'). It does not explicitly name alternatives or state when not to use it, but the context of a registered connection and the sibling set make the intended use reasonably clear.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, covering safety. The description adds substantial behavioral context: results are deduplicated, cycles are detected, traversal is depth-limited, and stats include depthReached, rootCount, leafCount, cycleCount, and deadEndCount. It does not contradict the annotations.

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

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

The description is one tight, front-loaded sentence that leads with the core operation and then lists the key output artifacts and stats. No filler, repetition, or unnecessary detail.

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

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

Given the output schema, annotations, and 100% parameter coverage, the description plus schema provides enough for correct invocation: roots, direction, depth, load cap, and alias are all accounted for. The only notable omission is explicit guidance about when to prefer this tool over sibling germplasm tools, but that is a usage nuance rather than a completeness blocker.

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

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

Schema description coverage is 100%, and each parameter already has a rich description including defaults, enums, caps, and alias behavior. The main description adds useful conceptual context for the traversal parameters but does not need to compensate for schema gaps.

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

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

The description states a specific verb ('Walk'), a specific resource ('germplasm ancestry or descendancy'), and a distinctive mode ('deduplicated DAG'). It clearly sets this apart from sibling find/get tools even without naming them explicitly.

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

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

The description implies when to use the tool (whenever pedigree traversal is needed), but it does not explicitly state when not to use it or which sibling to prefer. The only alternative guidance appears in the loadLimit parameter description, which routes overflow rows to brapi_dataframe_query.

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