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

Annotations already declare read-only, idempotent, non-destructive, open-world behavior, so the bar is lower. The description still adds real context beyond them: the return field semantics (share = fraction of all Yandex searches) and the non-obvious constraint that toDate must land on a period boundary. Missing: any note on rate limits, empty-result behavior, or data granularity 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?

Three short sentences, front-loaded with the core purpose and return shape, followed by usage and the one tricky parameter constraint. No 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 usefully documents the returned {date, count, share} fields and explains share, covering the biggest gap. Remaining gaps are minor: what happens if toDate is not aligned to the period, and whether the series can return empty buckets.

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 re-states that period sets the series step and that from/to use RFC3339 with toDate aligned to period boundaries, but this largely duplicates the schema and adds nothing about devices or regionIds.

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 verb: shows how demand for a phrase changed over time, and returns a concrete series shape {date, count, share}. This is inherently distinct from time-agnostic siblings like top_requests or regions, so an agent can select 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?

"Подходит для оценки сезонности и тренда" gives clear usage context for when this tool is appropriate. It does not name an alternative or state exclusions (e.g. when a single-point snapshot would be enough), leaving that inference to the agent.

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 readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds genuinely non-obvious traits beyond them: the response is large, it is stable over time, and caching is the intended usage pattern. It stops short of describing pagination or exact 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?

Three sentences, front-loaded with what is returned, then downstream usage, then the caching recommendation. Every sentence carries information an agent would otherwise have to discover empirically.

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?

No output schema exists, and the description compensates by describing the payload (id + label). Enough to call it correctly, but it never resolves the relationship with the similarly named `regions` sibling, which is the remaining completeness 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?

Zero parameters, so the baseline is 4. The description does useful adjacent work by explaining the semantics of the returned ids in the consuming tools' `regionIds` parameter, though there is no parameter schema of its own to enrich.

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: returns a reference tree of regions supported by Wordstat, with ids and labels. It also names sibling tools (top_requests, dynamics) where the ids are consumed. However, it does not differentiate itself from the sibling `regions`, leaving real ambiguity about which of the two to call.

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?

Explains what to do with the output (plug ids into regionIds of top_requests/dynamics, use labels to decode responses) and advises fetching once and caching because the tree is large and stable. No exclusion against the `regions` sibling, which is the one missing piece of routing 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 readOnly/idempotent/non-destructive/open-world, so the lower bar applies, and the description still adds real context: POST is the only supported method, `body` is serialized as JSON, and folderId is injected automatically. It does not cover error behavior or what an invalid path returns, which matters for a pass-through tool, 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?

Two sentences with no filler: the first establishes what it is and when to reach for it, the second carries the operational constraints. Nothing could be removed without losing 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 raw HTTP pass-through with no output schema and open-world semantics, the description never says what comes back — raw JSON of unknown shape, or an error envelope — which is the single most important unknown for this kind of tool. It covers invocation well but leaves the result contract and failure modes 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 coverage is 100%, so the baseline is 3, but the description goes beyond the schema by explaining that `body` is sent as JSON and that folderId is auto-injected into it — non-obvious behavior the schema does not state. Neither `path` formatting beyond the example nor enum restriction gets extra clarification, keeping it at 4.

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 uses a specific verb and resource ('обращается напрямую к любому пути Wordstat в Yandex Cloud Search API') and immediately scopes it to endpoints without a dedicated tool, which separates it from the four sibling tools. An agent can tell this is a raw passthrough, not a typed query wrapper.

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 explicitly states the selection rule — use this only for endpoints that have no separate tool — which is a clear when-to-use condition. However, the illustrative path it names ("v2/wordstat/topRequests") is exactly what the sibling top_requests already covers, which slightly muddies the rule it just 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?

Adds context beyond the annotations: the fixed 30-day window, the exact row fields (id, count, share, affinityIndex), and how to interpret affinityIndex above/below 100. No output schema exists, so this return-value disclosure is genuinely valuable, and it is consistent with the readOnly/idempotent 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?

Three tight sentences, front-loaded with the core purpose, followed by return shape, parameter meaning, and a pointer to a helper tool. No 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?

Covers purpose, return fields, metric interpretation, and the regionMode grouping. With no output schema, the enumerated row fields fill that gap, leaving nothing an agent needs 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 already documented, including the enum values for regionMode. The description restates the regionMode grouping without adding syntax or edge-case detail, 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 verb and resource: returns how demand for a phrase is distributed across regions over the last 30 days. This is distinguishable from siblings like dynamics and top_requests 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?

The use case (regional breakdown of demand) is clear, and it explicitly points to list_regions for mapping region ids to names. It does not state when to prefer this over dynamics or top_requests, so it stops short of full routing 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, idempotentHint and openWorldHint, so the description doesn't need to re-establish safety. It does add real behavioral context: the two-bucket result structure and the caveat that counters may arrive as strings (int64), which is non-obvious and valuable. It does not cover rate limits, ordering, or pagination behavior, so it stays at a moderate score.

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?

Three sentences, front-loaded with the return structure and then the type caveat and parameter hints. Dense but every clause carries information; minor redundancy with the schema on parameter ranges keeps it from a 5.

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 explaining returns — and it does: names results, associations and totalCount and flags the int64-as-string quirk. Together with complete schema descriptions for all parameters, an agent has everything needed to call and interpret this 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 all four parameters are already documented in the schema with examples and defaults. The description only restates that regionIds/devices narrow the sample and numPhrases is 1..2000 — no syntax or semantics beyond the schema. 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 states a specific verb and resource (returns search demand for a phrase over the last 30 days) and explicitly distinguishes the two result buckets: results (containing the phrase) and associations (semantically similar, may not contain it), plus totalCount. This is far more precise than the tool name and lets an agent understand the payload without opening a 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 gives a clear usage context (keyword selection and demand estimation) and tells the agent that regionIds and devices narrow the sample. However, it never names an alternative sibling — e.g. when to prefer dynamics or regions — so the agent gets context but no explicit routing against alternatives.

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