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

Annotations only declare safety properties (read-only, idempotent, open-world), so the description carries the rest and does: it discloses that the index is live rather than a snapshot, that matching covers titles/abstracts/full text where available, that results are relevance-ranked, and that rows omit abstracts and authors — a limitation that materially affects downstream tool choice.

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-loads the identity and scope in the first sentence, then usage, then caveats, then return shape — a sensible priority order. Despite its length, each sentence supplies a distinct fact (source, ranking, alternative routing, return fields, pagination, limit cap) 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?

For a six-parameter, open-world search tool with an output schema, this covers what to call it with, when to prefer a sibling, what the ranking means, what comes back and how to page. The only real gap is the year-range filter semantics, which is minor against otherwise thorough coverage.

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 50%: query, cursor and open_access are documented in the schema, while limit, year_from and year_to are not. The description repeats the limit cap and explains cursor paging but adds little beyond the schema on those, and never explains what year_from/year_to filter or whether bounds are inclusive, leaving two parameters undocumented anywhere.

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?

States a specific verb and resource ("live keyword search of OpenAlex") and immediately scopes it against the alternative ("not of the citation graph snapshot"), which is exactly the distinction an agent needs given siblings like query_citation_graph and explore_citation_network.

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 an explicit when-to-use ("find seed papers when you have a topic but no DOIs yet") and an explicit when-not, both as an exclusion ("not a systematic search") and as a named alternative behavior ("keyword matches miss related work that uses different words, which the citation graph finds"). The routing decision is fully determined.

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