Search People (Apollo)

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds crucial behavioral context: results are intentionally slim with obfuscated last names and no email/phone numbers, and it explicitly warns against looping for contact data. This goes beyond annotations to prevent misuse.

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 3-4 sentences, front-loaded with the core purpose, then cost/API key requirement, then behavioral limitations and forwarding guidance. Every sentence adds value without redundancy or fluff, making it easy for an agent to parse quickly.

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 (14 parameters, no output schema), the description covers purpose, usage guidelines, and key behavioral traits. It provides sufficient context for the agent to avoid common pitfalls. However, it could be more complete by mentioning pagination parameters or the fields projection feature, which are in the schema but not summarized.

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 description mentions high-level filter categories (title, seniority, location, employer domain/id, employer size) which map to some of the 14 parameters, but does not detail specific parameters like page, fields, perPage, qKeywords, revenueRange, etc. With schema description coverage at 36%, the description partially compensates but leaves many parameters unexplained, limiting the agent's ability to use them effectively.

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 immediately states 'Find people via Apollo' with specific criteria (title, seniority, location, employer domain/id, employer size), clearly distinguishing it from sibling tools like apollo_companies_search. The verb 'find' and resource 'people' are explicit, and the later guidance to use apollo_person_enrich for contact data reinforces its unique purpose.

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 explicitly states it is FREE (no credits) but requires a MASTER Apollo API key, providing cost and auth context. It further advises against looping for contact data and directs the agent to use apollo_person_enrich instead, giving clear when-to and when-not-to usage guidance.

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