search_archives

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

With no annotations provided, the description carries the full burden. It discloses what results contain (id, title, category, short summary), that there's a category filter, and the limit default (10) and max (50). This is reasonably transparent behavior for a read/search operation. It doesn't describe pagination or error behavior, but for a search tool this covers the essential behavioral surface.

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?

Well-structured with a brief purpose statement, a clear return-value note, a follow-up recommendation, and compact Args documentation. Every sentence earns its place — no fluff. The format is scannable with clear section breaks.

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 having an output schema, the description explains what a search returns and how to follow up. For a search tool with 3 parameters (1 required), plus an output schema, plus a sibling chain to drill into results, this is complete. The follow-up recommendation to get_schema_card completes the workflow story.

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 0%, so the description must compensate. It does explain each parameter in the Args section: query is a natural-language search with a concrete example, category is an optional filter with an example and comma-separate guidance, and limit is documented with default and max. This adds real value beyond the bare schema, though the category value format ('Genomics & Bioinformatics') is somewhat ambiguous as to whether it's an exact match or fuzzy.

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?

Clear verb+resource+scope: 'Search the Scigantic catalog of public scientific data archives by natural-language query.' It states what is searched (catalog of public scientific data archives), the method (natural-language query), and explicitly notes returns 'across all domains,' distinguishing from siblings like get_archive and list_archive_files which target specific archives.

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 when to use it (to search the catalog by natural language) and gives a clear follow-up path (get_schema_card to understand a match's structure), which implicitly distinguishes it from the archive-specific sibling tools. It doesn't explicitly say when NOT to use it, but the follow-up recommendation and description of returning ranked matches across all domains provides clear usage context.

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