Skip to main content
Glama
adsabs

NASA SciX MCP Server

by adsabs
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
TypeScript
Remote

NASA SciX MCP Server

A Model Context Protocol (MCP) server for the NASA Astrophysics Data System (SciX) API. This server enables LLMs to search astronomical literature, retrieve paper metadata, analyze citation metrics, and export bibliographic data.

Quick Start (MCP clients)

Get an API Key

  1. Create an account at SciX

  2. Generate an API token at https://scixplorer.org/user/settings/token

  3. Set the environment variable:

export SCIX_API_TOKEN=your_api_key_here

Or create a .env file:

cp .env.example .env
# Edit .env and add your key

Configure your MCP client (Claude, Codex, etc.)

Add to your MCP client configuration:

{
  "mcpServers": {
    "ads": {
      "command": "npx",
      "args": ["scix-mcp"],
      "env": {
        "SCIX_API_TOKEN": "your_api_key_here"
      }
    }
  }
}

Common locations: Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %AppData%\\Claude\\claude_desktop_config.json on Windows) and Codex CLI (~/.config/codex/config.json). Restart your client after editing.

Local MCP clients that read .mcp/server.json can also pick up the packaged config in .mcp/server.json; just drop in your SCIX_API_TOKEN.

Environment variables

  • SCIX_API_TOKEN (required): your SciX/ADS API key.

  • SCIX_API_BASE (optional): override the API base URL. Defaults to https://api.adsabs.harvard.edu/v1 when unset. Primarily used to point the server at a local mock during the e2e test suite.

Related MCP server: NASA ADS MCP Server

Example Prompts

- Find refereed JWST exoplanet papers from 2022-2024 sorted by citation_count, return the top 5 in markdown with bibcodes, titles, first author, and citation counts.
- Build a query for gravitational wave kilonova follow-ups since 2017 (fielded abstract search), add the first 50 results to library <library_id>, and then give me metrics (h-index, total cites) for those bibcodes in JSON.
- Fetch paper 2020ApJ...905....3A, list its first 10 references with titles, and also list the first 10 forward citations with publication years.
- Create a public library named “Cosmic Web Reviews”, seeded with bibcodes [...], then share the public URL and export the contents in BibTeX.
- For bibcodes [...], return citation metrics plus a ranked list of which papers cite the most recent one (rows=25) in markdown.
- Get all my libraries, pick the one with the most documents, and return its metadata plus the first 5 document titles in JSON.

Features

  • Literature Search: Full-text search with advanced Solr query syntax

  • Paper Details: Retrieve metadata for any publication

  • Citation Metrics: Calculate h-index, citation counts, and usage statistics

  • Citation Network: Explore forward and backward citations

  • Export: Generate citations in 23 bibliographic formats (BibTeX, AASTeX, EndNote, RIS, and more) — see the export tool's format enum in src/types.ts for the full list

  • Documentation Search: Query SciX help/docs content via the search_docs tool

  • Health Check: Diagnose setup (token, API reachability, tool registry) via the health_check tool

  • Dual Format: Support for both human-readable Markdown and machine-readable JSON

Available Tools

Search & Metadata

  • search: Solr-powered search across SciX. Params: query (required), rows (1-100, default 10), start (offset, default 0), sort (score desc | citation_count desc | date desc | date asc | read_count desc, default score desc), response_format (markdown | json, default markdown).

    • Example queries: author:"Einstein, A." title:relativity, black holes year:2020-2023, author:^Smith, dark energy AND galaxy clusters.

  • get_paper: Fetch a paper by bibcode, DOI, arXiv ID, or SciX ID (scix:...) with optional response_format.

  • get_metrics: Metrics for bibcodes (1-2000) with optional response_format; returns h-index, g-index, citation counts, usage stats.

Citation Network

  • get_citations: Forward citations for a paper (bibcode, DOI, arXiv ID, or SciX ID); optional rows (1-100, default 20) and response_format.

  • get_references: Backward references for a paper (bibcode, DOI, arXiv ID, or SciX ID); optional rows (1-100, default 20) and response_format.

Export

  • export: Export bibcodes (1-2000) in format — one of the 23 formats in the ExportInputSchema enum in src/types.ts (e.g. bibtex, aastex, endnote, ris, ieee, mnras). Use custom_format with format: custom for a template. Returns plain text in the chosen format.

Documentation

  • search_docs: Search SciX help documentation. Params: query (required, natural language), limit (1-20, default 5). Returns a ranked list with title, section/subsection, source URL, relevance score, and a focused snippet.

