ZENITH Code

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

Annotations only declare readOnlyHint; the description goes well beyond by disclosing the TOC shape (tag, Japanese heading, size), that MD&A sections can be very long, that image-embedded content is lost and rendered as "[画像]", and that a missing section produces a 404 whose body lists suggestedTags. These are the operational facts an agent needs to recover from failure.

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

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

Front-loaded with the correct call sequence, but the entire English text is duplicated verbatim in Japanese, roughly doubling length without adding information. The trailing ISO 8601 date-time note is generic boilerplate with little relevance to a narrative-text tool.

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

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

With no output schema, the description carries the return-format burden and does so by describing the TOC fields and the plain-text conversion (tags stripped, tab-separated cells, "[画像]" placeholders). It is silent on how very long sections are bounded (truncation or pagination), which is the one remaining gap.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns more by enumerating the full alias vocabulary (business, risks, mdna, governance, rnd, facilities, etc.) that the schema only samples, and by explaining that `risks` always resolves to jpcrp_cor:BusinessRisksTextBlock. `fiscalPeriod` and `content` are only covered by the schema, not expanded here.

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

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

States a specific verb and resource — narrative sections of the annual securities report (有価証券報告書) — and the two-mode retrieval pattern (TOC vs. section body). This is clearly distinct from the numeric XBRL/statement siblings such as get_balance_sheet or get_xbrl_facts.

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

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

Gives an explicit two-step procedure: call without `tag` to get the table of contents, then call again with a tag/alias. It also names the correct alias for special cases (investment-risks for REITs/funds, going-concern-risks semantics varying by filer) and the fallback when `risks` is absent (404 with suggestedTags).

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered; the description adds genuinely useful context beyond that: units (yen), that both current and prior year are returned, that non-audit share is a 0–1 ratio, and the exact date/time conventions. It does not discuss coverage gaps (e.g. companies that disclose nothing) or response shape, so it stops short of a 5.

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

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

It is front-loaded, with the purpose and field inventory stated before the format notes, which is good. However, the fully duplicated Japanese rendering of both the content list and the date-format rules roughly doubles length without adding information for a single reader, and the timezone note is repeated in both languages.

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

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

There is no output schema, so the description carries the burden of describing the return values, and it does so thoroughly (fee categories, entities, periods, network firms, ratio, currency). Only minor gaps remain, such as whether a single object or a time series is returned when fiscalPeriod is omitted.

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

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

Schema description coverage is 100%, so the baseline is 3: symbol and fiscalPeriod are already fully documented in the schema, including the YYYY-MM pattern and the omit-for-latest behavior. The description's date-format paragraph concerns returned values rather than the parameters, so it adds no new parameter meaning.

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

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

The description names a specific resource and scope: fees paid to the independent auditor per the annual securities report, broken into audit-service and non-audit-service fees, reporting company / consolidated subsidiaries / total, current and prior year, plus network-firm fees and the non-audit share. That is far more specific than any sibling (get_director_compensation, get_sga_breakdown), so an agent can identify it on sight.

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

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

Usage is only implied by the subject matter; there is no explicit when-to-use, when-not-to-use, or named alternative among the many sibling tools. The only real guidance is the format note (ISO 8601 UTC, add 9 hours for JST) and the schema's note that omitting fiscalPeriod returns the latest annual report.

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

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

readOnlyHint=true already declares that this is a safe read, so the bar is lower. The description adds useful context, namely that each row carries document-level provenance (doc_id) and that timestamps are returned in ISO 8601 UTC while date-only fields use YYYY-MM-DD, which matters because no output schema exists. It says nothing about units or scale (yen vs. thousands), pagination beyond limit, or ordering, however.

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

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

It is short and front-loads the core statement of purpose before the format conventions. The only waste is that every sentence is duplicated in Japanese, which doubles the length, but for a Japan-market data tool that duplication is deliberate rather than padding.

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

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

For a three-parameter read tool this is close to adequate, and the date-format note and provenance hint compensate somewhat for the missing output schema. It still omits the two things an agent most needs to interpret a financial statement series, namely units and scale and which line items come back, which leaves a real gap.

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

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

Schema coverage is 100% and every parameter, including the enum for period and the 1–40 bound on limit, is already documented in the schema. The description adds no parameter-specific meaning such as what Q1–Q4 mean relative to FY, or whether period=annual differs from FY. Baseline 3 applies.

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

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

States the resource and what is returned: "Balance sheet history with document-level provenance." That is specific enough to distinguish it from get_income_statement and get_cash_flow, but it never acknowledges the closest sibling, get_full_financial_statement, which likely overlaps heavily, so the boundary is left to guesswork.

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

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

There is no explicit when-to-use or when-not-to-use guidance and no named alternative. The agent must infer that this tool is for per-period balance-sheet data and that get_full_financial_statement covers the broader statement set, which is pure inference from sibling names.

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

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

Beyond the readOnlyHint annotation, the description discloses important batch behavior: results follow request order, unknown symbols return found=false instead of failing, dividend yield uses forecast dividends when available, and capped progressive dividend years are represented as "N or more". These details materially affect how an agent interprets and trusts the results.

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

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

The description is front-loaded with the core purpose and the preferred alternative, followed by relevant return and formatting details. It is somewhat long because the English content is largely duplicated in Japanese, but the structure remains clear and the extra details are not filler.

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

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

With no output schema, the description does a good job naming the returned metrics, preserving request order, and explaining the found=false sentinel. It references get_key_metrics_latest for the exact field set, which is useful, though the precise response envelope shape is not spelled out.

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

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

The input schema already fully documents the single symbols parameter as comma-separated 4-digit ticker codes with a max of 50, so the description does not need to repeat syntax. It does add useful input-related semantics by stating that request order is preserved and unknown symbols return found=false rather than causing failure.

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

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

The description states a specific batch operation: latest PER, PBR, dividend yield, dividend, streak, and 3y/5y CAGRs for up to 50 companies in one call. It explicitly names get_key_metrics_latest and clarifies that this is the batch equivalent, making it distinguishable from the single-company sibling.

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

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

It gives explicit guidance to prefer this over repeated get_key_metrics_latest calls when comparing or screening a list. It also explains how missing symbols behave, removing ambiguity about whether an unknown ticker aborts the batch.

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

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

The annotations already declare readOnlyHint=true, so the description does not need to repeat that safety profile. Beyond that, it discloses two real behaviors the agent could not otherwise infer: that results follow the request order, and that unknown symbols return found=false rather than failing the whole call. It does not cover pagination, and for a batch read the cost or latency per symbol, but the partial-failure semantics are the important part.

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

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

The English text is front-loaded with the returned fields, then the alternative tool, the behavior, and the date format — every sentence earns its place. The main cost is the full Japanese restatement, which roughly doubles the length; however, that serves a localization purpose, and the structure remains scannable.

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

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

This is a one-parameter batch read with no output schema, and the description still specifies the returned fields, the ordering guarantee, the handling of unknown symbols, and the ISO 8601 UTC format with a Japan-time conversion note. Nothing an agent needs in order to call it correctly and interpret the result is missing.

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

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

The schema description coverage is 100%, so the parameter's comma-separated 4-digit code format and 50-symbol cap are already documented and the baseline would be a 3. The description adds value by tying the found=false behavior to the symbols the caller submits, which tells the agent how to map output back to input, along with the hard limit of 50, so it earns a 4 rather than the baseline.

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

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

The description names a specific verb and resource: it retrieves the latest price, price date, change percentages and market cap for up to 50 companies in one call, and it explicitly states that these are the same fields as get_quote. It also distinguishes itself from the sibling get_batch_key_metrics_latest, so an agent can select the correct tool without opening either schema.

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

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

It states both when to use this tool ("Prefer this over repeated get_quote calls when comparing a list") and which tool to use instead when different fields are needed ("For PER, dividend yield and CAGRs of a list use get_batch_key_metrics_latest"). This explicit routing and its exclusions leave nothing to inference.

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

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

readOnlyHint already covers the safety profile. The description adds useful output-shaping context (results are a history/time series, dates are ISO 8601 UTC, date-only fields use YYYY-MM-DD) which matters because there is no output schema, but it omits currency/units, whether figures are consolidated, and pagination behavior beyond the schema's limit.

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

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

The purpose is front-loaded in the first clause, but the entire date-format section is stated twice in English and Japanese, and the timezone conversion note is verbose for what it conveys. Roughly half the text is duplication rather than new information.

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

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

With no output schema, the description should characterize returned data more fully. It handles date formatting well but says nothing about units, currency, sign conventions, or the shape of free-cash-flow figures, leaving meaningful gaps for a financial-statement tool.

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

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

Schema description coverage is 100%, so symbol, period, and limit are already documented in the schema. The description adds no meaning about parameter interaction (e.g., how limit interacts with period filters), so the baseline 3 applies.

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

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

States a specific resource: historical cash flow statements, explicitly including free cash flow. This distinguishes it from get_income_statement and get_balance_sheet, though it does not name or contrast with the closest sibling, get_full_financial_statement.

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

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

Usage is only implied by the resource name — an agent can infer this is the tool for cash flow time series, but there is no explicit when-to-use, when-not-to-use, or pointer to an alternative such as get_full_financial_statement for a complete statement set.

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

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

With readOnlyHint already declaring a safe read operation, the description adds substantive behavioral context: it defines the annual dividend treatment and explains the preferred-share/assetType edge case. It still omits data freshness or error behavior, so it is not fully comprehensive.

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

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

The description is front-loaded and compact for the amount of return-field and edge-case detail it conveys. The bilingual restatement is somewhat duplicative and the parentheticals make it dense, but nothing is clearly extraneous.

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

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

Because there is no output schema, the description carries the burden of describing return content, and it covers profile fields, valuation metrics, dividend semantics, and preferred-share handling. Remaining omissions such as data freshness or currency details are minor for this read-only profile tool.

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

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

Schema coverage is 100%, so the symbol format and example are already documented in the input schema. The description does not directly define the symbol parameter, and its 5-digit preferred-share note concerns output classification rather than adding clear input syntax beyond the schema.

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

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

The description names the resource and enumerates the profile plus latest valuation fields the tool returns. It is specific enough to separate it from unrelated siblings like get_historical_prices, but it does not explicitly contrast with overlapping siblings such as get_quote or get_key_metrics_latest.

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

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

There is no explicit when-to-use or when-not-to-use sentence, and it does not name alternatives among the many sibling tools. The field list implies the tool is for company profile and latest valuation lookups, but selection between this and get_quote/get_key_metrics_latest is left to inference.

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

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

readOnlyHint=true already covers the safety profile, so the bar is lower, and the description still adds meaningful context: the data source (annual securities report), the unit of all amounts (yen), the fact that both current and prior-year carrying amounts are returned, and the presence of aggregates. Gaps remain around empty results for companies with no strategic holdings and record-volume/pagination behavior.

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

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

The purpose and field list are well front-loaded, but the body is padded: the full Japanese translation restates the English verbatim, and two separate paragraphs explain ISO 8601 date formatting for a tool with only two parameters. The date-time formatting note is boilerplate that does not change how an agent calls this tool.

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

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

With no output schema, the description carries the full return-value burden and discharges it by naming each returned field plus the aggregation dimensions and currency. A three-file-level question about strategic holdings can be answered or routed correctly from this text alone.

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

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

Schema coverage is 100% and both parameters are documented there, including the 4-digit ticker example and the YYYY-MM pattern with the omit-for-latest default, so the baseline is 3. The description adds only indirect meaning, tying fiscalPeriod to annual securities report coverage rather than explaining fiscal-period edge cases (e.g., non-March year ends).

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

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

