mgnify_list_studies

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

The description outlines the output items ('Each item has accession, title, biome, ena_accessions') and explains the semantics of several filters (e.g., 'matches descendants' for biome_lineage, prefix '-' for order). However, it does not explicitly state that the operation is read-only, nor does it describe pagination behavior (page/size defaults) or what happens when no results match, and there are no annotations to supplement this.

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 compact—two sentences—with no redundant fluff. Every sentence contributes meaning: the first states the action and lists filters, the second describes the output structure. It is efficiently organized for quick consumption.

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 list/search endpoint, the description covers the main use cases: search terms, biome lineage matching, pipeline filtering, and ordering. It omits pagination parameters and default ordering, but these are minor and apparent from the schema. The description is sufficient to use the tool effectively without needing the schema, though it could benefit from a note on default pagination.

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 description clarifies parameter meanings beyond the schema by providing concrete examples (e.g., 'has_analyses_from_pipeline' with '5.0') and noting that order supports '-' for descending. It does not mention page and size, but those are straightforward with schema defaults, and the description adds value for the key filtering parameters.

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's purpose as 'Search MGnify studies' and enumerates the key filtering and ordering parameters, making the primary function apparent. However, 'search' is a generic verb and could be more explicit about listing vs. returning a single study, though the filter list helps clarify.

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 no guidance on when to use this tool relative to sibling tools such as mgnify_get_study or mgnify_list_samples. It does not mention that this is the appropriate tool for browsing/top-level study discovery or filtering by biome/pipeline, leaving the selection context implicit.

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