Libraries

  • get_libraries: List libraries; optional type (all | owner | collaborator, default all) and response_format.

  • get_library: Metadata + documents for library_id; optional response_format.

  • create_library: Create with name (required), optional description, public (default false), bibcodes, and response_format.

  • delete_library: Permanently delete by library_id; optional response_format.

  • edit_library: Update name, description, or public for library_id; optional response_format.

  • manage_documents: Add/remove documents with library_id, bibcodes (1-2000), action (add | remove), and optional response_format.

  • add_documents_by_query: Add search results to a library with library_id, query, optional rows (1-2000, default 25), and response_format.

  • library_operation: Run set ops on a library with library_id, operation (union | intersection | difference | copy | empty), optional source_library_ids, name/description (for copy), and response_format.

Permissions & Sharing

  • get_permissions: View owners/collaborators for library_id; optional response_format.

  • update_permissions: Grant/change a user's access with library_id, email, permission (owner | admin | write | read), and optional response_format.

  • transfer_library: Transfer ownership with library_id, email, and optional response_format.

Annotations

  • get_annotation: Fetch note content for library_id + bibcode; optional response_format.

  • manage_annotation: Add/update note with library_id, bibcode, content, and optional response_format.

  • delete_annotation: Remove note for library_id + bibcode; optional response_format.

Diagnostics

  • health_check: Diagnose the server setup. No required params (optional response_format). Reports server name/version, API base URL, whether a token is configured, an authentication probe result (ok | unauthorized | rate_limited | unreachable | skipped), and the registered tool names. Never emits the token value. Runs without a token (probe is skipped); use it to tell setup problems apart from ordinary API errors.

Rate Limits

  • 5000 requests per day per API key

  • Rate limit info is returned in response headers

  • Contact adshelp@cfa.harvard.edu for higher limits

SciX Search Syntax

The SciX search supports Solr query syntax:

Syntax

Description

Example

author:"Last, F."

Exact author

author:"Huchra, John"

author:^Last

First author

author:^Smith

title:keyword

Title search

title:exoplanet

abstract:keyword

Abstract search

abstract:"dark matter"

year:YYYY-YYYY

Year range

year:2020-2023

property:refereed

Refereed only

property:refereed

citations(bibcode:X)

Papers citing X

citations(bibcode:2019ApJ...)

references(bibcode:X)

Papers cited by X

references(bibcode:2019ApJ...)

AND, OR, NOT

Boolean operators

black holes AND galaxy

Development

Install & Build

pnpm install
pnpm build

Local commands

# Watch mode
pnpm dev

# Test with MCP Inspector
npx @modelcontextprotocol/inspector node build/index.js

Testing

The project uses Vitest.

Running Tests

# Run all tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Run tests with coverage
pnpm test:coverage

# Run the end-to-end protocol smoke suite (builds first, then drives the
# built server over stdio against a local mock ADS API)
pnpm test:e2e

The e2e suite (test/e2e/protocol.test.ts) spawns node build/index.js, connects a real MCP client over stdio, and asserts the live tool/prompt/ resource surface plus one canned call per tool. It points the server at a local mock via the SCIX_API_BASE environment variable (see below); no real network access is required.

Test Structure

Tests are organized in the test/ directory:

test/
├── helpers/
│   └── mockFetch.ts        # Fetch mocking utilities
├── client.test.ts          # HTTP client tests
├── search-docs.test.ts     # Documentation search tests
└── tools/
    ├── search.test.ts      # Search tool tests
    ├── paper.test.ts       # Paper details tests
    ├── metrics.test.ts     # Metrics tests
    ├── citations.test.ts   # Citations/references tests
    ├── export.test.ts      # Export tests
    └── library.test.ts     # Library management tests

Test Coverage

The test suite covers:

  • HTTP Client: GET/POST/PUT/DELETE methods, error handling (401/404/429), timeouts, request formatting

  • Search Tools: Query parameter encoding, pagination, result limiting, response formatting

  • Paper Tools: Bibcode validation, field selection, error handling for missing papers

  • Metrics Tools: Batch bibcode processing, MAX_BIBCODES limits, metric type selection

  • Citation Tools: Forward/backward citations, sorting, row limits

  • Export Tools: Multiple export formats (BibTeX, AASTeX, EndNote, etc.), batch processing

  • Library Tools: All CRUD operations, permissions, annotations, library operations

API Token for Tests

Tests use mock fetch and don't require a real API token. Individual tests set SCIX_API_TOKEN='test-api-key' as needed.

Project Structure

