query_genes_by_pathway

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

With no annotations, the description carries the full burden, but it only says 'Find genes...' without discussing prerequisites (e.g., requiring a pathway ID or name), filtering behavior, or output details. It does not mislead but is severely under-informative.

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 a single, clear sentence with no irrelevant words. It is front-loaded and efficient, but the brevity comes at the cost of completeness, earning a still respectable score.

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 five optional parameters, no annotations, and only an output schema, the description is far too sparse. It does not explain how to form a query, what filters are available, or any behavior expectations, leaving major gaps.

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?

The description does not mention any of the five parameters, and since schema descriptions are absent, the agent has no help interpreting fields like 'size' or 'source'. It adds no value beyond what the parameter names already suggest.

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 states the action ('Find genes') and the resource ('in specific pathways'), which distinguishes it from sibling tools like query_genes_by_disease or query_genes_by_chemical. However, it could be more specific about how pathways are identified (e.g., by ID or name).

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 implies use when a pathway is of interest, which is a loose usage guideline. But it does not explicitly mention alternatives or when not to use this tool, leaving the agent to infer the context from the tool name.

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