recommend_papers

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

No annotations are provided, so the description carries the full burden. It discloses that the tool blends two signals, excludes papers already in the user's library (queue + 100 most recent), caps max_results at 20, and returns picks with a 'via' field and a problems array. It also notes that interests lead results and that problems should be relayed. It does not mention any destructive side effects or authentication requirements, but the tool appears to be read-only, so this is acceptable.

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 well-structured with a clear opening sentence, then explains the signals, parameters, output format, and important usage notes. It is front-loaded with purpose. While slightly verbose, each sentence adds value and no information is redundant. A minor improvement could be tighter phrasing.

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 no annotations and zero schema coverage, the description provides a comprehensive overview: it explains the two discovery arms, the output format (picks and problems), the 'via' field semantics, and the exclusion of library papers. It also mentions an upstream limit (computer science only). It lacks information about error states (e.g., if all seeds fail) or rate limits, but for a recommendation tool it is reasonably complete.

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 input schema has 0% description coverage, so the description must compensate. It explains each parameter: interests (2-4 short phrases), seed_refs (for citation graph seeding), max_results (capped at 20), and recent_only (new vs all-time). It also clarifies defaults (uses library if no interests) and constraints (computer science only upstream). This adds meaningful context beyond the raw 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 clearly identifies the tool as discovering papers the user may want to read, blending citation-graph and keyword signals. It specifies sources (Semantic Scholar, OpenAlex) and states that it excludes already-in-library papers. This distinguishes it from sibling tools like search_papers (which likely returns exact matches) and queue/send operations.

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 explains when to use the tool (to get paper recommendations) and how to provide inputs (interests as phrases, seed_refs for explicit seeds). It also advises to present picks and let the user choose, not send unasked. However, it does not explicitly state when not to use it, e.g., if the user wants a simple keyword search rather than a blended recommendation.

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