Exposes Japan's CiNii Research API (NII) as seven read-only MCP tools for searching Japanese-language scholarship and fetching single records, each returning a typed JSON envelope with provenance and optional hash-chained query receipts.
cinii_search_articles — journal articles (JALC, Crossref, PubMed, IRDB), with title, author, journal, year-range, data-source filters and sort order.
cinii_search_books — books and monographs (NACSIS-CAT, NDL Search), with title, author, publisher and ISBN filters.
cinii_search_dissertations — doctoral dissertations from Japanese universities, filtered by author and year.
cinii_search_kaken — KAKEN (科研費) funded research projects, filtered by researcher, institution and year.
cinii_search_all — cross-type search across all CiNii content types.
cinii_search_researchers — researcher profiles and affiliations.
cinii_get_record — single-record lookup by full CiNii URL or CRID (the only non-search tool; omits searched_for).
Query in English or Japanese; every search reports the term actually sent, its detected script, matching mode and per-item matched_in field.
Typed diagnostics — OK, ZERO_CONJUNCTION, SCRIPT_LATIN_QUERY, API_ERROR, TRANSPORT_ERROR, plus receipt-status codes.
Breadth flagging on result.total (none/narrow/broad/very_broad) so large result sets are marked rather than passed through clean.
Pagination and language control via start, count (max 200) and lang (ja/en) on every search.
Optional citable query receipts — enable MCP_RECEIPT_DIR to append a hash-chained JSONL line per query, verifiable and summarisable with the cinii-mcp-ledger CLI (verify, verify-dir, manifest) for reproducible, disclosable searches.
No interpretation — results are the source's own answer, credentials redacted; the server does not summarise, rank or paraphrase.
Enables searching journal article metadata aggregated from PubMed through the CiNii Research API, returning records such as articles in article and cross-type searches.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@cinii-mcp search for recent articles on Japanese history"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A FastMCP stdio server exposing the CiNii Research API — Japan's national academic database, operated by the National Institute of Informatics (NII) — as seven tools for use with Claude Desktop and other MCP clients.
CiNii Research aggregates metadata from KAKEN, CiNii Articles, CiNii Books, IRDB, Crossref, DataCite, PubMed, and NDL Search. There is no established open MCP tooling for it, so this server fills that gap for researchers querying Japanese-language scholarship.
CiNii Research indexes Japanese scholarship across five kinds of record, and this puts all of them inside a Claude conversation: journal articles, books and monographs, doctoral dissertations, KAKEN grant projects, and researcher profiles, plus single-record lookup by CRID. Ask a question in English and get Japanese-language scholarship back, with the Japanese term actually sent shown beside the results.
KAKEN repays separate attention — it records what was funded, so it surfaces projects underway, collaborations forming, and research that reached a grant report before it reached print.
Every result carries the term sent, its script, how CiNii matched it, and a receipt fixing the query, so a search standing behind a footnote can be named, cited, and run again by someone else.
Related MCP server: article-mcp
A search you cannot re-run is a claim you cannot check. When a footnote rests on a database query, say that no article in this index uses a term before a certain year, the reader is asked to take the search on trust: which term, in which script, on what date, against which index and which version of it, and how far down the results the author went. Ordinary searching leaves none of that behind. This server leaves all of it. Every query-answering tool returns its envelope through the ledger, which appends one line to an append-only file: the term actually sent and its script, how the source matched it, how many records existed and how many came back, the diagnostics, the tool and its parameters, the server version, a timestamp, and the hash of the previous line. The hash makes the file a chain: a line cannot be altered, removed or reordered afterwards without the verifier saying so.
What that gives a researcher:
A citable search. Name the receipt in the footnote (session slug, server, date, line hash) and a reader can see exactly what was asked and run it again against the same version.
Negative findings that carry weight. "Not found" is evidence only if the search that produced it is on record, with its term, its script and its breadth.
A method section that writes itself. cinii-mcp-ledger manifest <folder> summarises every
query a project made, by server, script and session: the disclosure a journal, a
data-availability statement or a research-integrity review asks for.
A record of AI-mediated research. When a model chose the term, the receipt shows the term it chose and what came back, which is the thing to disclose about work done with an assistant.
Nothing interpreted. The receipt is the source's own answer with credentials removed. The server does not summarise, rank or paraphrase, so the record is of the source, not of the tool.
Receipts are off until you name a folder (MCP_RECEIPT_DIR); each server then writes its own
<server>.jsonl inside it, and MCP_RECEIPT_SESSION stamps a project or article slug on every
line so one folder can serve several projects. cinii-mcp-ledger verify-dir <folder> checks the chains.
The mechanics, the variables and what the envelope says when nothing is deposited are in the
receipts section below.
Tool | Purpose |
| Journal articles (JALC, Crossref, PubMed, IRDB) |
| Books and monographs (NACSIS-CAT, NDL Search) |
| Doctoral dissertations from Japanese universities |
| KAKEN (科研費) funded research projects |
| Cross-type search across all content types |
| Researcher profiles and affiliations |
| Single record lookup by URL or CRID |
Results come from the CiNii Research OpenSearch v2 API as JSON-LD and are returned as one typed JSON response envelope — see Response format below. (Releases before v2.0.1 returned formatted markdown text; that is a breaking change, not a formatting preference.)
Every tool returns one JSON response envelope, built by mediation.py and defined in response-schema.json. Schema version 2.3.0. The same module and schema are vendored byte-identically across the server family, so an envelope from one server can be read by a consumer written for another.
The envelope reports how the search was made, not only what it found:
searched_for — on search operations, the term actually sent, its detected script, and the matching mode, hoisted to the top of the envelope so a relaying client cannot drop it. Fetch operations (cinii_get_record) omit it: they were handed an identifier and chose no term.
query — input_terms as supplied, normalized as sent, and the detected script. This pair is the record of any rendering performed between the caller's language and the corpus.
matching_mode — metadata_conjunction for this server. It tells you how to read result.total.
result.breadth — none, narrow (1–50), broad (51–1000), very_broad (>1000). Thresholds are low on purpose: a few hundred hits that look like a literature are marked rather than passed through clean.
items[].matched_in — which field the match was made in, per record.
receipt — an ISO 8601 timestamp, a SHA-256 taken over the normalised query and its parameters, and the identifiers returned. The hash verifies a term you already hold; it cannot be inverted to produce one, so the unit of deposit is the envelope, not the receipt.
attribution — the required credit line, in every response.
Typed and closed. A diagnostic is never prose the client has to parse.
Code | Level | Meaning |
| info | Records returned; nothing to flag. |
| warning | No records. CiNii matches catalogued metadata and ANDs a multi-word query, so an un-indexed compound returns zero even where related work exists. Vary the rendering before concluding the literature is absent. |
| warning | The query was Latin-script, so it matched romanised and English metadata only. The Japanese-script form reaches a different, larger corpus. |
| error | The API answered, and answered with an error. |
| error | The request did not complete. Kept distinct from |
| info | The response was not written to the query ledger, because no receipts destination is configured. The search is unaffected; no receipt survives it. |
| warning | A receipts destination is set, the write was attempted, and it did not land. Distinct from the line above because one is a choice and the other is a fault. |
Every envelope can be deposited to an append-only, hash-chained JSONL log by ledger.py. It is off unless MCP_RECEIPT_DIR (or the legacy MCP_RECEIPT_LOG) is set, and a logging failure is swallowed rather than raised — a search matters more than the record of it. Secrets are redacted before a line is composed.
Since schema 2.3.0 the envelope says so. When a response is not deposited, emit() appends RECEIPT_NOT_DEPOSITED if the variable is unset, or RECEIPT_WRITE_FAILED if it is set and the write did not land. The gap is then visible in the artefact that becomes the record, rather than only in a configuration file. mediation.deposit_enabled() reports the same fact on demand.
MCP_RECEIPT_DIR=C:\path\to\receipts # a folder, not a file
MCP_RECEIPT_SESSION=project-or-article-slug
MCP_RECEIPT_STRICT=1 # optional: make logging failure raise
MCP_RECEIPT_LOG=C:\path\to\receipts.jsonl # legacy single file; ignored when _DIR is setA folder, and one file per server. MCP_RECEIPT_DIR points at a directory
and each server writes its own <server>.jsonl inside it. That is not tidiness.
Appending is read-the-last-hash-then-write, and the lock around it is a threading
lock, which holds within one process and not between several — six servers are
six processes, and two answering at the same moment will both read the same
predecessor and both claim it. Measured, not theorised: six processes writing 150
lines to one file produced fourteen forks. MCP_RECEIPT_LOG still works and is
still correct for a single server; it is the wrong shape for a family.
install.ps1 sets this up for all six and writes a README into the folder.
Verify one chain, or the whole folder:
cinii-mcp-ledger verify receipts/cinii.jsonl
cinii-mcp-ledger verify-dir receipts
cinii-mcp-ledger manifest receipts # writes receipts/manifest.jsonverify exits non-zero on failure and says which kind it found: a fork
(concurrent writers — a configuration fault, and every line is still there), a
missing line, a reordering, or tamper (a line that does not hash to
its own content). Only the last is a claim about honesty, and reporting them
alike would invite a reader to mistake one for the other. The manifest is the
object to cite: one description of the whole deposit — per-file line counts,
first and last timestamps, terminal hashes, and combined totals by server,
script and session.
Python 3.10+ on PATH.
A CiNii Web API application ID (appid) — free; required.
The CiNii Research API requires a registered application ID, sent as a parameter on every request.
Register at the CiNii Web API Developer Registration page and obtain your application ID.
Agree to NII's API regulations: the Academic Content Service Usage Regulations, the CiNii Research Usage Detailed Regulations, and the Academic Content Service Web API Usage Detailed Regulations.
For commercial use, email ciniiadm@nii.ac.jp before applying.
The same application ID also works for the KAKEN API, which cinii_search_kaken uses.
Three routes. All three give you the same server; pick by how much you want to see of it.
Python. The pip and source routes need Python 3.10 or later; 3.10, 3.12, 3.13 and 3.14 are tested in CI on Windows, macOS and Linux. The Claude Desktop bundle uses whichever of these is already installed, and has uv download one only if none is.
Every route needs Python 3.10 to 3.14. The Claude Desktop bundle uses one already on the machine
and has uv download one only if none is; the other routes also need the venv module, which the
official installers include.
Windows. Download the 64-bit installer from python.org/downloads
and run it; tick "Add python.exe to PATH" on the first screen. Afterwards py --version (the
launcher the installer adds) or python --version in a new terminal should print 3.1x. If typing
python opens the Microsoft Store instead, Windows has no Python yet: that Store page is a stub,
and it is also what "'python' is not recognized" usually means.
macOS. The python.org installer, or
brew install python@3.13 with Homebrew. The /usr/bin/python3 that Xcode's
command-line tools provide may be older than 3.10; python3 --version says.
Linux. Your distribution's package: sudo apt install python3 python3-venv on Debian and
Ubuntu, sudo dnf install python3 on Fedora. Or let uv provide one (next line).
Any platform, with uv. uv
installs Python itself: uv python install 3.13, then uv venv or the uvx route below.
Download cinii-mcp-3.1.2.mcpb from the latest release and open it; Claude Desktop installs it. One bundle serves Windows, macOS (Apple Silicon and Intel) and Linux. Claude Desktop asks for CiNii application ID and a receipts folder at install time; the key is stored in the OS keychain.
The bundle carries the server's source and a lock file, nothing compiled, and needs no Python of its own. Claude Desktop builds the bundle's environment when you install it, with uv, a copy already on your PATH if there is one and otherwise one the app downloads for itself: uv takes a Python 3.10 or later already on the machine, downloads one only if there is none, and installs the locked libraries, roughly 40 MB, behind the install progress bar. Every launch then reuses that environment and takes under a second. Bundles 3.1.0 and 3.1.1 kept pyproject.toml one folder down, which made Claude Desktop skip that install step and download everything during the first connection attempt instead; on a slow or filtered network that attempt never completed and the app reported it could not connect to the extension server. Bundles before 3.1.0 vendored libraries compiled for CPython 3.12 only and failed on every other interpreter. See Troubleshooting.
pip install "git+https://github.com/ckgerteis/cinii-mcp@v3.1.2"
# or, without an environment of your own:
uvx --from "git+https://github.com/ckgerteis/cinii-mcp@v3.1.2" cinii-mcpinstalls the cinii-mcp console script and cinii-mcp-ledger. The tag is the thing to cite; @main gets whatever is current. Then register it in Claude Desktop (below), or let install.py do that.
pip install "git+https://github.com/ckgerteis/bibliograph-mcp@v1.0.4" && bibliograph installinstalls all six servers and registers them together — one receipts folder, credentials asked for once. See bibliograph-mcp. From a checkout of this repository, python install.py does the same for this server alone, python install.py --all for the six, on Windows, macOS and Linux; install.ps1 remains for Windows.
python3 -m venv .venv
.venv/bin/pip install .On Windows:
py -3.11 -m venv .venv
.venv\Scripts\pip.exe install .Or straight from the repository, without cloning:
uvx --from "git+https://github.com/ckgerteis/cinii-mcp" cinii-mcpVerify the install:
.venv/bin/python -c "import cinii_mcp; print(cinii_mcp.__version__)"That fails loudly if the package or one of its vendored modules is missing. Do
not use cinii-mcp --help as the check: unknown arguments are ignored, the
server starts, reads end-of-input and exits 0, so it reports success whatever
the state of the code.
Six independent packages. None imports another, none depends on another, and
each installs and answers on its own — pip install . in this directory is a
complete install of this server and nothing else.
They do share three things: a response envelope, a query ledger, and — if you
run more than one — a receipts folder. install.ps1 is vendored byte-identical
into all six and handles that on Windows; install.py is its cross-platform port. Both install this server by default, because
cloning one repository is not a request for five more.
.\install.ps1 # this server
.\install.ps1 -All # all six
.\install.ps1 -Servers cinii,ndl # a chosen subsetNothing about where things go is decided for you. The script asks where to
install (the virtual environment Claude Desktop will be pointed at), which
folder receives the receipts, and which session slug to stamp on them,
offering a neutral suggestion for each that Enter accepts; run without a
terminal it does not guess, and stops unless --venv and --receipts-dir
(or --no-receipts; -VenvDir and -ReceiptsDir for install.ps1) say
so. Whatever subset you name is registered against one receipts folder, asked for
once. The script prefers a sibling checkout to the network, carries across
credentials already registered rather than asking again, leaves servers it was
not asked about alone, and stops rather than guessing where the servers already
registered disagree about the folder or the session slug. It also asserts that
ledger.py and mediation.py are byte-identical across everything it
installed, so two envelope versions cannot end up in one environment unnoticed.
Nothing here is specific to Claude. The server speaks the Model Context Protocol over stdio and nothing else: any client that can start a process and talk JSON-RPC to it (Claude Code, Cursor, VS Code and Continue, Zed, LibreChat, a script of your own using an MCP SDK) can use it. The Claude Desktop bundle and the installers are conveniences for one client; the server underneath is the same console script. Register it anywhere by giving the client the absolute path of the console script and, optionally, the environment:
{
"mcpServers": {
"cinii": {
"command": "/absolute/path/to/.venv/bin/cinii-mcp",
"env": {
"CINII_APPID": "your application ID",
"MCP_RECEIPT_DIR": "/absolute/path/to/receipts",
"MCP_RECEIPT_SESSION": "project-or-article-slug"
}
}
}
}Claude Code takes the same thing on the command line:
claude mcp add cinii -- /absolute/path/to/.venv/bin/cinii-mcpOn Windows the path ends in \.venv\Scripts\cinii-mcp.exe. MCP_RECEIPT_DIR and MCP_RECEIPT_SESSION
are optional; without them the server runs and every envelope says RECEIPT_NOT_DEPOSITED. The
stdio transport is the only one: there is no HTTP endpoint to expose, and nothing to host.
"Server disconnected" is all Claude Desktop says when the server process exited before or during the handshake, whatever the reason. The reason is in the log:
Windows: %LOCALAPPDATA%\Claude\Logs\mcp-server-<name>.log (builds before August 2026: %APPDATA%\Claude\logs) (the extension's display name, or the key under mcpServers), with mcp.log beside it for the app's side of the conversation.
macOS: ~/Library/Logs/Claude/mcp-server-<name>.log and mcp.log.
Linux: ~/.config/Claude/logs/.
Read the last launch from the bottom up. Three shapes account for nearly every report:
A Python traceback ending in ImportError or ModuleNotFoundError (for example No module named 'pydantic_core._pydantic_core'). The interpreter started, the code was found, and a compiled library did not match that interpreter. This is what every bundle before 3.1.0 did on any Python other than 3.12. Install the current bundle, or use the pip route, which resolves wheels for the interpreter you install into.
'python' is not recognized, spawn python ENOENT, or a line from the Microsoft Store: no interpreter was found on the PATH Claude Desktop constructs. Nothing of this server ran. The current bundle does not launch python at all; for the pip route, register the console script by absolute path as shown above.
A line from uv (error: ..., or a download that never finished), or Unable to connect to extension server with nothing from the server in the log: the environment was not built. From 3.1.2 the app builds it at install time; look in main.log beside the server log for lines tagged [UV Runtime], which record the download and the uv sync, and for missing pyproject.toml, which means a bundle older than 3.1.2. If the install-time build failed (no network, a proxy that blocks github.com or pypi.org), reinstall the bundle once the network is back; the launch also rebuilds the environment itself, so a second launch on a working network completes.
The bundle's own entry point writes one line naming the interpreter, its path and the supported range before re-raising an import failure, so a log from 3.1.0 onwards says which of these it is.
The server reads your application ID from the CINII_APPID environment variable. Copy the example file and fill it in (never commit the real value):
cp .env.example .envCINII_APPID=your_application_id_hereAdd an entry to %APPDATA%\Claude\claude_desktop_config.json under
mcpServers, pointing at the console script in the environment you installed
into. On macOS or Linux use the absolute path to .venv/bin/cinii-mcp.
{
"mcpServers": {
"cinii": {
"command": "C:\\path\\to\\.venv\\Scripts\\cinii-mcp.exe",
"env": {
"CINII_APPID": "your_application_id_here"
}
}
}
}Changed in 3.0.0. Earlier versions were registered by path —
"command": "…\\python.exe", "args": ["…\\server.py"]. That entry will not
start this version, because server.py is now a module inside a package rather
than a script beside its imports. Replace it with the console script above.
Restart Claude Desktop. The seven tools should appear under "cinii" in the tool list.
NII enforces usage rules; breaking them can get your access blocked or your registration cancelled. This server sends your appid on every request (required) and is designed to respect the rules, but you remain responsible for use:
Do not issue a high volume of requests in a short time. Excessive access that affects other users may be blocked without notice.
The appid is for API requests only; do not expose it in user-facing links to CiNii pages.
Respect copyright when using retrieved data, per NII's regulations.
If this software supports your research, please cite it. See CITATION.cff, or use the "Cite this repository" button on GitHub.
.venv/bin/python tests/smoke_stdio.pyStarts the installed console script over stdio, performs the MCP handshake, and checks tools/list against the tool table above; exits non-zero on a mismatch. RUN_LIVE=1 … <tool> '<json params>' adds one live call and reports the envelope's diagnostic codes.
MIT © 2026 Christopher Gerteis.
This license covers the server code only. It grants no rights over CiNii data or the CiNii API, which remain governed by NII's terms linked above.
A research tool, maintained on a best-effort basis and provided "as is", without warranty. Not affiliated with or endorsed by the National Institute of Informatics.
Dr Christopher Gerteis, SOAS University of London. Data provided by CiNii Research, National Institute of Informatics.
Fetch a single CiNii record by URL or CRID. Returns the unified envelope (operation 'get_record').
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint, covering the safety profile. The description adds value by stating the return envelope format (operation 'get_record'), which is not in annotations. No contradiction; it contextually enriches what the tool returns.
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 crisp sentences: the first states the action and input, the second the expected output. Front-loaded with the core purpose and no filler. Every word earns its place.
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 single-record fetch with a straightforward input and an output schema provided, the description covers the essential behavior. It mentions the envelope and the operation. The only omission is potential error handling or edge cases, but given the output schema and annotations, it is sufficiently complete for an agent to use correctly.
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 0% because the tool description does not discuss parameters. The single parameter 'record_url' is described in the schema as 'Full CiNii URL or CRID', but the description does not compensate for the low coverage. It adds nothing beyond the schema, so the agent must rely solely on the schema's minimal description.
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'), a resource ('single CiNii record'), and the two identifier forms ('by URL or CRID'), which clearly distinguishes it from the sibling search tools (cinii_search_*). It also notes the return envelope with operation 'get_record', making the tool's purpose unambiguous.
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: you need a specific URL or CRID, which differentiates it from the search siblings. However, it does not explicitly say 'use this when you have an identifier' nor name the alternatives. The context of siblings makes it clear enough, but explicit guidance is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cross-type search across all CiNii content. Returns the unified envelope.
Records are emitted with record_type 'article' as a default; the cross search mixes types and CiNii does not always disambiguate them in the OpenSearch response.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds meaningful behavioral detail beyond the annotations: records default to record_type 'article', mixed types are not always disambiguated, and a unified envelope is returned. This is exactly the kind of caveat an agent needs before relying on the output.
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 compact and front-loaded: purpose first, then output envelope, then the critical record_type caveat. Every sentence earns its place with no 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?
The output schema and annotations cover return shape and safety, and the description covers the important cross-type ambiguity. Parameter semantics are missing from the description, but the schema's property names, defaults, and constraints make invocation reasonably clear.
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 0%, and the description does not explain query, lang, count, start, from_year, or to_year. With no parameter guidance in the description, it fails to compensate for the low schema coverage.
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 identifies a specific operation: cross-type search across all CiNii content. 'All CiNii content' distinguishes this from the type-specific sibling tools without needing to open their schemas.
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 gives clear context: use this for cross-type/all-content searching. It does not explicitly name alternatives or state when not to use it, but the scope is sufficiently explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search CiNii Research for journal articles. Returns the unified envelope.
CiNii matches catalogued metadata and ANDs a multi-word query, so an un-indexed compound returns zero even when related work exists — a ZERO_CONJUNCTION diagnostic marks this; vary the rendering rather than concluding the literature is absent. A SCRIPT_LATIN_QUERY diagnostic means the query searched romanized metadata only. The same string may behave very differently on J-STAGE (full text). Foundational monographs sit in cinii_search_books, not the article index.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, covering safety. The description adds substantial behavioral detail: it explains the ANDing of multi-word queries, the ZERO_CONJUNCTION diagnostic suggesting the query may be unindexed, the SCRIPT_LATIN_QUERY diagnostic for romanized-only searches, and the difference from J-STAGE full-text searching. This goes well beyond the annotations and gives the agent critical insights for interpreting results correctly.
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 short paragraphs. The first sentence states the purpose and return envelope. The second paragraph packs three sentences of useful caveats. It is front-loaded with the core purpose and each subsequent sentence earns its place by clarifying search behavior or pointing to the right sibling tool. There is no fluff or repetition, making it highly concise and well-structured.
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 description covers the essential behavioral quirks that could lead an agent astray (zero results, romanized search, J-STAGE differences) and routes monographs to the correct tool. It does not explain the 'unified envelope' return format, but an output schema exists so that is acceptable. It also does not detail pagination or sorting semantics, but those are likely standard and inferable from the schema. The description is sufficient for effective use given the existing schema and annotations.
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 has a description for the 'query' parameter, but the overall schema coverage is low (0% per signals, though query has a description). The description compensates by explaining how the query is interpreted (ANDs multi-word queries, may hit romanized metadata), which directly affects how to construct the query. It does not explain other parameters like sort, count, or filters, but those are standard and have defaults. Given the low coverage, the description adds meaningful semantic value for the most critical parameter, so a 4 is warranted.
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 'Search CiNii Research for journal articles' — a specific verb and resource, clearly distinguishing it from the other CiNii tools. It also explicitly notes that monographs belong in cinii_search_books, reinforcing the boundary to sibling tools. This is unambiguous and immediately tells an agent what the tool does and what it does not cover.
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 when-to-use context: it tells the agent that the article index is for journal articles and that monographs should be searched in cinii_search_books. It also warns about behavioral differences from J-STAGE, which helps the agent decide if this is the right search. However, it does not explicitly name all alternatives (e.g., cinii_search_all) nor provide a comprehensive when-not-to-use list, so it slightly lacks in guiding against other nearby tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search CiNii Research for books and monographs. Returns the unified envelope.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide safety information (readOnlyHint=true, idempotentHint=true, destructiveHint=false). The description adds only the phrase 'Returns the unified envelope', which hints at the output format but is redundant given the output schema exists. It does not add behavioral context such as pagination limits, potential delays, or any special handling. Since annotations are present, the bar is lower, but the description still contributes almost nothing beyond 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?
The description is a single, compact sentence that is easy to read. It is appropriately sized for a simple search tool, but it is overly sparse — it does not elaborate on scope or usage. It is concise without being informative, so it earns a middle score.
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 has a rich schema with 10 parameters and is part of a family of similar search tools, the description is insufficient. It does not mention which parameters to use for common scenarios, does not clarify the 'unified envelope' output structure beyond the schema, and omits any guidance on how this tool differs from its siblings. The presence of an output schema covers return format but not usage context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% — the description does not explain any of the parameters (query, isbn, title, author, etc.). While some parameter names are self-explanatory, the description offers no guidance on how they interact or which are mutually exclusive. With low coverage, the description must compensate, but it does not, leaving the agent to rely on the schema alone.
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 ('Search') and a clear resource ('CiNii Research for books and monographs'). It implicitly differentiates from sibling search tools by specifying 'books and monographs', which is distinct from articles, dissertations, and researchers. However, it does not explicitly name a sibling or contrast them, so a 4 is appropriate rather than a 5.
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?
There is no guidance on when to use this tool versus alternatives. The description does not mention that this is the tool for book/monograph searches or that other tools are for different document types. No prerequisites, exclusions, or alternative tools are referenced, leaving the agent to infer usage solely from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search CiNii Research for doctoral dissertations. Returns the unified envelope.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey readOnly, openWorld, idempotent, and non-destructive behavior, so the description need not repeat those. However, the only additional behavioral information, 'Returns the unified envelope,' is cryptic and unexplained, leaving the agent unsure about the actual output structure. This adds little transparent value.
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 very short (a single sentence), so it is concise in word count, but that brevity comes at the cost of essential detail. It lacks any structure (e.g., bullets, sections) to organize information, and the sentence itself is too terse to be complete.
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?
Despite having an output schema and a 7-field nested input schema, the description provides almost no context. It does not explain how to form queries, what the 'unified envelope' contains, or how filters work. An agent cannot confidently call this tool without additional documentation, making it severely inadequate for the tool's complexity.
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 0%, so the description has the full burden of explaining parameters. It mentions none of the seven parameters (lang, count, query, start, author, to_year, from_year) nor their meaning. The agent must rely solely on field titles and defaults, which is insufficient for correct invocation.
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 action ('Search'), the resource ('CiNii Research'), and the specific scope ('doctoral dissertations'). It inherently distinguishes itself from sibling tools that target articles, books, researchers, etc., through the explicit mention of dissertations.
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?
No guidance is given on when to use this tool versus the alternative search tools (e.g., cinii_search_all, cinii_search_articles). The use case is only implied by the tool name and scope, with no explicit 'use this when' or 'for other content types use...' instruction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search KAKEN (科研費) research projects. Returns the unified envelope (record_type 'project').
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering safety and side-effect expectations. The description adds that it returns the unified envelope with record_type 'project', which is a useful behavioral detail. However, it doesn't disclose pagination behavior, result ordering, or potential rate limits. With annotations covering the main traits, the added value is modest but non-trivial.
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 a single, front-loaded sentence with no filler. It communicates the core purpose and the key return-type detail efficiently, which is ideal for an AI agent that needs to quickly parse tool intent.
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 has multiple optional parameters and 0% schema coverage, the description is under-specified. It doesn't explain how to construct a valid query, how filters interact, or any constraints. An output schema exists but is not visible in the prompt; the description only hints at the return envelope. An agent would likely need to inspect the schema or make trial calls to use the tool effectively.
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 0%, so the description must compensate for the meaning of parameters like query, lang, count, start, from_year, to_year, researcher, and institution. The description only mentions the search action and return type, providing no explanation of how to use the filters. Field names are self-explanatory to some degree, but without any description guidance, an agent may not know parameter formats or combinations.
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 ('Search') and a clear resource ('KAKEN research projects'), and it distinguishes itself from sibling search tools by specifying the record_type 'project' in the unified envelope. This makes the tool's purpose unambiguous even without reading the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for KAKEN projects but does not explicitly contrast with alternatives such as cinii_search_articles or cinii_search_all. There is no 'use this when' or 'not for' guidance. The sibling list is provided in context but the description itself doesn't reference it, so an agent must infer when to choose this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for researchers in CiNii. Returns the unified envelope (record_type 'researcher').
Note: researcher affiliation is not carried by the record schema; the researcher name occupies the title field and the profile URL the ids.url_ja field.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds a useful, non-obvious note about field mapping (name in title, profile URL in ids.url_ja) that goes beyond the schema. No contradictions; the note clarifies result interpretation without repeating annotation information.
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 a single concise sentence followed by a clearly separated note. The main purpose is front-loaded, and the note is relevant without bloating the text. Efficient and well-structured.
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 schema has no parameter descriptions and the tool has multiple parameters (query, institution, pagination controls), the description is incomplete. The field-mapping note is helpful, but it doesn't cover parameter semantics or usage context. An agent would need to infer most functional details from parameter names alone.
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 0%, and the description mentions none of the parameters (query, lang, count, start, institution). The tool requires more than one parameter in practice (via the nested 'params' object), yet the description provides no semantic help, leaving the agent to guess from names alone.
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 'Search for researchers in CiNii' with a specific verb and resource, and mentions the record_type 'researcher'. It differentiates from siblings like cinii_search_articles by resource type, though it doesn't explicitly name alternatives. The purpose is unambiguous.
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?
No guidance is provided on when to use this tool versus cinii_search_all or other sibling search tools. There is no mention of scenarios, prerequisites, or exclusions, leaving the agent to infer usage context from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v3.0.0cinii_get_recordcinii_search_allcinii_search_articlescinii_search_bookscinii_search_dissertationscinii_search_kakencinii_search_researchersScored across 7 tools
Each search tool explicitly targets a distinct content type (articles, books, dissertations, KAKEN projects, researchers, and a cross-type search), with no overlap in purpose. The get_record tool is clearly separate as a single-record fetcher by URL or CRID.
All tools follow the identical pattern 'cinii_search_<type>' for searches, plus 'cinii_get_record' for retrieval, maintaining consistent snake_case and verb-noun ordering throughout.
Seven tools is well-scoped for a literature search MCP server, covering the major CiNii content types without redundancy or unnecessary bloat. Each tool earns its place.
The surface covers all primary search categories (articles, books, dissertations, KAKEN, researchers) plus an all-search and a record fetch, leaving no obvious gaps for the stated purpose of querying CiNii Research.
Academic research MCP server for paper search, citation checks, graphs, and deep research.
Federated search of books and papers, BibTeX/RIS citations, open-access retrieval and reading.
Authoritative JLPT-graded Japanese dataset (kanji, vocab, grammar, history) via MCP and REST.
Search GitHub, npm, PyPI, StackOverflow, ArXiv from one MCP — built for coding agents.
