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

Beyond the annotations (readOnly, idempotent, openWorld), the description discloses caching behavior (14 days, skipCache flag), result ordering and logging when items are dropped, email quality caveats with concrete evidence, and explicitly states it reads only company-published content. These details affirm the safety profile and add operational nuance.

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 (twelve sentences) but each sentence conveys a distinct fact or guidance: output format, empty-result interpretation, grain behavior, filtering semantics, email caveats, caching, and scope boundary. It is well-structured and front-loaded with the primary purpose, with no filler.

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 compensates by explaining return values (names, titles, page, reached pages, people_json array), edge cases (empty results), parameter trade-offs (emails on company row only), and the operational context (cache, credits, exclusions). This is a fully self-contained explanation.

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 100% and each parameter already has detailed explanations. The description mostly reiterates schema content (e.g., output_grain flattening, seniority ordering) with minor additions like 'what most tables want'. Since it adds little beyond the schema, baseline 3 is appropriate.

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 starts with 'Extract the people a company publishes on its own team, leadership or about page, and return their names, titles and the page each one came from' – a specific verb and resource with a clear output. It also explicitly distinguishes itself from LinkedIn scraping, leaving no ambiguity about the tool's scope.

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?

Provides explicit recommendations: 'output_grain person ... is what most tables want', 'include_emails is off by default and should usually stay off', and 'Nothing here scrapes LinkedIn or any profile network'. It also clarifies prerequisites (APIFY_TOKEN, Apify credits) and how to interpret empty results, giving the agent a complete decision framework.

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