build_search_pipeline

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

With no annotations provided, the description carries the full burden of disclosing side effects and behavior. It mentions the Entrez History Server, hinting at server-side state, but does not clarify whether the operation is read-only, whether it has lasting side effects, how errors or rate limits manifest, or what happens after execution. This is insufficient for a compound action that 'builds and executes' a pipeline.

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 at two sentences plus an example. The first sentence states the core purpose, the second adds the technical mechanism (Entrez History Server), and the example clarifies the intended query pattern. Every element earns its place with no redundancy or fluff.

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?

The tool is complex with a nested parameter structure, but the schema provides rich detail and the description gives one use case. However, the absence of any behavioral caveats (e.g., limits on number of steps, required authentication, or whether results are returned as IDs or summaries) makes it only partially complete. An output schema exists, so return format may be covered there, but broader execution expectations are missing.

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 input schema already provides 100% parameter coverage, including detailed descriptions for the 'steps' array and 'output_step'. The description adds an illustrative example that demonstrates how to combine search and link operations in the steps parameter, which reinforces the schema's abstract structure with a concrete scenario.

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: 'Build and execute a multi-step search pipeline.' This specifies a concrete action (build and execute) on a specific resource (multi-step search pipeline), and the example ('Find diabetes reviews, then limit to articles linked to HLA genes') distinguishes it from single-step sibling tools like pubmed_search or link_to_databases.

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 clear context on when to use this tool: it is 'Ideal for complex queries' and mentions the efficiency gain from using the Entrez History Server. However, it does not explicitly state when not to use it or mention alternative simpler tools (e.g., pubmed_search for one-step searches), so it lacks exclusions.

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