arxiv-mcp-server

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

The description mentions 'full metadata' implying comprehensive data retrieval, and 'one or more' matching the schema's array support. However, with readOnlyHint=true already declared in annotations, the description adds minimal behavioral context regarding error handling (e.g., invalid IDs), rate limits, or the 10-item maximum constraint documented in the schema.

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?

Two sentences total with zero waste. The first sentence front-loads the core capability (what), while the second provides usage context (when). Every word earns its place with 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 presence of an output schema (covering return values), simple single-parameter input, and readOnlyHint annotation, the description adequately covers the essential context. Minor gap: it doesn't mention the 10-item limit or error behavior, though these are partially covered by the schema.

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 100% schema description coverage, the parameter paper_ids is already well-documented with format examples and constraints. The description references 'by ID' but does not add semantic meaning, examples, or usage patterns beyond what the schema already provides, warranting the baseline score for high-coverage schemas.

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 specific action ('Get full metadata'), resource ('arXiv papers'), and access method ('by ID'). The 'by ID' qualifier effectively distinguishes this tool from siblings like arxiv_search (which finds papers) and arxiv_read_paper (which likely retrieves content).

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 second sentence provides explicit contextual guidance: 'Use when you have known IDs from citations, prior search results, or memory.' This clearly indicates when to use this tool versus searching, though it doesn't explicitly name the sibling search tool as the alternative.

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 readOnlyHint annotation already establishes this is a safe read operation. The description adds workflow context (that results are used as filters for arxiv_search) but does not disclose additional behavioral traits like rate limits, pagination, or caching behavior that might be relevant given it queries an external API.

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 consists of two efficient sentences with zero waste: the first establishes purpose, the second establishes usage context. Every word earns its place and the information is front-loaded appropriately.

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 a simple enumeration tool with one optional parameter and an output schema present, the description is complete. It explains what the tool returns (category codes and names) and the practical purpose (discovering filters), which is sufficient given the structured fields handle the rest.

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 100% schema description coverage, the schema already fully documents the optional 'group' parameter and its behavior when omitted. The description adds no parameter-specific details beyond what the schema provides, which warrants the baseline score of 3 for high-coverage schemas.

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 ('List') and resource ('arXiv category codes and names') and explicitly distinguishes itself from sibling tools by stating it provides 'valid category filters for arxiv_search', clearly differentiating it from the search and paper-reading tools.

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 this tool ('Useful for discovering valid category filters') and references the sibling tool 'arxiv_search' by name, establishing the clear workflow that users should call this first to obtain valid filter values before searching.

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?

With readOnlyHint=true in annotations, the safety profile is covered. The description adds valuable behavioral context not present in structured fields: the fallback mechanism ('Tries native arXiv HTML first, falls back to ar5iv') and the return format ('Returns raw HTML'). It does not mention rate limits or error states for invalid paper IDs, preventing a perfect score.

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?

Three sentences efficiently structured: purpose first, implementation detail second, output format third. Zero redundancy. Every sentence conveys distinct information (what it fetches, how it fetches, what it returns) without wasting tokens.

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 existence of an output schema (which handles return value documentation) and 100% input schema coverage, the description provides sufficient context. It acknowledges the output format (raw HTML), explains the fetching strategy (fallback), and covers the tool's scope completely for a 2-parameter read operation.

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%, establishing a baseline of 3. The main description does not explicitly discuss the parameters (paper_id, max_characters) or add semantic context beyond what the schema already provides. The detail about 'HTML head/boilerplate is stripped' appears in the schema's max_characters description, not the main description text.

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 states a specific verb ('Fetch') and resource ('full text content of an arXiv paper') and distinguishes from siblings by specifying 'full text content' versus metadata (arxiv_get_metadata) or search results (arxiv_search). The HTML rendering scope further clarifies the specific format retrieved.

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 functional context by specifying 'full text content,' which implicitly distinguishes it from the metadata-focused sibling (arxiv_get_metadata) and search sibling (arxiv_search). However, it does not explicitly state 'use arxiv_get_metadata instead for bibliographic data only' or similar explicit alternative guidance.

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?

With readOnlyHint=true in annotations, the description appropriately doesn't reiterate safety. It adds value by specifying the exact metadata fields returned (title, authors, abstract, categories, links), but omits details about pagination limits, empty result handling, or rate limiting.

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?

Two sentences with zero waste: first covers the search action and available filters, second covers the return payload. Every word earns its place; appropriately 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 presence of an output schema and comprehensive input schema, the description provides sufficient context for an agent to understand the tool's function. It appropriately summarizes the return values without redundant detail.

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?

Given 100% schema description coverage, the description meets the baseline by referencing 'category and sort filters' generally. It does not add semantic meaning beyond the detailed schema descriptions (e.g., it doesn't explain the query syntax that the schema already documents).

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 searches arXiv papers using queries with category and sort filters, and specifies it returns metadata (not full text). This implicitly distinguishes it from sibling arxiv_read_paper, though it doesn't explicitly contrast with arxiv_get_metadata.

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 implied usage guidance by specifying it returns paper metadata (title, authors, abstract, etc.), suggesting use for discovery rather than full-text retrieval. However, it lacks explicit when-to-use guidance or direct comparison with sibling tools.

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