The opening question states the exact resource and its scope: shares the company holds for strategic (non-investment) purposes, explicitly excluding pure investment holdings. It then enumerates the returned fields (issue name, shares held, carrying amount current/prior year, holding purpose) and the aggregates by purpose and listing status. An agent can distinguish this from holder-side siblings such as get_major_shareholders or get_large_holders without opening any schema.

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

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

Usage is implied rather than stated: the annual-securities-report framing and the strategic-vs-pure-investment split signal when this tool applies, and the schema notes that omitting fiscalPeriod yields the latest report. However, no sibling tool is named as an alternative, and there is no explicit when-not-to-use guidance (e.g., use get_major_shareholders for who owns the company).

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds useful context beyond that: default time window, JST basis for the bounds, and the fact that records are sourced from TDnet documents. It says nothing about pagination, ordering, or how the 200/500 limit affects results.

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

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

The core scope and default are front-loaded in the first sentence. The bilingual repetition and the date-format explanation add length, and the YYYY-MM-DD statement partly duplicates the schema's regex pattern, but the JST-versus-UTC distinction genuinely needs spelling out.

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

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

For a four-parameter, read-only listing tool with no output schema, the description covers scope, defaults, timezone semantics, and the fields returned. Only pagination and result ordering are left unaddressed, which is a minor gap given the schema carries the limit bounds.

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

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

Schema coverage is 75%, and the description compensates by clarifying that from/to are JST dates rather than UTC, which the schema does not say. It also reinforces the 'today' default for `from`. The `limit` parameter remains undocumented in the description, but its bounds and default are fully specified in the schema.

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

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 ('Scheduled and completed delistings of Japanese listed companies') and names the returned fields (delisting date, status, source TDnet document). It is clearly distinguishable from every sibling, none of which cover delistings, though it does not explicitly contrast itself with any of them.

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

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

It states the default scope ('Defaults to delisting dates from today onward'), which is genuine usage guidance, and the JST semantics of from/to imply how to widen the window. It never says when not to use it or points to any alternative tool for related corporate-action data.

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

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

readOnlyHint=true already covers the safety profile, and the description adds meaningful context beyond it: the upstream source (annual securities report), that amounts are in yen, and that the ¥100M+ named-officer list is consolidated-basis while the by-category aggregates are not. It does not state what is returned when compensation is undisclosed, which is the main remaining gap.

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

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

The lead sentence and the resource enumeration are well front-loaded, but the text then repeats everything in Japanese and appends a two-sentence date-formating boilerplate twice (ISO 8601 UTC, add 9 hours for Japan time) that is irrelevant here — the schema has no date-time fields and results are keyed by fiscal year. A substantial fraction of the description does not earn its place.

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

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

With no output schema, the description does the right work by enumerating the returned blocks (totals, by-type breakdown, head-count, named officers) and the unit (yen), so an agent knows what comes back. It falls short only on edge-case handling such as companies with no disclosed compensation or partial disclosures.

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

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

Schema description coverage is 100%, with both symbol and fiscalPeriod fully documented including format and the 'omit for latest annual report' default, so the schema carries the burden. The description adds nothing about the parameters themselves, so baseline 3 applies.

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

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

The description names the exact resource and enumerates its contents: total remuneration, by-type amounts (base, bonus, stock options, performance-linked, non-monetary), head-count per officer category, and named officers earning ¥100M+. This is far more specific than the title, and the 'annual securities report' source makes it distinguishable from siblings like get_directors (roster) or get_audit_fees.

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

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

Usage is only implied: the agent can infer this is the tool for pay levels because the description states the source document and the exact data returned. There is no explicit when-to-use statement and no mention of how this differs from get_directors or where compensation data is unavailable, so the agent must infer the routing.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description only needs to add context beyond that. It does add useful context: the data originates from the annual securities report (implying reporting lag and an official filing source), and it specifies the exact date and datetime encodings including the JST offset rule. It does not say what happens when no report exists for a company, whether results are ever empty versus an error, or anything about response size.

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

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

The payload list is front-loaded well and is genuinely informative, but the entry is padded by full English/Japanese duplication and by a date-format paragraph repeated in both languages. That format note is boilerplate that likely applies to many sibling tools and consumes roughly a third of the text. The rhetorical opener 'Who runs the company?' is pleasant but not load-bearing.

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

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

With no output schema, the description carries the burden of describing returns, and it does so thoroughly by enumerating every field plus the derived gender counts and 0–1 female ratio. A caller can predict the shape of the response. What is missing is only edge-case behavior, such as what is returned for a company without a filed annual report.

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

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

Schema description coverage is 100%, so the schema already explains that symbol is a 4-digit ticker with a Toyota example and that fiscalPeriod is YYYY-MM with omission meaning the latest report. The description adds no further meaning to either parameter; the date-format note is about returned values rather than inputs. Baseline 3 is appropriate.

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

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

The description opens with a concrete scoping question and then names the exact resource (directors and corporate auditors from the annual securities report) along with the specific fields returned: title, name, date of birth, term, shares held, career summary, plus gender counts and female ratio. That is a specific verb-plus-resource statement an agent can match to a request. It does not, however, explicitly differentiate itself from near neighbors such as get_director_compensation or get_diversity_metrics, which also touch officer data.

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

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

There is no explicit when-to-use or when-not-to-use guidance. Nothing tells the agent that officer pay belongs to get_director_compensation, that board-level gender ratios might also be surfaced by get_diversity_metrics, or that get_company_profile is the place for general corporate facts. The only implied guidance is the phrase 'from the annual securities report', which hints at the data source but not at tool selection.

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

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

Beyond readOnlyHint=true, it discloses the token cost (10), the 93-day maximum window, the download route /stable/filing-document with no age limit, and a redistribution restriction — real behavioral context an agent cannot get from annotations. It omits pagination behavior and how the limit parameter affects result completeness.

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

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

Key facts are front-loaded, but the entire content is duplicated verbatim in Japanese, and the timezone/format rule appears twice within the English text, roughly doubling length without adding information. An agent reading one language gets everything, so the second pass is pure overhead.

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

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

For a read-only listing tool with no output schema, it covers cost, date-window limits, timezone conventions, and how to fetch the actual PDF — everything needed to call it correctly. The only gap is the undeclared limit default/ceiling semantics (100/500) and whether results are paginated.

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

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

Adds meaning beyond the schema by clarifying that from/to are JST calendar dates while returned date-times are UTC ISO 8601 (+9h for JST) and that symbol omission requires from/to — the latter is echoed in the schema, but the timezone rule is new. The limit parameter's purpose remains undocumented in both schema and description.

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

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

Opens with a specific verb+resource ('TDnet timely-disclosure document list') and enumerates the returned fields (announcement time, title, document-type code, pdfUrl). It is clearly distinguishable from the many financial-statement and profile siblings in the get_* family.

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

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

Explicitly states the two filtering modes: by company (symbol) or by date window across the whole market, and adds the precondition that omitting symbol makes from/to mandatory. It does not name a sibling alternative for overlapping disclosure/news needs, but the when-to-use context is unambiguous.

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

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

Annotations declare readOnlyHint=true, so safety is already covered; the description adds genuinely new behavior context, notably the disclosure source (annual securities report), that subsidiary rows are included, and that ratios are decimals where 0.039 means 3.9%. It does not say what happens when a company discloses nothing or how far back fiscalPeriod can reach, so it stops short of a 5.

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

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

The purpose statement is front-loaded and precise, but the entire text including the date-format paragraph is duplicated in Japanese, doubling length for no new information to an English-reading agent. The ISO 8601 / add-9-hours paragraph is boilerplate that applies to no parameter in this tool's schema, so it does not earn its place.

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

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

With no output schema, describing the returned fields was necessary and is done, along with units and the consolidated-subsidiary dimension. For a two-parameter read-only lookup this is close to sufficient; only missing-data behavior and fiscal-period range are absent.

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

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

Schema description coverage is 100% and both parameters (symbol, fiscalPeriod) are documented in-schema with examples and the omit-for-latest rule, so the description need not repeat them. The unit convention (0.039 = 3.9%) does add interpretation value for what the symbol/fiscalPeriod pair will yield, but is not per-parameter guidance; baseline 3 applies.

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

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

States a specific resource (diversity indicators disclosed in the annual securities report) with an explicit scope (the reporting company plus each consolidated subsidiary) and enumerates the three metrics returned: women managers ratio, male childcare-leave rate, and gender wage ratio. An agent can distinguish this from siblings like get_workforce or get_employee_count on the strength of the metric list alone.

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

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

Usage is only implied: an agent infers it should call this when it needs ESG/diversity disclosure figures for a ticker. The only explicit conditional is in the schema (omitting fiscalPeriod gives the latest annual report), and the description never names a sibling or says when another tool (e.g. get_workforce for headcount) is the better choice.

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

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

Annotations only declare readOnlyHint, and the description adds real behavioral context: the 2026-05-18 detection cutoff, what a null changeFlag means and that such rows are excluded when filtering, and a stated cost of 10 tokens. It does not describe pagination/limit behavior across the 500-row cap, so it falls short of full disclosure.

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

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

Front-loaded with the core purpose, but the entire text is duplicated in Japanese, roughly doubling length, and the date-format guidance is repeated twice within the English portion. The information is useful but the delivery is padded.

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

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

With no output schema, the description names the returned fields (previous vs new dividend, change rate, implied yields, source document) and explains the null-flag edge case. The only gap for a 5-parameter filtered-list tool is pagination/limit behavior near the 500 maximum.

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

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

Schema coverage is 80%, yet the description adds meaning the schema does not carry: from/to are JST dates while timestamps are UTC ISO 8601, symbol omission means whole-market scan, and the null-changeFlag semantics are restated in context. The limit parameter remains undocumented beyond its numeric bounds.

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

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

States a specific verb+resource: annual-dividend revisions detected from TDnet earnings releases, with the fields returned (previous vs new dividend, change rate, implied yields, source document). It explicitly separates itself from the sibling get_dividends by time coverage, so an agent can choose without opening either schema.

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

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

Gives explicit when-to-use (omit symbol to scan the whole market for a date window), an explicit exclusion (announcements before 2026-05-18 are not included), and an explicit alternative (use get_dividends for older changes) with a concrete example.

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

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

Annotations only declare readOnlyHint=true, so the description carries the real behavioral load and does so well: it defines the four status values and their meaning, mandates that compound conditions such as 'the higher of' be preserved as structure rather than collapsed to one number, and specifies numeric precision (0-1 decimals; value or range; floor/ceiling/guideline/target) plus ISO 8601 UTC date formats with the +9h Japan offset. It does not state the response envelope or how many records are returned, which is the remaining gap.

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

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

The English content is dense but well front-loaded: resource first, then fields, then status semantics, then formats. However, the Japanese text restates the English almost verbatim, including the ISO-date explanation twice, which is pure duplication for a single-locale reader and inflates the definition considerably.

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

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

With no output schema, the description must describe the return payload, and it largely does: field meanings, precision rules, the four-state status vocabulary, and the structural requirement for compound conditions. For a one-parameter read tool this covers nearly everything an agent needs, short of naming sibling alternatives.

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

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

There is a single required parameter with 100% schema description coverage ('4-digit Japanese ticker code / 4桁の証券コード (e.g. "7203" = Toyota)'), so the schema already does the work. The description adds no constraint on symbol, such as whether a 5-digit code or an EDINET code is accepted or what error occurs for an unknown ticker. Baseline 3 applies.

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

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

The description names a specific resource with scope: 'Verified dividend policy of one Japanese company,' and enumerates the content (DOE / payout ratio / total return ratio targets, progressive-dividend stance, minimum dividend, effective period, quotes). That distinguishes it implicitly from payment-history siblings like get_dividends and get_dividend_changes. It never names a sibling explicitly, so it stops short of a 5.

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

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