src/
├── index.ts             # Main server entry point
├── client.ts            # SciX API client wrapper
├── types.ts             # TypeScript/Zod type definitions
├── formatters.ts        # Response formatting utilities
├── config.ts            # Configuration constants
├── identifier-query.ts  # Identifier (bibcode/DOI/arXiv/SciX) resolution
├── search-docs.ts       # Offline docs search (search_docs tool)
└── tools/
    ├── search.ts        # Search tool
    ├── paper.ts         # Paper details tool
    ├── metrics.ts       # Metrics tool
    ├── citations.ts     # Citation network tools
    ├── export.ts        # Export tool
    └── library.ts       # Library management tools

Example Usage

Search for papers

Use search with query "supernova 2023" to find recent supernova papers

Get paper details

Use get_paper with bibcode "2023ApJ...950..123S"

Calculate metrics

Use get_metrics with bibcodes ["2023ApJ...950..123S", "2022MNRAS.517.1234T"]

Export citations

Use export with bibcodes ["2023ApJ...950..123S"] and format "bibtex"

Error Handling

The server provides clear error messages:

  • 401: Invalid API key - check SCIX_API_TOKEN

  • 404: Resource not found - check bibcode format

  • 429: Rate limit exceeded - wait until reset

  • Timeout: Request took > 30 seconds

Resources

License

MIT

Support

For API issues: adshelp@cfa.harvard.edu For server issues: Open an issue on GitHub

Available Tools

21 tools
add_documents_by_queryB

Add documents to a library from a SciX search query.

ParametersJSON Schema
NameRequiredDescriptionDefault
library_idYesLibrary identifier
queryYesSciX search query
rowsNoNumber of results to add (1-2000, default 25)
response_formatNomarkdown

TDQS

B3.4/5.0
Behavior2/5

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

Annotations indicate a mutation (readOnlyHint=false) but no destructive or idempotent hints. The description merely says 'add' without disclosing behavior on overlapping queries, error handling, or side effects beyond the basic action.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that immediately states the tool's purpose without any extraneous words. It is front-loaded and efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of output schema and minimal annotations, the description is too brief. It does not cover return format, error scenarios, or the behavior when the query yields no results, which a mutation tool should ideally address.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema covers 75% of parameters with basic descriptions. The description adds no additional meaning for 'library_id' or 'query' beyond the schema. The 'rows' and 'response_format' parameters have useful defaults and enumerations in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (add documents) and the source (from a SciX search query) and target (to a library). It distinguishes from sibling tools like 'search' which only retrieves results.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when a user has a SciX query and wants to populate a library. However, it does not provide explicit when-not-to-use guidance or mention alternative tools.

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

create_libraryA

Create a new library with optional initial documents.

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYesLibrary name (1-255 characters)
descriptionNoLibrary description (optional)
publicNoWhether library is public
bibcodesNoInitial bibcodes to add (optional)
response_formatNomarkdown

TDQS

A4/5.0
Behavior4/5

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

Annotations indicate a write operation (readOnlyHint: false) and non-destructiveness (destructiveHint: false). The description adds the context of optional initial documents, fitting the operation without contradicting annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that efficiently conveys the essential purpose without any redundant or extraneous words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple creation tool with no output schema, the description adequately covers the core action and optionality. However, it could be improved by noting what is returned or any side effects, though not strictly necessary.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

All parameters have schema descriptions (100% coverage), so the description adds minimal value. It mentions 'optional initial documents' but this is already captured by the bibcodes parameter description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('create'), the resource ('a new library'), and an optional feature ('with optional initial documents'). This effectively distinguishes it from sibling tools like delete_library or edit_library.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for creating a library but does not specify when not to use it or suggest alternatives. It lacks explicit guidance compared to tools like edit_library for updates.

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

delete_annotationA
Destructive

Delete an annotation/note for a document in a library.

ParametersJSON Schema
NameRequiredDescriptionDefault
library_idYesLibrary identifier
bibcodeYesBibcode to remove annotation from
response_formatNomarkdown

TDQS

A3.6/5.0
Behavior3/5

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

Annotations already indicate destructiveHint: true. The description confirms the destructive action but adds no further behavioral context beyond what annotations provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, clear sentence with no unnecessary words, effectively conveying the tool's purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple operation and annotations (destructiveHint: true), the description is mostly complete. It lacks mention of response format, but overall adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema descriptions cover 67% of parameters. The description does not add extra meaning beyond the schema, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Delete an annotation/note for a document in a library', using a specific verb and resource, distinguishing it from sibling tools like get_annotation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives (e.g., manage_annotation). The description does not specify preconditions or scenarios.

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

