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

Goes well beyond the readOnly/idempotent annotations: discloses the ordering rule (events starting in-window by start date, then ongoing items like exhibitions by end date), that series are collapsed into a single card, how defaults are echoed in applied_filters.defaulted_dates, and the 60-day lookback cap. Crucially it explains the degraded-path warning when data_freshness = 'резервная копия' and notes that prices and registration status are absent — exactly the operational context annotations cannot carry.

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?

Front-loaded with purpose then behavior, no filler sentences, and every clause carries information the agent needs. It is however dense and somewhat run-on, packing window defaults, ordering, series collapsing and freshness handling into long sentences that could be split for faster scanning.

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 and 11 parameters, the description carries the return-value burden and does so: short cards, total, next_cursor, data_freshness. Combined with the fallback warning and the ordering semantics, an agent has everything needed to call it correctly and to interpret a degraded response.

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 91%, so the baseline is 3; the description adds real value by explaining how date_from/date_to interact to form the window and how the resulting defaults are surfaced in applied_filters. It does not restate every parameter, but the derived-default semantics and the cursor-pagination contract (next_cursor) are meaningfully clarified beyond the schema text.

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?

Opens with a precise verb+resource plus the full filter surface (city, online/offline, direction, format, text search) and an explicit date window. It also delineates the boundary with get_event ('полное описание отдаёт get_event'), so an agent can separate this search tool from its sibling without opening schemas.

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 concrete when-to-use rules: default window is 7 days from today (Moscow time), and the derived-window behavior for date_from-only and date_to-only cases is spelled out. It also states the exclusion condition for past events (only when the window starts before today, max 60 days back) and points to get_event for full text and list_directions for direction names.

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