There is no explicit when-to-use or when-not-to-use statement and no named alternative (e.g. list_dividend_policies for screening many companies, get_dividends for actual paid amounts). Usage is only implied by the enumerated content and by the 'status' semantics. The one strong guideline — not_collected means 'not collected,' NOT 'no policy' — is interpretation guidance rather than tool selection guidance.

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

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

With readOnlyHint=true already declaring the safety profile, the description adds genuinely useful behavior: record ordering differs depending on whether from/to is present, limit truncation emits a continuation hint, and same-ex-date rows are grouped so a call may exceed limit (with a concrete 7203 example). However, this is the strongest area and it still omits error behavior for invalid tickers and any indication of response envelope shape beyond the field list.

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

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

The purpose is front-loaded and the substantive content (ordering, continuation, grouping overshoot, timezone) all earns its place. But the entire description is duplicated in Japanese and the timezone/format rules are restated twice even within the English text, roughly doubling length for an agent that needs only one pass.

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

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

For a read-only, 4-parameter list tool with no output schema, the description covers ordering, pagination continuation, grouping edge cases, and date/time formatting thoroughly. The remaining gap is sibling disambiguation and failure behavior, which are relevant given the many neighbouring dividend tools.

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

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

At 75% schema coverage the description goes well beyond the schema: it clarifies that from/to filter on ex-dividend date (inclusive) in JST while the schema only says 'earliest/latest ex-dividend date', and it explains the interaction between limit and same-date grouping that can push a response past the limit. The undocumented limit parameter's default (40), maximum (100), and overshoot behavior are all covered.

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

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

The first sentence states a specific resource (dividend history) and enumerates the exact fields returned (ex-dividend date, payment date, announcement date, split-adjusted amount, forecast/actual), so an agent knows precisely what data it gets. It does not, however, distinguish itself from close siblings such as get_dividend_changes, get_dividends_calendar, or get_dividend_streaks, leaving that discrimination to the caller.

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

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

It gives clear operational context: call without from/to for the newest records, pass from/to for older periods, and expect a continuation 'to' value in the response only when from/to were supplied. It does not state when this tool should be preferred over the sibling dividend tools, so it stops short of full alternative routing.

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

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

Annotations only declare readOnlyHint, and the description substantially exceeds that: it discloses the 10-token cost, the 93-day window cap, result ordering, the fact that busy days exceed 2,000 rows, and the exact pagination recovery step. It also resolves timezone behavior (from/to in JST, date-times in UTC with a +9h conversion note), which is real operational context an agent would otherwise get wrong.

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

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

Front-loaded with the core purpose, window cap, cost, and pagination recovery before the formatting details each sentence earns its place. The cost is that every point is stated twice in English and Japanese, which roughly doubles length for an agent reading only one language, though the duplication appears intentional for a Japan-market tool.

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

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

For a read-only, five-parameter list tool with no output schema, the description covers the window cap, ordering, filtering, pagination, token cost, and date/time formatting, which is everything needed to call it correctly. The only minor omission is the limit parameter's behavior.

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

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

Schema coverage is 80%, and the description adds meaning the schema lacks: from/to are Japan-time dates and date-time fields return UTC. It also contextualizes symbol (one company) and offset (next page after truncation). The one gap is limit, which has no description in either the schema or the description.

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

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

States a specific resource and scope: 'Upcoming/past ex-dividend dates across the whole market within a date window', plus ordering ('ex-dividend date then symbol') and a per-company mode. This clearly separates it from per-company dividend tools, but it never names the closest siblings (get_dividends, get_dividend_changes, get_earnings_calendar), so the agent must infer the boundary itself.

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

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

Gives concrete usage conditions: pass symbol for a single company, omit for market-wide, and re-call with the given offset when the result reports more rows. However, there is no explicit 'use X instead when...' routing against the sibling dividend tools, so the when-not-to-use side is absent.

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

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

Annotations only supply readOnlyHint, and the description goes well beyond it: data starts in 2013, zero-dividend years break the streak, values are split-adjusted, ETF/REIT figures use calendar-year totals (two periods for a semiannual J-REIT), and the capped flags mean the streak reached the first year of the series. The meaning of capped=true as a lower bound ('N years or more', never set for 0) is exactly the kind of subtle behavior an agent would otherwise misread.

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

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

The answer to the core question is front-loaded and every English sentence carries substantive information (streak definitions, 2013 cutoff, capped semantics, ETF/REIT handling). The main cost is the full Japanese restatement, which duplicates content and roughly doubles length, plus the parenthetical-packed final sentence.

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

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

With no output schema and a readOnly annotation, the description carries the return-shape burden and does so: it names the fields returned and explains the capped sentinels. Minor gaps remain — currency/units for the per-share amounts and the exact ordering/shape of the per-fiscal-year list are not spelled out.

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

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

Schema coverage is 100% and both parameters are documented in the schema, so the baseline of 3 applies. The description adds context for the returned per-year dividend values but says nothing extra about limit semantics (newest-first ordering, max 25) beyond what the schema already states.

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

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

Opens with a concrete framing question and then names the returned fields (consecutive-increase years, consecutive-non-decrease years, annual dividend per share per fiscal year). That clearly separates it from raw-history siblings like get_dividends or get_dividend_changes, but no sibling is named explicitly, so the differentiation is inferred rather than stated.

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

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

Usage is implied by the 'how many years in a row...' framing, which tells an agent this is the streak-summary tool rather than the raw dividend series. However, there is no explicit statement of when to prefer it over get_dividends / get_dividend_changes / get_dividend_policy, and no prerequisites or exclusions are given.

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

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

Annotations only supply readOnlyHint=true, so the description carries most of the behavioral burden and does so: null semantics for fiscalPeriod/beforeAfterMarket/EPS, the consensus-vs-company-forecast distinction, JST date interpretation, and the >500-row pagination condition. It stops short of stating result ordering or exact row shape, which keeps it from a 5.

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

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

The content order is sensible, leading with what the tool returns before describing fields, but the description is very long and restates essentially the same field definitions twice in English and Japanese, inflating length without adding information for a monolingual reader.

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

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

With no output schema, the description usefully documents returned fields (fiscalPeriod, fiscalDate, beforeAfterMarket, actualEps, estimateEps) and their units, which is exactly what an agent needs to interpret rows. It omits only minor details like default sort order or the exact meaning of the surprise rate's denominator.

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

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

Schema coverage is 80%, and the description adds real meaning the schema lacks: from/to are interpreted in Japan time (JST), the offset is tied to the 'more rows exist' signal, and symbol is framed as an optional narrowing filter. The limit parameter is left entirely to the schema.

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

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

States a specific verb-like resource and scope: 'Upcoming and past earnings announcement dates for Japanese listed companies,' plus the payload (actual vs estimated EPS, surprise rate). It implicitly separates itself from the forecast sibling by noting 'the estimate is a market consensus, not the company forecast,' though it never names get_earnings_forecast directly.

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

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

Gives concrete invocation guidance: pass symbol to narrow to one company, and re-call with the given offset when 'more rows exist.' However, there is no explicit when-to-use vs alternatives such as get_earnings_forecast, get_events_feed, or get_dividends_calendar, so the agent must infer routing.

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

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

The annotations only declare readOnlyHint, while the description adds substantive behavioral context: row-to-fiscal-year mapping, null handling for withheld guidance, the 0–1 ratio scale, and ISO 8601 UTC date conventions. It does not describe response shape or error behavior, but it provides considerably more than the 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.

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

The core purpose and output semantics are front-loaded and organized clearly. The full Japanese translation repeats the English content and the date-format guidance is repeated, adding some redundancy, but the overall structure remains readable and purposeful.

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

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

For a read-only retrieval tool with no output schema, the description covers the returned forecast metrics, row semantics, null handling, ratio scale, and date formats. It mentions forecastTarget without defining it and does not describe the overall response structure, but the definition is broadly sufficient for correct use.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining that FY rows carry next fiscal year guidance while Q1–Q3 rows carry current fiscal year guidance, which clarifies the period filter’s effect; it adds little for limit or symbol beyond what the schema already says.

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

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

The description states that this tool returns company guidance from each earnings release, with specific metrics such as revenue, operating income, net income, EPS, and derived ratios. The forecast/guidance framing distinguishes it from actual financial statement siblings, but it does not explicitly name an alternative tool, so it falls short of the strongest sibling differentiation.

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

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

It explains how FY versus Q1–Q3 rows should be interpreted and that withheld guidance is null, which gives meaningful usage context. However, it does not say when to choose this tool over get_income_statement, get_key_metrics, or other financial siblings, and it gives no explicit exclusions.

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

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

readOnlyHint=true already covers the safety profile, so the description's main contribution is the non-obvious output behavior: the data source appears once in a note after the result, not per row. That is genuine behavioral context an agent could not get from annotations or schema. It does not discuss rate limits or coverage gaps for untracked series.

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

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

Front-loaded with purpose, then default window, then the source-note quirk, so the most important facts come first. The Japanese sentence duplicates the English content, which is localization overhead rather than new information, but it is brief.

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

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

With no output schema, the description must carry return-value expectations, and it does explain that results are a schedule bounded by date and that the source is in a trailing note. Coverage of what fields each entry contains is thin, and it does not clarify what 'tracked' series means in practice.

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

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

Schema description coverage is 100%, with both from/to documented including their defaults, so the schema carries the load. The description only restates the 30-day default in prose, adding no format or constraint detail beyond what the schema already provides.

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

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

States a specific verb+resource ('Upcoming release dates for the tracked macroeconomic series') with examples (CPI, jobs report, GDP) and a default scope of the next 30 days. It is clear what it returns, though it does not explicitly distinguish itself from near-neighbors like get_earnings_calendar or get_dividends_calendar.

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

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

The default window and the 93-day maximum (in the schema) imply when this tool applies, but there is no explicit when-to-use guidance versus get_economic_series or get_economic_indicators, which return actual data rather than schedules. The distinction is inferable from the names but not stated.

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

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

readOnlyHint is already supplied by annotations, so the safety profile is covered; the description adds genuinely new behavior — the source attribution appears once in a note after the result, and the result carries bilingual labels plus unit and frequency. The ISO 8601/UTC and +9h Japan-time conventions are disclosed but look like boilerplate that is not clearly relevant to a static catalog.

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

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

The lead sentence and the "call this first" instruction are well front-loaded, but the entire content is then duplicated in Japanese and followed by date-format boilerplate that a metadata-listing tool arguably does not need. Roughly half the text is redundant, diluting the actionable guidance.

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

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

With no output schema, the description carries the burden of describing the return value, and it does — series names in two languages, unit, frequency, and a post-result source note. What is missing is any hint of result size or pagination, which matters for a catalog spanning two economies.

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

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

Schema coverage is 100% and the single enum parameter is already documented as "Filter by country / 国で絞り込み". The description implies the US/JP split via its enumeration, but adds no filter semantics (e.g. what happens when country is omitted and whether all series are returned) beyond what the schema provides, so the baseline 3 applies.

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

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

The description opens with a specific verb plus resource ("List the available macroeconomic series") and enumerates exactly what is covered — CPI, unemployment, payrolls, Fed funds, Treasury yields, GDP, USD/JPY, and the Japan equivalents — along with the returned metadata (ja/en name, unit, frequency). That is enough for an agent to distinguish it from get_economic_series, which fetches values rather than the catalog.

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

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

"Call this first to find a series id for get_economic_series" gives an explicit ordering and names the tool it feeds, which is exactly the routing an agent needs. It stops short of a when-not condition (e.g. that this returns no actual data points), so it falls just short of a full 5.

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

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

With readOnlyHint=true already supplied, the description adds real context: results are newest first, metadata is bundled with observations, attribution carries the single data-source credit, and discontinued series have stopped updating at the source. It stops short of disclosing truncation/pagination behavior when limit is smaller than the available history.

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

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

