Google Scholar Author Alternative: Find Experts & KOLs by Topic

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

Annotations already declare read-only and non-destructive, so the description correctly spends its words on what the annotations cannot say: the Apify Actor it runs, $0.0025 per expert pricing, the no-charge-on-empty-runs rule, the per-call spending cap, and realistic 5-15 s latency with timeout remediation. It also clarifies the run_max_items / maxResults billing interaction, which is a genuine behavioral gotcha.

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?

Front-loaded with purpose and sibling differentiation before mechanics, and every section (use, don't use, params, behavior, returns) is labeled implicitly by position. The parameter recap paragraph is somewhat long given 100% schema coverage and repeats a few schema facts, which keeps it from a 5.

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 an 18-parameter tool with no output schema, the description supplies the return envelope ({actor, count, items}), the per-item field list (score, ORCID, institution, h-index, recent papers), and the structuredContent trimming behavior. Combined with cost, latency, and timeout guidance, an agent has everything needed to call it and interpret results.

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 earns above that by adding cross-parameter semantics the schema does not spell out, notably that the ranked pool is capped at 200 authors so maxResults above 200 adds nothing, and that run_max_items fills maxResults and therefore bounds billing while a larger maxResults can bill more than is returned. The yearFrom/yearTo-vs-activeSince and maxAuthorsPerPaper notes largely restate the schema, so this sits at 5 rather than higher.

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?

Opens with a specific verb and resource ("Rank the academic experts and key opinion leaders on a research topic from OpenAlex") and immediately disambiguates against the sibling literature_search ("returns people" vs "returns papers"). An agent can pick this tool without opening either schema.

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?

Gives concrete use cases (reviewers, KOLs, collaborators, speakers), states the optional country/institution dimension, and adds explicit exclusions with named alternatives ("Do not use for company contacts (use company_team_finder) or for papers themselves (use literature_search)"). 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.