Tools reference: Japanese company financials and filings
Kabuken MCP provides 18 tools across three subscription tiers: BASIC, INVESTOR, and DEVELOPER. BASIC has three kinds of access: 7 free tools (company search, company lookup, industry list, risk context, document list, account quota, and data issue report), 7 fact tools that work within a free allowance of 3 lookups per day for TOPIX-99 companies, and 4 tools that need INVESTOR or DEVELOPER. INVESTOR and DEVELOPER include all 18 tools — the two differ only in daily request quota, not tool access.
search_companies
Section titled “search_companies”Search for listed Japanese companies by name.
Tier: BASIC (free tool)
Parameters
Section titled “Parameters”| Parameter | Type | Required | Description |
|---|---|---|---|
query | string | One of query or queries | Company name in Japanese or English (partial match supported) |
queries | string[] | One of query or queries | 1-20 company names, resolved in one call. Not combined with query or cursor |
limit | integer | No | Maximum results to return per name (1-20, default: 10) |
cursor | string | No | The next_cursor of the previous response, sent with the same query and limit |
With queries, the response is {"results": [{"query", "companies", "total", "returned", "truncated"}]}, one entry per name in request order. A name with no match returns an empty companies list. The call counts as one call.
Example prompt
Section titled “Example prompt”“Search for companies with ‘Hitachi’ in the name”
get_company
Section titled “get_company”Get details for a specific company by its identifier.
Tier: BASIC (free tool)
Parameters
Section titled “Parameters”| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | The company identifier value |
id_type | string | No | Type of identifier: entity_code, ticker, name, simple_name (default: entity_code) |
include_sites | boolean | No | When true, adds a sites summary built from the company’s latest annual securities report that has parsed site rows. Default: false; the response is unchanged when omitted. |
The sites object contains source (doc_id, period_end, doc_type_code, submit_date), home_country, total_sites, by_country (entries of country_code, scope and count, where scope is domestic when the country is home_country (JP), foreign when a different country is set or when the row is in an overseas-subsidiary section without a resolved country (country_code: null there means abroad, country not resolved), and unknown otherwise, for example filer or domestic-subsidiary rows whose location text was not resolved, since they can be foreign addresses; sites with a resolved Japanese prefecture, or with a stored country code JP, are reported as JP; other sites without a resolved country are null), by_prefecture (JIS prefecture code, the matching ISO 3166-2 subdivision_code such as JP-13, and count), and by_precision (counts per location precision, such as municipality, prefecture, country, none). In by_precision, none means the location text was not resolved. sites is null when no parsed filing exists, which means no parsed filing, not zero facilities. Municipality-level detail is not returned.
Counts are facility rows as listed in the filing’s major-facilities tables (主要な設備の状況), which cover the filer and its consolidated subsidiaries; equity-method affiliates are not included. One row can be a head office, one plant or a group of stores the filer aggregated, so the count is not size, book value, headcount or revenue. Country codes are ISO 3166-1 alpha-2; prefecture codes are JIS X 0401.
Example prompt
Section titled “Example prompt”“Get details for the company with ticker 7203”
list_industries
Section titled “list_industries”List all industry categories used in Kabuken’s classification.
Tier: BASIC (free tool)
Parameters
Section titled “Parameters”None.
Example prompt
Section titled “Example prompt”“What industries are available to filter by?”
list_documents
Section titled “list_documents”List EDINET filings for a specific company.
Tier: BASIC (free tool)
Parameters
Section titled “Parameters”| Parameter | Type | Required | Description |
|---|---|---|---|
entity_code | string | Yes | EDINET entity code for the company |
limit | integer | No | Maximum results (1-100, default: 20) |
cursor | string | No | The next_cursor of the previous response, sent with the same entity_code and limit |
An unknown entity_code returns not_found. A company with no filings returns an empty list with a notes entry.
Example prompt
Section titled “Example prompt”“List the recent filings for Toyota (entity code E02144)”
get_financial_facts
Section titled “get_financial_facts”Retrieve structured financial data (XBRL facts) from a specific filing.
Tier: fact tool. BASIC within the free allowance (3 per day, TOPIX-99 companies); unlimited on INVESTOR or DEVELOPER
Parameters
Section titled “Parameters”| Parameter | Type | Required | Description |
|---|---|---|---|
doc_id | string | Yes | Document ID from list_documents |
statement_type | string | No | Filter by statement: bs (balance sheet), pl (income statement), cf (cash flow), ss (statement of changes in equity). Every section name accepted by section is also accepted here |
concepts | string[] | No | XBRL concept names (fact_name) to filter to |
outline | boolean | No | With only doc_id, list the sections of the filing. With section, list the top-level headings of that section. No values are returned |
section | string | No | A section name, taken from the next field of an outline response: BalanceSheet, IncomeStatement, CashFlows, ChangesInEquity, ComprehensiveIncome, Notes, Other, CoverPage, or Unclassified for facts without a section. The short codes of statement_type also work. DEI is still accepted but returns no facts and a note: document and entity information comes from get_company and list_documents |
context | string | No | all (default) returns every context. primary returns only facts whose context has no dimension member and is not NonConsolidatedMember; this includes prior periods (Prior1YearDuration) and FilingDateInstant. The other facts stay available with all. concepts cannot be combined with parent |
parent | string | No | A heading or concept name, as returned in a next field or written prefix:Name (both spellings work); needs section. Returns the direct children of that heading with values |
query | string | No | Facts whose English label, Japanese label or concept name contains this text, case-insensitive (up to 100 characters) |
limit | integer | No | Maximum facts to return (1-500, default: 100) |
cursor | string | No | The next_cursor of the previous response, sent with the same doc_id, filters and limit |
Facts carry English and Japanese labels together, so there is no language parameter. An unknown doc_id returns not_found.
Finding one fact step by step
Section titled “Finding one fact step by step”A filing holds hundreds of facts. To reach one fact, descend one level per call. Every node in an outline response has a next field with the exact arguments of the next call.
outline: truewith onlydoc_idlists the sections withfact_count,concept_countandnext.sectionwithoutline: truelists the top-level headings of that section (eachconceptin theprefix:Nameform, in filing display order), 100 per page, withchild_countandnext. Send thenext_cursorof a response, with the samedoc_idandsection, to get the next page. Anextfield holds only the changing arguments: send it together with thedoc_idandsectionof the response. Headings without a fact of their own get a label derived from the concept name; the response says so inlabel_note. A node that is a fact with children also hasown_facts_nextfor its own values.sectionwithparentreturns the direct children of that heading with values. A child that has children of its own hashas_children: trueand anextfield. Repeat this step until you reach the fact. The response givestotal(also on a cursor page) andcontext_counts: the number of facts inprimarycontexts (no dimension member),non_consolidatedcontexts (NonConsolidatedMember) anddimensioncontexts (segments, equity components and other members). A heading such asStatementOfIncomeLineItemscan hold all three kinds. Sendcontext: "primary"to get only the primary facts.queryis a shortcut: it searches labels and concept names of the whole filing and pages withcursor. It can be combined withsectionorstatement_type. Document and entity information (jpdei_cor) facts are not returned byget_financial_factsin any mode, so noDEIsection appears in an outline; useget_companyorlist_documentsfor them. The other cover-page items are inCoverPage, andqueryfinds them.
Outline calls return no values and stay small. Each step is one call. A cursor from before this change is no longer valid.
Example prompt
Section titled “Example prompt”“Get the income statement facts from Sony’s latest annual report”
get_calculation_tree
Section titled “get_calculation_tree”Show how a financial total decomposes into its component line items, based on the XBRL calculation linkbase.
Tier: fact tool. BASIC within the free allowance (3 per day, TOPIX-99 companies); unlimited on INVESTOR or DEVELOPER
Parameters
Section titled “Parameters”| Parameter | Type | Required | Description |
|---|---|---|---|
doc_id | string | Yes | Document ID from list_documents |
root_concept | string | No | XBRL concept name to use as the root of the subtree (omit to return all root nodes) |
limit | integer | No | Maximum calculation arcs to process (1-500, default: 200) |
An unknown doc_id returns not_found. The result gives total and returned beside total_arcs and returned_arcs (same numbers).
Example prompt
Section titled “Example prompt”“Show me how operating profit is calculated in this filing”
get_segment_breakdown
Section titled “get_segment_breakdown”View business segment or geographic breakdowns reported in a filing.
Tier: fact tool. BASIC within the free allowance (3 per day, TOPIX-99 companies); unlimited on INVESTOR or DEVELOPER
Parameters
Section titled “Parameters”| Parameter | Type | Required | Description |
|---|---|---|---|
doc_id | string | Yes | Document ID from list_documents |
fact_name | string | No | XBRL dimension axis name to filter to one axis |
include_all_axes | boolean | No | Also return non-segment axes (default: false) |
view | string | No | all, segments or geographic (default: all) |
limit | integer | No | Maximum segment records to return (1-500, default: 100) |
An unknown doc_id returns not_found. Each segment record carries unit and decimals of its fact. When two different members on one axis share a member label, the label is made unique across all pages: member_label_ja gets the English label in full-width brackets (for example その他(All Other)) and member_label_en gets the member local name in brackets. The original label stays in member_label_ja_raw or member_label_en_raw, which appear only on changed rows.
Example prompt
Section titled “Example prompt”“Break down revenue by business segment for this company”
get_document_summary
Section titled “get_document_summary”Get an AI-generated summary of a specific filing. For short filings whose structured data holds only cover-page items (for example an extraordinary report), the summary is written from the filing body text and starts with a one-line source notice; citations then use [Section:<doc_id>:<n>] tags. If the body cannot be read, the tool says so instead of summarising the cover page.
Tier: INVESTOR or DEVELOPER
Parameters
Section titled “Parameters”| Parameter | Type | Required | Description |
|---|---|---|---|
doc_id | string | Yes | Document ID from list_documents |
language | string | No | Response language: EN or JA (default: JA) |
The result echoes doc_id and language, also when the summary comes from the cache.
Example prompt
Section titled “Example prompt”“Summarize the key points from Sony’s latest annual report”
analyze_document
Section titled “analyze_document”Get an AI-powered analysis of a filing’s financial content, including strengths, risks, and notable items.
Tier: INVESTOR or DEVELOPER
Parameters
Section titled “Parameters”| Parameter | Type | Required | Description |
|---|---|---|---|
doc_id | string | Yes | Document ID from list_documents |
question | string | Yes | Question to answer about the document (max 1000 characters) |
language | string | No | Response language: EN or JA (default: JA) |
Example prompt
Section titled “Example prompt”“Analyze this filing and highlight key investment considerations”
compare_companies
Section titled “compare_companies”Compare up to 5 companies side by side using key financial metrics.
Tier: fact tool. BASIC within the free allowance (3 per day, TOPIX-99 companies); unlimited on INVESTOR or DEVELOPER
Parameters
Section titled “Parameters”| Parameter | Type | Required | Description |
|---|---|---|---|
entity_codes | string[] | Yes | EDINET entity codes for the companies to compare (2 to 5) |
If none of the codes exists, the call returns not_found. If some do not exist, their rows stay in the result with not_found: true and a notes entry. Every metric carries unit and decimals, and each row has a units object for revenue, net_income, total_assets, equity and operating_income.
Example prompt
Section titled “Example prompt”“Compare Sony, Panasonic, and Sharp on key financial metrics”
screen_companies
Section titled “screen_companies”Filter companies by financial metric thresholds and return matching results.
Tier: INVESTOR or DEVELOPER
Parameters
Section titled “Parameters”| Parameter | Type | Required | Description |
|---|---|---|---|
filters | object[] | Yes | Array of filter conditions, each with metric, operator, and value |
limit | integer | No | Maximum results (default: 20, max: 100) |
industry_id | string | No | Industry ID from list_industries |
sort_by | string | No | Metric to sort by: roe, roa, operating_margin, current_ratio, debt_to_equity |
sort_direction | string | No | asc or desc (default: desc) |
exclude_negative_equity | boolean | No | Exclude companies with negative equity (default: true) |
include_financials | boolean | No | Include banks, insurers and securities firms (default: false) |
include_delisted | boolean | No | Include companies no longer on the JPX listed-company list (default: false) |
cursor | string | No | The next_cursor of the previous response, sent with the same filters, sort and limit. total is returned on the first page only. |
Valid metric values: roe, roa, operating_margin, current_ratio, debt_to_equity.
Valid operator values: gt (greater than), lt (less than), gte (greater than or equal), lte (less than or equal).
Example prompt
Section titled “Example prompt”“Find companies with ROE above 10% and debt-to-equity below 1”
get_industry_overview
Section titled “get_industry_overview”Get sector-level aggregated data for a given industry, including company count, mean, median, and top/bottom companies.
Tier: INVESTOR or DEVELOPER
Parameters
Section titled “Parameters”| Parameter | Type | Required | Description |
|---|---|---|---|
industry_id | string | Yes | Industry ID from list_industries |
An unknown industry_id returns not_found.
Example prompt
Section titled “Example prompt”“Give me an overview of the Electric Appliances sector”
get_risk_context
Section titled “get_risk_context”Get risk context indicators for a company: Bank of Japan interest-rate sensitivity and METI export-control classification, derived from its industry, together with recent shipping-relevant NGA navigational warnings.
Tier: BASIC (free tool)
Parameters
Section titled “Parameters”| Parameter | Type | Required | Description |
|---|---|---|---|
entity_code | string | Yes | EDINET entity code of the company (e.g. E02144). Obtain from search_companies or get_company. |
include_routine_warnings | boolean | No | Include routine navigational warnings (survey work, buoys, cable and pipeline operations, small local zones). Default false. |
Response
Section titled “Response”Besides the rate-sensitivity and export-control indicators, the response includes recent_maritime_warnings: NGA navigational warnings from the last 30 days, up to 10, newest first. Routine warnings are left out unless include_routine_warnings is true. Each entry has event_source_id, title, severity, warning_type, chokepoint (null outside the nine chokepoints), region and published_at. See Market Events for how warnings are classified.
Example prompt
Section titled “Example prompt”“What’s the export control and interest rate risk profile for this company?”
get_company_financials
Section titled “get_company_financials”Retrieve the headline figures (revenue, operating income, net income, total assets, equity, current assets, current liabilities, total liabilities) per filing and a per-fiscal-year series with the 主要な経営指標等の推移 indicators for a company. The full statements (income statement, balance sheet, cash flow, grouped by statement type across annual and interim filing periods) are returned when include lists statements.
Tier: fact tool. BASIC within the free allowance (3 per day, TOPIX-99 companies); unlimited on INVESTOR or DEVELOPER
Parameters
Section titled “Parameters”| Parameter | Type | Required | Description |
|---|---|---|---|
entity_code | string | Yes | EDINET entity code (e.g. E02144 for Toyota). Obtain from search_companies. |
period_type | string | No | Filter by filing period type: ANNUAL, INTERIM, or ALL (default: ANNUAL) |
periods | integer | No | Number of most recent fiscal years to return (1-20, default: 3; values below 1 are treated as 1). fiscal_years holds one entry per fiscal year, including years carried as prior-year comparatives; periods holds one entry per filing, at most this many. |
detail | string | No | Shape of the human_capital and officers sections: summary (default) or full (case-insensitive). See “Detail” below. The other sections are the same in both. With summary, periods and fiscal_years are omitted when include lists only human_capital or officers. |
include | string[] | No | Sections beyond the headline figures: indicators, statements, omitted_concepts, human_capital, officers (case-insensitive). indicators adds fiscal_years[].indicators. statements adds income_statement, balance_sheet and cash_flow to each period. omitted_concepts adds the per-period lists of statement concepts with no consolidated current-period value. human_capital and officers add the sections described below, read from the latest annual report. Default: ["indicators"]. An explicit list replaces the default: [] returns headline figures only and ["statements"] returns statements without indicators. An unknown value returns a validation error. |
The response includes periods_requested and periods_returned (counting filings) and fiscal_years_requested and fiscal_years_returned (counting fiscal years). fiscal_years is built from annual reports only; each value names its source doc_id, context_ref and period_role, and carries restatement when a later filing reports a different figure for the same year. A derived value (J-GAAP equity) carries derived: true and derived_from, the component facts it is computed from. A revenue value carries basis and basis_label naming the revenue concept the filer reports. A year carries basis_change: true when the filer’s consolidation basis differs from the next older year, and irregular_period: true when its period is shorter or longer than a regular year. A net income value with omission_reason: only_total_profit_including_nci means the filing reports only profit including non-controlling interests, so no figure attributable to owners of the parent is given. A company that does not exist returns not_found. A company that exists but has no filings of the requested period_type returns periods: [] with a notes entry. Each metric in key_metrics carries unit and decimals.
Amended annual reports. When a company files an amended annual report (訂正有価証券報告書) for a fiscal year, the amendment supersedes the original report for that year. For each figure, the newest amendment that carries a value is used; a figure that no amendment carries keeps the original report’s value. The same rule applies to each line of income_statement, balance_sheet and cash_flow, and to fiscal_years. A period built this way has doc_id set to the amendment, doc_type_code 130, amended: true and original_doc_id, the report it supersedes. In such a period, each key_metrics figure and each statement line also carries doc_id, the filing it comes from, and amended (true for the amendment, false for the original). A fiscal_years value taken from an amendment carries amended: true. Periods with no amendment do not have these fields.
Human capital (include: ["human_capital"]). The 人的資本 metrics of the latest annual report (有価証券報告書), as filed: ratio of female employees in managerial positions (female_managers_ratio); ratio of male employees taking childcare leave, routed by the legal basis the filer used and by employee group (_regular and _non_regular suffixes for regular and non-regular employees): male_childcare_leave_ratio for the rate under 育児・介護休業法施行規則 第71条の6第1号 (Article 71-6, Item 1 of the ordinance of the Childcare and Caregiver Leave Act) (and the plain subsidiary rate), male_childcare_and_childcare_purpose_leave_ratio for the 第71条の6第2号 (Article 71-6, Item 2) rate that also counts leave for childcare purposes, and male_childcare_leave_ratio_womens_act for the rate calculated under the Act on the Promotion of Women’s Active Engagement (女性活躍推進法); each key is filled only from its own standard concepts; and the gender wage gap for all, regular and non-regular employees. A filed 0 is returned as 0; a cell the filing leaves blank (「-」, nil in the XBRL) is null. When a 訂正 filing nils a cell, the nil replaces the original figure. reporting_company holds the filer’s own figures; consolidated_subsidiaries holds one row per subsidiary row of the filing (numbered as in the filing; name is the company name the filing tags for the row, 指標を公表した会社, and is null when the filing does not tag it). The standard keys hold only the standard EDINET concepts (jpcrp_cor); a filer’s own extension concept of the same family is listed in extension_metrics (per row) or reporting_company_extension_metrics with its concept_id. Ratios are fractions as filed (0.04 = 4%), each with unit, value_format: "fraction", concept_id, context_ref, doc_id and period_instant. labels gives the EN and JA label of each metric key. A filing with none of these facts returns null values and a note, not an error.
Officers (include: ["officers"]). The 役員 of the latest annual report: officers lists every officer of the 役員の状況 table (the member identifier, name_ja and title_ja as filed, name_en from the XBRL label or identifier) with remuneration_total (the total remuneration paid by the group to that officer, JPY, disclosed individually only for officers paid 100 million yen or more), remuneration_components and shares_held, ordered by pay; shares_held and remuneration_total are null where the filing shows 「-」. role names the 役員の状況 table that lists the person: director_or_auditor for the 取締役・監査役 table, executive_officer for the 執行役 table of a company with a nomination committee (指名委員会等設置会社), director_and_executive_officer for a person in both tables, who is listed once with title_ja and shares_held from the 取締役・監査役 table. in_officer_table is true for a member of either table at the filing date and false for a person who appears only in the individual pay table (paid in the year, no office at the filing date; role is null); total counts the members with in_officer_table true, once per person, and paid_only_count the others, whose rows are kept. candidates lists the officers expected after the annual general meeting, as filed (the …Proposal concepts: name_ja, title_ja, term_ja as filed, role by table). The filed table can include continuing officers who are not up for election, so the list is not the number of persons elected. candidates are not counted in total. When a person’s individual pay is filed in a prior-year context (for example Prior1YearDuration) inside the pay table of the report, a note names the person; the value is returned as filed. remuneration_by_category gives, per officer category (directors, outside directors, corporate auditors and so on), officer_count (the standard head count), total (the filed total), components (JPY amounts only: fixed, bonus, share awards and so on, including the filer’s own amount concepts; a component carries persons when the filer tagged a head count for that pay type, matched by name with the Etc spelling variant normalised) and unmatched_person_counts (tagged head counts that match no single component, each with its concept_id). officer_count and total are null when the filing has no such element; components are never summed. A pay category whose cells are all blank (nil) in the filing has no remuneration_by_category row. board_composition gives the male and female officer counts and the female ratio. Terms of office, dates of birth and career summaries are not returned. Every figure carries concept_id, context_ref, doc_id and its period with detail: "full"; the default summary folds them into the section as described next.
Detail (detail). The per-figure fields above (concept_id, context_ref, doc_id, unit, value_format, period) made a filing with 64 subsidiary rows a 141 KB response, which assistants truncate. The default, detail: "summary", keeps every figure and every field of the full shape (role, in_officer_table, paid_only_count, candidates, unmatched_person_counts included) and moves the provenance up one level. The section carries doc_id, period_end, unit (and value_format for ratios), a concepts table and concept_ids (the concept of each keyed figure: per metric key and scope for human capital; remuneration_total, shares_held, officer_count, category_total and the board keys for officers). Each block (the reporting_company, a subsidiary row, an officer, a pay category, the board_composition) carries ctx, the context of its figures. A figure is then a plain number when it is in its block’s ctx under its key’s concept and from the section’s doc_id; otherwise it is {v, c, ctx, d} with only the fields that differ: c indexes concepts, d is the figure’s own doc_id (an untouched original figure under an amended section). Figures with no key (pay components, extension_metrics, unmatched_person_counts, persons) always carry c. Blank cells are omitted from the keyed records (labels lists the keys present); an empty unmatched_person_counts is omitted. The long lists are tables, {columns, rows}: columns names each position of a row array and a blank cell is null. consolidated_subsidiaries: row, name (the company name as filed; null when the filer did not tag it) only when some row has one, ctx, then member only when some row’s ctx does not name it (for example a row with only extension metrics, whose ctx is null), its labels only when some row has one, extension_metrics only when some row has one, then every metric key with a value in at least one row. officers (pay descending, as in full): member only when some officer’s ctx does not name it, name_en only when some officer has an XBRL label (otherwise it is the member identifier split on capitals), name_ja, title_ja, role, in_officer_table only when it differs from role != null for some officer, ctx, remuneration_total, remuneration_components, shares_held. candidates: member and name_en under the same rules, name_ja, title_ja, term_ja, role, ctx, and d only when some candidate comes from a filing other than the section’s. A member omitted this way is the context ref without its period prefix: a bare local name is in the standard namespace (CurrentYearInstant_Row1Member names jpcrp_cor:Row1Member), a filer namespace is written <prefix>-000:<Local> (FilingDateInstant_jpcrp030000-asr_E02144-000ToyodaAkioMember names jpcrp030000-asr_E02144-000:ToyodaAkioMember); the same rule drops member from a remuneration_by_category row. An omitted name_en is the member local name split at capitals (ToyodaAkioMember gives Toyoda Akio). Per-figure unit and period_* are not repeated in summary: the section-level units and the period type in ctx stand for them; use detail: "full" when you need them per figure. In both shapes consolidated_subsidiaries holds at most 100 rows in filing order; subsidiaries_total, subsidiaries_returned and subsidiaries_truncated say when the filing has more. detail: "full" returns the shape described in the two paragraphs above, several times larger. With summary, a request whose include lists only human_capital or officers (none of indicators, statements, omitted_concepts) gets no periods and no fiscal_years block, about 3.4 KB it did not ask for; a notes entry states this, and include: [] still returns the headline figures. The summary notes of both sections carry only the data-dependent remarks and one note that points to the reading rules; the field notes of the full shape are in the tool’s include description. The consolidated_subsidiaries table has a ctx column only when some row’s context is not CurrentYearInstant_Row{row}Member.
Example prompt
Section titled “Example prompt”“Show me Toyota’s income statement and balance sheet for the last 3 annual reports” (the assistant sets
includetostatements)
“What is the gender wage gap at Toyota, and how much was each director paid last year?” (the assistant sets
includetohuman_capitalandofficers)
get_major_shareholders
Section titled “get_major_shareholders”Return who holds the shares of a company. The default part, large_holdings, is the major shareholder reports (large shareholding reports, 大量保有報告書): shareholder, ownership percentage, shares held, and filing date, ordered by report date, newest first. Reports identical in shareholder, report date, percentage, shares, change type and purpose are merged into one row; doc_ids lists every source filing and doc_id is the first. Three further parts read the latest annual securities report (有価証券報告書): top_holders (大株主の状況: rank, holder_name and holder_address as filed, shares_held, shareholding_ratio as a fraction, and the total row), holder_categories (所有者別状況: shareholder count, units held and ratio for the seven EDINET owner categories, per share class, with totals and shares_less_than_one_unit) and policy_holdings (政策保有株式: 特定投資株式 rows with holding_type specified and みなし保有株式 rows with deemed, each with issuer_name as filed, shares_held and book_value for the current and prior year end, holding_purpose and the filing’s own answer issuer_holds_reporting_company_shares; holder_scope is REPORTER for the company’s own holdings and LARGEST_HOLDING_COMPANY or SECOND_LARGEST_HOLDING_COMPANY for the holdings of those subsidiaries). A row whose current-year cells are blank (「―」: the issuer is no longer held at year end) has held_at_year_end: false. scope_counts gives held_specified_count and held_deemed_count next to the row counts. A cursor page returns only the paged lists; top_holders and holder_categories are on the first page only. An amendment (訂正有価証券報告書) supersedes a part only when its facts for that part differ from the original’s; an amendment that re-carries a part unchanged leaves the original doc_id on it. source_filing.amended_by names the amendment only when it superseded a returned part. Names are as filed, including line breaks inside a name; EDINET codes of holders and issuers are not resolved. detail also shapes top_holders and holder_categories: with summary (default) their rows carry context_ref only and doc_id and period_end sit on the part; with full every row carries them too. A policy_holdings page reads the dimension rows of the filing’s policy contexts only, and a later page of the same filing within ten minutes is served from a per-filing cache without a new fact read.
Tier: fact tool. BASIC within the free allowance (3 per day, TOPIX-99 companies); unlimited on INVESTOR or DEVELOPER
Parameters
Section titled “Parameters”| Parameter | Type | Required | Description |
|---|---|---|---|
entity_code | string | Yes | EDINET entity code of the company (e.g. E02144) |
include | array | No | Parts to return, values: large_holdings (default), top_holders, holder_categories, policy_holdings |
detail | string | No | Shape of the annual-report rows: summary (default) keeps context_ref on top_holders and holder_categories rows and the figures, texts and current-year context_ref on policy_holdings rows, with doc_id and period_end (and prior_period_end) on each part; full also puts doc_id and period_end on every row and doc_id, context_ref and period_end on each policy_holdings year column. large_holdings is the same in both. |
limit | integer | No | Rows per page of each paged list (1-500, default: 100): large_holdings rows, and policy_holdings rows, whose page is at most 40 rows (larger values are clamped) |
cursor | string | No | The next_cursor of the previous response, sent with the same entity_code, include, limit and detail; it continues both paged lists |
An unknown entity_code returns not_found; a company with no reports returns an empty list with a notes entry; a company with no annual report returns the annual-report parts as null with a notes entry. Without include the response is unchanged from earlier versions. top_holders and holder_categories rows carry context_ref; their parts carry doc_id and period_end, and with detail: "full" the rows carry them too. policy_holdings is paged: the part carries returned, total and truncated, and the response next_cursor (null when no list has more rows); a page holds at most 40 rows, so a bank with 78 rows and long purpose texts arrives in two pages of under 30 KB each. In policy_holdings, current and prior are read from the current and prior year-end contexts only; a year whose figures the filer replaced by * (below the disclosure threshold) carries not_disclosed_below_threshold: true with shares_held and book_value null, and a figure filed in any other context (for example a filing-date context) is listed in the row’s other_context_facts instead of being mapped to a year (a row with figures only in such a context is kept, with current and prior both null). scope_counts gives specified_count and deemed_count per holder_scope; the top-level counts are the totals. In holder_categories, a value the filer left empty (nil) is null; a filed 0 is 0. The result has a units object: ownership_pct is in percent, shares_held in shares, shareholding_ratio a fraction (0.1384 = 13.84%), units_held in trading units, and book_value carries its currency.
Example prompt
Section titled “Example prompt”“Who are the major shareholders of MUFG?”
“List the major shareholders in Toyota’s annual securities report and the shareholding ratio of each owner category” (the assistant sets
includetotop_holdersandholder_categories)
“List MUFG’s policy shareholdings (specified and deemed holdings) by book value, largest first” (the assistant sets
includetopolicy_holdings)
get_filing_text
Section titled “get_filing_text”Return narrative sections of an annual securities report (有価証券報告書) as filed: business_risks (事業等のリスク) and md_and_a (the management analysis of financial position, operating results and cash flows). The text is in Japanese, reproduced verbatim from the filing’s text blocks with markup removed; no AI is used. Text is reproduced verbatim from the filing; the filing company holds the rights to its text. Takedown requests: https://kabuken.intellics.ai/support
Tier: fact tool. BASIC within the free allowance (3 per day, TOPIX-99 companies); unlimited on INVESTOR or DEVELOPER
Parameters
Section titled “Parameters”| Parameter | Type | Required | Description |
|---|---|---|---|
entity_code | string | One of | EDINET entity code of the company (e.g. E02144). Uses its latest annual report |
doc_id | string | One of | EDINET document id of a specific filing. Give exactly one of entity_code and doc_id |
sections | string[] | No | business_risks and/or md_and_a (default: ["business_risks"]) |
max_chars | integer | No | Characters of text per page (1-30000, default: 12000) |
cursor | string | No | The next_cursor of the previous response, sent with the same entity_code or doc_id and sections |
The result also carries doc_id, entity_code and period_end of the filing the text was read from. Each entry of sections has section, source_element, context_ref, label_ja, label_en, text, char_offset, total_chars and truncated. Sections the filing does not hold are listed in missing_sections. A filing without stored text returns not_found; a cursor that is not valid for the arguments returns invalid_input; text too large to serve returns repository_error. A filing whose text extraction produced no text blocks adds a notes entry. With entity_code, the newest annual report that has XBRL data is used.
Example prompt
Section titled “Example prompt”“Show me the business risks section of Toyota’s latest annual report”
get_account_quota
Section titled “get_account_quota”Check the caller’s current daily API quota: subscription tier, calls used today, daily limit, remaining calls, and reset time.
Tier: BASIC (free tool, available on every tier)
Parameters
Section titled “Parameters”None.
Calling this tool does not use up your daily request quota. For BASIC accounts the result also shows the free fact allowance (3 per day, TOPIX-99 companies, resets at 00:00 JST).
Example prompt
Section titled “Example prompt”“How many API calls do I have left today?”
report_data_issue
Section titled “report_data_issue”Report a figure or field that looks wrong or missing for a listed company. The report is stored with the text you write and the account that sent it, and is reviewed by the Kabuken team. The result is a report_id and the status new.
Tier: BASIC (free tool, available on every tier). Each account can send up to 10 reports per day; further reports return rate_limited until 00:00 UTC.
Parameters
Section titled “Parameters”| Parameter | Type | Required | Description |
|---|---|---|---|
entity_code | string | Yes | EDINET code of the company concerned (e.g. E02144) |
doc_id | string | No | EDINET document id of the filing the figure comes from |
concept_id | string | No | XBRL concept of the figure (e.g. jppfs_cor:NetSales) |
context_ref | string | No | XBRL context reference of the figure (e.g. CurrentYearDuration) |
description | string | Yes | What is wrong or missing, up to 2000 characters. Do not include personal data. |
Only the fields above and your account id are stored. Your email address is not stored with the report. An unknown entity_code returns not_found.
Example prompt
Section titled “Example prompt”“The net sales for Toyota in its latest annual filing looks wrong. Report it.”
Tool availability by tier
Section titled “Tool availability by tier”| Tool | Class | BASIC | INVESTOR | DEVELOPER |
|---|---|---|---|---|
search_companies | Free | Yes | Yes | Yes |
get_company | Free | Yes | Yes | Yes |
list_industries | Free | Yes | Yes | Yes |
get_risk_context | Free | Yes | Yes | Yes |
list_documents | Free | Yes | Yes | Yes |
get_account_quota | Free | Yes | Yes | Yes |
report_data_issue | Free | Yes | Yes | Yes |
get_company_financials | Fact | 3 per day, TOPIX-99 only | Yes | Yes |
get_financial_facts | Fact | 3 per day, TOPIX-99 only | Yes | Yes |
get_calculation_tree | Fact | 3 per day, TOPIX-99 only | Yes | Yes |
get_segment_breakdown | Fact | 3 per day, TOPIX-99 only | Yes | Yes |
get_major_shareholders | Fact | 3 per day, TOPIX-99 only | Yes | Yes |
get_filing_text | Fact | 3 per day, TOPIX-99 only | Yes | Yes |
compare_companies | Fact | 3 per day, TOPIX-99 only (up to 3 companies per call) | Yes | Yes |
get_document_summary | Paid only | No | Yes | Yes |
analyze_document | Paid only | No | Yes | Yes |
screen_companies | Paid only | No | Yes | Yes |
get_industry_overview | Paid only | No | Yes | Yes |
The free allowance is shared by all fact tools on a BASIC account: 3 lookups per day in total, for TOPIX-99 companies only. It resets at 00:00 JST. This is a separate counter from the daily request limit, which resets at 00:00 UTC. All tools except get_account_quota count toward the daily request limit.
INVESTOR and DEVELOPER have identical tool access. The two tiers differ only in daily request quota — see MCP Overview for the quota table.
Errors, attribution and AI-generated output
Section titled “Errors, attribution and AI-generated output”Every tool error has the same shape: one text part holding a JSON object with two keys, error and message. The result has isError: true, except for tier_denied (a scope limit of the account: a tool, company or number of companies outside what the account can use), which is a normal result without isError:
{"error": "tier_denied", "message": "screen_companies is not included in the free account. Account page: https://kabuken.intellics.ai/account\nscreen_companiesは無料アカウントには含まれていません。アカウントページ: https://kabuken.intellics.ai/account"}The error codes are validation_error, invalid_input, not_found, tier_denied, quota_exceeded, rate_limited, repository_error and analysis_worker_error. Plan limits, the free allowance, an unknown company or filing, and an unknown tool name all use this shape. A company or filing that does not exist is not_found in every tool that takes an entity_code or a doc_id. On BASIC the free-allowance check runs first, so an entity_code outside TOPIX-99 returns tier_denied whether or not the company exists.
Every response that contains EDINET-derived data carries an attribution object with the source, the licence and a processing notice. Every tool returns one JSON object in a single text part. Lists sit under a named key (companies, industries, documents, facts, segments) beside total, returned and truncated; when truncated is true, total is null because only part of the result was read. Notices such as the free-allowance count appear in a notes array in the same object. Responses of get_document_summary and analyze_document use the AI-generated attribution, whose ai_generated_notice states that the output is AI-generated by Kabuken from EDINET filings, may contain errors and is not investment advice.
Lists that can exceed one page (search_companies, list_documents, get_financial_facts, get_major_shareholders, get_filing_text, screen_companies) take an optional cursor and return next_cursor, which is null on the last page. A cursor is valid only with the same arguments that produced it, otherwise the call fails with invalid_input.
On BASIC, every fact-tool call, including each get_financial_facts or get_filing_text page and each call with a cursor, counts as one of the daily fact lookups.
Every numeric fact carries unit and decimals (null when the filing gives none). The metrics of get_company_financials (key_metrics) and compare_companies (metrics) carry the same two fields; a derived metric takes the unit its components share and the smallest decimals of them. get_segment_breakdown rows carry them, get_major_shareholders returns a units object and analyze_document source facts carry decimals. screen_companies returns a units object and each get_industry_overview metric a unit: ROE, ROA and operating margin are fractions (0.10 = 10%), current ratio and debt-to-equity are multiples.
get_calculation_tree returns total, returned, total_arcs, returned_arcs and truncated. truncated is true when limit cut the list of calculation arcs before the trees were built, so the trees can be incomplete.
get_account_quota returns reset_at, the next UTC midnight as an ISO 8601 timestamp, together with the existing resetAt date. The free_facts.reset_at value is in JST (+09:00).
AI request limits
Section titled “AI request limits”get_document_summary (when the summary is not cached) and analyze_document share a daily AI request limit per account: 5 for BASIC, 20 for INVESTOR and 50 for DEVELOPER. The same counter also covers AI questions and chat replies in the web app. Cached summaries do not count. The daily AI budget applies across MCP and the web app for all tiers. On the web, BASIC accounts also keep the existing limit of 5 AI questions per month. The counter resets at 00:00 JST. When the limit is used, the tool returns an error with the code ai_budget_exhausted.
get_account_quota can be called up to 100 times per day. get_company_financials accepts periods up to 20; larger values return a validation error. Values below 1 are treated as 1.
See MCP Overview for tier details, Authentication for setup, and Resources Reference for the MCP resources exposed alongside these tools.