Core facts are front-loaded: what is returned, where ids come from, then the discontinued-series caveat and date formats. The one efficiency cost is that nearly every sentence is restated in Japanese, roughly doubling length without adding new information for a single-language reader.

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

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

There is no output schema, so the description must carry the return shape — and it does, specifying date/value pairs, embedded series metadata, and the attribution field. The only gap is what happens when limit cuts off the requested range or when from/to span no observations.

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

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

Schema coverage is 100%, with each parameter already documented including the YYYY-MM-DD pattern, default 100 and maximum 5000. The description reinforces the id format with example codes and the date conventions, and clarifies that limit/ordering return newest first, but adds little the schema does not already state.

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

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

Names a specific verb and resource — observations (date, value) for one macroeconomic series — plus ordering ('newest first') and the accompanying metadata. It also names the sibling get_economic_indicators as the source of valid ids, so an agent can distinguish it from that tool without opening either schema.

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

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

Explicitly routes the agent to get_economic_indicators to obtain series ids and explains how to interpret series flagged discontinued: true, including the replacementId substitute. It does not state when to avoid this tool or how it differs from the broader get_economic_indicators call beyond the id lookup.

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

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

Annotations only declare readOnlyHint=true, and the description adds the operationally important behavior: a missing annual report is not an error but a null field, an unknown symbol returns an empty array, and sibling annual-report tools 404 in that case. This null-vs-empty-array-vs-404 distinction is exactly the kind of error-semantics context an agent cannot get from structured fields.

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

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

The English text is front-loaded with the definition and then the failure semantics, with no wasted clauses. The full Japanese restatement doubles the length for the same content, which is a deliberate localization choice but still redundant volume from an agent's perspective.

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

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

There is no output schema, and the description compensates by naming the returned field (employeeCount) and enumerating its null and empty-array cases. For a single-parameter read tool, nothing an agent needs in order to call it correctly or interpret the result is missing.

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

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

Schema coverage is 100% and the sole parameter is documented with a concrete example, so the baseline is 3. The description still adds meaning beyond the schema by specifying how a bad or unknown symbol resolves (empty array rather than an error), which directly informs how to interpret the symbol argument's failure mode.

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

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

States a specific resource (employee count), a specific source (latest annual securities report), and the consolidation basis (consolidated, falling back to the reporting company alone). It also names the sibling get_workforce and explains how it differs, so an agent can distinguish the two without opening either schema.

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

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

Gives clear eligibility context: listed companies with no annual securities report yield employeeCount: null rather than an error, and unknown symbols yield an empty array. It explicitly contrasts this with get_workforce, which 404s in the same situation. It stops short of an explicit 'prefer this tool when...' directive, so it lands at 4 rather than 5.

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

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

Beyond the lone readOnlyHint annotation, the description discloses the most decision-relevant trait: data is report-based and refreshes only about twice a year, not daily, and metricDate reflects the report's 'as of' date. It further enumerates the exact cases that yield null (ETNs, no first report, no EDINET filing, PDF-only foreign funds), which is precisely the failure-mode context an agent needs.

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

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

The content is front-loaded and each English clause carries real information, but the entire passage is duplicated in Japanese, roughly doubling length without adding new facts for a single reader. The bilingual pattern is defensible for audience reach, yet it dilutes conciseness relative to a tight single-language statement.

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

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

With no output schema available, the description carries the full burden of explaining return values, and it does so: both fields, their meaning, their timestamps, and their null conditions. For a one-parameter read-only lookup, nothing material is missing.

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

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

Schema coverage is 100% and the single symbol parameter is already documented with format and an example in the schema. The description adds no further meaning about symbol handling or ETF-vs-stock code behavior, so the baseline of 3 applies.

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

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

The description names the resource precisely ('Net assets and distribution yield for a Japanese ETF') and enumerates the two returned fields, which separates it from equity-metric siblings like get_key_metrics or get_key_metrics_latest. It stops short of naming any sibling explicitly, so the distinction is inferred rather than stated.

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

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

Usage is implied through the negative scope: NAV per unit, units outstanding, premium/discount and tracking difference are declared out of scope, which steers the agent away from misusing this tool. However, there is no explicit 'use this when… / use X instead when…' routing against list_etfs or get_key_metrics, leaving the choice to inference.

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

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

readOnlyHint is already declared, and the description adds substantial context: the default 365-day window, the market-wide 31-day cap, the coverage boundary for dividend-change detections starting 2026-05-18, and the interpretation rule that a null details.changeFlag means neither an increase nor a cut (share basis undetermined after a split). The one gap is that it does not explain how the maximum limit of 500 is enforced or what happens if more events exist inside the range.

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

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

Content is front-loaded with the scope statement, but the full description and caveats are duplicated verbatim in Japanese, roughly doubling length without adding information for an English-reading agent. The opening rhetorical question 'What happened recently?' is decorative rather than informative. Removing the duplication would make it noticeably tighter.

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

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

For a five-parameter, no-output-schema aggregation tool, the definition covers the important pieces: sort order, date and datetime encodings with a JST offset note, filter values, mode-dependent range rules, and the dividend-change coverage start date. It could say more about the shape of returned records (for example the details.changeFlag nesting it references) but is otherwise sufficient to call correctly.

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

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

With schema coverage at 80%, the schema already documents to, from, types and symbol, so the baseline is 3. The description adds real meaning beyond it: the interplay between omitted symbol and required from/to, the 31-day maximum for whole-market queries, the 365-day default for single-company queries, and the explicit filter-by-types behavior. Only `limit` is left entirely to the schema.

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

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

The description names a concrete verb-plus-resource: a single date-sorted feed that aggregates TDnet timely disclosures, EDINET extraordinary reports, dividend changes, splits and delisting schedules. It also scopes the two modes (single company by default over 365 days vs whole market limited to 31 days), which lets an agent tell it apart from the narrower sibling tools such as get_disclosures, get_splits or get_delisting_schedule.

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

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

It gives explicit operating conditions: omit `symbol` for the whole market only when from/to are supplied and the range is at most 31 days, and use `get_dividends` for dividend changes detected before 2026-05-18. That covers the main routing decision and the market-wide constraint. It stops short of stating when to prefer this feed over other per-type siblings, and gives no exclusion guidance.

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

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

With readOnlyHint=true already covering safety, the description still contributes real behavioral context: result timestamps are ISO 8601 UTC (add 9 hours for JST) while from/to filters are JST date-only values, and reasons are machine-classified. It omits return shape, ordering, and whether the 50/100 limit implies pagination, so it stops short of full disclosure.

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

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

Purpose and scope are front-loaded correctly, but the English/Japanese duplication inflates the text and the promotional line 'Corporate-event data no competing Japanese API exposes' does not help an agent decide or call. The timezone rule is stated effectively twice before the JST filter clarification is added.

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

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

For a read-only, filter-only feed with no output schema, the description covers what is returned (classified extraordinary-report events), the filter axes, and the timezone semantics needed to interpret both inputs and outputs. Remaining details like default ordering are minor.

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

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

Schema coverage is 80%, so a baseline of 3 would apply, but the description adds a genuinely non-obvious constraint: from/to are Japan-time dates even though the payload timestamps are UTC. Combined with the reason-key examples and sibling list tool in the schema, the parameters are well understood.

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

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

States a specific resource (EDINET 臨時報告書 / extraordinary reports), what it delivers (a feed with machine-classified reasons), and enumerates the reason classes. This clearly separates it from siblings like get_events_feed or get_disclosures, so an agent can pick it without opening the schema.

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

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

The description gives scope options — 'Query by company or across the whole market for a date range' — which implies how to call it, but never states when to choose it over get_disclosures, get_events_feed, or get_extraordinary_report_reasons, nor any exclusions. The pointer to the reasons sibling exists only in the schema, not the description.

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

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

readOnlyHint=true already establishes this is a safe read, so the description's job is to add return context — which it does by disclosing that results carry Japanese/English labels and a category, and by naming the actual key vocabulary. It does not state ordering or whether unknown categories error, which is the only remaining gap.

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

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

Front-loaded with the payload (enumerated keys) and the routing instruction in two tight sentences. The Japanese half is a verbatim restatement, which is redundant for most agents but serves the stated ja/en bilingual audience.

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

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

With no output schema and one optional filter parameter, the description has to sketch the return shape itself, and it does: keys plus ja/en labels plus category. A note about whether the list is stable/cacheable would make it complete, but an agent can call this correctly as written.

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

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

Schema coverage is 100% with a single enum parameter whose six values and per-value meaning are already in the schema. The description does not expand on what each category contains, so it adds nothing beyond the structured field — baseline 3 applies.

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

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

States a specific verb and resource ('List the reason keys that classify EDINET extraordinary reports'), enumerates actual example values, and distinguishes itself from the sibling get_extraordinary_report_events by positioning itself as the master lookup feeding that tool's `reason` field.

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

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

Explicitly tells the agent the workflow: use a returned key as `reason` in get_extraordinary_report_events, and omit the category filter for all values. There is no equivalent alternative master-list tool among the siblings, so the absence of when-not guidance costs nothing.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered; the description adds real value by spelling out the full returned field set (location, segment, equipment, book values breakdown, headcount) and their units (yen, area). It does not mention pagination, historical depth limits, or what happens when a company reports no overseas subsidiaries.

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

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

The core enumeration is front-loaded and efficient, but every clause is duplicated verbatim in Japanese, roughly doubling length beyond what an English-reading agent needs. The trailing ISO 8601 / JST conversion boilerplate appears to be generic template text with little relevance to a book-value and headcount dataset.

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

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

With no output schema, the description correctly compensates by enumerating the return columns and their units, which is the main thing an agent needs to decide whether to call it. Missing are caveats on history depth and coverage gaps for companies that omit the facilities section.

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

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

Schema description coverage is 100%, including the YYYY-MM pattern and the omit-for-latest default, so the schema carries the parameter burden. The description only reinforces the source document (annual securities report), which implicitly motivates fiscalPeriod but adds no new syntax or edge-case guidance.

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

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

The description opens with a framing question and then names the exact resource (major facilities from the annual securities report) and its granularity (one row per site), then enumerates the columns returned. This lets an agent distinguish it from near-neighbours like get_subsidiaries, get_segments and get_workforce without opening the schema.

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

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

Usage is only implied by the rhetorical question 'Where does the company operate?' and by the mention of the annual securities report as the source. There is no explicit when-to-use statement, no exclusion naming a sibling (e.g. use get_segments for segment financials), and no note about how far back fiscalPeriod can go.

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

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

The annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds genuinely useful context about what the score is (a proprietary volatility-based composite, not a standard published index) and what fields come back, but it says nothing about refresh cadence, update frequency, or licensing/limits.

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

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

The return-content sentence is front-loaded and earns its place, but the remainder is largely duplicated boilerplate: the Japanese restatement of the score name and a two-language ISO 8601 date-format note that is irrelevant to a zero-parameter tool whose described outputs contain no date fields. Roughly half the text is noise for this specific tool.

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

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

With no output schema and no parameters, the description must carry the return shape, and it does: numeric score, qualitative label range, previous close, one-month-ago comparison, and components. The only shortfall is that 'components' is unspecified — an agent cannot tell how many sub-indicators or what they are named.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain and the baseline applies. Nothing in the description misleads about inputs.

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

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

The description names a specific resource (current market sentiment score 0-100) and enumerates the payload: label, previous close, one-month-ago score, and components. That is enough to separate it from sibling metrics like get_market_breadth or get_sector_performance, though it never names an alternative explicitly to sharpen the distinction.

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

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

There is no explicit when-to-use statement, no exclusions, and no pointer to sibling tools such as get_market_breadth or get_technical. Usage is only implied by the phrase 'Current market sentiment score', which an agent can infer, but the definition does nothing to route the agent among alternatives.

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

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

