The server provides 9 tools for accessing Japanese corporate data via government APIs. While tool names follow clear verb_noun conventions and all have descriptions, there are significant gaps in parameter documentation, output schema clarity, and error handling guidance. Most tools accept only 1-2 parameters with minimal constraint specification. Output is returned as formatted JSON strings rather than structured objects, forcing LLMs to parse unstructured text. Error responses are generic ('Error fetching...') without recovery guidance. Parameter descriptions exist but lack format specifications, validation rules, and dependency hints. The server scores slightly above the 50-59 'Poor' baseline due to presence of descriptions and reasonable naming, but falls short of 'Good' due to missing output schema documentation and weak error handling.
Output returned as JSON strings, not structured objects. LLMs must parse unstructured text rather than receive typed fields. Violates pattern:response-shaper and wastes tokens.
Error responses lack recovery guidance. All errors return 'Error <action>: {e}' with no actionable next steps. Violates pattern:recovery-guide, LLMs cannot determine if error is retryable, user-fixable, or fatal.
Convert all tool returns from json.dumps() to structured dictionaries. Define a return TypedDict per tool documenting fields, types, and whether fields can be null. Example: 'CompanySearchResult = TypedDict("CompanySearchResult", {"total": int, "companies": list[CompanyInfo], "nextCursor": str | None})'.
Add per-request _meta logLevel support to error handling. When an API call fails, catch specific exception types: httpx.TimeoutException → 'retryable_timeout', httpx.HTTPStatusError with 401 → 'auth_required_user_fixable', ValueError on input validation → 'invalid_input_user_fixable'. Return structured error objects with category, message, and recovery hint.
Replace example values with formal constraints. For 'prefecture', document as: 'Prefecture name (e.g., 東京都, 大阪府, or any of Japan's 47 prefectures; case-insensitive).' For 'days_back', add minimum=1, maximum=90 to the parameter definition.
Add pagination to search_company and get_company_patents. Change signature to accept optional 'limit' (1-100, default 20) and 'offset' (default 0). Return {"total": int, "companies": [...], "offset": int, "limit": int, "hasMore": bool}.
Document output schemas in tool docstrings. Example for search_company: 'Returns {"total": int, "companies": [{"corporate_number": str, "name": str, "location": str, "status": str, "update_date": str}]}'.
Add WHEN guidance to tool descriptions. For search_company: 'Use this to find a company by name if you only have its display name, not its corporate number. If you already have the corporate number, call get_company_info() directly for faster results.'
Score history
Overall score trend
First recorded score · v2 rubric
55/100
Scored
Grade
Overall
Spec posture
Rubric
2026-09-23
D
55
2026-07-28+
v2
Get actual statistical data for a specific e-Stat table.
Parameter descriptions lack format specification and validation rules. 'Optional prefecture filter (e.g. "東京都", "大阪府")' uses example values rather than formal constraints. LLMs will attempt to pass literal example strings.
No output schema documentation. Tool descriptions state what they return narratively ('List of matching companies...') but provide no structured schema for fields, types, or pagination. LLMs cannot plan downstream calls reliably.
search_company hardcodes result limit to 20 ([:20]) but does not document pagination. No 'total', 'page', 'limit', 'offset', or 'next_cursor' parameters offered. Large result sets will be silently truncated.
Parameter 'days_back' in get_edinet_reports lacks min/max bounds. Description says 'default 30, max 90' but schema has no constraints. LLMs could pass negative, zero, or huge integers.
All tools handle API failures identically with broad try-except. No distinction between network timeout (retryable), auth failure (user-fixable via config), missing API key (fatal), or invalid corporate_number (user-fixable with guidance).
Tool descriptions are narrative ('Search Japanese companies by name') but lack WHEN guidance. No indication of when to use search_company vs search_statistics, or when a tool is more expensive/slower than alternatives.
get_company_finance, get_company_patents, and similar tools return 'No financial records available' when the API returns an empty list. This conflates 'no data exists' with 'tool failed.' LLMs may retry unnecessarily.
Implement error-classification. Replace generic 'Error fetching...' with categorized responses: If env var is missing, return 'Auth Error: API key not configured. Set GBIZINFO_API_TOKEN in MCP server config.' If corporate_number is invalid format, return 'Invalid Input: corporate_number must be 13 digits.' If API returns 404, return 'Not Found: No company with this corporate number. Try search_company() if you only have the name.'
Add per-tool timeout and retry guidance. Document in descriptions: 'This tool queries the gBizINFO API which may be slow during business hours. If the request times out, retry after 5 seconds. Typical response time: 1-3 seconds.'
Document corporate_number format more explicitly. Change parameter description from '13-digit corporate number (法人番号).' to '13-digit Japanese corporate number (法人番号), format: NNNNNNNNNNNNN (digits only, no hyphens or spaces).'
For search_statistics and get_edinet_reports, add optional 'limit' parameter defaulting to 20. Document: 'Results are paginated. Increase limit up to 100 for larger result sets, but be aware response parsing may be slower.'
Add toolAnnotations (readOnlyHint) to all tools. Since all are read-only queries, decorate with @mcp.tool(readOnlyHint=True) to signal to clients that no state modification occurs.
Add example corporate_number usage in get_company_info docstring without placing it in the parameter description. Example in docstring: 'Example: get_company_info("1010001012345") to fetch Sony Group Corp (as of 2024).'
For tools calling multiple government APIs (gBizINFO, EDINET, e-Stat), add dependency hints in descriptions. Example: 'Requires GBIZINFO_API_TOKEN environment variable. If not set, tool will return error message with setup instructions.'