Emails And Contacts

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

With no annotations, the description carries the burden of behavioral disclosure. It transparently exposes the existence of async mode, explains that long crawl/enrichment may occur, and points to requests_get for progress tracking. It also flags the async parameter as deprecated in favor of execution_mode. However, it does not explicitly state whether the operation is read-only or write-related, nor does it mention any potential costs or rate limits. These are minor gaps given the detailed mode guidance, so a 4 is warranted.

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 well-structured with a one-sentence purpose, bullet-point 'Best for', and clear decision sections. It is front-loaded with the core function, and every section serves a distinct purpose—usage, async guidance, and alternative routing. No filler or repetition. It is longer than average, but every sentence earns its place given the tool's complexity.

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?

For a tool with 5 parameters (1 required), an output schema, and multiple execution modes, the description covers all necessary aspects: main use case, when to use this vs. the sibling, async behavior and tracking, and parameter guidance. The existence of an output schema relieves the need to describe return values. The description also anticipates common questions (e.g., many domains at once) making it complete for agent invocation.

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%, so the baseline is 3. The description goes beyond schema definitions by explaining parameter interplay: it defines query as 'domains or URLs' with an example, elaborates on execution_mode ('Use auto to let the MCP server choose between sync and async'), and clarifies async as a 'Deprecated compatibility flag'. It also adds context to preferred_contacts as 'contact-role prioritization.' This adds meaningful value over the schema's brief descriptions.

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 clear, specific action: 'Find emails, phones, and social/contact data from one or more company domains.' It names the exact resource types and the input (domains), and explicitly differentiates from sibling company_insights by stating what it does NOT do (firmographics, revenue, etc.). This is a textbook example of a specific verb+resource with sibling differentiation.

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 sections: 'Prefer this tool when...' and 'Use company_insights instead when...', directly addressing when to choose this tool over an alternative. It also gives concrete async usage guidance ('Use async mode when...') and references tracking with requests_get. Nothing is left to inference.

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