Research account

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

Adds substantial context beyond annotations: it discloses the return shape (raw sources with title/url/date/excerpt plus known_facts), the important boundary that it does not write prose, a security warning that excerpt is untrusted third-party text to be treated as data not instructions, and that it consumes credits and is budgeted. The readOnlyHint=false is consistent with the disclosed credit consumption, and openWorldHint=true aligns with the web-gathering behavior.

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?

Four tightly packed sentences, front-loaded with purpose then outputs, boundaries, security, and cost. Every sentence earns its place, and the prompt-injection warning is placed appropriately after the return-format description.

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?

With no output schema, the description usefully covers the return shape, and it addresses the credit/budget dimension for a costly open-world tool. The main gap is parameter coverage, which the 20%-covered schema does not fill, so the agent lacks guidance on max_credits/max_sources/company_name.

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 only 20%, so the description must carry parameter meaning, but it only gestures at 'focus area' and 'if configured' for Apollo. It never explains domain, company_name, max_credits, or max_sources (limits, defaults, or why to set them), leaving most parameters undocumented in both schema and description.

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 names a specific verb+resource ('Gather cited source material about an account') and scopes the outputs (firmographics from Apollo, web results per focus area, known_facts from structured fields). It clearly differentiates research-gathering from other SDR operations, though it never names a sibling like sdr_enrich_company or sdr_prepare_outreach_brief to route the agent explicitly.

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?

It states the workflow expectation ('write the dossier yourself and cite the source URLs') and flags cost behavior ('consumes credits and is budgeted'), which implies when this deep-research tool is appropriate. However, it gives no explicit when-to-use/when-not or comparison against alternatives such as sdr_enrich_company, leaving the choice to inference.

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