With readOnlyHint=true already declaring the safety profile, the description still adds two pieces of genuinely non-obvious behavior: the response is a complete hierarchical tree rather than a flat metric set, and it "Costs 10 tokens," which lets an agent weigh it against cheaper siblings. It does not disclose response size, whether multiple fiscal years are included, or latency, which matter for a presumably large payload.

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

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

Purpose and usage are front-loaded in the first two sentences, which is good. However, every sentence is duplicated in Japanese and there is a long ISO 8601 / Japan-offset formatting paragraph that appears to be boilerplate appended to the tool rather than something specific to a full statement dump; the useful content is roughly half the text.

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

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

For a tool that returns a large, unschema'd hierarchical document, the description establishes what comes back (tree, all line items) and its cost, but leaves the agent guessing on framing details such as which filings are covered when fiscalPeriod is omitted, whether prior periods are included, and how big the response can get. No output schema exists, so the description bears that burden and only partly meets it.

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

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

Schema description coverage is 100% (symbol, quarter, fiscalPeriod each documented, with enum and pattern constraints), so the schema already carries parameter meaning. The description adds nothing about parameters — not even the default behavior when quarter/fiscalPeriod are omitted (e.g. which filing is returned). Baseline 3 applies.

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

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

"The COMPLETE filed financial statement as a hierarchical JSON tree — every line item, not just headline metrics" is a specific verb+resource with explicit scope (line-item granularity, tree structure). It distinguishes itself from summary/key-metric tools, but never names the closest siblings it overlaps with (get_income_statement, get_balance_sheet, get_cash_flow, get_xbrl_facts), so an agent cannot tell from this text alone why it should pick this over a single-statement tool.

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

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

"Use this when the user asks about a specific account, footnote or breakdown that summary metrics do not cover" gives a concrete triggering condition, which is more than most tools offer. It stops short of naming an alternative for the cheaper case (e.g. use get_income_statement if only income-statement lines are needed), and gives no explicit when-not guidance.

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

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

With readOnlyHint already declaring the safety profile, the description still adds substantive behavior: a hard 5-year-per-request cap and a 10-token cost, both of which affect call planning. It stops short of describing ordering, gaps for non-trading days, or what an over-long range returns.

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

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

It is short and front-loads the resource and the 5-year cap before the cost and timezone notes. The English and Japanese sentences convey the same information, which is useful for a Japan-market tool but is still duplicated content.

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

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

For a read-only, three-parameter tool with no output schema, the description covers return content (OHLCV, adjusted series), limits, cost, and date timezone. Remaining gaps, such as row ordering or handling of non-trading days, are minor.

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

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

Schema coverage is 100%, so the schema already carries defaults and formats, making 3 the baseline. The description adds genuinely new meaning by stating that from/to are JST calendar dates, a timezone fact absent from the schema's own parameter text.

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

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

The description names a specific verb+resource: daily OHLCV history, raw and split-adjusted, scoped to a symbol and date range. It is clearly distinguishable from quote/technicals-style siblings by the 'daily history' and 'split-adjusted' phrasing, though no sibling is named explicitly.

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

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

It provides real operating constraints (max 5 years per request, 10-token cost, JST date semantics) that imply how to call it, but never states when to choose this over get_quote, get_technicals, or get_market_cap_history, nor what to do when a range exceeds 5 years.

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

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

With readOnlyHint already declaring the safety profile, the description adds genuinely useful behavioral context: dual upstream sources (TDnet same-day vs EDINET), row-level provenance (doc_id + EDINET URL), and non-obvious derivation rules for revenue, grossProfit and operatingIncome under Japanese GAAP. It does not cover ordering beyond the schema, error/empty behavior, or rate limits, so it stops short of a 5.

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

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

The purpose and the GAAP caveats are correctly front-loaded, but every sentence is duplicated verbatim in Japanese, including the ISO 8601 datetime explanation and its 'add 9 hours' note, roughly doubling length without adding information. The core content is worthwhile; the structure is padded.

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

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

For a financial-statement tool with no output schema, the description covers the hard parts an agent would otherwise get wrong: the retailer/operating-revenue revenue formula, the operatingIncome derivation, and timestamp conventions. It omits the reporting units/currency scale of the figures, which is a meaningful gap for a numeric tool, and says nothing about how rows are ordered beyond the schema's 'newest first'.

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

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

Schema description coverage is 100%, so symbol, limit and the period enum are already fully documented, and the description adds no parameter-specific meaning. The formulas it cites reference output fields (netSales, otherOperatingRevenue, operatingGrossProfit) rather than input semantics, so it neither helps nor hurts parameter interpretation.

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

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

The opening line 'Income statement (P/L) history' gives a specific verb-free but unambiguous resource and scope, and the source detail (TDnet 決算短信 / EDINET) further pins down what data this returns. It is clearly distinguishable from get_balance_sheet and get_cash_flow by resource, but it never explicitly names a sibling or states how it differs from get_full_financial_statement.

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

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

Usage is only implied by the resource name — an agent can infer 'use this for P/L time series.' There is no explicit when-to-use/when-not guidance, no mention of when to prefer get_full_financial_statement or get_xbrl_facts, and no stated prerequisites for the symbol.

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

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

Beyond readOnlyHint=true, the description discloses the outlier exclusion rules (multiples <= 0, ROE > 100%), the units convention (decimals, 0.1 = 10%), how dividend yield is computed (forecast vs. actual), the share-class/market universe exclusions, the absence of a market-cap floor, and even the token cost. These are exactly the behavioral traits annotations cannot convey.

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

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

