СПОНТАННО

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

Annotations cover the safety profile (readOnly=false, destructive=false, idempotent=true, openWorld=true), and the description adds real substance on top: the return is a link valid 90 days, identical events+title deterministically yield the same link, and unknown ids surface as 'missing' rather than failing. That determinism and error-handling detail is exactly the behavioral context an agent needs before calling a creator tool.

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 the core action and output URL, then trigger phrases, then behavioral facts. Dense and mostly waste-free, though the first sentence carries several clauses at once and the quoting of Russian trigger phrases adds bulk.

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 an output schema present, the description needn't explain return shape, and it still covers the essentials an agent would otherwise guess: what gets created, link lifetime, idempotency semantics, and how invalid input is reported. Nothing material is left open for a 2-parameter creation 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% — both parameters are already documented with bounds (2–10 items, order preserved, Russian title, no links/emoji). The description only restates that ids come from previous results and adds the unknown-id outcome, which is return behavior rather than parameter meaning, so it sits at the baseline.

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 (save), a constrained resource (2–10 events from previous results), and the concrete artifact produced (a shareable page at spontanno.space/s/{code}). This is unmistakably distinct from sibling readers like search_events or get_event.

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 explicit triggering contexts — «скинь списком», «сохрани», «отправлю друзьям», and after planning an evening or weekend — so the agent knows when to reach for it. It stops short of naming when NOT to use it or pointing at an alternative, but the when-to-use signal is strong.

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, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds useful behavioral context beyond annotations: ticket prices are listed by seller with no links because purchase happens on the event page, and it hints at related output (similar events, calendar links).

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, front-loaded with the core purpose and then the usage condition. The first sentence is dense with an enumerated list of return fields, which is slightly overstuffed given an output schema exists, but nothing is wasted or confusing.

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 one-parameter read tool with rich annotations and an output schema, the description is complete: it covers what the tool returns, the accepted identifier forms, the when-to-use condition, and the notable ticket-link caveat. An agent has everything needed to invoke 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?

Schema coverage is 100%, and the schema parameter description already specifies the 8-character id format and full URL acceptance. The description repeats that ids come from previous results or a spontanno.space URL but adds no syntax or format detail beyond the schema, so the baseline of 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 ('Full details of one event by its `id`') and enumerates the returned content (dates, venues, address, age limit, prices, calendar links, similar events). This clearly distinguishes it from sibling search/list tools without needing to name them.

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?

Explicitly says when to use it: 'when the user asks about a specific event, its schedule, price or where to buy tickets.' It does not name an alternative for discovery (e.g., search_events), but the 'specific event' condition is clear enough to route correctly.

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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds that `query` performs fuzzy normalization of city names ('Питер', 'Екб', «в Нижнем»), which is useful behavioral context, but omits anything about result ordering or pagination behavior for the list mode.

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, both densely packed with no filler, and the coverage-checking purpose is front-loaded ahead of the usage condition. The sentences are long, but every clause carries routing or behavioral 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?

An output schema exists so return values need no explanation, and the description is complete enough to select and invoke the tool in either mode. The only gap is that it doesn't tell the agent how the two modes' outputs differ in practice or when to prefer the list mode over a targeted query.

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 both parameters are already documented in the schema, including the 'any form' behavior of `query`. The description only restates this, adding the overview dimensions returned (counts, free events, categories), which is return-value information rather than parameter meaning.

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 ('Check which Russian cities СПОНТАННО covers and how many events each has') and covers both operating modes: the no-argument list mode and the `query` resolution mode. It is clearly distinguishable from siblings like search_events and get_event, which operate on events rather than city coverage.

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?

Explicitly names the conditions under which to use it: 'when unsure whether a city is covered' or 'when the user asks what is happening in a city in general.' Clear positive guidance, but it never names an alternative sibling (e.g., search_events for specific event lookups) nor states when not to use it.

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/openWorld=false, so safety is covered. The description still adds real behavioral value: result cap of 20, the `next_cursor` pagination mechanism, city-local time semantics, and the note that organizer-authored titles/descriptions arrive as plain data (a useful prompt-injection caveat).

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 usage, then return shape — a sensible order. It is slightly padded: the long genre list partially duplicates the `categories` enum and the prose is denser than needed, but no sentence is wasted.

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 15-parameter tool with a nested `near` object, the description covers purpose, when to use, result count, pagination and time semantics; an output schema exists so return values need not be detailed. It stops short of covering city-vs-near mutual exclusion, which the schema handles.

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 every parameter is documented in-schema with enums, defaults and ranges, so the baseline is 3. The description maps a few user intents to parameters (free events, near a place, genre/performer) but adds little syntax or default detail beyond what the schema already carries.

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 concrete verb and resource ('Search the СПОНТАННО events listing') and scopes the domain (concerts, theatre, standup, etc., in Russian cities). It explicitly contrasts itself with the sibling spontanno_random_event ('A single surprise pick is what spontanno_random_event is for'), so an agent can route without opening either 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?

'Use this when the user wants options' enumerates the triggering intents — what's on today/tomorrow/weekend, genre, performer, venue, free events, near a place — and names the alternative tool for the single-pick case. Both when-to-use and the exclusion are present.

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/destructive annotations by disclosing the progressive relaxation order (drops time of day, then widens dates; never drops categories, price or «free») and that the response reports what was relaxed. Also says each pick carries a short `why` and event URL.

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-loads the signature feature and consumes no filler, but the middle sentence packs filtering, relaxation order, and follow-up routing into one long run-on. Dense and useful, though slightly harder to scan than a segmented version would be.

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 15-parameter tool with nested `near` and an output schema, the description covers selection purpose, filter behavior, degradation policy, and conversation-follow-up mechanics. Return format is covered by the output schema, so nothing an agent needs to invoke it correctly is 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% so the schema already documents all 15 parameters, establishing a baseline of 3. The description adds genuinely new semantics for two of them — that `exclude` should receive `exclude_next` from the prior result and that `count` caps at 3 different picks — which lifts it above baseline.

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 — 'pick ONE random worthwhile event (or up to 3)' matching filters — and immediately lists the user utterances it serves. This is clearly distinguishable from list/search/get siblings by the random-pick semantics.

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?

Maps concrete triggers («удиви меня», «куда-нибудь сходить», «не могу выбрать») to the tool, and routes the two follow-up cases explicitly: `like_event` for 'something else at the same day/time' and `exclude` with `exclude_next` for 'ещё раз / другое'. The condition selecting each alternative is spelled out.

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