Yandex Market: get stocks

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the operation is read-only, explains how stock types are normalized, and prominently warns about the two-method split. This is exactly the kind of non-obvious behavior an agent needs to know.

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, then adds normalization details and a critical call-pattern warning in a logical order. Every sentence earns its place, and the IMPORTANT section prevents the most likely misuse without being bloated.

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 complex stock endpoint with no required parameters, the description covers all key decisions: warehouse type selection, campaign_id necessity for FBY/warehouse groups, and the need to call twice. It also references ym_campaigns_list for id discovery, leaving no critical gap for an agent to call it 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?

The schema already documents most parameters, but the description adds meaning beyond it: campaign_id determines which warehouse model is queried (FBY/FBO vs FBS/DBS/Express), and business_id resolution is explained via connection or ym_campaigns_list. This materially improves correct parameter selection.

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 ('Returns Yandex Market stock levels') and immediately defines the scope ('available to order and reserved'). It also explains the normalization of stock types, which makes it clearly distinguishable from price, order, and non-Yandex stock tools.

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 explicit conditional guidance: without campaign_id the caller gets seller warehouses, with campaign_id it gets Market warehouses, and a single call does not cover both. It also tells the agent to call twice for full stock visibility and points to ym_campaigns_list for shop ids, which is strong routing context.

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