jquants-mcp

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v1.3.0
Disambiguation4/5
Most tools have clearly distinct purposes, and the descriptions explicitly cross-reference alternatives (e.g., detect_52w_high_low vs detect_ytd_high_low). A few pairs like get_indices_bars_daily/get_indices_bars_daily_topix and the earnings calendar tools could cause misselection, but they are well-documented.
Naming Consistency5/5
The naming conventions are highly consistent: get_ for retrieval, detect_ for screeners, compare_ for comparative analysis, and search_ for lookup. Range variants and plan-specific suffixes follow predictable patterns, making the tool set easy to navigate.
Tool Count2/5
55 tools is excessive for a single server. While the domain is broad, many tools could be merged (range variants, TOPIX-specific index bars, three earnings-related tools). The count makes the surface feel fragmented and heavy.
Completeness5/5
The tool set covers the full spectrum of Japanese equity market data: master data, OHLC bars, indices, derivatives, financial statements, earnings calendars, margin/short-sale data, screeners, briefings, technical indicators, charts, and bulk downloads. No major coverage gaps are apparent.
Average 4.7/5 across 55 of 55 tools scored. Lowest: 3.4/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 131 commits in the last 12 weeks
- Last stable release on August 22, 2026
- 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.json to 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

Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds context about the included indices and supported plans, but does not disclose behaviors such as default parameter handling, date range interactions, or pagination. This is adequate but not rich 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear purpose statement, return summary, plan note, and Args section. It is concise, though the first two sentences are slightly redundant ('Retrieve daily index bars (OHLC)' and 'Returns daily OHLC and volume').
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 4 optional parameters and an output schema, so return values are covered by the schema. However, the description does not clarify how parameters interact (e.g., using date plus date_from/date_to) or what happens when no parameters are provided. It also doesn't mention which indices are returned if code is omitted. This leaves gaps for a flexible retrieval tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It provides useful examples for code (e.g., 0000 = TOPIX) and date format (YYYYMMDD or YYYY-MM-DD), but leaves date_from and date_to with only names and no explanation of their relationship or usage. This partially compensates for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves daily index bars (OHLC) and names specific indices (TOPIX, Nikkei 225, Growth 250), which distinguishes it from equity and derivative bar tools. However, it does not differentiate itself from the sibling get_indices_bars_daily_topix, leaving a minor ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for daily index bar data but provides no explicit guidance on when to use this tool versus alternatives like get_indices_bars_daily_topix or get_equities_bars_daily. It does mention supported plans, which is a usage constraint, but lacks 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 already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds valuable context beyond annotations: return scope ('daily buy/sell breakdown'), data granularity ('per individual issue'), code format nuances (5-digit vs 4-digit), and date format examples. This enriches the behavioral understanding 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a summary, return details, plan support, and a parameter list. It is front-loaded with the main purpose. Minor redundancy exists between the first two sentences ('sell/buy by investor type' is repeated), but overall it remains concise and scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's purpose, parameters, and a return overview. It does not explain how parameters interact (e.g., whether code is required, whether date and date_from/date_to are mutually exclusive, or if a valid query must include at least one date). Since an output schema exists, return structure is covered elsewhere, but input constraints remain ambiguous.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning the JSON schema provides no property descriptions. The description fully compensates by explaining all four parameters with formats, examples, and edge cases ('4-digit codes match ordinary shares only'). This is essential for an agent to invoke the tool correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: retrieving market breakdown data (sell/buy by investor type per issue). It uses a specific verb ('Retrieve') and resource, and distinguishes it from generic list tools by mentioning 'per individual issue' and investor types. However, it does not explicitly differentiate from the sibling tool 'get_equities_investor_types', which may cover similar ground.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives. It mentions a supported plan (Premium) but does not state any exclusions, prerequisites, or comparative use cases. The only implied usage is 'if you need market breakdown data', but no alternative is referenced or distinguished.
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 declare read-only, idempotent, and non-destructive behavior, lowering the burden. The description adds meaningful context beyond annotations: it lists the specific dividend fields returned, the Premium plan requirement, and a nuance about 4-digit codes matching ordinary shares only. It does not mention rate limits or error behavior, but the provided additions are valuable and consistent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is tightly written with no redundant phrases. It opens with a clear one-sentence purpose, follows with a compact list of return fields, a short plan note, and a structured Args block. Every sentence adds value, and the layout is easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return format is covered. However, the description does not clarify parameter relationships or requirements: all parameters are optional in the schema, but it is unclear whether a code and a date/range are expected, or if date excludes date_from/date_to. This ambiguity could lead an agent to invoke the tool with an invalid parameter combination. Given the tool complexity, a few more usage constraints would make it complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must fully compensate for parameter semantics. It does: code is explained with an example and a note about ordinary shares; date format is specified; date_from and date_to are clearly labeled as range query boundaries. Each parameter gains meaning beyond the bare schema, making this parameter documentation complete and self-sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a clear verb and resource: 'Retrieve cash dividend data.' It then lists the specific data fields returned (record date, ex-dividend date, dividend amount, expected payment start date, and commemorative/special dividends), which distinguishes it from other tools like get_dividend_yield_ranking or detect_consecutive_dividend_increase. The purpose is unambiguous and specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool (when you need cash dividend data for a stock) and provides constraints like '4-digit codes match ordinary shares only' and '[Supported plans] Premium'. However, it does not explicitly contrast this tool with alternatives or state when NOT to use it, such as pointing to get_dividend_yield_ranking for yields. The usage context is clear but lacks exclusionary 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 declare readOnly, idempotent, and non-destructive. The description adds meaningful behavioral traits beyond annotations: 'All data is returned in a single response without pagination' and the supported plans restriction. It does not contradict annotations, though it omits potential context like response size, timezone, or error behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear one-line summary, then supporting details. There is some redundancy between the first line ('trading days and holidays') and the second line ('trading days, holidays, and half-day classifications'), but overall it remains compact and each section serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema and annotations, the description covers purpose, parameters, and a key behavioral detail (no pagination). It lacks explicit usage alternatives and date range inclusivity details, but for a read-only calendar tool with a rich output schema, it is sufficiently complete for an AI agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameter descriptions (0% coverage), but the description compensates thoroughly. It explains hol_div codes (1, 0, 3) and exact date formats for date_from/date_to, which is essential for correct invocation. This goes well beyond the schema's bare type information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb phrase 'Retrieve market calendar (trading days and holidays)' and clearly distinguishes it from earnings-oriented siblings like get_equities_earnings_calendar by focusing on trading days, holidays, and half-day classifications. No ambiguity about what resource is accessed.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context such as 'All data is returned in a single response without pagination' and supported plans, but it does not explicitly state when to use this tool versus alternatives like earnings calendars. Usage is implied by the tool's name and content, but no direct alternatives or exclusions are mentioned, so it falls short of clear 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 declare read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations: row-level Tier 1 caching, efficient incremental fetching, and supported plans, which helps the agent understand performance and access constraints.
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 fairly concise but has redundancy: 'Retrieve daily TOPIX bars (OHLC)' and 'Returns daily OHLC data for TOPIX' convey the same information, and the cache detail is repeated. It could be tightened without losing meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema and annotations, the description covers the essential aspects: purpose, date formats, caching behavior, and plan restrictions. It is sufficiently complete for a simple two-parameter read-only tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no parameter descriptions (0% coverage), but the description compensates fully by documenting date_from and date_to with formats (YYYYMMDD or YYYY-MM-DD) and their roles as start/end dates for the range query.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action and resource: 'Retrieve daily TOPIX bars (OHLC)' and mentions a dedicated endpoint, distinguishing it from generic index bar tools like get_indices_bars_daily.
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?
It provides clear context for when to use the tool: for daily TOPIX OHLC data with efficient incremental fetching via Tier 1 cache, and lists supported plans. However, it does not explicitly mention alternatives or when-not conditions.
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 already declare destructiveHint=true and idempotentHint=true. The description adds important behavioral context: it performs a 'bulk DELETE,' clears all tables when table is omitted, and offloads to a worker thread to avoid blocking the event loop. These details go beyond the annotations and are valuable for an agent assessing side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a one-line purpose, followed by a brief implementation note and an Args section. The offload explanation references internal docstrings (`_cache_clear_impl`, `health_check`) that may not be available to the agent, but it is still compact and contains no redundant filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity—one optional parameter, no enums, and an output schema—the description adequately covers purpose, destructive scope, and parameter behavior. It does not enumerate available table names, but that is likely an external concern and not needed for correct selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema only defines an optional table parameter with a string or null type and a default of null. The description provides the essential semantic meaning: 'Table name to clear. Clears all tables when omitted.' This fully compensates for the schema's 0% description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Clear cached data,' a specific verb+resource statement. This clearly distinguishes it from sibling tools such as cache_status, making the tool's purpose immediately obvious.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit when-to-use guidance or mention of alternatives. The intended usage is implied by the tool name and the first sentence, but the description does not state, for example, when cache clearing is preferable to cache inspection or what preconditions apply.
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 declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds valuable context beyond annotations by disclosing the Premium-only access requirement and specifying the output includes OHLC, volume, and open interest, which is not otherwise communicated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured with a title line, use-case keywords, returns summary, plan note, and a clear Args list. It is slightly longer than the ideal but every section earns its place, and the parameter list is essential given the zero schema coverage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with only 3 parameters and an output schema exists. The description covers the data returned (OHLC, volume, open interest), the Premium requirement, and all parameters thoroughly. Minor omissions like timezone handling or date edge cases are not critical given the available output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must fully explain parameters. It does so excellently: date format (YYYYMMDD or YYYY-MM-DD), category examples (Futures225, FuturesTOPIX) with 'omit for all', and contract_flag meaning (0=all, 1=front, 2=back). This adds complete meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool provides daily futures OHLC bars, listing specific contract types (日経先物, TOPIX先物, etc.) and explicitly distinguishes it from sibling tools like options and equities by the 'futures' keyword. The resource and data type are unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit 'Use for' keywords (先物, 日経先物, etc.) and notes the Premium plan requirement, giving clear context for when to invoke this tool. However, it does not explicitly mention when not to use it or name alternatives (e.g., the options tool), though sibling names imply this.
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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: the weekly update schedule (typically Thursdays), data coverage scope (proprietary, brokered, foreign investors, etc.), and supported plan levels (Light+).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: a one-line summary, followed by use cases, update frequency, coverage list, plan info, and then argument descriptions. Every sentence earns its place; no wasted words or redundant repetition of schema fields.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present and annotations covering safety, the description need not detail return structures. It adequately covers the tool's purpose, usage context, update cadence, parameter semantics, and data coverage. It omits potential error conditions or timezone nuances, but those are lower-priority gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description fully compensates by explaining each parameter: section with examples (TSEPrime, TSEStandard, TSEGrowth) and date_from/date_to with format examples (YYYYMMDD or YYYY-MM-DD). This adds meaning the schema lacks, though it could be more exhaustive on valid section values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource: 'Weekly trading value by investor type' with a specific, non-generic data focus. It distinguishes itself from all sibling tools by specifying investor-type breakdowns, and the Japanese keywords ('投資家別売買動向') and use cases make the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly lists use cases ('Use for 投資家別売買, 外国人買い, 個人投資家動向, 信託銀行売買, investor flow'), providing clear context for when to select this tool. It does not mention exclusions or alternatives, but the explicit use-case list is strong 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?
The annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is well covered. The description adds useful behavioral context by explaining this is the 'simplified' variant and listing supported plans (Standard/Premium). It does not contradict any annotation, and the plan accessibility note is valuable beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded with the core purpose, and includes plan info, an alternative reference, and an args list. The only minor issue is the ambiguous phrase 'Standard+' followed by 'Standard plan accessible', which creates slight redundancy and could confuse readers about the actual plan tier.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple single-parameter read-only tool with an output schema available, so the description does not need to explain return values. It covers purpose, target instrument, plan accessibility, alternative usage, and the date parameter format. The 'Standard+' ambiguity is a minor gap, but overall the context is sufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero description coverage for the single 'date' parameter, but the description compensates by specifying the accepted date formats (YYYYMMDD or YYYY-MM-DD) and marking it required. This gives the agent clear syntax guidance that is not present in the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as providing daily Nikkei 225 options OHLC bars, including the Japanese term 日経225オプション for disambiguation. It also distinguishes itself from the sibling get_derivatives_bars_daily_options by noting this is the simplified version for Nikkei 225 only, while the sibling covers TOPIX options and IV.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states the intended use: 'Use for 日経225オプション, オプション日足 (simplified)' and notes it is accessible on the Standard plan. It also directs users needing full options data including TOPIX options and IV to get_derivatives_bars_daily_options (Premium only), providing a clear alternative and 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 already declare readOnlyHint, idempotentHint, and destructiveHint, so safety is covered. The description adds valuable behavioral context: accepted date formats, the n parameter range and default, and the exact return structure (up to n items, each with code, volume, turnover_value, close). This exceeds minimal expectations, though it could mention potential edge cases like non-trading dates.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a one-sentence summary followed by a clear Args/Returns breakdown. It is concise, front-loaded, and every sentence adds value. No unnecessary repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with two parameters and an output schema, the description provides sufficient detail for an agent to select and invoke it correctly. It explains the return format and parameter constraints. Minor gaps include no mention of error behavior or when to use alternatives, but these are not critical given the annotations and simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the full burden. It fully explains both parameters: date format (YYYY-MM-DD or YYYYMMDD) and n (range 1-100, default 10). This is complete and unambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Return top stocks by trading volume on a given date.' It uses a specific verb, identifies the resource (stocks by volume), and includes the temporal scope. This distinguishes it from siblings like get_top_turnover_value (turnover value) and detect_volume_surge.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for use: it is for retrieving a ranked list of the most traded stocks on a specific date. However, it does not explicitly mention when not to use it or list alternatives, such as using get_top_turnover_value for value-based rankings. The context is clear but lacks explicit exclusions.
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 declare readOnly, idempotent, and non-destructive, so the baseline is covered. The description adds valuable context: cache-only (no API call), supported plans, and data availability timing. This goes beyond annotations, though it doesn't specify edge-case behavior like invalid or non-trading dates.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with the core purpose. However, there is minor redundancy between 'All plans.' and the later '[Supported plans]' list. Otherwise each section serves a purpose, and the length is appropriate.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with an output schema, the description covers purpose, scope, usage, alternatives, availability timing, cache behavior, and parameter format. It is complete enough for an agent to select and invoke correctly without needing additional documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema provides only type and title for the date parameter, with 0% description coverage. The description compensates by specifying accepted formats (YYYY-MM-DD or YYYYMMDD), which is essential. It doesn't add more context (like trading-day restrictions), but for a single parameter this is sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence clearly states the tool returns the daily advance/decline summary for all listed equities, using a specific verb and resource. It also distinguishes from siblings by naming get_advance_decline_ratio and get_sector_performance for related but different queries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use this tool ('Use for 値上がり銘柄数・値下がり銘柄数・騰落集計 queries') and provides alternatives for other use cases. Also includes a practical timing detail (data available ~17:15 JST on trading days), giving the agent clear selection criteria.
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 read-only and idempotent annotations, the description discloses the exact return contents (file keys, timestamps, file sizes) and the 5-minute URL validity from the subsequent step. It also clarifies that this is a list operation, not the actual download. This adds useful context that annotations do not cover.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with clearly labeled sections (Step, Use for, Workflow, Returns, Supported plans, Args). It front-loads the primary purpose and workflow, and while the endpoint list is lengthy, it is necessary and presented in a clean bullet format. Every sentence delivers functional information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simple single-parameter signature, the description covers all essential context: the workflow step, supported plan tiers, exact return fields, and the full set of valid endpoint values. The presence of an output schema means return value details don't need to be spelled out, but the description still provides them, making it complete for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only specifies 'endpoint' as a required string with no description. The tool description compensates fully by explaining the parameter as a dataset endpoint name and enumerating all 20 accepted endpoint values, providing concrete examples. This transforms an ambiguous parameter into a highly actionable one.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Step 1 of bulk CSV download: list available files for a dataset,' which identifies the specific action and resource. It distinguishes itself from sibling tools like get_bulk_download_url and other data-fetching endpoints by emphasizing its role as the initial listing step in a bulk download workflow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool: for bulk download scenarios (全データ一括ダウンロード, bulk download, CSV ダウンロード) and provides a clear workflow (get_bulk_list → get_bulk_download_url). However, it does not explicitly mention when not to use it or directly compare it with alternative per-dataset fetch tools, so it stops short of full exclusion 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?
While annotations already declare readOnly, openWorld, idempotent, and non-destructive hints, the description adds valuable operational context: data is only available for up to 2 years, a minute/tick data add-on is required on certain plans, and 4-digit codes match ordinary shares only. This goes beyond the structured annotations to guide correct usage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-organized: a one-line core definition, usage hints, plan info, and a labeled Args section. Every sentence provides useful information without redundancy or filler, achieving high information density in a short space.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (4 optional parameters, output schema present), the description covers purpose, use case, data limits, parameter formats, and plan constraints. It integrates seamlessly with annotations and schema, leaving no significant gaps for an agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, but the description fully compensates by documenting all four parameters: code format (5 digits, with special note on 4-digit codes), date formats (YYYYMMDD or YYYY-MM-DD), and clear definitions for date_from/date_to as range query endpoints. This is a complete semantic mapping with no ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns per-stock 1-minute OHLC bars, using the Japanese term 分足 to reinforce the granularity. It distinguishes itself from siblings like get_equities_bars_daily by explicitly focusing on minute-level intraday data, leaving no ambiguity about its function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit use cases ('Use for 分足, 1分足, 分足データ, minute-level price, intraday OHLC') and adds operational context like 2-year data availability and plan requirements. However, it does not explicitly name alternative tools (e.g., daily bars) or state when NOT to use this tool, which prevents a perfect score.
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 declare readOnly, idempotent, and non-destructive behavior. The description adds useful behavioral details: no-parameter invocation returns all listed stocks for today, 4-digit codes match ordinary shares only, and accepted date formats. It does not mention pagination or rate limits, but it goes beyond the annotation baseline.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core definition, followed by short use-case, default behavior, supported plan, and argument lines. Every line adds information without unnecessary prose, making it appropriately sized and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with two optional string parameters, a read-only operation, and an output schema present. The description covers purpose, parameters, default behavior, and supported plans, which is sufficient for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides only defaulted nullable string properties with no descriptions, and schema coverage is 0%. The description fully compensates by explaining the 5-digit code format with an example, the 4-digit ordinary-share behavior, and the accepted date formats (YYYYMMDD or YYYY-MM-DD).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as a listed stock master ('上場銘柄マスタ') returning company name, industry code, and market segment, and lists concrete use cases such as ticker lookup and sector code lookup. This distinguishes it from sibling tools by emphasizing static master data rather than bars, search, or derivatives.
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?
It provides explicit 'Use for' scenarios (銘柄名, 会社名, 業種, 市場区分, ticker lookup) and states the default behavior when parameters are omitted. It does not name alternative tools or when-not-to-use conditions, so it stops short of a full 5, but the usage context is clear.
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 declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds useful context beyond these: supported plans, the 12-week delay for free plan data, and the requirement that either code or date must be specified. It also notes the FiscalPeriod label values, which helps set expectations. It does not mention rate limits or authentication, but the annotation coverage lowers the burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded. The opening line is immediately actionable, followed by a compact list of return fields, then plan/delay notes, then parameter details. Every sentence provides necessary information without fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has only two optional parameters, an output schema, and strong annotations, the description covers all essential aspects: what it returns, usage priority, data freshness caveats, and parameter formats. It explains the 'either code or date' constraint. Nothing critical is missing for an effective invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description carries the full burden. It does an excellent job: code is explained with format (5 digits), an example (27800), and a nuance (4-digit codes match ordinary shares only). Date is explained with accepted formats (YYYYMMDD or YYYY-MM-DD) and the meaning of the parameter. This goes far beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Use this first for any financial metric query' and immediately specifies the exact output: 'quarterly financials: revenue, operating profit, net income, EPS/BPS/CF, dividends, and earnings forecasts.' This clearly states the verb (returns), resource (quarterly financials), and scope, distinguishing it from siblings like get_fins_details or get_fins_dividend by positioning it as the entry point for financial metrics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives an explicit usage instruction ('Use this first for any financial metric query') and lists concrete examples (EPS, BPS, 売上, 利益, 配当, 業績予想). It also mentions supported plans and the free-plan delay. However, it does not explicitly name alternatives or state when not to use this tool, so it stops short of the highest tier.
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 convey read-only, idempotent, and non-destructive behavior. The description adds valuable context by noting 'Standard+ only' and '[Supported plans] Standard / Premium', which is a plan restriction not present in annotations. It also clarifies the data scope (per-stock restriction status). This goes beyond annotation-only disclosure, though it doesn't describe every behavioral nuance (e.g., rate limits, pagination).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-organized: a one-line summary, a usage line with relevant keywords, an explicit alternative, a plan note, and a clear argument list. Every sentence adds value without redundancy. The structure makes it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (4 optional params, no nested objects) and the presence of an output schema, the description covers purpose, usage boundaries, plan requirements, and parameter formats. Minor gaps remain about parameter combinations and return value specifics, but the output schema handles return details. Overall, it is sufficient for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description compensates by covering all four parameters: code format ('5 digits, e.g. 27800'), date format ('YYYYMMDD or YYYY-MM-DD'), and the semantics of date_from/date_to as 'range query'. It would benefit from explaining how parameters interact (e.g., whether date vs. date range are mutually exclusive), but it provides substantial meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Per-stock margin trading restriction status: 増担保規制・信用規制.' It clearly indicates what data is returned and explicitly distinguishes itself from a related sibling tool by stating 'For margin balances... use get_markets_margin_interest instead.' This fully differentiates it from other tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use context ('Use for 追証, 規制銘柄, 増担保規制, 信用規制, margin restriction/alert') and names an alternative tool for a different use case ('For margin balances... use get_markets_margin_interest instead'). This leaves no ambiguity about which tool to select for margin alert versus balance queries.
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 declare readOnly, idempotent, non-destructive, and openWorld. The description adds valuable context beyond that: 'Positions disclosed weekly per institution' (data cadence) and 'Standard+ only' (plan restriction). No contradictions. Minor gap: it doesn't mention pagination or response structure, but that's covered by output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: opening purpose, usage guidance, plan note, and organized argument list. It's slightly verbose due to the args duplication (though necessary given schema coverage) and a minor redundancy in mentioning 'Standard+ only' twice. Overall it earns its length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 optional params, no required) and presence of an output schema, the description covers purpose, usage, alternatives, parameter formats, and plan restrictions. It doesn't clarify which parameter combinations are valid (e.g., range vs single date), but for a read-only look-up tool this is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has zero descriptions for its 5 parameters, but the description fully compensates by documenting each arg with format and example (e.g., 'code: Stock code (5 digits, e.g. 27800)', 'disc_date: Disclosure date (YYYYMMDD or YYYY-MM-DD)'). This provides the semantic meaning the schema lacks.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool provides 'Per-stock institutional short sale positions (大量空売り残高)' with a specific verb and resource. It explicitly differentiates from the sibling tool 'get_markets_short_ratio' (sector-level short ratios), making its unique purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit use cases ('Use for 大量空売り残高, 空売り残, institutional short positions, short squeeze screening'), names an alternative ('For sector-level short ratios... use get_markets_short_ratio instead'), and even suggests a pairing ('Pair with get_equities_earnings_calendar...'). This is exemplary guidance for tool selection.
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 declare readOnlyHint=true and idempotentHint=true. The description supplements this by explaining the split-adjusted price calculation, the formula, and the inclusion of previous_date in the return object. No contradictions and useful extra behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concisely structured with a purpose statement, formula, Args list, and Returns list. Every sentence adds essential information without redundancy or verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only market data tool, the description covers input parameters, output keys, data types, and calculation logic. The return format is fully specified, and the context provided by annotations and sibling tool names further enriches the completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully documents all three parameters: date format (YYYY-MM-DD or YYYYMMDD), direction values ('up'/'down' with default), and n range (1-100 with default). It exactly compensates for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns top stocks by percentage price change on a given trading date, with a specific verb and resource. This distinguishes it from related tools like get_top_volume and get_top_turnover_value.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool (when needing top gainers/losers by percentage change) but does not explicitly mention alternatives or when-not-to-use. This is sufficient for an agent to infer usage among siblings.
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 beyond annotations by disclosing the operational consequence (subsequent tool calls fail) and the recovery path (register a new key). It also specifies the OAuth 2.1 authentication requirement, which is not present in the annotations, adding meaningful behavioral context without contradicting the destructiveHint and idempotentHint flags.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, deliberately structured to lead with the core action, then the consequence, then the authentication requirement. Every sentence adds necessary information without redundancy, making it exceptionally efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, clear destructive action, existing output schema), the description fully covers the purpose, consequences, auth requirements, and relationship to sibling tools. It is complete and self-contained for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters in the schema, there are no parameter semantics to explain. The description appropriately focuses on the tool's action and effects, and the baseline score for 0-parameter tools is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool deletes the user's registered J-Quants API key in multi-user mode, using the specific verb 'delete' and naming the exact resource. It distinctly contrasts with sibling tools like register_api_key, leaving no ambiguity about its function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for use: it removes the API key, and explicitly notes that subsequent tool calls will fail until a new key is registered with register_api_key. This references the alternative tool and establishes a usage sequence, though it does not explicitly state 'when not to use' scenarios.
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 declare readOnly, idempotent, non-destructive. The description adds meaningful context: it is cache-only with no API call, and data arrives ~17:15 JST. This enriches behavioral understanding beyond the structured hints, though it doesn't discuss failure modes or edge cases like missing data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is somewhat long but well-structured: purpose, use case, data availability, supported plans, and args. Every section serves a purpose, though the 'All plans' line is redundant with the subsequent '[Supported plans]' line. Still, it's efficiently organized and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is moderately complex, but the description covers the detection logic, parameter formats, defaults, data timing, and plan restrictions. An output schema exists, so return values need no explanation. This description is complete enough for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description carries full responsibility for explaining parameters. It does so thoroughly: rally_start is described as 'the low/reversal day' with accepted formats, date defaults to latest cached, and sigma_multiplier threshold with default 2.0. This fully compensates for the empty schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Check whether a follow-through day confirms a new uptrend.' It specifies the IBD method and the exact condition (TOPIX z-score ≥ +sigma on session 4+ from rally_start). This distinguishes it from sibling tools, and it even references detect_distribution_days as a related alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'Use when asking if a rally attempt is confirmed (IBD method).' It provides concrete criteria (session 4+, higher market turnover) and points to an alternative tool. It also notes the data availability time, which helps set expectations for usage.
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 declare readOnly, openWorld, idempotent, and non-destructive, so the description doesn't need to repeat these. It adds useful context about return fields (OHLC, volume, open interest, implied volatility) and the Premium plan restriction. No contradiction with annotations, but rate limits or pagination are not disclosed; still, annotations cover the main safety profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear Args section, but the 'Use for' list introduces some redundancy (e.g., repeating IV and implied volatility, and 'Premium only' appears twice). Despite minor repetition, every section serves a purpose and the description remains reasonably concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema, the description correctly omits detailed return formatting. It covers purpose, usage, parameters, returns, plan restriction, and a sibling alternative, making it complete for the tool's moderate complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description explains all four parameters in detail: date format and requiredness, category with concrete examples and omit-all instruction, code as issue code, and contract flag with value meanings. This fully compensates for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns daily options OHLC bars with IV, and explicitly names the sibling tool for Nikkei 225 options only, providing strong differentiation. The verb 'Returns' and resource 'options OHLC bars' are specific and 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage guidance with a list of supported contexts (e.g., オプション, 日経オプション, TOPIXオプション, IV) and directly points to get_derivatives_bars_daily_options_225 for Nikkei 225 options only. Also notes the Premium plan requirement and category omission behavior.
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 (readOnly, idempotent), the description discloses fallback behavior (live fetch on cache miss), date-window defaults, plan-specific coverage differences, and internal dependencies (daily_fetch sweeps). This adds substantial context for the agent about how the tool behaves in various scenarios.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured with clear sections and bullet points. It front-loads the purpose and use cases, then dives into technical details. While some internal references (e.g., jquants-mcp#621) are niche, they don't detract significantly from clarity. It could be slightly tightened, but every part adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (plan differences, fallbacks, multiple query modes) and the presence of an output schema, the description covers all necessary context: parameter semantics, plan limitations, default behavior, and edge cases (cache misses). It is complete for an agent to decide when and how to use it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description fully compensates by explaining the date format (YYYYMMDD or YYYY-MM-DD), code format (5 digits, trailing 0 padding), and the behavior when omitted (latest data for date, accumulated search for code). This is essential for correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool finds upcoming/past earnings announcement dates (決算発表日) and provides a list of query phrases, but it does not explicitly differentiate it from sibling tools like get_earnings_this_week or get_earnings_results_this_week, relying on the name and usage examples to distinguish.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage guidance: lists query phrases (決算発表, earnings calendar, etc.), pairs with get_markets_short_sale_report for specific screening, and explains plan-dependent behavior (Free vs Light+). This goes beyond a simple when-to-use by offering context and 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?
Adds significant behavioral context beyond annotations: default summary mode vs full data with detail=True, and that any filter parameter triggers full data. Annotations already declare read-only/idempotent, so the bar is lower; this description adds useful return-shape behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with purpose line, usage guidance, behavior explanation, supported plans, and args list. Slightly dense but every sentence is informative; the length is justified by the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only data tool with five optional parameters and an output schema, the description covers plan prerequisites, default vs detailed output, parameter formats, and the relevant sibling alternative. No significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description fully documents each parameter in Args: code (5-digit example), date formats, date_from/to, and detailed effect of detail flag. This entirely compensates for the schema gap.
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?
Clearly identifies the tool as returning per-stock margin balance (買残・売残・貸借倍率) with a specific resource. Distinguishes from sibling get_markets_margin_alert by stating that tool is for margin trading restrictions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'Use for 信用残...' and provides alternative: 'For margin trading restrictions, use get_markets_margin_alert instead.' Also mentions 'Standard+ only' plan requirement.
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 already declare read-only, non-destructive, idempotent behavior. The description adds substantial context: cache-only with no API call, supported plans, margin_ratio null unless Standard/Premium cache is populated, and detailed PER/PBR/ROE exclusion rules. This goes far beyond 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured into clear sections (purpose, usage, plan support, args) and every sentence carries relevant info. It is slightly dense but not wasteful; no filler. A 4 is appropriate as it is informative without being bloated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with an output schema, the description covers plan limitations, data nullability, filtering rules, and sibling references. It gives the agent complete enough context to decide when and how to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides no description for sector_type (0% coverage), but the description compensates fully by explaining the two possible values ('s33' default, 33 TSE sub-sectors; 's17' 17 top-level sectors). This gives the agent all necessary parameter context.
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?
Begins with a specific verb and resource: 'Return sector-level median PER, PBR, ROE, and margin ratio', which clearly states the tool's function. It distinguishes itself from siblings by explicitly naming get_market_briefing (market-wide), get_stock_briefing (single stock), and get_sector_performance (騰落率), making the purpose unmistakable.
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?
Provides explicit use cases ('Use for セクターバリュエーション・業種別PER/PBR・割安セクター・業種別信用倍率 queries') and lists alternative tools with their scopes. However, it lacks an explicit 'when-not' statement, though the context and alternatives clearly guide selection.
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 read-only, idempotent, non-destructive behavior. The description adds valuable context: results are null when not warmed up, supported plans include Free/Light/Standard/Premium, API fallback on cache miss, and the specific bb20 ±2σ convention. This goes beyond what the annotations alone 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized into sections (usage, alternatives, supported indicators, plans, arguments) and is front-loaded with a clear summary. Slight redundancy exists ('All plans' repeated in the first line and later in [Supported plans]), but it remains efficient and scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for a 5-parameter tool: it covers purpose, when to use, alternatives, parameter semantics, plan limitations, and edge-case behavior (null when not warmed up). An output schema exists, so returning detailed return values is not required, and the description still provides enough context for reliable invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description thoroughly explains every parameter: code is required, date overrides date_from/date_to, date formats are specified, range boundaries are inclusive, and indicators has a documented default list. This fully compensates for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool's action ('Compute technical indicators') and its target resource ('a single stock'), naming specific indicators (SMA, Bollinger Bands, RSI). It also differentiates from siblings by directing charting queries to get_candlestick_data and VWAP pressure to compare_close_vs_vwap.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use the tool ('Use for SMA・移動平均・ボリンジャーバンド・RSI queries on a specific stock') and names alternative tools for other use cases. It also clarifies supported plans and API fallback behavior, giving clear context for selection.
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 declare readOnlyHint=true and idempotentHint=true, so the description doesn't need to re-state safety. It adds valuable context beyond annotations: 'cache-only, no API call' and supported plans (Free/Light/Standard/Premium), plus the ranking basis being price×volume. This is helpful behavioral information 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded, with the primary purpose in the first sentence, then usage guidance, ranking clarification, and arg details. Slight redundancy exists: 'All plans' and then '[Supported plans] Free / Light / Standard / Premium' repeat the same information. Minor, but keeps it from a perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (2 params, output schema exists), and the description covers everything needed: what it returns, how it ranks, when to use it, parameter formats, and plan limitations. Combined with annotations (read-only, idempotent) and an output schema, the description is fully adequate for the agent to select and invoke this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must fully explain parameters. It does this well: date format is specified as 'YYYY-MM-DD or YYYYMMDD', and n is documented with range and default ('1–100, Default 10'). This adds meaning the schema lacks.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Return top stocks by turnover value on a given date.' It clearly distinguishes itself from the sibling tool get_top_volume by stating 'Ranks by price×volume (get_top_volume ranks by share count instead).' This makes the tool's unique purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage direction: 'Use for 売買代金ランキング・売買代金・turnover・trading value queries.' It also names the alternative tool for a different metric (get_top_volume for share count), giving clear when-to-use and 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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes far beyond annotations by disclosing a security warning (plaintext transmission), encryption at rest, plan auto-detection, and prerequisites (OAuth 2.1, MCP_ENCRYPTION_KEY). It also notes that calling again updates the key (idempotent) and that rate limits and date-range restrictions are applied. This adds significant behavioral context beyond the annotations without any 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but structured: purpose, security warning, behavior, requirements, and parameter definition. Each section adds necessary detail, and the most important information (purpose and security) is front-loaded. It could be slightly more concise, but the complexity justifies the length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers all essential context: purpose, side effects (storage, plan detection), prerequisites (OAuth, encryption), and behavioral consequences (affected rate limits). The output schema is present, so return values need no description. For a setup tool with security implications, this is comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains that api_key is 'Your J-Quants API key (refresh token from the J-Quants portal)', providing essential semantics beyond the schema's minimal title 'Api Key'. It clarifies what the parameter is and where to obtain it, fully covering the only parameter despite schema coverage of 0%.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Register or update your J-Quants API key'. This is a specific verb+resource combination, and it distinguishes from siblings like delete_api_key. The multi-user mode and OAuth association add context, making the tool's role unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that this tool is required for subsequent tool calls to work ('Subsequent tool calls will automatically use this key'), which implies when to use it. However, it does not explicitly mention alternatives or when not to use it, though the sibling delete_api_key exists. The context is clear, but explicit exclusions are missing.
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 annotations (readOnlyHint, idempotentHint), the description discloses that it reads from a local cache with no API call, and that it returns an empty list when the cache is unpopulated. These are valuable behavioral details not captured by annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a clear purpose and usage guidance, but contains minor redundancy — the 'no API call' detail is repeated in the prose and again in the [Source] line. Still, it remains compact and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter search tool, the description covers the purpose, use case, matching behavior, source, and edge case (empty cache). The output schema exists, so no need to spell out return shape here. It is complete for an agent to select and invoke.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description's Args section fully compensates by explaining the 'name' parameter — partial/full matching, case-insensitivity, and examples in Japanese and English. This adds meaning beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches for listed stocks by company name, using a reverse lookup (company name to code). It provides concrete examples and distinguishes this from sibling tools that retrieve market data, making its 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use when the user knows a company name but not the stock code' with illustrative queries. It doesn't explicitly name alternatives or when-not-to-use, but the instruction is clear enough to guide selection.
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 already declare readOnlyHint, idempotentHint, and non-destructive behavior, and the description adds valuable context: cache-only execution with no API call, supported plan availability, data timing, and the 52-week constraint on date_from. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear opening, usage guidance, and an Args block. Minor redundancy exists, such as stating 'All plans' in the first line and then listing supported plans again, and repeating the 52-week constraint in the description and parameter detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With strong annotations and an output schema present, the description covers the essential operational aspects: core behavior, parameter semantics, data availability, and plan support. It omits no critical details for using the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 6 parameters are described, with date formats, inclusivity, and constraints clearly stated, and detail/code behaviors explained. However, window_sessions and min_prior_sessions defer to another tool ('See detect_52w_high_low') rather than fully self-contained definitions, which is a minor gap given 0% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence clearly states the tool scans 52-week high/low breakouts across a date range, which is a specific verb+resource+scope. It distinguishes itself from the sibling detect_52w_high_low by explicitly referencing it for multi-day queries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly instructs to use this tool instead of repeated detect_52w_high_low calls for multi-day queries and warns against splitting into parallel range calls. It also provides data availability timing (~17:15 JST), giving clear when-to-use context.
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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, but the description goes further by disclosing key behaviors: lookahead-free backtesting via as_of_date, sorted output by consecutive_years descending, return field details, and cache-only operation with no API call. It also adds an investment caveat about performance guarantees, which is valuable context beyond 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with front-loaded purpose, explicit usage guidance, supported plans, and clearly separated Args/Returns sections. Each sentence adds useful information, and the minor redundancy of 'All plans' followed by the supported plans list does not detract from overall efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description still explains return fields and ordering, covers both parameters thoroughly, mentions supported plans and API behavior, and provides a realistic investment caveat. It is complete for an agent to decide when and how to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description's Args section fully compensates by explaining min_years as 'Minimum number of consecutive years of dividend increase' and as_of_date as a cut-off date with format examples and lookahead-free semantics. This adds substantial meaning beyond the raw schema properties.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Screen for stocks with consecutive annual dividend increases (連続増配).' This clearly distinguishes the tool from siblings like get_dividend_yield_ranking and other detect_* screeners by focusing on consecutive growth rather than yield or price patterns.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states use cases ('Use for 連続増配・dividend growth・増配継続 queries') and provides a caution about not relying on dividend growth alone, suggesting combining with yield/payout filters. It does not name alternative tools or state explicit when-not conditions, but the context is clear enough for an agent to select it appropriately.
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 (readOnly, idempotent, non-destructive), the description discloses caching behavior ('cache-only, no API call'), data availability time, and the cache-bypass effect when 'code' is set. These are significant behavioral traits that the annotations do not cover.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The structure is clear with sections for purpose, usage, plans, and arguments, and it is front-loaded. However, the 'date_from within 52 weeks' constraint appears twice (in the intro and in the Args), creating minor redundancy, and the reference to another tool for min_prior_sessions is a slight detour.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, alternatives, constraints, parameter semantics, caching, and availability. The only gap is the reliance on detect_ytd_high_low for min_prior_sessions, but the output schema likely handles return structure, so the core contextual needs are satisfied.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description fully compensates by documenting all five parameters: formats, inclusive ranges, defaults, and the special effect of 'code'. The Args section turns an otherwise opaque schema into a usable reference.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb ('Scan') and resource ('year-to-date high/low records') scoped to a date range, which clearly distinguishes it from the sibling detect_ytd_high_low (single date) and detect_52w_high_low_range (52-week range). The Japanese annotation further clarifies the concept.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly advises using this tool instead of repeated detect_ytd_high_low calls for multi-day queries and warns against splitting into parallel range calls. It also provides concrete constraints (date_from within past 52 weeks) and data availability timing (~17:15 JST), which are directly actionable.
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 declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds meaningful behavioral context: Premium plan restriction, the nuance that 4-digit codes match ordinary shares only, and that 'date' returns statements disclosed on that date. This goes beyond annotations, though it does not cover error conditions or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded: it starts with the primary use case, then the alternative, then return details, then parameter constraints. Every sentence serves a purpose, and the Args section is concise yet complete. No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (2 params with optional/nullable types, annotations, output schema), the description covers purpose, usage, parameters, plan restrictions, and GAAP/IFRS support. The output schema exists, so return format needs no description. It is complete for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description fully compensates with detailed Arg explanations: code format (5 digits, examples, 4-digit meaning), date format (YYYY-MM-DD) and semantics, plus the requirement that exactly one of them must be specified. This is essential and well done.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states clearly that the tool returns detailed financial statement line items (BS, PL, CF) and explicitly distinguishes it from the sibling tool get_fins_summary, noting when to use which. It uses a specific verb 'returns' with a clear resource and scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: 'Use only when individual BS/PL/CF line items are needed' and points to get_fins_summary for common metrics, including comparative advantages (faster/cached, available to all plans). It also states a precondition: 'Either code or date must be specified.'
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 declare readOnly, idempotent, and non-destructive. The description adds behavioral context: 'All plans' and 'cache-only, no API call', which informs the agent about data freshness and plan availability. While it doesn't detail return structure, the output schema covers that. This goes beyond 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-organized: purpose sentence, usage keywords, alternatives, plan info, then arg definitions. No wasted words; front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only data tool with 2 parameters, the description covers purpose, exact use cases, alternatives, plan restrictions, cache behavior, and parameter formats. Combined with annotations and output schema, it is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has only titles and defaults, with 0% coverage, so the description carries the full burden. It explains date format (YYYY-MM-DD or YYYYMMDD) and sector_type options ('s33' default, 's17') clearly, making both parameters fully understandable.
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?
States precisely: 'Sector-level average price change ranking' with Japanese equivalent, and distinguishes itself from get_sector_briefing (valuation) and get_market_briefing (full market briefing). The verb 'get' plus resource and the ranking nature are clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly lists use cases (業種別騰落率, セクター別パフォーマンス, etc.) and provides alternatives for different needs: 'For sector valuation (PER/PBR) use get_sector_briefing instead. For full market briefing use get_market_briefing instead.' This is exemplary 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?
Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses important runtime behaviors: null conditions for PER, ROE, and margin fields, plus cache-only execution and plan-level support. This rich context goes far beyond the annotations and clarifies edge cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a one-line purpose, then the return contents, edge-case details, supported plans, and argument explanation. Every sentence contributes necessary information without redundancy, making it both thorough and concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one parameter and an output schema (not shown), the description covers the main return fields, null semantics, plan restrictions, code rules, and related briefing tools. It provides enough context for an agent to select and invoke the tool correctly without requiring additional lookup.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides only the parameter name and type with no description, so schema coverage is 0%. The description compensates fully by explaining the code format: 'Stock code (5 digits, e.g. 27800; 4-digit codes match ordinary shares only).' This gives complete semantic meaning for the single parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'One-page briefing for a single stock: price, financials, valuation, and margin,' clearly identifying the resource (a stock) and the deliverable (briefing). It distinguishes the tool by scope and explicitly references related siblings get_sector_briefing and get_market_briefing, making its 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states it works for 'All plans' and provides input format rules (5-digit codes, 4-digit for ordinary shares), giving clear context for when to use it. However, it only says 'See also' without explicit when-not-to-use instructions or direct comparisons to alternatives, so it stops short of the highest bar.
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 cover read-only/idempotent/non-destructive. The description adds meaningful context: cache-only behavior, supported plans, exclusion of net-loss and negative-book stocks, and the disc_months stale-financial filter. Slightly held back from 5 because it doesn't mention potential output size limits or response format variants, but output schema exists to cover that.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized: it starts with purpose, then use cases, exclusions, alternatives, plan support, and a structured Args list. Every sentence adds value, and the structure makes it easy to scan. No redundant fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (8 optional params, many sibling tools), the description covers purpose, usage, alternatives, behavioral nuances, and parameter semantics. An output schema exists, so the lack of a return-value section is acceptable. The inclusion of plan restrictions and cache behavior adds operational completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description fully documents all 8 parameters with defaults, allowed values, and behavioral meaning (e.g., ascending order, min/max filters, market options, sector codes, disclosure-age cutoff). This completely compensates for the schema's lack of parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool ranks listed stocks by PER or PBR valuation multiple, with specific examples of intended use cases and metrics. It also distinguishes itself by naming alternative tools for related but distinct purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance on when to use this tool (for 割安株, PER/PBR ranking, screening) and when not to use it (use get_sector_briefing for sector medians, get_stock_briefing for single stocks, get_dividend_yield_ranking for dividend yield). This is exactly the kind of direct alternative mapping the dimension asks for.
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 already indicate read-only and idempotent, but the description adds valuable context beyond that: the multi-user mode nuance (returns authenticated user's plan), the fact that it performs a multi-GB row-count scan, and the explicit offload to a worker thread to avoid blocking the event loop. These are meaningful behavioral disclosures not present in annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured: the first sentence states the core purpose, followed by exclusion/alternative guidance, then a context nuance, and finally an implementation detail. Each sentence earns its place without redundancy. While longer than average, it is front-loaded and every sentence adds unique value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters, an output schema, and rich sibling context, the description is complete. It covers return content (metadata), exclusions, alternative tools, multi-user behavior, and performance characteristics. No important context is missing for an agent to select and invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there is no parameter semantics to explain. Per the rubric, 0 params baseline is 4. The description doesn't need to add parameter meaning, and it correctly focuses on what the tool returns and how it behaves.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Show database metadata: table row counts, file size, and detected plan.' It clearly distinguishes itself from sibling detection tools by explicitly stating it does NOT query screener signals and lists alternative tools for that purpose. This is a model of purpose clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use context (cache metadata) and when-not-to-use context ('Do not call this tool to look up market data or screener results'). It names specific sibling tools for alternative detection tasks (detect_52w_high_low, detect_ytd_high_low, etc.), fulfilling the alternatives requirement perfectly.
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 already declare readOnly, idempotent, and non-destructive, but the description adds meaningful behavioral details: default params hit a nightly pre-computed cache (sub-second) versus custom params computing on-demand (10-30s), data available ~17:15 JST, and plan restrictions. This goes well beyond the annotation signal and sets proper expectations for performance and availability.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections for use cases, performance, plans, and arguments, and every section earns its place. Minor redundancy exists (e.g., 'All plans' and '[Supported plans]' repeat plan info, and date constraint appears both in prose and in Args), but overall it remains readable and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 parameters, output schema present, clear annotations), the description covers the core function, alternatives, performance trade-offs, data timing, plan support, and parameter semantics. The output schema covers return values, so the description's focus on invocation and behavior makes it complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description fully compensates by explaining each argument: date format and constraint, optional code, window_sessions meaning and default, min_prior_sessions behavior and default, and detail's summary-vs-full toggle. Every parameter is given semantic meaning beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific action and resource: 'Screen for 52-week rolling high/low breakouts', supported by Japanese equivalents for clarity. It explicitly distinguishes itself from sibling tools by naming detect_52w_high_low_range for multi-date scans and detect_ytd_high_low for YTD scans, leaving no ambiguity about its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is highly explicit: the description states when to use this tool ('Use for 52週高値, 52週安値...'), when to use alternatives ('For multi-date scans use detect_52w_high_low_range', 'For YTD high/low use detect_ytd_high_low'), and adds constraints like date range and data availability. This fully guides selection among siblings.
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?
Despite strong annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds substantial context: data available ~17:15 JST, cache-only (no API call), supported plans, and the behavioral nuance that when a code is provided the row is always returned even if no limit hit. This goes well beyond 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized into clear sections (purpose, usage, alternatives, timing, plans, args) and front-loaded with the main action. It is slightly longer than strictly necessary due to the plan list and detailed param explanations, but every sentence contributes value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, return values need not be detailed. The description covers usage, exclusions, timing, plan availability, cache behavior, and parameter semantics, making it complete for successful invocation. The only minor omission is a direct statement about the output schema, but it's not required.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description fully compensates by explaining each parameter: date format (YYYYMMDD or YYYY-MM-DD), code's optional behavior and the consequence of omitting vs specifying it, and detail's purpose (include full per-stock data array). This adds meaning the schema alone lacks.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Find stocks that hit the daily price limit (ストップ高/安) on a trading day.' It clearly distinguishes this tool from siblings by explicitly naming detect_volume_surge and compare_close_vs_vwap as alternatives for different queries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use guidance: 'Use for ストップ高・ストップ安・値幅制限 queries.' It also names alternatives for other scenarios ('For volume spikes use detect_volume_surge; for VWAP pressure use compare_close_vs_vwap'), making the choice between tools 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?
Beyond the readOnly/idempotent annotations, the description discloses substantial behavioral context: it compares today against every session since the first trading day of the calendar year, matches Kabutan/Yahoo! conventions, uses a nightly pre-computed cache for default params (sub-second), requires date within the past 52 weeks, and notes data availability at ~17:15 JST. This fully informs the agent of performance and data freshness characteristics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded, but it contains slight redundancy: 'All plans.' appears both in the first sentence and again in the '[Supported plans]' line. Otherwise, every sentence earns its place, and the Args section is clear. A minor deduplication would make it perfect.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given an output schema is present, the description does not need to document return fields. It covers purpose, usage boundaries, behavior, supported plans, and all parameters with semantics and defaults. It also explains the historical comparison convention and cache behavior. No critical information is missing for correct tool selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides only types and defaults (0% description coverage). The description's Args section fully compensates by explaining each parameter: date format and range, code's optionality and cross-sectional behavior, min_prior_sessions meaning including the disable value (1), and detail's effect on output (summary counts vs full array). This is exemplary parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb-resource pair: 'Screen for year-to-date high/low records.' It also provides Japanese equivalents (年初来高値/安値) and explicitly differentiates from sibling tools by naming detect_ytd_high_low_range and detect_52w_high_low, making the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage guidance: 'Use for 年初来高値, 年初来安値, YTD high/low, 年初来高値更新.' It also states when NOT to use it: 'For multi-date scans use detect_ytd_high_low_range (not repeated calls here). For 52-week rolling window use detect_52w_high_low instead.' This is a model of clear when/when-not 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 adds rich behavioral context beyond annotations: offloaded to a worker thread due to SDK event-loop behavior, potential 10-60s first-call delay from lazy cache initialization, no error state, meaning of status/cache_integrity/cache_ready values, and multi-user plan behavior. This far exceeds the read-only/idempotent annotation hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Although lengthy, the description is densely informative and well-structured. It opens with a concise one-sentence purpose, then adds essential technical rationale (thread offload, SDK behavior, issue #537), usage timing, and detailed return-value semantics. Every sentence earns its place and no filler exists.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity, non-existent parameters, and rich output schema, the description fully covers all relevant context: what it returns, how to interpret status fields, behavior under multi-user mode, and latency expectations. It leaves no significant gaps for an agent to invoke or interpret results correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema properties object is empty, so there is no parameter semantics to add. Per the baseline for 0 parameters, a score of 4 is appropriate; the description cannot add meaning beyond what the schema provides because there is nothing to explain.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool checks server health, API key configuration, and cache readiness. It distinguishes itself from sibling cache_status by explaining it confirms cache.db has finished loading and also reports server version, API key status, active plan, and integrity details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is given: call at session start before detect_* or cache_status, and use after a tool-call timeout to distinguish transient cache-loading delay from permanent failure. This effectively differentiates when to use health_check versus cache_status or other tools.
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 declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds valuable behavioral context beyond these: the formula VWAP=Va/Vo (None when Vo=0), the interpretation of close vs VWAP, data availability timing, and cache-only behavior (no API call). This extra context significantly helps the agent understand what the tool does and its data nuances. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized and front-loaded, starting with the primary purpose. It then provides usage guidance, formula, data timing, plan support, and an argument list. Every sentence adds unique value, and the structure makes it easy to scan. Despite having several sections, it remains appropriately concise without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-stock VWAP comparison tool, the description covers purpose, scope, usage, interpretation, formula, data timing, supported plans, cache behavior, and all parameters. An output schema is indicated as present, so the description need not explain return values. The context is complete for an agent to correctly select and invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the full burden. It thoroughly explains every parameter: 'code' as required stock code, 'date' as a single date that overrides the range, and 'date_from'/'date_to' as an inclusive range. It also provides accepted date formats (YYYYMMDD or YYYY-MM-DD). This fully compensates for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb ('Compare'), resource ('a stock's close to its daily VWAP'), and scope ('for one code'). It explicitly distinguishes from cross-sectional screeners, making it easy to differentiate from siblings. The additional explanation of buying/selling pressure reinforces the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage context: 'Use for VWAP・買い圧力・売り圧力 queries on a specific stock; not a cross-sectional screener.' It clearly states when to use and when not to, and also includes data availability timing (~17:15 JST on trading days). No alternative tool is named, but the 'when-not' clause is sufficient for effective selection.
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 already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds substantial context beyond annotations: cache-only behavior, no API call, supported plans, and the IBD interpretation of the count. This provides clear expectations for how the tool executes and what the result means.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear opening, usage context, supported plans, and a labeled Args block. Every section adds value, and the content is appropriately sized for the tool's complexity. The slight redundancy of 'All plans' is minor and does not detract from the overall efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity and the presence of an output schema, the description covers all necessary aspects: purpose, when to use, parameter semantics, plan restrictions, and relationship to a sibling tool. The agent has enough context to select and invoke the tool correctly without needing further documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, but the description's Args section fully explains each parameter: date format and default, sigma_multiplier as z-score threshold, window_sessions as rolling window with IBD convention, and min_dist_days as the warning threshold. This directly compensates for the schema's lack of descriptions and adds domain meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Count') with a precise resource ('TOPIX distribution days') and explicitly identifies the IBD method. It distinguishes itself from sibling tools by referencing 'detect_follow_through_day' and explaining its role in confirming follow-through days.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use this tool (for distribution day/institutional selling queries), provides a concrete rule (≥4 days in 25 sessions = failing uptrend), and directs the agent to check it before confirming a follow-through day. It also references an alternative tool, making the guidance 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?
Beyond the readOnlyHint/idempotentHint annotations, the description discloses the detection formula (surge_ratio = Vo / mean(prior baseline_days)), the cache-only behavior with 'no API call', and data availability ('~17:15 JST on trading days'). It also explains that 'detail' controls the return of the full per-stock data array, adding valuable behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and concise: it opens with the core purpose, then usage guidance, formula, sibling alternatives, data availability, plan support, and a clear Args list. Every sentence adds value without unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a screening tool with five parameters and no sibling ambiguity, the description covers purpose, usage, parameter semantics, data timing, plan support, and cache behavior. Since an output schema exists, not detailing return structures is acceptable. The description is sufficiently complete for correct selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the schema has 0% description coverage, the description's Args section thoroughly explains every parameter: date format, multiplier threshold, baseline_days meaning, code optionality, and detail flag behavior. This fully compensates for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Identify stocks with abnormally high trading volume (出来高急増) on a given day.' It also provides Japanese synonyms and distinct criteria (surge_ratio), and explicitly differentiates from sibling tools like detect_52w/ytd_high_low and detect_price_limit, 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'Use for 出来高急増・出来高異常・売買活況・volume spike queries.' It also gives clear alternatives: 'For price extremes use detect_52w/ytd_high_low; for price limits use detect_price_limit.' Additionally, it notes data availability timing, which informs usage context.
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 read-only and idempotent annotations, the description adds important context: cache-only (no API call), supported plans, and the overbought/oversold thresholds (>120, <70) that guide interpretation. This provides substantial behavioral and interpretive value beyond the structured annotation data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with clear sections: purpose, usage context, thresholds, alternatives, supported plans, and parameters. Every sentence serves a purpose, and the information is front-loaded with the essential purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the annotations, and the presence of an output schema, the description covers all necessary aspects: purpose, when to use, parameter semantics, and plan restrictions. Nothing else is needed for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, but the description fully compensates by listing both parameters: date (End date, format YYYY-MM-DD or YYYYMMDD) and period (trailing trading days, default 25). This gives complete meaning beyond the schema's minimal type definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns the advance/decline ratio (騰落レシオ) over the last period trading days, with a specific verb and resource. It also distinguishes from siblings by explicitly directing daily counts to detect_price_change and sector breakdowns to get_sector_performance.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when-to-use guidance is provided: 'Use for 騰落レシオ・市場過熱感 queries.' It also names alternatives with clear distinctions, and notes supported plans and cache-only behavior.
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 already declare readOnly, idempotent, and non-destructive hints. The description adds valuable context about the signed URL's expiration and the dependency on a prior get_bulk_list call, enhancing behavioral understanding beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Compact and well-organized: summary, usage, plans, and args. Every sentence is actionable and non-redundant, with critical details front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with an output schema, the description covers prerequisites, timing, and invocation, leaving no critical gaps for an agent to select or call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, but the description fully defines the 'key' parameter as 'File key obtained from get_bulk_list', adding provenance and type context that the schema lacks.
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 'get a signed URL for a specific file' and identifies itself as 'Step 2 of bulk CSV download', distinguishing it from sibling get_bulk_list and other get_* tools with a specific verb and resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs 'Use after get_bulk_list; pass the Key returned there', providing sequencing and parameter source. Also notes time-sensitive behavior ('URL expires in approximately 5 minutes'), guiding immediate use.
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 already indicate read-only and idempotent behavior; the description adds valuable context such as 'cache-only, no API call', the return format (parallel arrays for Plotly/Recharts), detailed return keys including lock_days and earnings_dates, and the error response format. This goes well beyond the structured annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Although the description is lengthy, it is well-structured with clear sections (Args, Returns) and every sentence adds value. The parameter details and return schema are necessary given the tool's complexity, and the formatting enhances scannability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and 5 parameters, the description provides a complete picture: all parameters, return structure, error handling, plan coverage, and cache behavior. There is no missing critical information for correct invocation and interpretation of results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% coverage, so the description fully compensates by explaining every parameter: code with examples, from_date/to_date formats and defaults, indicators default and options list, and adjusted default. All 5 parameters receive clear semantic meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Return candlestick OHLCV + indicator data as JSON' with a specific verb and resource, and further specifies use cases (ローソク足・株価チャート・React artifact queries). It distinguishes itself from sibling tools by explicitly directing multi-stock comparison users to get_comparison_chart_data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit usage guidance is provided: 'Use for ローソク足・株価チャート・React artifact チャート queries (JSON format)' and 'For multi-stock comparison use sibling get_comparison_chart_data.' It also states plan support and cache-only behavior, helping the agent decide 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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context beyond annotations: cache-only behavior ('cache-only, no API call'), plan support, and the exact return format including error shape. This enriches the agent's understanding of performance and side-effect profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with clear sections for purpose, use cases, plan support, arguments, and return values. Every sentence adds meaningful information—no filler. The structure is front-loaded with the core purpose and use cases, then detailed parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema, the description fully specifies the return dictionary keys, the shape of records (Recharts-ready), series_keys, and error format. It covers all necessary context: when to use, parameter details, data shape, and behavioral notes (cache-only). Nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so complete burden falls on the description. It fully explains each parameter: codes (1-10, with examples), date formats and inclusivity, mode options with default and meaning, and labels as optional custom legend. This exceeds what the schema alone provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Return time-series data') with a clear resource ('multi-stock comparison') and scope ('up to 10 codes'), instantly distinguishing it from the sibling candlestick tool. The Japanese labels reinforce the exact purpose, leaving no ambiguity about what this tool 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'Use for 比較チャート・パフォーマンス比較・リターン比較・relative performance queries', and provides an explicit alternative: 'For ローソク足・candlestick charts use sibling get_candlestick_data (returns JSON)'. This is a model example of usage 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?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, but the description adds significant behavioral context: the dividend priority order (NxFDivAnn > FDivAnn > DivAnn), the Kabutan-equivalent default behavior, the effect of include_trailing, and the cache-only/no-API-call plan note. This goes well beyond the structured annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections and bullet-like argument definitions. Every sentence adds value: purpose, usage, behavior, plan support, and parameters. Despite its length, it remains focused and scannable, earning each line.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 8 parameters, no required fields, and an existing output schema, the description covers all necessary aspects: purpose, usage, behavioral nuances, parameter details, and supported plans. It provides complete context for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must provide parameter meaning. It does so thoroughly: each parameter is listed with its purpose, default, and allowed values (e.g., n: 1–100, market enum, date format). This fully compensates for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'High dividend yield stock ranking (高配当利回りランキング)'. It specifies the resource (stocks) and the action (get ranking), and differentiates from siblings by pointing to get_stock_briefing for single-stock yield. The purpose is unambiguous and specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit usage guidance is provided: 'Use for 高配当, 配当利回り, dividend yield ranking, 高利回り銘柄.' and 'For single-stock yield see get_stock_briefing instead.' This gives clear when-to-use and an explicit alternative, exceeding the minimum requirement.
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 (readOnlyHint, idempotentHint, destructiveHint false), the description adds meaningful behavioral details: results are 'disclosed in the past', each filing carries 'headline P&L' and other specifics, it is 'cache-only, no API call', and Free plan results are 'delayed 12 weeks, so the recent window is empty for Free.' This enriches the safety and data-freshness profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured into clear logical segments: purpose, usage examples, alternative tools, supported plans, and argument definitions. Every sentence contributes critical information without fluff, making it both compact and highly informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (2 optional params, output schema present), the description is complete. It covers purpose, usage, plans, edge cases (Free delay), defaults, and alternatives, leaving no significant gaps for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides no parameter descriptions (coverage 0%), but the description compensates with an 'Args' section that explains date_from and date_to, including inclusive window, accepted formats (YYYYMMDD or YYYY-MM-DD), and defaults. This fully covers the parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Earnings results actually disclosed in a date window, grouped by day', which is a specific verb+resource+scope. It also distinguishes from siblings by explicitly naming get_earnings_this_week for upcoming schedules and get_fins_summary for one stock's full financials.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage contexts: 'Use for 今週発表された決算, 直近の決算結果...' and directly states alternatives: 'For the upcoming SCHEDULE use get_earnings_this_week; for one stock's full financials use get_fins_summary.' This is clear when-to-use and 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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly=true, openWorld=true, idempotent=true, and destructive=false. The description adds valuable context beyond that: cache-first behavior with a fallback to live fetch under specific conditions (#523), enrichment with company name and 33-sector data, and supported plans. This is exactly the kind of behavioral clarification that helps an agent predict side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized into clear sections: purpose, use cases, defaults, enrichment, alternative, plan/cache note, and args. It is front-loaded with the core function, and every sentence earns its place without redundancy. The length is appropriate for the amount of behavioral detail provided.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists, the description does not need to explain return values. It covers essential contextual aspects: supported plans, caching fallback behavior, data enrichment, and parameter defaults. The tool is simple (2 optional params, read-only, list-style), and the description leaves no critical gaps for invocation or interpretation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description fully compensates with an explicit Args section. It details both parameters with inclusive bounds, accepted formats (YYYYMMDD or YYYY-MM-DD), and defaults (today for date_from, date_from+7d for date_to). This is far more informative than the bare schema, which only shows string/null types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb-resource phrase: 'Companies reporting earnings in a date window, grouped by day', and the Japanese '今週の決算予定' clarifies the weekly scope. It distinguishes from sibling get_equities_earnings_calendar by explicitly noting that tool is for a single stock's next earnings date.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It lists concrete use cases in both Japanese and English ('今週決算がある銘柄', 'earnings this week') and explicitly points to an alternative for single-stock queries: 'For a single stock's next earnings date use get_equities_earnings_calendar(code=...).' This gives clear when-to-use and when-to-use-otherwise 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?
Beyond the annotations (readOnly, idempotent, non-destructive), the description reveals important behavioral details: MktCap is null for ETF/ETN and non-trading days, ExRT encodes specific corporate action types, and data retention varies by plan. It also notes that date-only queries are slow and API fallback on cache miss, which are not conveyed by annotations alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense yet well-organized, with clear sections for overview, usage, data nuances, plan limitations, and argument definitions. Every sentence adds value—no filler—and the structure makes it easy to scan, despite the length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (4 optional parameters, multiple usage modes), the description covers all critical aspects: parameter combinations, special field behaviors (MktCap, ExRT), plan retention limits, performance warnings, and alternatives. The presence of an output schema means return format details are not needed, so the description is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description fully compensates by defining each parameter's format and semantics (e.g., code: 5-digit stock code, date: YYYYMMDD or YYYY-MM-DD). It also explains the interaction between parameters (code only → full history, code+range → period, date only → all stocks), which is crucial for correct usage and not derivable from the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as providing per-stock or per-day OHLC bars for equities, with a specific verb and resource. It also lists the exact query types it supports (株価, 日足, OHLC, etc.), making it distinct from sibling tools like get_equities_bars_minute or get_indices_bars_daily.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states what queries to use this tool for and points to an alternative for bulk downloads: 'For multi-stock bulk downloads use get_bulk_list'. It also explains parameter combination patterns (code only, code+range, date only), giving clear context on 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 annotations already declare safe operation (readOnlyHint=true, destructiveHint=false), so the description goes beyond by disclosing update and expiry times (updated around 12:00 JST; expires around 6:00 JST next day). This temporal behavior is not available through annotations or schema, adding genuine value. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized into clear sections: purpose, usage keywords, update/expiry schedule, alternative tool, supported plan, and args. Every sentence contributes unique information, and the most critical facts (what it does, when to use it) are front-loaded. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With only one optional parameter, an output schema present, and extensive annotations, the description covers all essential aspects: purpose, usage scenarios, schedule, alternative, plan restriction, and parameter semantics. It is complete for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, but the description fully compensates with a dedicated Args section. It explains the code parameter's format (5 digits), the special behavior for 4-digit codes (ordinary shares only), and the effect of omission (retrieve all stocks). This is more than sufficient for the single optional parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns 'Today's morning session OHLC bars' and includes Japanese equivalents, making the resource and verb explicit. It also distinguishes itself from the sibling tool get_equities_bars_daily by specifying that it is for current morning session data, not historical.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit usage contexts ('Use for 前場, 前場終値, 午前の株価, morning session OHLC, 前場引け') and names the alternative for historical data ('get_equities_bars_daily'). It also notes the premium plan requirement, which is a key access constraint.
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 already indicate read-only and idempotent, but the description adds valuable context: 'cache-only, no API call' and plan restrictions (e.g., sector_short_ratios requires Standard+). It also discloses null behavior when caches are absent, which goes beyond the safety profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Although lengthy, the description is highly structured with clear sections: purpose, usage, supports, returns, and args. Every sentence adds actionable information, and the essential purpose is front-loaded. No fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers all parameters, return fields, plan limitations, and null behavior. With an output schema present, it doesn't need to detail every field but still provides a useful summary. It also explains when to use the tool, making it complete for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must document parameters. It does this thoroughly: 'date' with format examples, 'sector_type' with allowed values and default, and 'n' with range and default. This fully compensates for the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose as a daily market briefing covering ADR, sector ranking, top movers, turnover, and screener highlights. It uses a specific verb-resource combination and explicitly differentiates from sibling tools by naming get_sector_briefing and get_stock_briefing as alternatives for different use cases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit usage guidance is provided: 'Use for 相場ブリーフィング, 市場概況, 今日の相場, daily briefing, market summary.' It also gives clear exclusions and alternatives: 'For sector valuation (PER/PBR) use get_sector_briefing instead. For single-stock detail use get_stock_briefing instead.'
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 significant behavioral context beyond the annotations: default returns a compact summary, detail=True returns full rows, and any filter parameter returns full data. It also discloses plan restrictions. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with a clear purpose statement, usage guidance, behavior explanation, plan note, and parameter list. Each section adds necessary information without redundancy, and the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity, the description covers all essential aspects: what it does, when to use it, alternatives, parameter semantics, plan requirements, and default output behavior. The presence of an output schema means return value details are not required in the description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema description coverage is 0%, the description's Args block thoroughly documents every parameter: s33 with an example code, date formats, range parameters, and the detail flag's conditional behavior. This fully compensates for the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as retrieving the TSE 33-sector short selling ratio, with both English and Japanese labels. It explicitly distinguishes itself from the sibling tool get_markets_short_sale_report by contrasting sector-level vs per-stock data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states when to use the tool ('Use for 業種別空売り比率, sector-level 空売り動向') and explicitly names the alternative tool for per-stock short positions. It also notes the plan requirement (Standard+ only) and explains the default vs detail behavior.
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 many behavioral details beyond annotations: all criteria must hold, dividend-yield priority rule (NxFDivAnn > FDivAnn), REITs excluded, margin_ratio/margin_date null on Free/Light plans, cache-only invocation, and edge cases like net-loss or negative-book stocks never matching. These add significant context beyond the read-only and idempotent hints. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but highly structured: summary sentence, keyword aliases, detailed criteria, exclusions, plan notes, and an Args section. Every sentence adds value and the organization makes it easy to scan even with its length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 10-parameter screen with no schema descriptions, the description is remarkably complete: it explains all criteria, defaults, edge cases, plan limits, and output nuances like margin_ratio null behavior. An output schema exists, so return values are covered; the description fills all other contextual gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, but the description contains a full Args block explaining every parameter with defaults, ranges, and edge-case semantics (e.g., 'Net-loss stocks (EPS<=0) never match'). This fully compensates for the schema's lack of descriptions, adding meaning far beyond the property titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Screen value stocks near their 52-week low with high forward dividend yield and a profit-increase forecast.' It clearly lists criteria and explicitly distinguishes itself from sibling tools (e.g., 'For a single criterion use get_valuation_ranking / get_dividend_yield_ranking / detect_52w_high_low') and notes it is included in get_market_briefing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage guidance: Japanese/English keyword aliases, a direct statement that single-criterion alternatives should be used, REIT exclusion with a pointer to get_dividend_yield_ranking, and supported plan information. This is far beyond a vague 'use when you need...' statement.
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:

[![jquants-mcp MCP server](https://glama.ai/mcp/servers/shigechika/jquants-mcp/badges/card.svg)](https://glama.ai/mcp/servers/shigechika/jquants-mcp)

Score Badge

Copy to your README.md:

[![jquants-mcp MCP server](https://glama.ai/mcp/servers/shigechika/jquants-mcp/badges/score.svg)](https://glama.ai/mcp/servers/shigechika/jquants-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

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/shigechika/jquants-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server