XMLStock: wordstat regions

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

Annotations provide little behavioral detail. The description adds critical non-obvious information: the call is PAID and more expensive than top/dynamics, and a cold 24h cache triggers an additional PAID regionsTree request. This is exactly the kind of side-effect disclosure an agent needs, and it does not contradict the annotations.

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

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

The description is compact and front-loaded: core purpose first, return shape second, and a clearly labeled warning about the additional paid request last. Every sentence contributes operational value with no fluff.

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 appropriately includes the return record shape. It also covers caching and cost behavior, which are essential for safe invocation. The main gaps are the lack of an explicit authentication prerequisite and no edge-case details such as empty results, but the schema and sibling tools partially cover these.

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 only says 'query' has minLength 1, so the description adds the key meaning: query is the phrase whose regional demand is returned. The account parameter is already described in the schema. Together they cover both parameters reasonably well, though query syntax and formatting are not detailed.

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?

Description states a specific verb-resource pair: returns regional demand distribution for a phrase via Yandex Wordstat/XMLStock. The exact returned record shape is listed, and the region focus clearly distinguishes this from siblings like wordstat_dynamics or wordstat_regions_tree.

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 phrase 'для фразы' implies the tool is used for per-phrase regional breakdowns, and the cost warning is useful context. However, it does not explicitly state when to choose this over xmlstock_wordstat or wordstat_regions_tree, nor does it mention alternatives by name.

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