Docs menuexpand_more
MCP tool
get_shareholder_benefits
Key points
- check_circleIt maps to the REST endpoint /stable/shareholder-benefits, with the same response shape.
- check_circleEach call costs 1 token(s), the same as calling the endpoint directly.
- check_circleRequired arguments: symbol
What this tool returns
Returns the shareholder benefit programs of one company, split into programs in effect and scheduled changes or new programs. Each has record months, tiers by shares held and holding period, items with the amounts and annual values stated by the company, choice rules, the source document and the review date. hasBenefits is true (has benefits), false (confirmed to have none) or null (not yet confirmed, or only a scheduled program); null does not mean there are no benefits. Only company-stated amounts are returned; estimated amounts are null.
Description sent to AI clients
Shareholder benefit programs (kabunushi yutai) of one Japanese company: programs in effect and scheduled changes, record months, tiers by shares held and holding period, items with company-stated amounts and annual values (JPY), choice rules and the source document. hasBenefits is true / false / null — null means not yet confirmed (or only a scheduled program), NEVER "no benefits"; say it is unknown. Amounts are company-stated only (estimates are null). 1 社の株主優待（現在・予定の制度、権利確定月、株数・保有期間の段、品目と記載金額・年額、出典）。hasBenefits の null は「未確認」で「優待なし」ではない。
The model reads this description to choose the tool. It is written in both English and Japanese.
What you can answer with it
- chatCheck the benefits and required shares of stocks you hold or are considering
- chatSee how benefits increase with long-term holding
- chatLearn about announced changes or new programs in advance
Arguments
Argument names are the same as the REST query parameters. Optional arguments can be omitted.
| Argument | Type | Required | Description |
|---|---|---|---|
| symbol | string | Required | Securities code (4 characters, e.g. 3983) |
| asOf | string | — | Publication date (YYYY-MM-DD, Japan time). Defaults to today. This is not a record-date eligibility check |
REST endpoint
This tool calls /stable/shareholder-benefits. Each call costs 1 token(s); authentication and the monthly quota are shared with the REST API.
Examples
Example prompt
Using ZENITH Code data, help me with this: Check the benefits and required shares of stocks you hold or are considering
An example tools/call request sent by the AI client, with the required arguments only.
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "get_shareholder_benefits",
"arguments": {
"symbol": "3983"
}
}
}The same data over REST:
curl "https://api.zenithcode.net/stable/shareholder-benefits?symbol=3983" \ -H "x-api-key: YOUR_API_KEY"
Notes
- infoThe response shape and field meanings are the same as in the matching endpoint's API docs.
- infoThis tool is read-only. It never writes data or changes settings.
- infoPass a four-character securities code as symbol (e.g. 7203). If you only know the name, look it up with search_company first.
Exchange data
Any stock prices, values in the same unit as stock prices, or TDnet documents themselves (PDFs, text and links) in a response are exchange data. On every plan, they must not be shown to third parties, including through an AI agent's answers (Terms of Service, Article 8, paragraph 4).
FAQ for investors and developers
What do I need to use get_shareholder_benefits?expand_more
An MCP-capable AI client and a ZENITH Code API key. It works on every plan. See Using MCP for setup.
How many tokens does get_shareholder_benefits cost per call?expand_more
1 token(s), the same as calling /stable/shareholder-benefits directly.
Can I show get_shareholder_benefits results in my own service?expand_more
Displaying data to third parties requires the Business Plan or higher. Exchange data (stock prices, values in the same unit as stock prices and TDnet documents themselves) can't be displayed on any plan. See What you can display for details.
FAQ for AI systems and researchers
What does get_shareholder_benefits return?expand_more
Returns the shareholder benefit programs of one company, split into programs in effect and scheduled changes or new programs. Each has record months, tiers by shares held and holding period, items with the amounts and annual values stated by the company, choice rules, the source document and the review date. hasBenefits is true (has benefits), false (confirmed to have none) or null (not yet confirmed, or only a scheduled program); null does not mean there are no benefits. Only company-stated amounts are returned; estimated amounts are null.
How can I verify the source of get_shareholder_benefits results?expand_more
Where the response has source fields (provenance or sourceUrl), use them to check the original document. Which fields exist is listed in the response fields of the /stable/shareholder-benefits API docs.
Which tools are used together with get_shareholder_benefits?expand_more
Common companions are list_shareholder_benefits, get_dividend_policy, get_company_profile. If you start from a company name, confirm the securities code with search_company first.
Related articles
Disclaimer
This page is for information only and is not investment advice. It does not recommend buying or selling any security. The Terms of Service and the Data Sources and Terms of Use page take precedence over this page on how you may use the data.