TAIR-Style Locus Summary

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: it is a proxy via BAR/ThaleMine, it is Arabidopsis-only, and it returns a specific set of data. It does not contradict any annotation and enriches the agent's understanding of the tool's source and constraints. Given the annotations carry the load, this is a solid 4.

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 compact block of three sentences that front-loads the core purpose, then explains the serving mechanism, the return contents, and the alias. Every sentence contributes to the agent's understanding; there is no fluff. It is slightly longer than strictly necessary (the alias note could be separate), but it remains efficient and well-organized. A 4 reflects the strong structure with minor 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 tool's simplicity (one parameter, full schema coverage, output schema present, and comprehensive annotations), the description covers the essential aspects: what it returns, its source, its scope, and its alias. It does not mention error handling or edge cases, but those are not critical for a read-only lookup. The context is complete for an agent to decide and invoke correctly, so a 4 is warranted.

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%: the single parameter 'locus' is fully described as 'Arabidopsis AGI locus, e.g. AT1G01010'. The description adds no additional parameter-level detail beyond reinforcing that it is Arabidopsis-specific, which is already implied by the schema. With full coverage, the baseline is 3, and the description doesn't need to compensate. No further elaboration is required.

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 pair: 'Fetch the TAIR curator-vetted Arabidopsis locus summary.' It clearly distinguishes this tool from siblings by specifying the TAIR-specific, Arabidopsis-only scope and listing the exact content returned (curator summary, Araport11 description, NCBI Gene ID, cross-DB aliases). It also names its alias, bar_gene_summary, which further clarifies its identity. This is unambiguous.

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 explains the tool's purpose and why it exists (served via BAR/ThaleMine because TAIR's own API is paid), and it notes the alias relationship. This gives context for when to use it: when a TAIR-curated Arabidopsis summary is needed. However, it does not explicitly compare against other locus tools like plantcyc_locus_info or ensembl_plants_lookup_locus, nor does it state when not to use it. The guidance is clear but lacks explicit exclusions, so a 4 is appropriate.

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