scrape_people

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

With no annotations, the description fully bears the burden of disclosing side effects. It clearly states that data is persisted in the database, upserted rather than duplicated, and that subsequent list_people calls avoid Apify costs. It also reveals cost differences between full_mode and short mode and lists exactly which fields each mode returns, giving an unusually transparent view of the tool's 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?

The description is well-structured with a purpose sentence, a usage/storage note, and an Args block. Every sentence carries functional value, and the parameter details are dense but easily scannable. While it is longer than average, the complexity of the tool justifies the length, and the key usage constraints are front-loaded.

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?

The tool has 4 parameters, one required, and an output schema, so the description need not explain return values. It covers all parameter semantics, default behaviors, cost implications, storage effects, and recommended usage patterns. An agent has enough information to call this tool correctly and decide when to use it.

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 0%, but the description compensates thoroughly. For url it provides a full example; for job_titles it gives a concrete list and explains the empty default; for max_items it gives default, max, and recommended values for leadership; for full_mode it explains cost, returned fields, and when to enable it. This far exceeds bare schema documentation.

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 'Scrape and store company employees/leadership from LinkedIn via Apify,' which names a specific verb, resource, and destination. It clearly distinguishes this company-level scraping tool from the sibling list_people and profile-level scrapers by highlighting that results are stored for instant retrieval.

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 clear when-to-use guidance: 'Run this once per company; re-run only when you need fresher data.' It also explains the relationship with list_people, saying results are stored so later calls are instant and cost-free. However, it does not explicitly mention alternatives like scrape_person_profile or scrape_profile for individual profile scraping, so the differentiation is incomplete.

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