delete_libraryA
Destructive

Delete a library permanently.

ParametersJSON Schema
NameRequiredDescriptionDefault
library_idYesLibrary identifier
response_formatNomarkdown

TDQS

A3.5/5.0
Behavior4/5

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

Annotations already indicate destructiveHint=true, and description adds 'permanently', confirming irreversibility. No hidden behaviors, but could mention what happens to associated data.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single concise sentence conveying the core purpose without unnecessary words. Lacks structure but is efficiently front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Basic information provided for a destructive tool with no output schema, but missing details on error scenarios, permissions, or idempotency. Adequate but incomplete considering sibling tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 50%, with one parameter described (library_id) and one enum (response_format). Description adds no parameter meaning beyond what the schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (Delete) and the resource (library) with 'permanently' emphasizing finality, differentiating it from sibling tools like create_library or get_library.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives (e.g., edit_library, delete_annotation) or prerequisites (e.g., ownership, empty library).

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

edit_libraryA
Idempotent

Edit library metadata (name, description, public status).

ParametersJSON Schema
NameRequiredDescriptionDefault
library_idYesLibrary identifier
nameNoNew library name (optional)
descriptionNoNew library description (optional)
publicNoWhether library is public (optional)
response_formatNomarkdown

TDQS

A3.5/5.0
Behavior3/5

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

Annotations already indicate this is a mutation (readOnlyHint=false), not destructive, idempotent, and open-world. The description adds no extra behavioral context (e.g., auth requirements, side effects), so it meets the minimum but adds no value beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, clear sentence with no unnecessary words. It is front-loaded with the verb and resource.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the core parameters but omits return value or success indicators. Given the absence of an output schema, more detail on what happens after editing would improve completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is high (80%), and the schema already describes all parameters. The description briefly lists three editable fields but adds no additional meaning or constraints beyond what the schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Edit' and the resource 'library metadata', specifying the exact fields (name, description, public status). It distinguishes from sibling tools like delete_library, create_library, and get_library.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives such as update_permissions or library_operation. No exclusions or prerequisites are mentioned.

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

exportA
Read-only

Export citations in 25+ academic formats (BibTeX, AASTeX, EndNote, IEEE, MNRAS, etc.) with support for custom formatting templates.

ParametersJSON Schema
NameRequiredDescriptionDefault
bibcodesYesList of SciX bibcodes to export (1-2000)
formatYesExport format
custom_formatNoCustom format string using field specifiers (required when format is custom)
sortNoSort order for bibcodes (e.g., "date desc", "first_author asc")
maxauthorNoMaximum number of authors to display (default: 200)
authorcutoffNoNumber of authors before using "et al."
journalformatNoJournal name format: 1 (AASTeX macros), 2 (abbreviations), 3 (full names)
keyformatNoBibTeX key format template (e.g., "%1H%Y" for FirstAuthorYear)

TDQS

A3.6/5.0
Behavior3/5

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

The description does not contradict annotations (readOnlyHint=true, destructiveHint=false). It adds minimal behavioral context beyond the annotations, simply stating 'export citations', which implies a read operation. No additional behavioral traits are disclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-structured sentence that front-loads the key information (export, many formats) and includes specific examples. Every word serves a purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of an output schema and the tool's complexity (8 parameters, many formats), the description is reasonably complete. It covers the primary purpose and mentions custom templates, though it could elaborate on the output format.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

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 all parameters adequately. The description mentions 'support for custom formatting templates', which adds a bit of context for the custom_format parameter, but overall adds little extra meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that the tool exports citations in over 25 academic formats, listing specific examples like BibTeX and IEEE. It distinguishes itself from sibling tools (e.g., get_citations, search) by focusing on format conversion.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not provide any guidance on when to use this tool versus alternatives. There is no mention of prerequisites, exclusions, or comparisons to sibling tools like get_citations or search.

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

get_annotationA
Read-onlyIdempotent

Get annotation/note for a document in a library.

ParametersJSON Schema
NameRequiredDescriptionDefault
library_idYesLibrary identifier
bibcodeYesBibcode to get annotation for
response_formatNomarkdown

TDQS

