omniseek_institution_cohort

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

With no annotations, the description carries the full behavioral burden and does so richly: it discloses ranking by output at that institution in that field, the juniors-surface property, the all-fields fallback when concept is omitted, the recency effect of year_from, and the OpenAlex data limitation about no PhD-student flags.

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 front-loaded with the primary use case and packs substantial guidance into two paragraphs plus a return shape. It is slightly redundant with repeated 'people-roster' phrasing and the niche 'SG/Canada cohort question' reference, but no sentence is purely 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?

This tool has no annotations and no output schema, so the description must cover purpose, usage, parameter semantics, behavioral caveats, and return shape. It does all of this: return fields are listed, important failure-of-verification caveats are stated, and sibling drill-in tools are referenced. The only minor gap is the limit parameter, which is already self-explanatory from the schema default.

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%, so the description must explain the parameters itself. It does this well for institution, concept, and year_from, with concrete examples like concept='machine learning'. However, the limit parameter is not mentioned in the description, relying entirely on its name/default in the schema.

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 specific verb-resource pair: producing the people-roster of a lab/department/university, and clearly frames the tool as answering the 'who's at this lab' question. It explicitly distinguishes itself from co-authorship tools by noting that same-lab, no-coauthorship is still a tie, so an agent can separate this tool from omniseek_coauthors.

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 states when to use the tool, what optional scoping to provide (concept, year_from), and what not to expect: the roster is a starting point, not a verified lab-member list. It also names the downstream drill-in tools (omniseek_coauthors / omniseek_read), giving clear alternative/next-step guidance.

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