The most important information (what it returns, what it's for) is front-loaded in the first two sentences, followed by caveats. The bilingual Japanese restatement is redundant for most readers but compact, and no sentence is filler.

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

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

With no output schema, the description carries the burden of describing return content and does so by enumerating every metric and the all-market row. Units, exclusions and cost are covered; only the exact row/response structure is left unspecified, which is a minor gap for a small two-parameter read tool.

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

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

Schema coverage is 100%, so both parameters are already documented, including the tokyoPro enum value and the 4-digit sector code pattern. The description's restatement of the tokyoPro behavior largely duplicates the schema, though the 'no market-cap floor' and preferred-share exclusions add useful framing for what the filters actually select.

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

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

The description states precisely what the tool returns: median and quartile (Q1/Q3) values for PER, PBR, PSR, EV/EBITDA, ROE, ROA, dividend yield, market cap and 3-year growth, for each of the 33 TSE sectors plus an all-market row. That is a concrete resource with a clear shape. It does not explicitly name which siblings it replaces (e.g. get_sector_performance, get_peers), so an agent must infer the boundary itself.

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

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

'Use it to judge whether a stock is cheap or expensive versus its industry' gives a concrete decision context for when to call it. There is no explicit when-not guidance or named alternative for single-company peer comparison, so the exclusion side is left implicit.

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

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

Annotations only declare readOnlyHint, so the description carries most of the burden and does add real behavior: PER/PBR/dividend yield use period-end price, ratios are 0-1 decimals, ETFs return empty, and J-REIT rows follow a 6-month cycle with annualized ROE/DOE and a 12-month dividend aggregation rule. It loses a point for not stating ordering/pagination behavior beyond the schema's 'newest first' and for a garbled sentence ('The the annual dividend...') that muddies the settlement rule.

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

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

The metric list is front-loaded and useful, but the description is bloated: the entire J-REIT and ETF explanation is repeated verbatim in Japanese, and the ISO 8601 date-format boilerplate (also bilingual) is generic across the whole tool set. Roughly a third of the text is duplication rather than added information.

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

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

With no output schema, the description carries the return-value burden and largely meets it by naming the returned metrics and explaining the tricky fields (annualDividend, dividendYield, dividendPerShare, eps) for J-REITs. Enough is present to call the tool correctly; only exact field names and row shape remain unspecified.

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

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

Schema coverage is 100%, so all three parameters are already documented. The description adds period-related context (J-REIT two-row years, annual-only dividend yield) but says nothing about limit or the annual/quarter enum beyond what the schema states, so 3 is the correct baseline.

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

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

States a specific resource (valuation and profitability metrics per period) and enumerates the metric families returned (PER, PBR, ROE, EV/EBITDA, etc.), so the agent knows exactly what data this yields. It explicitly contrasts itself with get_key_metrics_latest, making sibling discrimination possible without opening either schema.

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

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

Gives explicit routing: use get_key_metrics_latest for today's values, and get_etf_metrics / get_dividends for ETFs since this tool returns empty for them. Both a 'when to use the alternative' rule and an exclusion are stated, which is the top bar for this dimension.

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

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

Annotations only declare readOnlyHint=true; the description supplies the substantive behavior: PER uses latest annual EPS, PBR uses latest reported BPS including quarterly, priceDate is the price date used, annual dividend includes company forecast when available, and ratios are 0-1 decimals. It also explains the 'N or more' output when progressiveDividendYearsCapped is true, which is non-obvious return-value behavior.

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

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

The metric list and the sibling routing are front-loaded and earn their place, but the description is bloated by a full Japanese restatement of the same content plus a duplicated bilingual date-format note. For an agent consumer the second language block and the repeated ISO 8601 explanation are largely redundant text.

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

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

For a one-parameter read-only tool with no output schema, the definition covers computation basis, unit conventions, forecast handling, and date encoding — everything needed to interpret the returned numbers correctly. Nothing material is missing.

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

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

Schema coverage is 100% for the single `symbol` parameter, with an example ("7203" = Toyota) already in the schema, so the description adds nothing about the parameter. Baseline 3 applies when the schema fully carries parameter meaning.

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

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

States a specific resource (latest valuation and growth metrics computed with the latest close) and enumerates the exact fields returned: PER, PBR, dividend yield, annual dividend, consecutive non-decrease years, and 3y/5y CAGR of dividend/revenue/net income/EPS. It also distinguishes itself from the two nearest siblings, get_key_metrics (per-period) and get_quote (price/changes).

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

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

Explicitly routes the agent: 'For per-period values use get_key_metrics; for price and changes use get_quote.' The selection condition is stated, not implied, so an agent can choose among the three metric/price tools without opening schemas.

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

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

readOnlyHint already covers safety, so the description's job is added behavior — and it does add real substance: the data source, the temporal scope ('latest annual securities report'), the ownership-ratio scaling (0.0774 = 7.74%), and the non-obvious rule that joint holders under 5% each appear on their own row. It omits ordering and whether non-reporting issuers yield an empty set, which keeps it from a 5.

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

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

The English content is front-loaded and useful, but the definition is roughly tripled by a full Japanese restatement of every sentence plus a generic ISO 8601/UTC boilerplate block ('add 9 hours for Japan time') that is boilerplate rather than tool-specific guidance. The core facts survive trimming, so length costs it here.

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

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

With only two parameters and no output schema, the description carries the return-value burden and does it: it enumerates the returned fields (holder name, shares, ownership ratio, source document) and pre-empts the ratio-format confusion. What is missing is coverage/edge behavior — no data for non-reporting issuers, and the undocumented meaning of the total row.

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

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

Schema description coverage is 100%, so both `symbol` (with a Toyota "7203" example) and `includeTotal` are already documented; baseline 3 applies. The description adds no meaning for `includeTotal` — notably it never explains what the 'total' aggregate row contains or when to request it — so it does not exceed the schema.

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

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

States a specific resource and threshold (holders of 5%+) and pins down the exact source table (large-shareholding-report reference table in the latest annual securities report), plus the fields returned. It explicitly distinguishes itself from get_major_shareholders (top-10 table), so an agent can pick between them without opening either schema.

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

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

Gives clear context for selection by saying it 'complements get_major_shareholders (top-10 table)' and noting the Japanese equivalent (大株主本表とは別の参考表), which tells the agent this is a different table, not a different filter. It stops short of an explicit when-to-use/when-not rule, and it does not distinguish itself from the similarly named sibling get_large_holding_reports.

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

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

Annotations already declare readOnlyHint=true, so safety is covered; the description goes beyond that by disclosing that corrections are collapsed to the latest version and that unlisted-filer history is partially backfilled via a coverage field, plus the 93-day maximum window. That is genuine behavioral context an agent could not get from the annotations or schema. It stops short of describing ordering or what the coverage field actually looks like.

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

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

The core content is front-loaded and useful, but the entire description is duplicated in Japanese, including the ISO 8601 formatting explanation and the JST clarification, which roughly doubles length without adding new information for a reader who already parsed the English. The structure is otherwise scannable and every English sentence carries content.

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

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

For a six-parameter, no-output-schema read tool, the description covers what matters: the entity and fields returned, correction collapsing, three filter axes, the window cap, and a data-coverage caveat with a pointer to the coverage field. Missing only return ordering and whether 'each holder' breakdown is affected by includeHolders, both minor.

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

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

Schema description coverage is 67%, so the baseline is 3. The description does add real meaning: from/to are JST dates while other date-times are ISO 8601 UTC, the from/to range is capped at 93 days, holder is the filer's EDINET code, and symbol is the issuer ticker. It gives no semantics for limit or includeHolders, so it only partially compensates for the coverage gap.

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

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

The description opens with a concrete question ('Who crossed or changed a 5%+ stake?') and identifies the resource precisely: EDINET large shareholding and change reports, retrieved one filing at a time, with the specific fields returned (filer, issuer, filing date, change reason, holding ratio now vs previous). It does not, however, name or distinguish itself from the sibling tools get_large_holders and get_major_shareholders, which are the obvious alternative sources of holder data, so an agent must infer the difference.

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

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

The description gives clear filtering options ('Filter by issuer symbol, filer EDINET code (holder) or a from/to window (max 93 days)'), which implies usage, and it warns that historical filings by unlisted filers are still being backfilled 'see the coverage field'. But it never states when to choose this tool over get_large_holders or get_major_shareholders, and there is no explicit when-not guidance.

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

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

Annotations already declare readOnlyHint=true, so safety is covered, but the description adds real behavioral context: the data source (segment notes of the annual securities report) and the not-found outcome for companies with no such customers. That not-found contract is exactly the kind of edge-case disclosure an agent needs before calling.

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

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

The lead English sentence is well front-loaded and informative, but the entire content is duplicated in Japanese, roughly doubling length. The trailing ISO 8601 date-time boilerplate is largely irrelevant to a tool whose payload is fiscal-year customer revenue, so several sentences do not earn their place.

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

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

With only two parameters and no output schema, the description carries the return-shape burden and does so by listing the returned fields and the not-found case. It is nearly complete; only the relationship to sibling segment/shareholder tools is unaddressed.

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

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

Schema description coverage is 100% and both parameters are documented in the schema, including the 'omit for latest annual report' behavior, so the baseline is 3. The phrase 'current and prior year' hints at the returned periods but adds no syntax or format meaning for symbol or fiscalPeriod.

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

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

The description names a precise resource and scope: customers representing 10%+ of revenue, sourced from the segment notes of the annual securities report, plus the exact fields returned (name, revenue in yen, related segment, current and prior year). It is clearly distinct from siblings like get_segments or get_major_shareholders, though it never explicitly says so.

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

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

Usage is only implied — an agent can infer you call this when you want customer-concentration disclosure. There is no explicit when-to-use statement, no contrast with get_segments (which covers segment breakdowns) or get_major_shareholders, and no stated prerequisites.

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

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

Annotations only declare readOnlyHint=true, and the description adds real value on top: the data source (latest EDINET filing), the row granularity (one row per holder), the exact returned fields, the ownership-ratio normalization (0-1 decimal with a concrete example), and the presence of a source-document link. It does not state what happens when no filing exists or whether results are truncated, but the return-shape disclosure is strong for a read-only tool.

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

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

The field enumeration is front-loaded and useful, and the bilingual naming aids Japanese-market users. The closing claim 'This data is not available from competing Japanese data APIs' is marketing that consumes space without helping an agent call the tool, and the field list plus Japanese restatement makes the description longer than necessary.

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

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

With no output schema, the description compensates well by enumerating return fields, their units, and the source link. For a simple two-parameter read-only tool the remaining gaps are coverage questions (do all tickers have EDINET filings? how does this differ from get_large_holders?) rather than blockers.

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

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

Schema coverage is 100%, so both `symbol` and `includeTotal` are already documented with examples and defaults, warranting the baseline 3. The description adds nothing about the optional `includeTotal` flag, and its phrase 'one row per holder' arguably understates the aggregate row that flag introduces.

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

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

Names the resource precisely (major shareholders, one row per holder) and its provenance (latest EDINET filing), which an agent can map to a concrete result set. However, it never distinguishes itself from the closely-named siblings get_large_holders, get_large_holding_reports, and get_cross_shareholdings, leaving the agent to guess which shareholder tool to pick.

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

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

There is no explicit when-to-use or when-not-to-use guidance and no alternative is named. In a sibling cluster containing four other shareholder-related tools plus search_by_shareholder, the absence of routing guidance is a meaningful gap; only the implicit 'get major shareholders for a ticker' reading is available.

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

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

Annotations only declare readOnlyHint=true, and the description goes well beyond that: universe exclusions (preferred/class shares, TOKYO PRO Market stocks; market=tokyoPro narrows to that segment only), no market-cap floor, and counting rules (no-trade stocks and stocks whose 52-week high equals the low are not counted as new highs/lows). The only missing behavioral context is anything about output shape or ordering, which is partly covered by the "one row per sector" statement.

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

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

The metric list is front-loaded and the counting/exclusion caveats follow logically, so the structure serves scanning. It is dense and the trailing Japanese restatement largely duplicates the English enumeration, which costs some economy, but no sentence is filler in substance.

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

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

With no output schema, the description carries the burden of saying what comes back, and it enumerates every returned metric plus the row granularity for the sector variant. Combined with the eligibility rules and token cost, an agent has enough to call it correctly and interpret the result.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning on top: stocks with no sector code appear only in the whole-market row (an edge case the schema does not state), and it clarifies the market-omitted vs tokyoPro distinction and the common-stocks-only default behind includeEtf. This is meaning beyond the structured fields rather than repetition.

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

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

The description names a specific resource (advancers, decliners, unchanged, advance/decline ratio, new 52-week highs/lows, trading value for the latest trading day) with a sector-level variant, which is far more specific than the bare tool name. It does not explicitly distinguish itself from the closest siblings that overlap on this data, notably get_new_highs_lows, get_market_movers and get_sector_performance, so an agent must still infer which to pick.

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

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

It clarifies the two modes of use — whole-market row first, optionally one row per TSE 33-sector via groupBy=sector — and notes the 1-token cost, which helps an agent decide to call it. However, there is no explicit "use this instead of X" guidance against the overlapping siblings, so selection remains implied rather than stated.

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

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

Annotations only declare readOnlyHint=true, and the description adds genuinely non-derivable behavior: a 10-token cost, a 10-year cap per request, split/share-count adjustment semantics, and that from/to are interpreted in JST. Return format/pagination is not described, but the added context is substantial beyond the annotation.

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

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

Front-loaded with the core definition and formula, then defaults, limits, and timezone caveats. Dense and mostly waste-free; the bilingual duplication and the repeated JST note cost a little, but it is justified for a Japanese-market audience.

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

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

With no output schema and a fully documented 4-parameter schema, the description supplies the missing behavioral pieces (units in yen, adjustment method, cost, range limits, timezone). Adequate for an agent to call correctly, though return structure (series length, gaps for non-trading days) is left implicit.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds real meaning beyond the schema by clarifying that from/to are Japan-time dates and that weekly/monthly collapse the series to the last trading day of each period, but the interval semantics are largely restated from the schema.

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

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

States a specific verb and resource ('Daily market capitalization of a Japanese stock') and even discloses the computation formula (split-adjusted close x shares outstanding, treasury excluded), which makes its output concept clearly distinct from a snapshot tool. It does not explicitly name the sibling it differs from (e.g. get_market_capitalization or get_valuation_history), so it stops short of a 5.

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

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

Gives useful operational guidance: default is the last year, max 10 years per request, and interval=weekly/monthly thins the series. It never says when to prefer this over get_valuation_history or get_market_capitalization, and offers no exclusions, so usage context is implied rather than stated.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description contributes the currency (JPY) and the point-in-time nature of the value, which are genuinely useful, but says nothing about data freshness/lag, whether the figure is a raw or free-float-adjusted cap, or how a missing symbol is handled.

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

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

One tightly-scoped sentence with the key attributes (latest, JPY, listed company) front-loaded — nothing is padded. The Japanese restatement duplicates the same content verbatim, which costs a little space but is reasonable for a bilingual audience.

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

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

For a one-parameter read-only lookup with no output schema, the essentials (unit and recency) are present. It still leaves the agent guessing about the relationship to the many adjacent financial-metric tools, which is the main completeness gap for a catalog this dense.

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

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

Schema description coverage is 100%: the single 'symbol' parameter already documents itself as a 4-digit Japanese ticker with a Toyota example. The description adds no further meaning about the identifier beyond what the schema states, so the baseline 3 applies.

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

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

States a specific resource (market capitalization) with a clear scope qualifier ('Latest') and unit (JPY), so an agent knows exactly what comes back. It does not, however, distinguish itself from near-siblings such as get_market_cap_history, get_key_metrics_latest, or get_quote.

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

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

There is no explicit when-to-use or when-not-to-use guidance. The word 'Latest' hints that this is a point-in-time snapshot rather than a time series, implicitly routing agents away from get_market_cap_history, but that inference is left entirely to the reader with no named alternative.

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

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

Annotations already establish readOnlyHint=true, so the safety profile is covered; the description goes further by disclosing the universe rules (preferred/class shares and TOKYO PRO Market excluded, tokyoPro parameter flips that), the absence of a market-cap floor, that results are limited to the latest trading day, that changes are split-adjusted decimals, and the 10-token cost. It stops short of describing the shape of the returned ranking entries, which would be the remaining useful detail given there is no 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.

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

The definition is front-loaded with the resource and its three modes, then layers universe rules and formatting conventions in compact clauses. It is dense but mostly earns its words; the duplicated Japanese restatement of the first sentence adds length without new information, and the trailing 'Costs 10 tokens' would read better grouped with the other operational constraints.

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

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

For a read-only, zero-required-parameter ranking tool with a well-described schema and no output schema, the description covers everything needed to call it correctly: what is ranked, over what time window, which securities are in scope, how filters interact, and what the numeric output means. Nothing material for correct invocation is missing.

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

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

Schema coverage is 80%, so the baseline is 3, but the description earns above that by clarifying semantics the schema leaves ambiguous: 'actives' means largest trading value, the market parameter's omit-behavior versus tokyoPro, the common-stock-only default that governs includeEtf, and the decimal convention for reported changes. It does not address the limit bounds (1–100), which the schema handles silently.

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

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

The description states a specific resource and scope: top movers of the latest trading day in Japan, with the three modes (gainers = largest rise, losers = largest fall, actives = largest trading value) defined inline. It is clearly distinguishable in intent, but it never names or contrasts with close siblings such as get_rankings, get_new_highs_lows, or get_sector_performance, so an agent must infer the boundary.

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

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

Usage is implied through the filtering capabilities (TSE 33-sector or market segment) and the universe definition (common stocks only, no market-cap floor), which help an agent decide whether the tool fits a given request. However, there is no explicit when-to-use / when-not-to-use guidance or routing to an alternative tool for historical rankings or per-stock quotes.

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

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

Beyond readOnlyHint=true, it discloses a rich set of behavioral rules: split-adjusted intraday 52-week basis with 365 days, exclusion of IPOs under 200 trading days, exclusion of stocks with a split in the last 10 days, zero-trade and high==low exclusion, common-stocks-only universe with preferred/class and TOKYO PRO handling, no market-cap floor, sort order by trading value, and a 10-token cost.

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

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

It is a dense, front-loaded paragraph where nearly every clause carries a distinct rule (universe, exclusions, sorting, cost). It is long, and the trailing Japanese one-liner partly restates the English and slightly adds bulk rather than new information.

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

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

For a six-parameter screening tool with no output schema, the definition covers universe, exclusions, sort order, and cost, which is what an agent needs to call it correctly. Return-value shape is not described, though the 'sorted by trading value' note implies an ordered list, and `limit` semantics rely on the schema.

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

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

Schema coverage is 83%, so the baseline is 3. The description adds real meaning on top: it explains what omission of `market` does, clarifies that includeEtf=false implies common stocks with preferred/class shares excluded, and frames `type` and `days` in domain terms. Only `limit` is left entirely to the schema.

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

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

The description opens with a precise verb+resource: Japanese stocks that set a 52-week high or low on the latest trading day or within `days` days. It is immediately distinguishable from siblings like get_technicals, get_market_movers, and get_market_breadth by naming the specific 52-week breakout screen.

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

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

It clearly defines the use case window (latest day vs. a lookback of `days` calendar days) and states that it shares methodology with get_technicals, which helps orient the agent. It does not explicitly say when to prefer a sibling such as get_market_breadth or get_rankings, so there is no when-not guidance.

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

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

With only readOnlyHint=true supplied, the description carries real weight and delivers: row ordering, the full metric list, the rule that outliers are null rather than omitted, the decimal convention for ratios (0.1 = 10%), how dividend yield is computed (forecast vs. actual annual dividend), and the explicit 10-token cost. That is substantive behavioral context an agent could not derive from the annotation.

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

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

Front-loaded with the comparison purpose, then composition, then metric list and formatting caveats — a logical flow with no filler sentences. The Japanese restatement and the trailing cost note are reasonable for a bilingual tool, though the Japanese line adds no information the English sentence lacks.

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

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

There is no output schema, so the description must explain the return shape — and it does, naming every column, defining null handling, ratio formatting, and the dividend-yield formula, plus row ordering. For a two-parameter, read-only lookup, nothing an agent needs in order to call and interpret it is missing.

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

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

Schema coverage is 100%, so the schema already documents both symbol and limit, giving a baseline of 3. The description adds ordering knowledge that affects how row count should be interpreted (target row plus peer rows plus a median row), but it never states explicitly whether limit counts peers only or total rows, so the one genuinely ambiguous parameter remains ambiguous.

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

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

"Compare a stock with its sector peers" is a precise verb+resource, and the description goes further by specifying the exact composition (target first, same-sector large caps closest in market cap, sector-median row) and the metric set returned. This distinguishes it clearly from siblings such as get_sector_performance or get_industry_benchmarks, which do not return a per-stock peer table.

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

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

The comparative context is clear (same TSE 33 sector, similar market cap, common stocks only), which implicitly tells the agent this is a relative-valuation tool. However, no alternative is named and no exclusion stated — an agent must infer on its own when to prefer this over get_industry_benchmarks, get_key_metrics_latest, or get_sector_performance.

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

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

Annotations already establish readOnlyHint=true, so the safety profile is covered. The description adds material context the annotations do not: that change values are decimal fractions (0.03 = 3%), that timestamps are ISO 8601 UTC with a stated +9h offset for Japan time, and which fields are deliberately excluded. It stops short of describing freshness or what happens when the market is closed, which would be useful for a 'latest' snapshot.

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

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

The English content is well front-loaded and each fact earns its place, but the entire description is immediately restated in Japanese, roughly doubling length with no new information. The bilingual duplication is defensible for audience coverage yet inefficient for an agent parsing the definition.

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

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

With no output schema and one simple required parameter, the description covers return fields, units, date formats, and sibling exclusions – enough to call the tool correctly. Missing details about data freshness or null/empty handling for a 'latest' snapshot keep it from being fully complete.

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

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

Schema description coverage is 100% and the single symbol parameter is already documented with a concrete example ('7203' = Toyota). The description adds no syntax, format, or validation details for the parameter, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Latest price snapshot') and enumerates exactly which fields are returned (close price, price date, change windows, market cap). It also names the sibling tool (get_key_metrics_latest) that holds the metrics this tool does not return, so an agent can distinguish the two without opening either schema.

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

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

Explicitly routes the agent away from this tool for PER, PBR, dividend yield, streak years, and CAGRs, pointing to get_key_metrics_latest. It does not address other plausible alternatives such as get_batch_quotes for multiple tickers or get_historical_prices for time series, so the routing guidance is clear but not exhaustive.

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

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

Annotations only declare readOnlyHint, so the description carries most of the burden: it discloses the cost ('Costs 10 tokens'), the dividend-yield calculation rule (forecast dividend when available, actual otherwise), and clarifies that 'consecutive non-decrease years' counts flat years. It does not describe the shape of results or how ties/missing metrics are handled.

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

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

Two short sentences with the core ranking purpose front-loaded, followed by the one metric-specific caveat that matters. The duplicated Japanese title fragment adds little but costs almost nothing.

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

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

With no output schema and four parameters, the description should ideally indicate what a ranking row contains (company identifier, metric value, rank) so the agent can plan downstream use. The purpose and metric semantics are complete, but the result shape is unspecified.

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

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

Schema coverage is 75% and the metric enum is largely self-documenting, but the description adds real meaning beyond it: 'price change' and 'CAGRs' map the changePct*/Cagr enum values into plain language, and 'consecutive non-decrease years (including flat years)' disambiguates progressiveDividendYears. The limit, order, and sector parameters are left entirely to the schema.

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

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

States a specific verb and resource — 'Top/bottom ranked Japanese listed companies by a single metric' — and enumerates the metric families, which separates it in spirit from screening tools like screen_stocks. It never names an alternative explicitly, so sibling differentiation is implied rather than stated.

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

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

The 'top/bottom' framing implies the use case (finding leaders or laggards on one metric), and naming a single metric implicitly excludes multi-criteria screening. There is no explicit when-to-use vs. screen_stocks/run_screener_preset guidance and no stated exclusions.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description's main added value is the return format, notably that the 3y figure is an annualized 0-1 fraction. It does not disclose whether returns are split/dividend adjusted, how missing history is handled, or the response shape — gaps that matter for interpreting the numbers.

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

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

The content is front-loaded into one dense sentence listing periods and output format, followed by a short usage cue. The trailing Japanese sentence largely restates the English, which is a small redundancy but may follow a bilingual convention.

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

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

With no output schema, the description does the necessary work of specifying which periods come back and that the 3y value is a fraction rather than a percentage — an important disambiguation. Only the exact field naming and behavior with insufficient history remain unstated, which is minor for a one-parameter read tool.

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

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

The single parameter has 100% schema description coverage, including the '7203' = Toyota example, so the schema carries the semantics. The description adds nothing about the symbol beyond what the schema already says; baseline 3 applies.

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

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

The description names the exact resource (a period-returns bundle) and enumerates the periods returned (1d/1w/1m/3m/6m/1y/YTD plus 3y annualized), so an agent knows precisely what it gets. It signals a 'lightweight' variant exists relative to heavier siblings but never names which sibling to prefer, so it falls short of full differentiation.

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

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

'Use for quick performance comparisons' gives an implied when-to-use context, but there are no explicit alternatives (e.g., get_historical_prices or get_technicals) or when-not conditions. An agent must infer the boundary itself.

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

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

Annotations only declare readOnlyHint=true, so the description carries the behavioral burden and does so well: it discloses the all-market row ordering, that changes are split-adjusted decimals with a worked example, the common-stock-only universe with exclusions, and the tokyoPro carve-out. The only missing piece is a note on result size or whether all 33 sectors are always returned.

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

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

It is front-loaded with the use case, then the data definition, then the interpretation, then the universe caveats — a logical order. The Japanese restatement and the 'Costs 10 tokens' note take up space, but the bilingual line matches the schema's own bilingual style and the cost note is actionable.

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

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

For a read-only four-enum tool with no output schema, the description covers periods, bases, ranking order, return value format, universe exclusions, and cost. An agent can call this correctly and interpret the output without consulting anything else.

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

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

Schema coverage is 100% and all four parameters are enums with their own descriptions, so the baseline is 3. The description does add meaning beyond the schema by stating that ranking is by the chosen period and that market=tokyoPro counts TOKYO PRO Market only with no market-cap floor, but it does not elaborate further.

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

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

The description states a specific verb and resource ('Price change by TSE 33-sector') across four periods and two bases, ranked, with an all-market row first. It is clearly distinguishable from siblings like get_rankings, get_market_breadth, and list_sectors because it names the sector-level price change aggregation explicitly.

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

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

The opening question 'Which sectors are up or down?' plus the mention of rankings-style universes gives clear context for when this tool is the right choice. There are no explicit exclusions or pointers to alternatives (e.g., get_rankings for stock-level, list_sectors for the sector list itself), which keeps it below a 5.

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

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

Annotations only declare readOnlyHint=true; the description goes well beyond by disclosing the result shape (one row per segment × metric), the unit convention (values in table unit, multiply by unitMultiplier for JPY), the EDINET source link, and the empty-result behavior. These are exactly the traits an agent cannot infer from the annotation or schema.

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

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

The core content is front-loaded and useful, but the entire paragraph is then repeated verbatim in Japanese, and a generic ISO 8601 date-format note is appended that is irrelevant to a tool whose only parameters are a ticker and a year-month. Roughly half the text is duplication or boilerplate.

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

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

With no output schema, the description correctly compensates by explaining row structure, units, relatedItems, and the empty-items case. Minor gaps remain: no mention of error behavior for an unknown ticker or how many rows/segments to expect, but nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% and both parameters are documented in the schema (ticker format and YYYY-MM fiscal period). The description only restates that fiscalPeriod omitted yields the latest report, which the schema already says, and adds nothing about symbol semantics. Baseline 3 is appropriate.

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

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

Names a specific resource and scope: "Reportable-segment breakdown from the latest annual securities report (有価証券報告書)", and enumerates the metrics returned (external sales, segment profit, assets, depreciation, capex). It also distinguishes itself from adjacent data by stating that product/service and geographic tables live in relatedItems, separating it from siblings like get_sga_breakdown or get_subsidiaries.

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

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

Gives clear usage context: omit fiscalPeriod for the latest period, expect an explanatory note when items is empty (single segment / unsupported layout), and look in relatedItems for related-information tables. It does not explicitly name an alternative tool to use instead for other segment-like data, so it falls short of full when/when-not routing.

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

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

Annotations already establish readOnlyHint=true, so the safety profile is covered. The description adds real behavioral context beyond that: item-level SG&A appears in `items` only for companies that itemize it on the face of the income statement, and ratios are expressed as 0–1 decimals, both of which prevent misinterpretation of sparse or scaled results.

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

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

The opening sentence is well front-loaded and dense with useful scope information. However, roughly half the text is bilingual duplication plus generic ISO 8601 / Japan-offset boilerplate that is not specific to this tool, inflating length without adding tool-level guidance.

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

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

With no output schema, the description correctly takes on the burden of explaining return contents (statement lines, ratios, conditional `items`) and units, which is what an agent needs to interpret results. Missing only an explicit alternative-routing note against the broader income-statement tools.

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

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

Schema description coverage is 100%, with limit, period enum, and symbol all documented in the schema itself, so the baseline is 3. The description adds nothing about period filtering, ordering, or the 40-period cap, leaving parameter meaning entirely to the schema.

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

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

The description names a concrete resource (SG&A per period) and enumerates the co-returned income-statement lines and the two derived ratios, so the scope is unmistakable. It does not explicitly distinguish itself from sibling tools like get_income_statement or get_full_financial_statement, which is the only gap.

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

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

Usage is implied by the content description (use it when you want SG&A and expense ratios), but there is no explicit when-to-use, when-not-to-use, or pointer to get_income_statement / get_full_financial_statement as alternatives. An agent must infer the routing decision.

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

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

readOnlyHint already establishes the safety profile, yet the description adds substantive semantics beyond it: the three-state hasBenefits field with an explicit prohibition on reading null as absence, the rule that amounts are company-stated only with estimates returned as null, and ISO 8601 UTC date conventions. These are exactly the data-interpretation pitfalls an agent would otherwise get wrong; only minor operational details are absent.

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

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

The purpose and the critical hasBenefits warning are front-loaded, which is good. However, the entire body is then repeated in Japanese, roughly doubling the length without adding information for a reader of the English text, and the date-format paragraph is likewise duplicated.

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

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

With no output schema, the description must carry return-value semantics, and it does so thoroughly: the program facets, amount conventions, null handling, and date formats are all covered. Only minor gaps remain, such as behavior for an invalid or unsupported ticker with no benefit program.

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

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

Schema description coverage is 100% and both parameters (symbol, asOf) are fully documented in the schema, including format and defaults. The description adds no meaning about either parameter, so the baseline of 3 applies.

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

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

The description names a specific verb-plus-resource: shareholder benefit programs for one Japanese company, and enumerates the returned facets (current and scheduled programs, record months, tiers by shares and holding period, items with stated amounts, source document). It is clearly a single-company lookup, which implicitly separates it from list_shareholder_benefits, but it never names that sibling, so the differentiation is left to inference.

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

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

Usage is only implied by 'of one Japanese company' — there is no explicit statement of when to call this versus list_shareholder_benefits or search_by_shareholder. The one piece of real guidance is interpretive rather than selection-oriented: 'null ... NEVER "no benefits"; say it is unknown,' which is valuable but addresses output handling, not tool choice.

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

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

Annotations only supply readOnlyHint=true, so the description carries the rest — and it does useful work by naming the authoritative source (annual securities report), warning that share counts are in trading units rather than shares, and specifying that ratios are 0–1 decimals. That unit caveat is exactly the kind of trap an agent would otherwise fall into when presenting the numbers.

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

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

The core sentence is well front-loaded and information-dense. However, the ISO 8601 date-time boilerplate is restated in both English and Japanese and is largely irrelevant to a tool with no date-time parameters or documented date outputs, which roughly doubles the text for no added decision value.

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

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

With only two parameters, one required, full schema coverage, and read-only semantics, the description is nearly self-sufficient; because there is no output schema it also usefully enumerates the returned fields per category. Minor gaps remain around whether multiple fiscal years can be requested and what a missing report yields.

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

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

Schema description coverage is 100%, so both symbol and fiscalPeriod are already documented with format and an example. The description adds nothing about fiscalPeriod's semantics or behavior (e.g., what happens when no report exists for the requested period), so it sits at the baseline.

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

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

States a specific verb and resource — ownership broken down by shareholder type from the annual securities report — and enumerates the exact categories returned (governments, financial institutions, securities firms, other corporations, foreign investors, individuals). This implicitly separates it from holder-level siblings like get_major_shareholders and get_large_holders, but it never names them explicitly.

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

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

The 'from the annual securities report' phrasing and the parameter note 'Omit for the latest annual report' imply the usage context without stating it as a rule. There is no explicit guidance on when to pick this over get_major_shareholders, get_cross_shareholdings, or get_treasury_shares, all of which live in adjacent territory.

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

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

readOnlyHint=true already establishes the safe-read profile, so the description needn't restate safety. It does add meaningful context beyond annotations: the data is parsed from TDnet filings, exposes an 'extraction confidence' field and a source document reference, which hints at derived/probabilistic data quality — a genuinely useful disclosure. It stops short of describing ordering, coverage windows, or what an empty 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.

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

The field enumeration is front-loaded and earns its place, but the entire content is duplicated verbatim in Japanese and the ISO 8601 format rule is spelled out twice, roughly doubling length. If bilingual output is a product policy this is defensible, but from a pure information-density view it is redundant.

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

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

For a two-parameter read tool with no output schema, the description usefully enumerates return fields and provenance, which compensates for the missing output schema. It is still incomplete on the operational details an agent needs: result ordering, whether all historical splits are returned, and the behaviour of the undocumented limit parameter.

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

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

Schema coverage is only 50%: symbol is documented in the schema, but limit (default 50, max 100) has no description anywhere. The description adds no information about paging, ordering of returned events, or whether limit caps events per symbol — the gap that most affects correct invocation is left unfilled.

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

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

The description names a specific resource (stock split / reverse split events) and its source (TDnet filings), and enumerates the returned fields, so an agent knows exactly what this tool yields. It does not explicitly contrast itself with near-neighbours like get_disclosures or get_extraordinary_report_events, but no sibling returns split event data, so confusion risk is low.

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

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

There is no when-to-use guidance, no prerequisite statement, and no mention of alternatives. An agent must infer from the resource name alone that this is the right call for split history rather than get_disclosures or get_events_feed.

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

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

With only readOnlyHint supplied, the description does real work: it identifies the source document (有価証券報告書), states the voting-rights ratio is on a 0–1 scale, and gives date/time conventions including the JST offset. It also sketches what each returned row contains, which matters since there is no output schema; it stops short of saying what happens when no subsidiaries are reported or how large the result set can be.

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

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

The purpose statement is front-loaded and information-dense, but the entire body is duplicated in Japanese, roughly doubling length without adding information for a single reader, and the date-format boilerplate sits at the end where it reads as generic filler.

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

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

For a two-parameter read tool with no output schema, the description covers source, scope, returned fields, and value conventions well enough to invoke it confidently. Residual gaps (empty-result behavior, coverage limits) are minor.

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

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

Schema description coverage is 100%, so both parameters are already fully documented, including the ticker format and the 'omit for latest' default. The description adds no parameter-level meaning beyond that, so baseline 3 applies.

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

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

The description names a specific resource (group structure from the annual securities report) and enumerates its scope precisely: parent, consolidated subsidiaries, equity-method affiliates, and other related companies. The field list (address, capital, main business, voting-rights ratio, relationship) makes it clearly distinct from siblings like get_cross_shareholdings or get_major_shareholders.

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

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

Usage is implied by the stated data source ('from the annual securities report') and by the schema note that omitting fiscalPeriod returns the latest report, but the description never says when to choose this over get_cross_shareholdings or get_major_shareholders, nor any preconditions (e.g., only companies that file a securities report).

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

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

Annotations only declare readOnlyHint=true, which already establishes a safe read. The description adds genuinely useful context beyond annotations by specifying unit semantics: ratio fields are 0-1 fractions, not percentages, which prevents a real misinterpretation risk. It does not state computation windows for Sharpe beyond 3y, nor the response shape.

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

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

The metric list is front-loaded and dense, and the unit caveat is placed immediately after it. The bilingual repetition of the same content in Japanese roughly doubles the length without adding new information, which is the main inefficiency.

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

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

For a one-parameter read-only metrics tool with 100% schema coverage, the definition covers what is returned and how to interpret ratios. However, no output schema exists, so the description is the only source of return-value structure, and it omits field names, null/missing-data behavior, and whether results are point-in-time or windowed.

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

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

Schema coverage is 100% and the single symbol parameter is documented with format and an example ("7203" = Toyota), so the baseline is a 3. The description's unit conventions add a small amount of meaning about how results should be read, but nothing about the parameter itself.

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

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

The description enumerates the exact technical metrics returned (52w high/low, 50/200-day MAs, volatility, turnover, drawdown, 3y return, Sharpe), which is a specific verb+resource set that clearly distinguishes it from siblings like get_key_metrics or get_returns.

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

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

There is no explicit when-to-use guidance and no named alternatives, even though get_key_metrics, get_returns, get_market_cap_history and get_historical_prices overlap in scope. The agent must infer selection from the metric list alone.

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

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

Annotations only declare readOnlyHint=true, so safety is already covered; the description adds genuinely useful behavior beyond that — the legal basis of the data, the fact that the response also carries a `consolidated` block, and an explicit warning that the two counts are not interchangeable. It does not describe edge cases such as a missing voting-rights section or how holder rows are ordered, which keeps it short of a 5.

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

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

The English portion is front-loaded and well ordered: source, contents, the critical non-subtraction warning, then the pointer to `consolidated`. However, every sentence is repeated verbatim in Japanese and the ISO 8601 / YYYY-MM-DD boilerplate is stated twice, roughly doubling length without adding information relevant to this tool's two non-datetime parameters.

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

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

For a two-parameter read lookup with no output schema, the description covers what the record contains, where in the filing it comes from, how it relates to the separately returned `consolidated` figures, and the most likely downstream misuse. An agent has everything needed to call it and interpret the result correctly.

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

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

Schema description coverage is 100%, and the schema already explains the 4-digit ticker and that omitting `fiscalPeriod` yields the latest annual report, so the baseline of 3 applies. The description adds no further parameter meaning; its date-format notes concern returned values (and neither parameter is a date-time).

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

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

The description names a specific resource and its exact source: treasury shares from the annual securities report's voting-rights section, enumerating the disclosed sub-fields (own name, others' names, total, holder rows, ratio to issued shares, per-class issued shares). It explicitly contrasts this with the consolidated accounting count, so an agent cannot confuse it with the earnings-summary figures returned in `consolidated`.

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

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