A3.5/5.0
Behavior3/5

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, so safety and idempotency are covered. The description adds that it retrieves an annotation for a document, but does not disclose behavior like error handling for missing annotations or the effect of the response_format parameter. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that is clear and to the point. It could be slightly more informative about the response_format, but it is not verbose or wasteful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple with no output schema and good annotations. However, the description does not explain the behavior of the response_format parameter or what happens if no annotation exists. Given the low complexity, it is mostly complete but has a minor gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 67% (2 of 3 parameters have descriptions). The description does not add any additional meaning beyond the schema; it does not explain the response_format parameter (e.g., what each format looks like). Since coverage is not high (>80%), the description should compensate but does not.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (Get) and the resource (annotation/note for a document in a library). This distinguishes it from sibling tools like delete_annotation and manage_annotation, which have different verbs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not explicitly state when to use this tool versus alternatives. However, the purpose is implied by the verb 'Get' and the sibling tools suggest different actions like deletion or management, so usage context is indirectly clear but not explicit.

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

get_citationsA
Read-onlyIdempotent

Get papers that cite a given paper (forward citations).

ParametersJSON Schema
NameRequiredDescriptionDefault
bibcodeYesSciX bibcode identifier
rowsNoNumber of citations to return (1-100, default 20)
response_formatNomarkdown

TDQS

A4/5.0
Behavior3/5

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

Annotations already provide safety traits (readOnly, idempotent). The description adds minimal behavioral context beyond stating it returns citing papers. With annotations covering the safety profile, the description's contribution is adequate but not enriched.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence with specific verb ('Get') and resource ('papers that cite a given paper'), no wasted words, information clearly front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simplicity of the tool and thorough schema annotations, the description is sufficient. It lacks explicit output format details, but that is covered by the response_format parameter.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema descriptions cover all parameters comprehensively (bibcode as identifier, rows with range/default, response_format as enum). The description adds no extra meaning beyond the schema, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it retrieves citing papers (forward citations) for a given paper using a bibcode identifier. It implicitly distinguishes from the sibling tool 'get_references' (backward citations) by specifying 'forward citations'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context for when to use (when you need forward citations) and implies the alternative (get_references for backward citations) through the sibling list. However, it does not explicitly state when not to use this tool or provide additional usage constraints.

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

get_librariesA
Read-onlyIdempotent

Get all libraries for the authenticated user. Can filter by type (all, owner, collaborator).

ParametersJSON Schema
NameRequiredDescriptionDefault
typeNoFilter by library typeall
response_formatNomarkdown

TDQS

A3.8/5.0
Behavior3/5

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

Annotations already declare readOnlyHint, destructiveHint, idempotentHint, and openWorldHint. The description adds context about filtering but does not disclose additional behavioral traits such as pagination, rate limits, or return format beyond what annotations provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loads the core purpose, and contains no redundant words. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple list tool with 2 parameters (none required), rich annotations, and no output schema, the description adequately covers the main operation and filter option. However, it could mention the return format (list) and that the response_format parameter exists, though the schema provides enums.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 50%; the 'type' parameter is described in the schema as 'Filter by library type' and the description reinforces that. However, the 'response_format' parameter lacks a schema description and the description does not mention it, leaving half of the parameters with no added meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Get', resource 'libraries', and scope 'for the authenticated user' with optional filter by type, effectively distinguishing it from sibling tools like 'get_library' which retrieves a single library.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for listing libraries with optional filtering but does not explicitly state when to use this tool versus alternatives like 'get_library' for single library retrieval or 'search' for broader queries. No when-not-to-use guidance is provided.

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

get_libraryB
Read-onlyIdempotent

Get details about a specific library including metadata and list of documents.

ParametersJSON Schema
NameRequiredDescriptionDefault
library_idYesLibrary identifier
response_formatNomarkdown

TDQS

B3.3/5.0
Behavior2/5

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

Annotations already provide readOnlyHint and idempotentHint. The description adds minimal behavioral context beyond stating what is returned (metadata, documents). It does not elaborate on pagination, permissions, or output format specifics.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence that directly states the purpose. It is front-loaded and concise, though could be structured into bullet points for easier scanning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only tool with strong annotations, the description provides basic completeness by mentioning returned data (metadata, documents). However, it lacks details on response format, document list size limits, or filtering possibilities.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already describes both parameters adequately (library_id as 'Library identifier' and response_format with enum/default). The tool's description does not add further meaning or clarification beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Get' and resource 'library', specifying it includes 'metadata and list of documents'. This effectively distinguishes it from sibling 'get_libraries' and other mutation tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for retrieving library details but does not explicitly state when to use versus alternatives like 'get_libraries' for listing, or any exclusions.

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

get_metricsA
Read-onlyIdempotent

Get citation metrics including h-index, citation counts, and paper statistics for a list of bibcodes.

ParametersJSON Schema
NameRequiredDescriptionDefault
bibcodesYesList of SciX bibcodes (1-2000)
response_formatNomarkdown

