research

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

The annotations are minimal (readOnlyHint, openWorldHint), so the description must carry the behavioral burden — and it does. It names the specific upstream sources (Wikipedia, arXiv, Hacker News, Stack Exchange, Crossref, Brave/Tavily), explains the config-dependent availability of some, describes the decomposition and evidence-extraction pipeline steps, details the exact ResearchReport structure, and explicitly assigns the synthesis-writing responsibility to the model ('the server does the gathering, not the writing'). This goes well beyond the annotations without contradicting them.

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 long, but every component earns its place: operation → pipeline mechanism → sources → return structure → model's responsibility → depth guidance. The front-loading of the core 'run a pipeline' phrase followed by progressive detail creates a logical, scannable flow. Minor stylistic blemishes (the semicolon-heavy middle and parenthetical digression about keys) are the only reason it doesn't get a 5; it could be slightly tightened without losing information.

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 — multi-step orchestration across 6+ external sources, configurable depth with nonlinear cost implications, and a rich structured output — the description covers all critical dimensions explicitly. It addresses dependencies ('if keys are configured'), delineates agent vs. server responsibility, enumerates the output contract, and offers per-level trade-offs. The output schema presumably details the ResearchReport shape, so the description's lack of that detail is acceptable. No meaningful gap left for an agent deciding whether and how to invoke this.

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 coverage is 100% and the schema already documents both parameters well, establishing a baseline of 3. The description adds semantic value on top by re-framing the depth values by intent ('fast overviews,' 'normal research,' 'thorough multi-source investigations') and by showing how the parameter's granularity maps to pipeline trade-offs. It reinforces rather than merely restates the schema's mechanical counts (sub-questions, fetches).

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 precise verb+object pair ('Run a full deep-research pipeline on a complex question') and immediately unpacks what 'pipeline' means: decompose, fan out, fetch, extract, return structured output. It distinguishes itself from the search_* siblings by being the full orchestrated pipeline versus point lookups, and from plan_research/extract_evidence by stating that gathering and planning happen server-side while the model handles synthesis. An agent could confidently discriminate this from its siblings without opening the schema.

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 explicit, actionable when-to-use guidance via the depth parameter: "Use `depth='quick'` for fast overviews, 'standard' for normal research, 'deep' for thorough multi-source investigations." It also clarifies the model's post-call responsibilities (write the synthesis). However, it never explicitly says when NOT to use this tool versus calling one of the many search siblings directly (e.g., 'for a single fact check, prefer search_web'), which given 9 siblings would be the crowning touch.

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