Search arXiv

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds value beyond that by disclosing the return payload (metadata and abstracts) and by handing off to a different tool for full text. No mention of rate limits or result-cap behavior, but the schema covers the cap.

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?

Front-loaded with purpose, then query semantics, then the combination rules, then the hand-off. Every sentence carries information the agent needs; the prefix list and examples are dense but earn their place. No filler or restatement of the title.

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?

For an 8-parameter, no-output-schema search tool, the description covers the hardest part (query syntax) and tells the agent what comes back. What's missing is modest: guidance on paging behavior across offsets and a pointer that only metadata/abstracts come back rather than full text is present but thin on result volume.

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?

With 63% schema coverage, the description substantially compensates: it explains that bare terms are AND-ed across title/abstract/authors, enumerates the field prefixes (ti, au, abs, cat, all), and gives concrete boolean examples that the schema's one-line `query` description does not. It also clarifies how `query`, `category`, and the date window combine. It does not explain sort_by/sort_order/max_results, though those are self-documenting via enums and defaults.

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?

Opens with a specific verb+resource ("Search arXiv papers") and immediately states what the tool returns ("metadata and abstracts"), which implicitly separates it from the single-paper lookup sibling. It also explicitly routes full-text reading to arxiv_get_full_text, so an agent can distinguish this tool from at least one sibling without opening either schema.

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?

Gives clear in-context guidance on when to use plain text vs. raw arXiv syntax, and names the alternative arxiv_get_full_text for reading a paper. It stops short of explaining when to prefer arxiv_get_paper (single known paper) over this search, or when the biorxiv siblings are the better choice.

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