TDQS

A3.6/5.0
Behavior3/5

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description's 'Get' is consistent. However, the description adds no additional behavioral context such as error handling or performance implications, so it does not exceed the baseline provided by annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that front-loads the core purpose. Every word is functional with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (2 parameters, no output schema, and safety annotations), the description covers the essential function and inputs. It is nearly complete, though it does not explain whether returned metrics are per bibcode or aggregated.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 50% (the bibcodes parameter has a clear description and constraints). The description does not add new meaning beyond what the schema provides for either parameter, so it meets the baseline without adding value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Get'), the resource ('citation metrics'), and specifies the items included ('h-index, citation counts, and paper statistics') and the input ('list of bibcodes'). This distinguishes it from siblings like get_citations or get_references.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives like get_citations or search. There are no explicit conditions, exclusions, or recommendations for usage.

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

get_paperA
Read-onlyIdempotent

Get detailed information about a specific paper by its SciX bibcode (e.g., 2019ApJ...886..145M).

ParametersJSON Schema
NameRequiredDescriptionDefault
bibcodeYesSciX bibcode identifier
response_formatNomarkdown

TDQS

A3.7/5.0
Behavior3/5

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

Annotations already indicate readOnlyHint=true and idempotentHint=true, so the description's claim of 'detailed information' is consistent but adds little beyond stating it's a read operation. It does confirm the tool is safe to use.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence that front-loads the primary action and resource, with no extraneous words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple retrieval tool without an output schema, the description could hint at what 'detailed information' includes (e.g., authors, abstract, year). It is adequate but insufficient for full autonomy.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description provides an example bibcode (2019ApJ...886..145M) which adds semantic understanding beyond the schema's 'SciX bibcode identifier'. However, the response_format parameter is not explained in the description, leaving its behavior implicit.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool gets detailed information about a specific paper using a SciX bibcode, which is a specific verb+resource combination. It provides an example of the bibcode format, adding clarity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus siblings like get_citations or get_references. It does not mention when-not or alternative tools.

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

get_permissionsA
Read-onlyIdempotent

Get permission information for a library.

ParametersJSON Schema
NameRequiredDescriptionDefault
library_idYesLibrary identifier
response_formatNomarkdown

TDQS

A3.5/5.0
Behavior3/5

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

Annotations already declare readOnlyHint=true and idempotentHint=true. Description adds no behavioral details beyond the basic action. No contradictions, but also no added value.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence with no filler. Efficient and front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema, but description does not explain what 'permission information' includes. Lacks specification of return format or error handling. Minimal coverage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 50% (library_id described, response_format only via enum). Description does not elaborate on parameters, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the action (get) and resource (permission information for a library). No ambiguity, distinct from siblings like update_permissions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives like update_permissions. No hints about typical scenarios or prerequisites.

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

get_referencesA
Read-onlyIdempotent

Get papers referenced by a given paper (backward citations).

ParametersJSON Schema
NameRequiredDescriptionDefault
bibcodeYesSciX bibcode identifier
rowsNoNumber of references to return (1-100, default 20)
response_formatNomarkdown

TDQS

A3.9/5.0
Behavior3/5

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds that it retrieves backward citations, but no additional behavioral traits (e.g., pagination, rate limits) are disclosed. The description does not contradict annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, clear sentence with no unnecessary words. It front-loads the core purpose and includes a clarifying parenthetical note.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has 3 parameters and lacks an output schema. The description does not explain the return format or structure, though the 'response_format' parameter hints at choices. For a simple list retrieval, this is adequate but could be more complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 67% (2 of 3 parameters have descriptions). The description does not add any parameter-level information beyond what the schema provides. The schema already explains the parameters adequately.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's action ('get papers referenced') and identifies the resource ('by a given paper'). It explicitly mentions 'backward citations', which distinguishes it from the sibling tool 'get_citations' that handles forward citations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for retrieving backward citations but does not explicitly mention when not to use it or suggest alternatives like 'get_citations' for forward citations. However, the context is clear enough for an agent familiar with citation concepts.

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

library_operationB

Perform set operations on libraries (union, intersection, difference, copy, empty).

ParametersJSON Schema
NameRequiredDescriptionDefault
library_idYesTarget library identifier
operationYesOperation to perform
source_library_idsNoSource library IDs for set operations (optional)
nameNoName for new library (for copy operation, optional)
descriptionNoDescription for new library (for copy operation, optional)
response_formatNomarkdown

TDQS

B3.4/5.0
Behavior3/5

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

