jp-lit-mcp
Server Quality Checklist
Latest release: v0.13.0
- Disambiguation5/5
Each tool has a distinct purpose with clear cross-references to alternatives. For example, jp_lit_search, jp_lit_search_fulltext, and jp_lit_search_pages address different search scopes, and descriptions explicitly differentiate them.
Naming Consistency5/5All tools follow the consistent pattern jp_lit_<verb>_<noun> in snake_case, e.g., jp_lit_list_sessions, jp_lit_search_fulltext. Compound verbs like search_fulltext are predictable and uniform.
Tool Count4/528 tools is on the higher side for a single server, but each tool serves a distinct function within a broad domain (Japanese literature research). The count is justified by the comprehensive coverage, though still slightly above ideal.
Completeness5/5The toolset covers the full research lifecycle: session management, searching diverse sources, record retrieval, fulltext access, authority resolution, classification, cache management, and export. No obvious gaps for the stated purpose.
Average 4.5/5 across 28 of 28 tools scored. Lowest: 3.9/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 122 commits in the last 12 weeks
- Last stable release on
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add
glama.jsonto the root of your repository:{ "$schema": "https://glama.ai/mcp/schemas/server.json", "maintainers": [ "your-github-username" ] }Then . Browse examples.
Add related servers to improve discoverability.
How to sync the server with GitHub?
Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.
To manually sync the server, click the "Sync Server" button in the MCP server admin interface.
How is the quality score calculated?
The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).
Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.
Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).
Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.
Tool Scores
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly explains the non-destructive local-write behavior: external source is unchanged, cache hits update session history, and cache misses or force_refresh create/replace local cache. This adds significant behavioral context beyond the annotations, clarifying why readOnlyHint is false while destructiveHint is false.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and contains no filler; every clause adds information about scope, side effects, or cache behavior. It is slightly dense and run-on, and it leads with side-effect status rather than the core search purpose, but it remains efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 7 parameters and an output schema, the description covers the non-bibliographic purpose, external/local side effects, and cache/force_refresh semantics. The main gap is the lack of explicit guidance on how this relates to sibling tools like jp_lit_search_guides_cases, but an agent has enough to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents all 7 parameters with 100% coverage, including query, page, limit, lib_id, lib_group, session_id, and force_refresh. The description adds overall purpose but no additional per-parameter meaning, so it stays at the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: it searches how-to manuals in the Reference Cooperative Database. It also clarifies that this is not a bibliographic search but a tool for getting research clues about materials, indexes, and reference books. It does not explicitly distinguish itself from the sibling tool jp_lit_search_guides_cases, so it is clear but not fully differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase '書誌検索ではなく、どの資料や索引・参考図書をどう使って調べるかの手がかりを得るためのツール' implies when the tool is appropriate, but there is no explicit when-to-use or when-not-to-use guidance. It does not name alternatives or explain how this differs from sibling tools such as jp_lit_search_guides_cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description clearly discloses the mixed read/write behavior ('external read / local bookkeeping write') and that it is non-destructive, which adds meaning beyond the annotations. It also explains cache semantics: cache hits still update session history, while cache misses or force_refresh create/replace local cache. This is valuable behavioral context beyond what readOnlyHint=false and destructiveHint=false alone convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is information-dense and front-loads the most important framing, but it reads as a long run-on passage with multiple clauses and a fragmented transition ('最終確認する 外部sourceは変更しない'). Splitting the cache behavior, external dependency, and return-value list into separate sentences or bullets would improve scannability. Still, every element contributes useful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with external network dependency, local side effects, and an output schema, the description covers the essential operational context: what it returns, what it does not fetch, its upstream dependency, the need for official confirmation, and its cache/history behavior. The agent has enough information to decide whether to call it and to anticipate its side effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers all parameters with descriptions, so the baseline is 3. The description adds extra meaning for force_refresh by explaining the exact side effects on local cache and session history, and it clarifies that keyword is used for tag matching. This goes beyond the schema text without duplicating it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource ('画像タグをキーワード検索する') and clearly states what it returns: tag strings, image path strings, bid, frame number, and official confirmation URL. It also explicitly says it does not fetch image bodies or IIIF APIs, which helps distinguish it from illustration- or image-related siblings. The tool's scope is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear context: search image tags in the National Book Database and get metadata rather than image content. However, it does not explicitly name sibling tools or state when to prefer this tool over alternatives like jp_lit_search_illustrations. The caveat about verifying on the official screen is useful but does not fully substitute for explicit tool-selection guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructive (destructiveHint: true) and non-read-only (readOnlyHint: false). Description adds that session history is not deleted but cache body cannot be restored, providing useful context. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences in Japanese are concise and front-loaded with the action. Slight redundancy in the warning about irreversibility could be tightened.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the destructive nature and presence of annotations, the description adds necessary context about irreversibility and session history. An output schema exists but is not shown, so completeness is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema shows zero parameters, but description mentions 'cache_key' and 'clear_all=true', which are not reflected in the schema. This creates confusion about how to invoke the tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool deletes local cache by cache_key or clear_all=true, distinguishing it from siblings like jp_lit_list_cache and jp_lit_prune_cache.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly suggests using jp_lit_list_cache for pre-deletion check and jp_lit_prune_cache with dry_run=true for safe inspection, plus warns that cache body is irreversible.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description clearly discloses that this is an external read with local bookkeeping write, explicitly says external sources are not modified, and explains cache/session side effects on cache hit, cache miss, and force_refresh. It also exposes edge-case behavior such as ndl_digital returning non-public metadata and CiNii diagnostics. None of this contradicts the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The content is dense and most of it earns its place, but it is written as one enormous run-on paragraph with no list structure or visual separation. The side-effect warning is front-loaded, but the long mapping and mixed operational caveats make it harder for an agent to parse than it should be.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a high-complexity tool, the description covers source selection, default behavior, excluded sources, source-specific caveats, cache behavior, and follow-up verification via jp_lit_get_record / jp_lit_get_records. Since an output schema exists, return-value documentation is not required, and nothing essential for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds real value by explaining the default source behavior, providing a large user-phrase-to-source mapping, clarifying per-call pagination semantics, and giving source-specific filter guidance such as filters.cinii.category and force_refresh/cache behavior. This is meaningful enrichment beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource: '日本語文献ポータルを検索する', and adds scope by explaining the default 8-source cross-search and listing sources that are not included by default. It does not explicitly contrast itself with sibling search tools such as jp_lit_search_fulltext or jp_lit_search_pages, so it falls just short of full sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives unusually detailed when-to-use guidance: which sources are excluded from the default cross-search, when to use them explicitly, and how to interpret user phrasing into the correct source value. It also routes users to jp_lit_get_record / jp_lit_get_records for verification before checking holdings, but it does not state when to prefer sibling search/refinement tools over this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description's 'read-only' and 'does not modify cache or session' mostly restate the structured metadata. It adds no further behavioral details such as output shape or edge-case behavior, but the output schema and annotations reduce the burden; this is adequate but not beyond baseline expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the most important fact ('read-only'), then states the tool's purpose, filter dimensions, and alternatives in three sentences. The final safety statement is somewhat redundant with the annotations but reinforces the non-destructive nature without wasting much space.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only, filterable listing tool, the description covers purpose, scoping, main use case, and sibling alternatives. With 100% schema coverage, a full output schema, and annotations that disclose the safety profile, nothing essential needed to call this tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters are already well-documented in the schema. The description reinforces that filtering by tool, session_id, saved date, and source is possible, but adds no genuinely new semantic detail beyond what the schema already provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies a read-only tool that returns a list/aggregation of local cache entries and can be filtered by tool, session_id, saved date, and source. It explicitly names sibling tools (jp_lit_search_cache_index, jp_lit_delete_cache, jp_lit_prune_cache) that cover different operations, so the agent can immediately distinguish this tool from them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states exactly when to use this tool: for inventorying caches to find a cache_key. It also gives explicit alternatives for content search and deletion, telling the agent to use jp_lit_search_cache_index instead for cross-searching saved jp_lit_search contents, and jp_lit_delete_cache or jp_lit_prune_cache for deletion. This is strong routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly discloses that the operation is non-destructive, that external sources are never modified, and that local session history/cache is updated or replaced depending on cache hit/miss or force_refresh. This adds meaningful behavioral detail beyond the annotations, especially since readOnlyHint is false and destructiveHint is false.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the key safety property (external read / local bookkeeping write), then states the search resource, purpose, and cache behavior. It is dense but not redundant; a slight loss of clarity comes from mixing safety, purpose, and cache mechanics in one run-on sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, annotations provided, and a description covering side effects, cache behavior, and intended research purpose, the tool is well-specified. It could be slightly stronger by explicitly naming sibling search tools to help route selection, but this is a minor gap given how specific the resource 'reference cases' is.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% description coverage for all parameters, so the schema already documents parameter semantics. The description adds high-level behavior around caching and force_refresh, but does not add parameter-specific meaning beyond the schema, which matches the baseline for full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches reference cases (レファレンス事例) in the Reference Cooperative Database, using a specific verb and resource. This distinguishes it from siblings like jp_lit_search_guides_manuals and jp_lit_search, which cover different scopes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear intended usage context: it is meant to provide similar questions, answer processes, and reference materials as input for the next research step. It does not explicitly name alternatives or when-not-to-use conditions, but the context is sufficient for an agent to decide when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses several behavioral traits beyond the annotations: external sources are unchanged, local session history is updated even on cache hits, cache is created/replaced on miss or force_refresh, OpenAlex is skipped without OPENALEX_API_KEY, and absence from OpenAlex or low citation counts is not evidence of low importance. This strongly supplements the limited annotation signals.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense and front-loaded with the core purpose and scoping constraint. The latter half packs several important caveats into a run-on structure, with some redundancy between '非破壊' and '外部sourceは変更しない', so it could be better organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 7 parameters and an output schema, the description covers the essential context: purpose, non-destructive behavior, local side effects, provider availability, and interpretation caveats. Since an output schema exists, the description does not need to document the return shape.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the input schema already documents DOI-priority, title-only matching, authors/issued_year usage, provider skipping behavior, force_refresh, and session_id format. The description adds little parameter-level meaning beyond what the schema already provides, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the operation: verifying an already-found single literature candidate against Crossref/OpenAlex and returning a bibliographic confidence score with evidence. It explicitly distinguishes itself from a literature search source, which differentiates it from the many jp_lit_search sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says when to use it: for external validation of candidates obtained from NDL/CiNii/J-STAGE/IRDB, and when not to use it: not as a literature search/discovery source. It does not name a specific alternative sibling tool, but the boundary is explicit enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the annotations by disclosing that the external source is never modified, that local session history is updated even on cache hit, and that local cache is created/replaced on cache miss or force_refresh. This gives agents precise expectations about side effects without contradicting the 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every clause earns its place: side-effect summary, search scope, result contents, and cache behavior. It is front-loaded with the non-destructive nature and immediately specifies the resource and action. No filler or redundant restatement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, annotations are present, and all parameters are described, the free-text description covers purpose, scope, result content, and cache/session side effects thoroughly. The only gap is the absence of explicit guidance about when not to use this tool versus the many sibling search tools, but the described focus on illustrations makes the use case reasonably clear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter already has a meaningful description. The tool description adds context about cache behavior and IIIF image results, but does not materially deepen understanding of individual parameters beyond what the schema provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb-resource pair: it searches illustrations and figures (図版・挿絵) across the full NDL Digital Collection by text keyword, restricted to publicly available material. This clearly differentiates it from sibling tools like jp_lit_search_fulltext or jp_lit_search_kokusho_image_tags by focusing on illustration search with IIIF image URL results.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when this tool is appropriate: searching illustration/figure content by text keyword across all public NDL materials. It also clarifies scope boundaries (public range only) and side effects. It does not explicitly name when-not-to-use or alternative sibling tools, so it misses the top bar of 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial behavioral context beyond annotations: external read vs local bookkeeping write, non-destructive cache behavior, cache-hit session history updates, cache creation/replacement on miss or force_refresh, and dependence on a public JSON endpoint. This fully explains side effects 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is information-dense and front-loaded with the essential external-read/local-write nature. Minor redundancy exists between '非破壊' and 'local bookkeeping write' and between 'external read' and '外部sourceは変更しない', but nearly every sentence conveys a distinct operational fact.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity—external dependency, local cache semantics, session-history side effects, and snippet-scoped results—the description covers all necessary operational context. The output schema exists, and the description complements it by explaining exactly what kind of data is returned and how to treat cached vs fresh results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description confirms the search targets snippets and clarifies that returned data is snippet-level, but it does not add new meaning about individual parameters beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource: keyword search over Kokusho DB transcription/OCR snippets. It further distinguishes itself by stating what it does not fetch (full text, manifest body, image body) and what it returns (bid, frame number, snippet, official URL), making its role clear relative to sibling search/retrieval tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: use this for snippet-level keyword search, not for full-text or image retrieval, and confirm results on the official screen before adoption. It does not explicitly name alternative tools or state when to prefer them, so it stops short of full referral guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as non-read-only and non-idempotent, and the description reinforces this with 'write' and '追記または更新' (append/update). It adds useful behavioral context beyond annotations by explaining that this tool maintains a ledger of investigation progress and judgments rather than raw search outcomes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the operation type, immediately lists what can be updated, and closes with a clear exclusion and alternative. Every sentence contributes meaning, and there is no redundant restatement of the tool name or schema fields.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex session-trace tool with six parameters and detailed schema documentation, the description provides the essential purpose, scope, and sibling distinction. It could be more explicit about whether updating an existing session trace merges or replaces prior content, but the schema, annotations, and sibling guidance otherwise give the agent enough context to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description summarizes the main fields (research goal, scope, source reasons, open questions, next actions) and maps them to the session-trace concept, but it does not add material parameter-level detail beyond what the input schema already documents.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific operation and resource: append or update the session trace for the session identified by session_id, covering research goal, confirmation scope, source selection reasons, open questions, and next actions. It also explicitly distinguishes itself from jp_lit_annotate_session by clarifying that this tool is for the session-level investigation ledger, not candidate-level notes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives an explicit exclusion and alternative: it is not for storing search results or selected candidates, and candidate-level accept/reject notes should use jp_lit_annotate_session. This gives the agent a clear routing rule for when to use this tool versus the most relevant sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are all false and carry essentially no safety information, so the description carries the burden. It discloses that the tool writes to the session, only adds selection judgments, and does not modify unselected results or the cache. This is useful behavioral context beyond the schema, though it does not cover overwrite/idempotency semantics explicitly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four short clauses, front-loaded with the core purpose, followed by side-effect clarification and sibling routing. Every sentence earns its place and there is no redundant restatement of the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complex nested schema and rich per-parameter descriptions, the description adds the missing behavioral and routing context: write scope, non-destruction of raw results/cache, and clear alternative tools. An output schema exists, so return-value documentation is not required. No meaningful information needed for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and each parameter already has detailed descriptions, validations, and examples in the schema. The tool description adds no parameter-level meaning beyond mentioning session_id and the cache in passing. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific action—saving candidate labels and short memos to existing search/bibliographic results within a session identified by session_id—and clearly scopes what is written. It also explicitly distinguishes itself from jp_lit_update_session_trace, jp_lit_find_sessions, and jp_lit_list_sessions, so an agent can tell them apart without opening schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states exactly when to use this tool (annotating selection decisions on existing results) and when not to: overall research goals/unresolved items/next actions go to jp_lit_update_session_trace, and plain history retrieval goes to jp_lit_find_sessions / jp_lit_list_sessions. This is explicit routing with named alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description adds useful behavioral context: the session is only read and not modified, and the default Markdown output is formatted for human readability. Annotations state readOnlyHint=false because the tool writes a file, yet the description clarifies that the source session itself is untouched, which prevents a common misreading. It does not contradict the 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact: two sentences that front-load the core action, then add the default format, the important safety note about the session not being modified, and the sibling alternative. 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.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having seven parameters, the full parameter semantics live in the input schema, and an output schema is present. The description supplies the missing operational context: where output goes, default formatting, read-only treatment of the session, and which sibling to use for lighter exports. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters are already fully documented in the input schema. The description only restates session_id, output_path, and the default Markdown format, without adding meaning beyond what the schema provides. This meets the baseline for high schema coverage but does not elevate it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'export/write file' for the research session identified by session_id. It unambiguously distinguishes this tool from jp_lit_export_view by stating that the latter handles only cache lists or re-extraction results. This is more than sufficient for an agent to know which export tool to select.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states the primary use case: writing a session to exports/ or output_path. It also gives an explicit exclusion and alternative: if you only need to write cache lists or re-extraction results, use jp_lit_export_view. This is clear routing between the two export-related siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool writes files to exports/ or output_path and that it does not modify cache or session. However, it does not detail overwrite behavior or permission requirements. 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences with each adding value: purpose, specific features, and alternative. It is front-loaded and efficient, though slightly longer than necessary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description need not explain return values. It covers the tool's role, scope, and sibling distinction. Minor omissions like error handling are acceptable for this level of complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, and schema coverage is 100% by default. The description adds context about what is exported (refined_results, cache views) beyond the empty schema, meeting the baseline for no-parameter tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool exports/writes file results of cache-based views (list, cross-search, re-extraction). It distinguishes itself from jp_lit_export_session by specifying that the latter handles whole session logs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use this tool (for cache-based view results) and when not (for whole session logs, use jp_lit_export_session). It also notes that cache and session are only read, not modified, providing clear usage boundaries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses that it never mutates cache or session, never re-queries upstream even when enrichment is enabled, and only overlays saved enrichment caches conditionally. This gives an agent a precise behavioral model not inferable from readOnlyHint/idempotentHint alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The core behavior is front-loaded, and the description packs the important constraints into a compact form. It is slightly dense and has minor redundancy between 'read-only' and 'cacheやsessionは変更しない', but every distinct behavior is covered without filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no input schema and an output schema, the description adequately covers targeting, no-upstream behavior, enrichment overlay conditions, and non-mutation guarantees. It does not spell out the exact refinement operations or cluster-request semantics, but those are likely expressed in the output schema or request parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema is empty, so the description is the only source for parameter meaning. It names cache_key, cache_keys, session_id, include_enrichment, and enrichment_cache_keys, and explains their roles. However, the sort/filter/set-operation parameters are not explicitly enumerated, leaving some ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a concrete action: refine saved jp_lit_search results locally via sort/filter/set operations without upstream re-search. It distinguishes itself from siblings like jp_lit_search and jp_lit_enrich_record by emphasizing it operates on cached results and never queries Crossref/OpenAlex.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly indicates this tool is for refining already-saved jp_lit_search results and names cache_key/cache_keys/session_id as the targeting mechanism. It also routes cache_key discovery to jp_lit_search_cache_index or jp_lit_list_cache, but does not explicitly state when to prefer this over running a new search.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful context beyond those: it reads only local cache and session bindings, does not modify cache or session, and clarifies that the output is a lightweight key list. This is consistent with annotations and slightly enriches them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded with the read-only nature and core action, and each sentence earns its place. It combines purpose, sibling routing, and behavioral transparency without redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description does not need to explain return structure. It covers the core use case, safety profile, parameter context at the schema level, and sibling distinctions, leaving no major gap for an agent deciding whether and how to call this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with detailed descriptions for all 9 parameters including enums, defaults, and semantics. The tool description does not add parameter-specific meaning beyond stating the search targets saved caches, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: it searches across saved jp_lit_search caches and returns a list of cache_keys intended for re-extraction or export. It distinguishes itself clearly from siblings such as jp_lit_search, jp_lit_list_cache, and jp_lit_refine_results.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says when to use this tool (searching saved caches to obtain cache_keys for re-extraction/export) and names concrete alternatives for adjacent use cases: jp_lit_search for new external searches, jp_lit_list_cache for inventory, and jp_lit_refine_results for set operations/deduplication.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial context beyond annotations: it clarifies that readOnlyHint=false means 'external read / local bookkeeping write (non-destructive)', explicitly states external sources are unchanged, and details the cache side-effect semantics (cache hit updates session history; cache miss or force_refresh creates/replaces local cache). This resolves the apparent tension of readOnlyHint=false with a non-destructive operation. 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.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense and front-loads the core purpose, with every sentence carrying substantive information. However, it is a single run-on paragraph mixing purpose, exclusions, param semantics, sibling routing, and cache behavior; '外部sourceは変更しない' partially repeats the opening 'external read / local bookkeeping write' claim. Line breaks or topic separation would improve scannability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with significant coverage caveats, this is remarkably complete. It captures the critical failure mode (false 'no hits' conclusions from incomplete coverage) and prescribes the mitigation. Combined with the presence of an output schema, the description covers purpose, exclusions, param behavior, sibling routing, and side effects. Nothing an agent needs to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline 3 applies. The description adds a small amount of param context (searchfield=contentonly 本文のみ/metaonly メタデータのみ/all 両方, and force_refresh cache semantics), but these largely mirror what the schema already documents. It does not meaningfully compensate beyond the schema's existing descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource: keyword search (キーワード検索する) over OCR full text (OCR 全文テキスト) in the next-generation digital library. It also differentiates itself from the main Digital Collection full-text search screen/API and from sibling tools like jp_lit_search and jp_lit_search_kokusho_fulltext by declaring what it is NOT.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use and when-not-to-use guidance: it covers next-gen library OCR, but not the main Digital Collection API, not login-free materials, and not library-restricted/transmission-service materials. It warns against concluding 'no hits' from this tool alone and instructs combining with official browser search. It also routes to specific siblings: jp_lit_search_pages for page identification and jp_lit_get_text_coordinates for OCR coordinates.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses the read/write split: external read but local bookkeeping write, non-destructive, never modifies the external source, and updates local session history even on cache hits while creating/replacing local cache on miss or force_refresh. This is rich, decision-relevant behavioral context that annotations alone do not provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every clause earns its place: purpose, use case, alternatives, and side effects are all covered. It is slightly monolithic as one long sentence, but there is no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists and annotations cover the safety profile, the description still provides the critical missing context: when to use the tool, which siblings to prefer for other cases, and the cache/session side effects. Nothing essential for correct tool selection or invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents every parameter. The description adds high-level context about classification-based vocabulary expansion but no per-parameter detail beyond what the schema provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific operation: use Web NDL Authorities to find subject heading candidates from NDC classifications and return exploration terms for unknown books. It also differentiates itself from siblings by explicitly naming jp_lit_resolve_authority and jp_lit_search, so an agent can distinguish it without opening schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit when-to-use guidance: use this tool for vocabulary expansion when the classification symbol is known, and explicitly routes to jp_lit_resolve_authority for person-name/subject-string lookups and to jp_lit_search for the main literature search. This is clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial behavioral detail beyond the annotations: it is an external read with only local bookkeeping writes, it never modifies the external source, and cache hits still update session history while cache misses or force_refresh create/replace local cache. This fully explains the side effects implied by readOnlyHint=false and idempotentHint=false.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but not bloated; every clause contributes useful guidance. However, it is formatted as one long unbroken paragraph with an abstraction-like prefix before the concrete purpose, which slightly reduces skimmability for an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, the description covers prerequisites, material-type restrictions, alternative tools, accepted input origins, external-source safety, and local cache/session side effects. Since an output schema exists, return-value details are not needed here.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already explains pid, source, source_id, session_id, and force_refresh in detail. The description adds only a small integration hint about passing pid from jp_lit_search_fulltext, which is also already stated in the schema, so it does not significantly elevate parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific action and resource: retrieving full-text OCR JSON from NDL Digital Collection materials, with the clear restriction that only internet-public materials are covered. It also distinguishes itself from sibling tools by pointing to jp_lit_get_text_coordinates for specific pages and jp_lit_search_pages for in-document page discovery.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit routing: use jp_lit_get_record to verify next_digital_library.available=true before using source_id, use jp_lit_get_text_coordinates for single-page checks, and use jp_lit_search_pages for page-level searching. It also clarifies that pids from jp_lit_search_fulltext can be passed directly, which tells the agent exactly how to feed this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations say readOnlyHint=false and destructiveHint=false, and the description resolves this apparent tension by clarifying 'external read / local bookkeeping write (non-destructive)'. It further explains side effects beyond annotations: external source is never changed, cache hits still update local session history, and cache misses or force_refresh create/replace local cache. This is rich behavioral context that annotations alone do not provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but compact, front-loading the core purpose and safety profile, then adding routing alternatives and cache behavior. Every sentence carries useful information; the only minor flaw is slightly run-on punctuation and a somewhat abrupt transition between the sibling-tool routing and the cache side-effect clause.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a moderately complex tool with an output schema and annotations, the description adequately covers external behavior, local state mutation, cache semantics, sibling differentiation, and the non-destructive nature of the operation. Nothing critical that an agent needs to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 five parameters including query, session_id, type, limit, and force_refresh behavior. The description adds high-level context about returning aliases and search hints, but does not materially add parameter-level semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description states a specific verb (確認し、返す) and a clear resource (Web NDL Authorities), and defines the core purpose: resolving authority candidates for person/corporate/subject names and returning aliases and safe search hints. It also explicitly distinguishes itself from bibliographic search tools, making sibling differentiation unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit routing guidance: this is not a literature search source but a search-term expansion/name-confirmation helper; for classification-based subject lookup use jp_lit_find_authority_terms_by_classification, and for actual literature search use jp_lit_search. This tells an agent exactly when to choose this tool versus named alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses important behavior beyond the annotations: it is an external read but performs local bookkeeping writes, is non-destructive, never modifies external sources, updates local session history even on cache hits, and creates/replaces local cache on cache miss or force_refresh. This is consistent with the annotations—readOnlyHint=false matches the local write behavior, and destructiveHint=false matches '非破壊'—so there is no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one dense block but every clause carries operational value: scope, sibling routing, source_id precondition, pid pass-through, non-destructive guarantee, and cache behavior. It could be more scannable with a list or clearer sentence breaks, but it is not bloated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity—8 parameters, many siblings, and an output schema—the description covers the essential workflow context: external access pattern, internet-public-only constraint, source_id prerequisite, when to use alternatives, direct pid reuse, and cache/session side effects. The output schema already handles return-value details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description reinforces parameter relationships like passing jp_lit_search_fulltext pids directly and checking OCR availability before using source_id, but the schema already documents these details, so the description adds little new parameter-level meaning beyond what is already structured.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb and resource: keyword full-text search of pages inside NDL Digital Collection materials, with the scope constraint of 'インターネット公開資料のみ'（internet-public materials only）. It also explicitly distinguishes itself from sibling tools by saying candidate-pid discovery belongs to jp_lit_search_fulltext and specific-page OCR/image checks belong to jp_lit_get_text_coordinates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit routing: use jp_lit_search_fulltext when searching candidate pids across all materials, use jp_lit_get_text_coordinates for page-level OCR text and image URLs, and check jp_lit_get_record first when using source_id. It also states that pids from jp_lit_search_fulltext can be passed directly, leaving no ambiguity about when to invoke this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explains that research_goal and scope_note are saved in the new session's trace, while search results, candidates, and annotations remain in the old session. This adds context beyond annotations, which already indicate the tool is not read-only and not destructive. However, it does not mention any potential limitations like session count limits or authentication requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with the main action stated first, followed by the effect on parameters, and then alternative tools for clarity. Every sentence adds value, and there is no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's role in session lifecycle management and the presence of an output schema, the description covers the essential behavioral aspects. It explains the fate of old session data and parameters. However, it does not describe the output or what happens if no parameters are provided beyond starting without a purpose, leaving minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining how the parameters are used: both research_goal and scope_note are stored in the new session's trace. It also clarifies that if research_goal is unspecified, the session starts without a purpose, which is not explicit in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: starting a new empty research session while preserving the current session as history. It uses specific verbs and resources, and differentiates from siblings by naming jp_lit_update_session_trace for updates and jp_lit_list_sessions/jp_lit_export_session for reviewing old sessions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides when-to-use and when-not-to-use guidance. It states to use jp_lit_update_session_trace for appending to an existing session, and jp_lit_list_sessions or jp_lit_export_session for checking old sessions, making it clear when to choose this tool over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readonly and idempotent hints. Description adds explicit statement that session and cache are not modified, reinforcing safety 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: first defines purpose, second gives usage guidance. No extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given output schema exists, description provides sufficient context for a search tool: what it searches, when to use, and that it's non-modifying.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%. Description adds detail for 'query' parameter (matches subject, candidate title, memo, preview) beyond schema's partial-match description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool searches past sessions by topic, keyword, etc., and distinguishes from jp_lit_list_sessions which is for browsing without a search term.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use (when search term is known) and when not (when term is unknown, use list_sessions). Also declares read-only nature.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. The description adds value by explicitly stating 'session や cache は変更しない' (does not modify session or cache), which names the specific resources that are unaffected and reinforces the read-only contract in a way that matters to an agent tracking side effects. 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Four compact sentences with no filler: read-only status and core function are front-loaded, followed by use cases, alternative tool routing, and a safety note. Every sentence contributes a distinct piece of information, and the description is appropriately sized for a tool with 10 parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description, combined with full schema coverage and an output schema, fully equips an agent to call this tool correctly. It covers purpose, filters, sort behavior, use case, alternative routing, and side-effect guarantees, leaving no critical gap for a listing operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so a baseline of 3 applies. However, the description adds a high-level functional grouping: it maps the listed filters (trace presence, selected-candidate presence, source, date range) to the specific parameter categories, and the ordering phrase ('新しい順または作成日順') clarifies the sort_by/sort_order semantics. This helps an agent select relevant parameters without reading every schema entry.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('一覧し' = list), a clear resource ('過去の調査セッション' = past research sessions), and the key scoping dimensions (ordering, trace/selected presence, source, date range). It also explicitly distinguishes itself from the sibling 'jp_lit_find_sessions' by noting the alternative is for searching by specific terms, so an agent can select this tool confidently.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit use cases: inventorying research history when search terms are not remembered, and finding candidates to resume. It also names the alternative tool 'jp_lit_find_sessions' and states the condition for choosing that instead ('特定語で探す場合は'), offering clear when-to-use vs. when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations include destructiveHint=true, which aligns with the description's mention of deletion when dry_run=false. The description adds context about the default non-destructive behavior, but lacks details on error handling or side effects, which is acceptable given the annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences that are front-loaded with the key behavior. Every sentence adds value, with no redundant information. Efficiently communicates purpose, usage, and alternatives.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and annotations, the description covers the essential behavior, parameter interactions, and alternative tools. It is complete for an agent to use this tool appropriately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with all parameters described. The description adds meaning beyond schema by explaining the workflow: enumeration vs deletion based on dry_run, and the role of older_than_days and limit. This enhances parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool enumerates old cache candidates and deletes them when dry_run=false. It distinguishes from sibling tools jp_lit_delete_cache (individual deletion) and jp_lit_list_cache (listing), making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides guidance on when to use this tool (pruning old caches) and when to use alternatives. It explains the dry_run parameter behavior, ensuring the agent knows when deletion actually occurs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses the local write side effects (session history update even on cache hit, cache creation/replacement on miss or force_refresh), the non-destructive nature, and the fact that external sources are not modified. This meaningfully complements the annotations and sets correct expectations for a non-idempotent, open-world tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description opens with a compact safety/effect classification, then states the operation, routes to siblings, and closes with cache behavior. Every sentence earns its place; there is no repetition of schema fields or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 6-parameter tool with a rich output schema, the description supplies the missing decision context: external data sources involved, the exact filter compatibility of the returned parameter, the sibling disambiguation, and the local-storage behavior. No critical information needed to invoke it correctly is absent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 six parameters. The description adds only high-level context (that the output feeds CiNii Books category filters and includes a jp_lit_search call), not per-parameter semantics, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description names the exact operation (suggest NDC/NDLC classification codes from a subject term via Web NDL Authorities), the return artifact (suggested_category_param + jp_lit_search call example), and explicitly distinguishes the reverse-direction sibling jp_lit_find_authority_terms_by_classification and the actual-search sibling jp_lit_search. It leaves no ambiguity about what this tool uniquely does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It states the expected use case (subject term -> classification codes) and gives explicit alternatives: use jp_lit_find_authority_terms_by_classification for classification-to-term lookup and jp_lit_search for actual literature search. This is exactly the when/alternative guidance an agent needs to choose the right tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses that cache hits still update local session history and that cache misses or force_refresh create or replace local cache. It also notes the local bookkeeping write is non-destructive and clarifies that no strict distinction is made between missing content and access restrictions. The description meaningfully extends annotation data without contradicting it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long, but it is densely packed with source-specific behavior and cross-tool routing information. It front-loads the core purpose before enumerating source cases. The length is justified by the multi-source complexity, though it is near the upper limit of conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the large source enum, an output schema, and sibling tools, the description is unusually complete: it covers per-source return scope, pid/source_id exclusivity, downstream tool availability, manual viewing guidance, cache behavior, and the batch alternative. No critical calling context appears to be missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is high at 80%, so the baseline is 3; the description adds meaningful semantics by explaining that source_id and pid are alternatives for source=ndl_digital and that exactly one must be specified. It also gives source-specific meaning for source values and clarifies that pid is used instead of source_id. While pid itself has no schema description, the tool description compensates well for that gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource: it fetches record details from an external source without mutating it. It further distinguishes behavior per source and explicitly names the sibling jp_lit_get_records for batch retrieval, so an agent can tell what this tool is not. The opening 'external read / local bookkeeping write' clarifies the dual read/write nature beyond the generic title.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance: single record lookup, with jp_lit_get_records for 2–10 pre-selected candidates. It also describes when downstream tools like jp_lit_get_text_coordinates are usable, and when they are not when source_metadata.next_digital_library.available is false. It explicitly states what is not fetched (images, IIIF, OCR, fulltext) and how to check for manual viewing alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses that this performs an external read plus local non-destructive bookkeeping write, preserves input order, triggers individual external lookups for uncached IDs, never modifies the external source, and updates local session history even on cache hits while creating/replacing local cache on misses or force_refresh. These are material behavioral traits not captured by readOnlyHint=false, openWorldHint=true, idempotentHint=false, or destructiveHint=false, and there is no contradiction with any annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but mostly every sentence carries necessary information, and it leads with the most important framing ('external read / local bookkeeping write（非破壊）'). It is slightly long and mixes several distinct rules in one paragraph, with a run-on break between 'jp_lit_get_record を使う' and '外部sourceは変更しない', so it loses a point on structural polish.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of a rich input schema, annotations, and an output schema, the description covers all the contextual information an agent needs: when to use the tool, what side effects occur, how caching behaves, how inputs are constrained, and how it differs from the single-record sibling. No important call-time decision is left ambiguous.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by stating that source_ids and pids are mutually exclusive, that pids are only valid for ndl_digital, and that per-candidate cache behavior is tied to force_refresh. It does not add much per-parameter syntax detail because the schema already covers that, but the added relationships and constraints justify a score above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific verb ('詳細取得する'), resource ('同じ source の選別済み文献候補1〜10件'), and key behavior (batch retrieval returning per-candidate success/failure and cache info in input order). It also explicitly distinguishes itself from the single-record sibling jp_lit_get_record, so an agent can select the right tool without inspecting schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance: use for selected candidates from the same source, avoid for auto-enriching all search results or as an upstream bulk API, and use jp_lit_get_record for a single record. It also names the source_ids vs pids exclusivity rule and the ndl_digital-specific pid option, making the choice and invocation conditions unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description clearly discloses behavioral side effects beyond the annotations: it says cache hits still update local session history, cache miss or force_refresh creates/replaces local cache, and it explicitly claims '外部sourceは変更しない' (external sources are not modified). This complements the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false) by explaining exactly what local state gets written and what does not.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense and packed with necessary information, and it front-loads the core semantic (external read / local bookkeeping write, non-destructive). It is shaped like a compact technical spec rather than a prose paragraph. It is slightly over-stuffed: the final sentence about cache behavior could be more readable, but it earns a 4 because every sentence carries unique value and it does not repeat the schema or annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the output schema exists (the tool has a return schema, so return details do not need to be explained), the description covers all key behavioral and workflow aspects: the non-destructive read/write split, the internet-public-only constraint, the prerequisite check with jp_lit_get_record, the routing to sibling tools, and the caching semantics. There is nothing an agent needs to decide to call this tool correctly that is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3; the description adds extra meaning by explaining that pid from jp_lit_search_fulltext can be passed directly (a workflow shortcut), that source_id must be paired with an OCR availability check, and that source should usually be ndl_digital. It also clarifies the role of session_id (application state handle) and distinguishes it from MCP transport connection IDs or cache keys. It loses one point because some parameter details (e.g., force_refresh behavior) are described more in the schema than in the description, but the description still adds workflow-level semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific operation: get page-unit OCR text and coordinates from NDL Digital Collection materials, with the explicit constraint that only internet-public materials are supported. It also distinguishes itself from siblings (jp_lit_search_pages for finding page numbers, jp_lit_get_fulltext for bulk text) and defines its read/write nature as an external read with local bookkeeping writes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance: use jp_lit_search_pages when locating page numbers, use jp_lit_get_fulltext for full-text batch retrieval, and verify next_digital_library.available=true via jp_lit_get_record when using source_id. It also states that pids from jp_lit_search_fulltext can be passed directly, and it clarifies that source_id requires a prior availability check.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations by characterizing the operation as 'external read / local bookkeeping write (non-destructive)' and explicitly confirming external sources are unchanged. It also discloses cache replacement and session-history updates, which align with and explain the readOnlyHint=false and idempotentHint=false annotations without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Each segment of the description contributes substantive scope or behavioral information, and the non-destructive external/local label is front-loaded. It is slightly dense and run-on in the middle, so it is not quite as clean as the highest benchmark.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 10-parameter tool, the description, combined with 100% schema coverage and an output schema, is complete enough for correct invocation: it covers domain scope, side effects, cache semantics, external-source non-modification, and the follow-up verification caveat. No critical operating detail is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds useful meaning beyond the schema: results are 'clues' rather than verified citations, cache hits still update session history, and cache miss/force_refresh replaces local cache, which clarifies session_id, force_refresh, and include_outputs behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
States the exact verb and resource (search KAKEN research projects) and describes what it returns: research themes, keywords, report PDFs, and output-list leads. The 'supplementary tool' framing and KAKEN scope clearly separate it from general literature, guide, and illustration searches among siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says final confirmation of papers and books must be re-checked via CiNii / J-STAGE / IRDB / NDL, which tells an agent when not to treat this tool's results as authoritative. It also states that external sources are not modified and local cache/session behavior varies by hit/miss, giving concrete operational context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GitHub Badge
Glama performs regular codebase and documentation scans to:
- Confirm that the MCP server is working as expected.
- Confirm that there are no obvious security issues.
- Evaluate tool definition quality.
Our badge communicates server capabilities, safety, and installation instructions.
Card Badge
Copy to your README.md:
Score Badge
Copy to your README.md:
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/itarunnn/jp-lit-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server