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.