It states the interpretive boundary sharply: this is Companies Act art. 308 voting-rights disclosure, and shares outstanding must not be derived by subtracting it from issued shares. It also points to where the consolidated counts actually live. It stops short of naming sibling tools (e.g. the key-metrics/earnings tools) by name, so selection among siblings is inferred rather than directed.

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

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

Beyond readOnlyHint=true, the description discloses aggregation granularity, that byEndpoint truncates past 100 entries into a single "(other)" row, that this request is not counted in its own totals, and the difference in totals between an individual account and an organization member. That is substantive behavioral context an agent could not infer. It does not mention rate limits, caching, or freshness of the figures.

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

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

The English content is well front-loaded (purpose, then payload, then edge cases), but the entire passage is then repeated verbatim in Japanese, roughly doubling length with no added information for an English-reading agent. The date-format sentences are also duplicated in both languages. The core is efficient; the duplication is the main cost.

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

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

With no output schema and no parameters, the description carries the full burden of describing return values, and it does so field by field, including date formats (ISO 8601 UTC with a JST hint). Missing only secondary details such as error behavior or data freshness, which are minor here.

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

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

The tool takes zero parameters, so the baseline is 4 and the schema has nothing to explain. The description does reference a breakdownScope=member mode that does not appear in the input schema, which is slightly confusing, but it usefully clarifies how results differ for organization members.

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

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

The description opens with a direct question that names the resource precisely (monthly token quota) and then enumerates the exact return payload: plan, tokens used/limit/remaining, requests used, and per-endpoint/per-day breakdowns. Nothing in the sibling list covers quota usage, and the scope statement ('aggregated per account, all API keys share one quota') removes any ambiguity about what is being measured.

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

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

Usage context is clear and specific: current month only, UTC, account-level aggregation, and the note that the call itself is excluded from the figures. It also explains the organization-member case (totals are the organization's, breakdown is your own). It does not state exclusions such as what to use for historical months, but no sibling provides that, so the gap is minor.

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