ym_get_stocks

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

Annotations already carry readOnlyHint=true and openWorldHint=trueikuha. The description adds useful behavioral context: it is a POST endpoint that returns warehouse-level stock and supports pagination via page_tokenasia, and optionally includes turnover. No contradiction with 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?

Four compact lines cover purpose, endpoint, every parameter, and return shape. No filler or redundancy; the information is dense and 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?

Given that an output schema exists, the description does not need to detail return fields. It explains the endpoint, all parameters, and the high-level data shape. Missing only minor operational details like rate limits or auth requirements, but what is present is sufficient for correct invocation.

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 0%, so the description carries the full burden of explaining parameters. It covers all five: campaign_id (shop id), offer_ids (comma-separated filter, empty=all), with_turnover (per-offer turnover), page_token (pagination), and limit (page size, <=200). This fully compensates for the schema's lack of descriptions.

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, actionable purpose: 'Stock per offer per warehouse for one shop, with optional turnover,' reinforced by the explicit endpoint. This clearly distinguishes it from sibling price/order/offer tools even without reading 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 clearly explains scope (per-shop stocks) and parameters, but it does not explicitly say when to choose this over related tools like ym_get_offers or ym_get_prices, nor does it state exclusions like draft/archived campaigns or authorization prerequisites.

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