Annotations indicate the tool is read/write (readOnlyHint=false) and not destructive (destructiveHint=false). The description adds 'perform operations' but does not disclose that operations like 'empty' might remove all content or whether changes are reversible. With annotations providing basic safety info, the description offers minimal additional behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with 8 words, immediately stating the core action and listing operation types. It is extremely concise with no wasted words, and the key information is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 6 parameters and 5 operations, the description omits critical details: return values (no output schema), error behavior, prerequisites, and whether operations are in-place or create new libraries. The openWorldHint suggests potential side effects not described. The description is too brief to fully inform an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema descriptions cover 83% of parameters, providing clarity on each parameter's purpose. The description adds a list of operations but does not explain parameter relationships (e.g., source_library_ids only relevant for set operations). Given high schema coverage, the contribution is marginal, earning a baseline 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states 'Perform set operations on libraries' and lists the specific operations (union, intersection, difference, copy, empty). This clearly identifies the tool's purpose and distinguishes it from sibling tools like create_library (creates new) or delete_library (removes).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternative tools. For example, it does not clarify whether 'copy' should be used instead of create_library for duplicating a library, or when to prefer edit_library for modifying existing libraries. There is no mention of prerequisites or typical use cases.

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

manage_annotationA
Idempotent

Add or update an annotation/note for a document in a library.

ParametersJSON Schema
NameRequiredDescriptionDefault
library_idYesLibrary identifier
bibcodeYesBibcode to annotate
contentYesAnnotation content (1-10000 characters)
response_formatNomarkdown

TDQS

A3.5/5.0
Behavior3/5

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

Annotations already indicate idempotentHint=true and non-destructive. Description adds that it adds or updates, which aligns but does not provide additional behavioral context or side effects beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence with no wasted words, directly conveys the tool's purpose. Well-suited for quick agent comprehension.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, description could mention return values. It adequately explains functionality but lacks completeness regarding result format or behavior on conflict (e.g., updating existing annotation).

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is high (75-100%), so baseline is 3. Description does not add new meaning beyond what the schema already provides for parameters like library_id, bibcode, and content.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Add or update an annotation/note for a document in a library.', specifying the verb and resource, and distinguishes from siblings like delete_annotation and get_annotation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus alternatives, such as get_annotation or delete_annotation. Lacks context on prerequisites or scenarios where this is appropriate.

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

manage_documentsB
Idempotent

Add or remove documents from a library.

ParametersJSON Schema
NameRequiredDescriptionDefault
library_idYesLibrary identifier
bibcodesYesList of bibcodes (1-2000)
actionYesAction to perform
response_formatNomarkdown

TDQS

B3.2/5.0
Behavior3/5

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

Annotations indicate idempotent and non-destructive behavior. Description adds no extra behavioral context beyond 'add or remove'. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence with no superfluous words. Efficiently communicates the core function.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Minimal description for a tool with 4 parameters, 2 enums, and no output schema. Lacks return value explanation and usage constraints beyond schema defaults.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 75% with parameter descriptions. Description adds little beyond 'add or remove', which is already captured by the 'action' enum.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description states the verb (add/remove) and resource (documents from a library). It is clear but does not distinguish from sibling tools like 'add_documents_by_query' or 'library_operation'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives. Does not specify prerequisites or exclusions.

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

search_docsA
Read-onlyIdempotent

Search SciX help documentation for information about search syntax, features, API usage, and best practices.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesNatural language search query (e.g., "how to search by author", "export formats", "library permissions")
limitNoMaximum number of results to return (1-20, default 5)

TDQS

A4.1/5.0
Behavior3/5

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, so the safety profile is clear. The description adds the scope (help docs) but does not provide additional behavioral details beyond what annotations cover.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that is front-loaded with the verb and resource. It contains no fluff and is efficiently structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple search tool with two parameters and no output schema, the description is sufficient. It covers the tool's purpose and scope without needing additional details.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptions for both parameters. The description does not add extra meaning beyond the schema, so it meets the baseline but does not enhance understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool searches 'SciX help documentation' for specific topics (search syntax, features, API usage, best practices). This distinguishes it from siblings like 'search' which presumably searches papers.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

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 (help docs) but does not explicitly state when not to use or mention alternatives. It is effective but lacks exclusions.

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

transfer_libraryC

Transfer ownership of a library to another user.

ParametersJSON Schema
NameRequiredDescriptionDefault
library_idYesLibrary identifier
emailYesEmail of new owner
response_formatNomarkdown

TDQS

C2.9/5.0
Behavior2/5

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

