generate_search_queries

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

No annotations are provided, so the description carries full burden. It discloses behaviors like spelling correction via NCBI ESpell, MeSH term lookup, synonym expansion, and query analysis showing PubMed's interpretation. It also describes the return structure (JSON with fields like corrected_topic, keywords, mesh_terms, all_synonyms, suggested_queries with estimated_count and pubmed_translation). There is 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 lengthy but well-structured with headers, modes, steps, and features. It is front-loaded with the core purpose and uses clear formatting. While some detail might be excessive (e.g., full workflow steps), it is justified given the tool's complexity and integration with other tools.

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 (4 parameters, output schema, many siblings), the description is highly complete. It covers what the tool does, how to use it in two modes, parameter details, return value structure (listing keys), and integration with follow-up tools. The presence of an output schema is mentioned, but the description already explains the return fields.

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%, but the description includes an 'Args:' section that explains each parameter (topic, strategy, check_spelling, include_suggestions) and their effects (e.g., strategy affects suggested_queries, check_spelling for spelling correction). This adds significant meaning beyond 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 clearly states the tool's purpose: 'Gather search intelligence for a topic - returns RAW MATERIALS for Agent to decide.' It distinguishes itself from sibling tools like unified_search and analyze_search_query by emphasizing that it provides building blocks, not finished queries. The two usage modes (keyword and PICO) further clarify its role.

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 explicit when-to-use guidance with detailed step-by-step workflows for both keyword and PICO modes. It contrasts with sibling tools by stating that the agent decides how to use the raw materials, and it references subsequent steps (analyze_search_query, unified_search). No alternative tools are mentioned, but the usage context is thoroughly explained.

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