find_paper_code

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

Annotations already establish readOnlyHint and openWorldHint, so the safety profile is covered. The description goes further by disclosing real behavioral traits beyond the annotations: no API key required, a paper with nothing linked returns found=false rather than an error, and partial sub-lookup failures surface in warnings while the rest of the result is still returned. That degradation semantics is genuinely useful and not recoverable from the annotations alone.

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?

A single dense sentence-and-a-half paragraph with the resource scope front-loaded, followed by the auth and failure-mode clauses. Every sentence carries information, though the opening clause runs long and could be split for faster scanning.

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?

An output schema exists, so return field documentation need not live in the description, yet the description still covers the two things an agent most needs: the empty-result sentinel (found=false) and partial-failure warnings. Combined with the no-key note, an agent can call this correctly and interpret the response without further context.

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 100%, so the schema already documents both paper_id (arXiv ID with ignored version suffix) and max_results (per-type cap, default 5). The description adds no parameter-level detail — such as paper_id syntax examples or how max_results interacts with the per-type grouping — so baseline 3 applies.

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 uses a specific verb+resource framing ('Find where the code and artifacts for an arXiv paper live') and enumerates exactly what is returned: GitHub repo with stars, project page, most-downloaded HF models/datasets, and linked Spaces. That is clearly distinguishable from siblings like search_papers or read_paper, which operate on paper text rather than artifact linkage.

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?

Usage is implied by the resource description — an agent can infer this is for locating code/artifacts rather than reading content — but no sibling is named and there is no explicit when-not guidance. Nothing steers the agent away from calling search_papers first or clarifies ordering relative to download_paper.

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