Annotations set readOnlyHint=false and openWorldHint=true, indicating a mutating operation with potential side effects. The description adds little beyond the verb 'transfer', failing to disclose whether the previous owner loses access, if the action is reversible, or success indicators.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no extra words, achieving high conciseness. However, it could be restructured to front-load key info like side effects or usage context without increasing length.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the absence of an output schema, the description should clarify return values, error handling, or confirmation of ownership transfer. It does not, leaving the agent with incomplete context for a mutating tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 67% (library_id and email have descriptions). The tool description does not add meaning beyond what is already in the schema; it does not explain the 'response_format' parameter or parameter interactions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: transferring library ownership. It uses a specific verb ('transfer') and resource ('ownership'), distinguishing it from siblings like 'create_library' or 'delete_library'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives like 'edit_library' or 'update_permissions'. The description does not mention prerequisites, such as needing current owner permissions, nor exclusions.

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

update_permissionsC
Idempotent

Grant or modify permissions for a user on a library.

ParametersJSON Schema
NameRequiredDescriptionDefault
library_idYesLibrary identifier
emailYesUser email
permissionYesPermission level to grant
response_formatNomarkdown

TDQS

C2.9/5.0
Behavior2/5

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

Annotations indicate idempotentHint=true, but the description does not explain idempotent behavior or clarify outcomes (e.g., overwriting vs. cumulative). It also omits details on access or role restrictions, relying solely on annotations without adding context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, focused sentence with no redundant information. It efficiently conveys the core purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and four parameters, the description lacks details on response format, error handling, or behavioral nuances (e.g., idempotency). It feels incomplete for a mutation tool with multiple parameters.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage, so the description adds minimal value beyond listing parameters. It does not explain parameter interactions or constraints beyond what the schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Grant or modify permissions for a user on a library' clearly states the action and resource, distinguishing it from the sibling 'get_permissions'. However, it does not specify whether permissions are replaced or appended, leaving some ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives like 'get_permissions' or other permission-related tools. There is no mention of prerequisites or conditions for use.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 21 tool updatesv1.0.14
    • First observedadd_documents_by_query
    • First observedcreate_library
    • First observeddelete_annotation
    • First observeddelete_library
    • First observededit_library
    • First observedexport
    • First observedget_annotation
    • First observedget_citations
    • First observedget_libraries
    • First observedget_library
    • First observedget_metrics
    • First observedget_paper
    • First observedget_permissions
    • First observedget_references
    • First observedlibrary_operation
    • First observedmanage_annotation
    • First observedmanage_documents
    • First observedsearch
    • First observedsearch_docs
    • First observedtransfer_library
    • First observedupdate_permissions
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.7/5.0

Scored across 21 tools

Disambiguation5/5

Each tool targets a distinct operation or resource. There is clear separation between library management, document operations, annotations, search, metrics, and citation/reference retrieval. No observable overlap or ambiguity.

Naming Consistency4/5

Most tools follow a verb_noun pattern (e.g., create_library, delete_annotation). Exceptions are 'export' (verb only) and 'library_operation' (noun_noun), which break the pattern slightly. Overall, the naming is clear and predictable.

Tool Count5/5

With 21 tools covering search, libraries, annotations, citations, metrics, permissions, and export, the scope is well-supported. Each tool serves a distinct purpose without redundancy, and the count is appropriate for a full-featured literature API.

Completeness5/5

The tool set provides comprehensive coverage for managing and querying scientific literature: CRUD for libraries and annotations, search (including documentation), citations (forward and backward), metrics, and export. No obvious gaps are apparent for the domain.

Maintenance

ActivityMaintained
ResponsivenessUnresponsive

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • NASA ADS MCP Server

    prtc
    A
    license
    A
    quality
    D
    maintenance
    Provides seamless access to the NASA Astrophysics Data System (ADS) for searching astronomical papers, tracking citations and metrics, managing paper libraries, and exporting BibTeX references through natural language conversation.
    10
    7
    MIT

  • Scopus MCP Server

    qwe4559999
    A
    license
    A
    quality
    D
    maintenance
    Provides access to the Elsevier Scopus API, enabling AI assistants to search for academic papers, retrieve detailed abstracts, and look up author profiles. It facilitates bibliometric research and scholarly data analysis through natural language commands.
    5
    39
    MIT

  • SciX Client

    yipihey
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables AI assistants to interact with the SciX (formerly NASA ADS) API to search scientific literature, export citations, and analyze bibliometric data. It supports advanced tools for managing libraries, resolving astronomical object names, and exploring citation networks.
    1
    MIT