query_authors

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

Annotations already declare the tool read-only, idempotent, and non-destructive, so the bar is lower. The description adds meaningful behavior beyond those annotations: the dependency on a pre-built graph index, ranking semantics ('summed PageRank', 'ranked by shared papers'), and the meaning of hops/depth for the network query. It does not describe error cases if the index is absent, but the prerequisite is disclosed.

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 dense but not bloated. Every sentence earns its place: purpose, usage trigger, query-type definitions, and a prerequisite. The most important behavioral constraint is placed at the end but clearly signposted, and there is no filler or restatement of the tool name.

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?

Given the tool's complexity — five query modes, an optional depth, an author-name parameter, and a prerequisite — the description covers all essential operational knowledge. An output schema exists, so detailed return-value documentation is unnecessary. The only small gap is the undocumented limit parameter, but defaults and schema metadata mitigate that.

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 carry the parameter documentation. It explains all query_type enum values, clarifies author_name for coauthors_of and network, and defines depth as hops. The limit parameter is never mentioned, and it is not systematically stated which query types ignore author_name, so the coverage is strong but not complete.

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 names a specific resource ('author co-authorship network') and a clear verb ('Query'), then enumerates five concrete query types that define exactly what the tool does. The scope is distinct from sibling graph tools such as get_citation_graph or query_knowledge_graph, so an agent can identify it confidently.

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?

It explicitly tells the agent when to use the tool: when the user asks about prolific authors, collaborations, or an author's network. It also adds a critical prerequisite ('build_index(type='graph') must be run first'). However, it does not name alternative tools or give when-not-to-use exclusions, stopping short of a 5.

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