Skip to main content
Glama

jp_lit_search_kaken_projects

Search KAKEN-funded projects to retrieve research themes, keywords, report PDFs, and output lists for Japanese academic research.

Instructions

KAKEN から研究課題を検索し、研究テーマ・キーワード・報告書 PDF・成果リストの手がかりを返す補助 tool。論文・図書の文献確定は CiNii / J-STAGE / IRDB / NDL で再確認する

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
queryYes
limitNo
pageNo
detail_limitNo
researcher_nameNo
from_fiscal_yearNo
to_fiscal_yearNo
include_outputsNo
force_refreshNo

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
queryYes
pageYes
limitYes
totalYes
itemsYes
cacheNo

Implementation Reference

  • The main handler function createJpLitSearchKakenProjectsTool that executes the tool logic. It parses input using searchKakenProjectsInputSchema, delegates to the KakenClient via runCachedTool, validates output with searchKakenProjectsOutputSchema, and returns structured content.
    import { createFileCache } from "../lib/persistence/fileCache.js";
    import type { FileCache } from "../lib/persistence/fileCache.js";
    import { runCachedTool } from "../lib/persistence/runCachedTool.js";
    import { createSessionStore } from "../lib/persistence/sessionStore.js";
    import type { SessionStore } from "../lib/persistence/sessionStore.js";
    import { withToolCache } from "../lib/toolCache.js";
    import {
      searchKakenProjectsInputSchema,
      searchKakenProjectsOutputSchema
    } from "../lib/schemas.js";
    import type { SearchKakenProjectsOutput } from "../lib/schemas.js";
    import type { KakenClient } from "../sources/kaken/client.js";
    
    export function createJpLitSearchKakenProjectsTool(
      client: KakenClient,
      cache: FileCache = createFileCache(),
      sessions: SessionStore = createSessionStore()
    ) {
      return async (input: unknown) => {
        const parsed = searchKakenProjectsInputSchema.parse(input);
        const { force_refresh, ...cacheableInput } = parsed;
        const result = await runCachedTool<SearchKakenProjectsOutput>({
          tool: "jp_lit_search_kaken_projects",
          input: cacheableInput as Record<string, unknown>,
          cache,
          sessions,
          bypassCache: force_refresh,
          live: async () => searchKakenProjectsOutputSchema.parse(await client.searchProjects(cacheableInput))
        });
        const structuredContent = searchKakenProjectsOutputSchema.parse(
          withToolCache(result.structuredContent as Record<string, unknown>, result)
        );
    
        return {
          content: [{ type: "text" as const, text: JSON.stringify(structuredContent, null, 2) }],
          structuredContent
        };
      };
    }
  • Input schema (searchKakenProjectsInputSchema) defining the Zod validation for the tool's input: query, limit, page, detail_limit, researcher_name, from_fiscal_year, to_fiscal_year, include_outputs, force_refresh.
    export const searchKakenProjectsInputSchema = z.object({
      query: z.string().trim().min(1),
      limit: z.number().int().positive().max(20).default(10),
      page: z.number().int().positive().default(1),
      detail_limit: z.number().int().nonnegative().max(10).default(5),
      researcher_name: z.string().trim().min(1).optional(),
      from_fiscal_year: z.number().int().optional(),
      to_fiscal_year: z.number().int().optional(),
      include_outputs: z.boolean().default(true),
      force_refresh: forceRefreshFieldSchema
    });
  • Output schema (searchKakenProjectsOutputSchema) defining the structure of the tool's response: query, page, limit, total, items (array of kakenProjectSchema), and optional cache.
    export const searchKakenProjectsOutputSchema = z.object({
      query: z.string(),
      page: z.number().int().positive(),
      limit: z.number().int().positive(),
      total: z.number().int().nonnegative(),
      items: z.array(kakenProjectSchema),
      cache: toolCacheSchema.optional()
    });
  • The kakenProjectSchema defining a project item: project_id, title, url, principal_investigator, fiscal_years, project_type, fields, keywords, summary, detail_fetched, report_pdf_status, report_pdfs, outputs_preview, search_hints.
    const kakenProjectSchema = z.object({
      project_id: z.string(),
      title: z.string(),
      url: z.string(),
      principal_investigator: z.object({
        name: z.string(),
        affiliation: z.string().nullable(),
        researcher_number: z.string().nullable()
      }).nullable(),
      fiscal_years: z.string().nullable(),
      project_type: z.string().nullable(),
      fields: z.array(z.string()),
      keywords: z.array(z.string()),
      summary: z.string().nullable(),
      detail_fetched: z.boolean(),
      detail_omitted_reason: z.enum([
        "detail_limit_exceeded",
        "include_outputs_false",
        "fetch_failed"
      ]).nullable(),
      report_pdf_status: z.enum(["found", "none_found", "not_checked", "fetch_failed"]),
      report_pdfs: z.array(z.object({
        label: z.string(),
        fiscal_year: z.string().nullable(),
        url: z.string()
      })),
      outputs_preview: z.array(z.object({
        type: kakenOutputTypeSchema,
        raw_type: z.string().nullable(),
        title: z.string(),
        authors: z.array(z.string()),
        year: z.string().nullable(),
        doi: z.string().nullable(),
        url: z.string().nullable(),
        note: z.string().nullable()
      })),
      search_hints: z.object({
        project_terms: z.array(z.string()),
        researcher_terms: z.array(z.string()),
        keyword_terms: z.array(z.string()),
        caution: z.string()
      })
    });
  • src/server.ts:456-464 (registration)
    Registration of the tool 'jp_lit_search_kaken_projects' via server.registerTool with description, input/output schemas, and the handler function.
    server.registerTool(
      "jp_lit_search_kaken_projects",
      {
        description: "KAKEN から研究課題を検索し、研究テーマ・キーワード・報告書 PDF・成果リストの手がかりを返す補助 tool。論文・図書の文献確定は CiNii / J-STAGE / IRDB / NDL で再確認する",
        inputSchema: searchKakenProjectsInputSchema,
        outputSchema: searchKakenProjectsOutputSchema
      },
      searchKakenProjectsTool
    );
Behavior2/5

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

No annotations are provided, so description must carry full behavioral transparency burden. It mentions returning 'clues' and being a support tool, implying non-authoritative results, but does not disclose idempotency, side effects, authentication, or rate limits required for safe invocation.

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

Conciseness3/5

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

The description is concise (two sentences) and covers core purpose, but lacks any structured detail about parameters or behavior. While front-loaded, it sacrifices completeness for brevity.

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

Completeness2/5

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

Despite having 9 parameters and an output schema, the description only explains the tool's overall purpose and verification note. It omits pagination, default behaviors, and return value structure, making it incomplete for an agent to use effectively.

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

Parameters1/5

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

Schema description coverage is 0% and the description provides no details about any of the 9 parameters (e.g., query, limit, researcher_name). The agent must rely solely on parameter names, which is insufficient for correct invocation.

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

Purpose5/5

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

Description clearly states the tool searches KAKEN for research projects and returns clues for themes, keywords, and reports. It explicitly differentiates from siblings by focusing on KAKEN and indicating verification via other databases.

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

Usage Guidelines4/5

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

Description advises that final confirmation of papers/books be done via CiNii/J-STAGE/IRDB/NDL, providing clear when to use this tool (initial search) and when not (final verification). However, it lacks explicit comparison to other sibling search tools.

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

Install Server

Other Tools

Latest Blog Posts

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