sra_search

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

Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety profile. The description adds behavioral value by disclosing the accepted input forms (accessions, field syntax), the returned fields, and the presense of first_run_accession for chaining. This goes beyond the annotation-only picture and gives the agent a realistic expecation of the response.

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 has two focused sentences: one front-loaded purpose statement and one detailed-but-compact explanation of query forms and output fields. No fluff or repition. Every sentence serves a distinct purpose.

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 search tool with no output schema, the description covers accepted query syntax, accession types, and the result field list, which is sufficient for invoking and interpreting results. It could add explicit pagination notes or caveats about open-world searhes, but those are partly conveyed by annotations and the parameter schema. Minor gap, not a 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%, so the schema already defines query, limit, and offset with descriptions, defaults, and constraints. The tool description retsates much of the query semantics and adds one example, but does not meaningfully extend parameter understanding beyond the schema. This is the baseline-3 case where schema carries the load.

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: 'Search NCBI's Sequence Read Archive (SRA) for sequencing experiments and runs.' It clearly differentiates this search tool from its sibling sra_get by noting the results are meant for chaining into sra_get. The scope is precise and the tool's role is unmistakable.

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 context on when to use the tool: any query that is free text, an accession, or NCBI field syntax. It also names the downstream tool (sra_get) for chaining, implying when a more specific retrieval is needed. It lacks explicit exclusions or 'use X instead' wording, but the context is clear enough for an agent.

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