arxiv-mcp-server

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

Annotations already declare readOnlyHint=true, so the agent knows this is a safe read operation. The description adds minimal behavioral context beyond stating the function. It does not mention any potential side effects or unusual behaviors, but none are expected for a read-only metadata lookup. The absence of contradiction with annotations is noted.

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 two sentences long and entirely informative. The first sentence states the function, and the second gives usage guidance. There is no redundant or filler content, making it highly concise 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?

The tool is simple with only one parameter, and the schema fully documents its format. The presence of an output schema means return values need not be described. The description adequately covers purpose and usage context, and annotations cover safety. No additional context is necessary.

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 coverage is 100%: the input schema fully describes the paper_ids parameter, including formats like '2401.12345' and '2401.12345v2', and the array limitation of up to 10 IDs. The description adds only the context of when to use these IDs ('from citations, prior search results, or memory'), which is minor. Baseline 3 is appropriate since the schema already provides the necessary parameter semantics.

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 states the tool's function: 'Get full metadata for one or more arXiv papers by ID.' It uses a specific verb ('Get'), identifies the resource ('arXiv papers'), and specifies the exact input ('by ID'). This distinguishes it from sibling tools like arxiv_search (search by query) and arxiv_read_paper (read full text).

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 when to use the tool: 'Use when you have known IDs from citations, prior search results, or memory.' This gives clear context for usage, though it does not explicitly mention alternatives or exclusions beyond implying that the tool is for ID-based lookups rather than search.

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

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

Annotations declare readOnlyHint=true, and the description adds useful context beyond that, such as that it lists subject classes only and that arxiv_search can accept a bare archive code. It also clarifies the scope of categories returned.

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 concise sentences, each contributing meaningful information: what it lists, why it's useful, and a key distinction from arxiv_search. No redundancy or filler.

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 the simple single-parameter schema, the presence of an output schema, and the readOnly annotation, the description fully covers the tool's purpose and usage context. It explains the essential nuance about subject classes vs. archive codes, making the tool complete for its intended use.

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 schema already fully describes the single optional 'group' parameter with an enum and clear description, achieving 100% schema coverage. The tool description adds no additional parameter-specific semantics but does not need to; the schema carries the burden.

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 states the tool lists arXiv category codes and names, making the resource and action explicit. It also distinguishes itself from sibling tools by referencing arxiv_search and clarifying the difference between subject classes and bare archive codes.

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 provides explicit usage context: it is useful for discovering valid category filters for arxiv_search. It also gives an alternative behavior (arxiv_search accepts bare archive codes) effectively indicating when this tool may not be needed.

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

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

The description is rich with behavioral insights beyond the readOnlyHint annotation: it discloses the multi-source fallback strategy (arxiv.org/html → ar5iv → PDF extraction), the presence of a 'source' field to identify the answering renderer, the character-based paging mechanism, and the note that whole-paper reads can be 300KB-1MB+ and may exceed tool-result caps. This gives the agent actionable knowledge about how the tool behaves, not just what it does.

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 two sentences, each earning its place. The first sentence states the core purpose and discloses the fallback chain and source field. The second sentence provides paging instructions and the null option in a compact, well-structured way. There is no fluff, and the most important information is 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?

Given the tool's complexity (multi-source fallback, paging, character limits), the description is remarkably complete. It covers the main behavioral facets, mentions the response field 'source' and 'body_characters,' and provides enough guidance for safe usage. The output schema fills in return value details, and the annotations cover the read-only safety, so the description focuses on the highest-value contextual information.

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 each parameter already has detailed documentation. The description text adds complementary value by framing start and max_characters as a paging system (e.g., 'start=100000 with max_characters=100000 returns chars 100,000–199,999') and by warning about result size limits for null max_characters. This enhances the agent's ability to choose appropriate parameter values, going slightly beyond the schema's own descriptions.

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 starts with 'Fetch the full text of an arXiv paper,' which is a specific verb and resource that clearly distinguishes it from the sibling tools (metadata, list categories, search). It goes beyond a simple restatement of the title by detailing the source fallback chain and paging behavior, making its purpose unmistakable.

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 provides clear context for when to use the tool—whenever full text of an arXiv paper is needed—and includes practical usage notes about paging with start/max_characters and the null option for full-body reads. It doesn't explicitly contrast with sibling tools, but the siblings are functionally different enough that exclusion isn't necessary, and the guidance is strong enough to warrant a 4.

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

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

The description adds no behavioral context beyond the readOnlyHint annotation. It does not disclose any rate limits, pagination quirks (though these are in the schema), or other side effects. There is no contradiction, but the description itself is silent on behavior.

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 two concise sentences: the first establishes the purpose with a clear verb and object, the second lists the return content. No wasted words and information is 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?

Given the extremely detailed input schema and the presence of an output schema, the description is adequate for a search tool. It gives the essential purpose and return type, though it could be slightly more explicit about usage boundaries relative to sibling tools for a perfect score.

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 every parameter is already documented in the schema. The description only mentions 'category and sort filters' at a high level, adding no new meaning beyond what the schema provides. 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 clearly states it 'Search arXiv papers by query with category and sort filters', using a specific verb and resource. This distinguishes it from sibling tools like arxiv_get_metadata (retrieval of specific papers) and arxiv_list_categories (listing categories).

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 usage for query-based paper search but does not explicitly state when to use this tool vs alternatives, nor does it mention any exclusion criteria or when to prefer arxiv_get_metadata for a known paper ID. It is clear but not instructive beyond the obvious.

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