find_similar_papers

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

No annotations are provided, so the description carries the burden of disclosing behavior. It explains the operation is read-only in effect, returns "the most similar papers... each with the full summary and code link," and notes the seed must come from a prior search result. It does not discuss error handling or edge cases, but for a retrieval tool this is sufficient; the disclosure is clear and non-misleading.

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 three sentences long, with the core purpose stated first, followed by usage guidance and a chaining example. Every sentence adds value, there is no repetition of schema content, and the structure is well-organized and front-loaded.

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?

Despite having no output schema, the description tells the user what to expect (full summary and code link) and how to use the tool iteratively. It covers prerequisites (a paper from a prior search), the use cases, and the workflow with search. It does not mention potential error scenarios, but for a straightforward recommendation tool, the description is sufficiently 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 already provides 100% coverage of all four parameters, so the description does not need to add parameter-level detail. The description reinforces that the seed paper must already exist ("from a prior search result"), which aligns with the schema's emphasis on using a real arXivSub id. Since schema coverage is complete, the baseline of 3 is appropriate.

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, actionable statement: "Given ONE paper you already have... return the most similar papers from the same corpus — semantic nearest neighbours." This clearly identifies the tool's function and resource, and distinguishes it from sibling search or library tools by emphasizing that it requires a prior paper as input rather than a query.

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 explicitly states common use cases: "Use for 'more like this', 'related work', 'what else is in this line of work', or to expand a literature review." It also provides a chaining workflow (search -> pick a seed -> find_similar_papers -> repeat), which gives practical guidance. However, it does not explicitly name when NOT to use this tool or mention specific alternatives, so it falls just 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.