Дизайн-афиша

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

Beyond the readOnlyHint/idempotent annotations, it discloses real behavioral details: organizer text is truncated to 3000 chars, venue/organizer names appear only if confirmed, and past events carry past:true while remaining an archival page. These edge-case behaviors are exactly the kind of context annotations cannot convey.

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?

One dense but well-front-loaded sentence that puts the resource and id sourcing first, then enumerates returned fields, then the past-event archive note. Information-rich with little waste, though the field enumeration is packed tightly.

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 carries the return-shape burden and does so by listing the card's key fields and the past-event flag. Annotations cover safety; only minor gaps like exact field naming/format remain.

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% (baseline 3), and the description adds meaning the schema lacks: the id may be supplied either bare or as the full design-events.fun/event/<id> address. That clarifes accepted input forms beyond 'id события, как в url карточки'.

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+resource (retrieve the full event card by id) and enumerates what it returns: description, timezone, city, format, directions, links, venue/organizer. The id-based single-fetch scope clearly distinguishes it from the search_events/list_directions/plan_my_week siblings 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 implies when to use it — you have an id or a card URL ('по id ... или по самому адресу'), so you fetch that one event. But it names no alternative (e.g. 'use search_events to find the id first') and gives no when-not-to-use condition, leaving the routing mostly to inference.

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=false, so the safety profile is fully covered. The description adds value by disclosing the shape of each returned item (slug, name, page URL), which compensates for the absence of an output schema. It does not mention ordering, total count, or whether the list is static/cacheable — gaps that keep this at a 3 rather than higher.

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?

A single sentence that front-loads the resource and then lists the returned fields and their downstream use. Every clause earns its place; nothing is redundant with the title alone.

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 carries the burden of explaining return values, and it does so by naming the three fields an agent will receive. What is missing is minor: nothing about list size, ordering, or stability. For a zero-parameter read-only lookup tool this is close to complete.

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 tool takes zero parameters, so there is nothing to disambiguate; the baseline of 4 applies. The description correctly avoids inventing parameter guidance.

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 names the resource (направления/темы афиши) and, crucially, tells the agent what each entry contains: slug, название, and the direction page URL. It also connects the resource to the sibling tool by identifying the slug as the value for search_events.directions. It stops short of an explicit verb like 'returns the list of', but the intent is unambiguous.

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 'slug для search_events.directions' effectively states the primary use case: call this to obtain direction slugs before calling search_events with a directions filter. There is no explicit exclusion or alternative-tool comparison, but the sibling routing is clear enough for an agent to act on.

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 only cover the safety profile (readOnly, idempotent, non-destructive). The description adds the decisive behavioral fact that is nowhere in structured data: the call is a dead-end stub that yields a waitlist link, not a plan. It also flags the downstream obligation not to over-promise to the user, which meaningfully changes how an agent should sequence calls.

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, each doing distinct work: intent, actual behavior, then the alternative route. The most decision-relevant fact (Pro is not open) is placed early, and there is 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?

For a two-parameter stub with no output schema, nothing material is missing: the agent learns what it returns, that it will not satisfy the user's request, and which sibling to fall back on. Annotations already cover safety, so the remaining burden lands on the description and it is met.

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 has to carry both parameters — it does name them by concept ('по интересам и городу'), which maps to interests and city. But it gives no format detail: nothing on language, whether interests are free-text tags or a controlled vocabulary, or whether an empty call is valid despite zero required parameters. Partial compensation only.

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 the nominal purpose (a personal weekly plan by interests and city) and immediately corrects it with what the tool actually does: returns a waitlist/application link because Pro isn't open yet. It also names the sibling that produces real plans (search_events), so an agent can tell it apart. It loses a point only because the leading 'weekly plan' framing is a purpose the tool does not fulfill, requiring the agent to read past it.

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?

Explicit guidance on both edges: Pro is not open, so this tool only returns a signup link, and the agent should not promise the user a finished plan from it — build the plan via search_events instead. The alternative and the condition selecting it are named outright.

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?

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.