Starosta.ru — каталог артистов

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds useful beyond-annotation context: only published profiles are retrievable, price may be absent ('если указана'), and contacts shown on the page are direct/free. It omits what happens when the profile is not found or when neither id nor alias is supplied.

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 resource and returned fields are front-loaded in a single dense sentence. The trailing line 'Связь с артистом напрямую, бесплатно' is promotional rather than selection-relevant and does not earn its place, keeping it from a 5.

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 simple read tool with full schema coverage and rich annotations, most needs are met. However, with zero required parameters and two alternative identifiers, the description should clarify that at least one of id/alias must be provided and how they behave relative to each other; that gap matters 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 100% and the schema itself explains that id comes from search_artists and alias is the slug without domain. The description adds no further meaning about how the two identifiers relate or which to prefer, so baseline 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?

The description gives a specific verb+resource ('Подробная информация об одной опубликованной анкете') and enumerates the fields returned (описание, город, категории, сайт, стоимость, контакты). It implies a single-record lookup versus the sibling search_artists, but never names that sibling or states the relationship explicitly.

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?

Usage is only implied: 'одной опубликованной анкете' signals a single-record fetch rather than a list/search, so an agent can infer this is the drill-down step after search_artists or list_cities. No explicit when-to-use, prerequisites, or alternatives are stated in the description itself.

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 structurally. The description adds genuine value by disclosing that entries carry a count of published profiles and links, which hints at returned shape. It does not say whether the taxonomy is hierarchical/nested, whether unpublished or empty categories are included, or how large the result typically is.

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 compact sentence with no filler, and the payload content (counts, links) is front-loaded. The trade-off is that its terseness comes partly from omitting a verb and any operational detail, so it is efficient but slightly under-specified rather than optimally structured.

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 zero-parameter, read-only listing with no output schema, the description should carry the return-shape burden — and it partly does by mentioning counts of published profiles and links. It stops short of describing the hierarchy (flat sections vs. nested subcategories), whether counts are filtered by publication status, or the expected result size, which an agent consuming this data would want.

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 no parameter meaning for the description to supply and the baseline of 4 applies. Nothing in the sentence misdescribes the (empty) input contract.

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?

Names a specific resource — the catalog's sections and subcategories — and adds what comes back with them (count of published profiles and links). That is far more informative than a tautological restatement of the name, and it implicitly separates this taxonomy listing from the artist- and city-oriented siblings. It loses the top score only because it is a bare noun phrase with no verb, so the 'list returns' framing is inferred rather than stated.

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?

There is no guidance on when to call this rather than get_artist, list_cities, or search_artists, and no stated prerequisites or follow-up patterns (e.g. use the returned count/links to drive a filtered search). An agent must infer the routing from the resource name alone.

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 destructiveHint=false, so the safety profile is covered. The description usefully adds that only cities with published profiles appear and that counts are included, but says nothing about ordering, pagination, or how min_artists changes the result set.

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 short sentences with the core scope stated first and the filtering option second; no filler. It is terse to the point of omitting parameter detail, but not 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 small read-only list tool with no output schema, the description conveys what the rows represent and that counts are returned. It falls short on the min_artists threshold and on result ordering/limits, which an agent would need to use the tool precisely.

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 50%: 'query' is described only as 'part of the city name', and the description clarifies it as a prefix match ('начало названия'), which is a real semantic addition. However, min_artists has no description anywhere and the text only vaguely alludes to profile counts, so the second parameter remains undocumented.

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 (cities) and the exact subset returned: cities that have published profiles, together with the profile count. That is specific enough to separate it from search_artists or list_categories, though it never explicitly contrasts itself with those siblings.

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 states that results can be narrowed by the start of a city name, which implies a browsing/autocomplete use case, but gives no explicit when-to-use versus search_artists or list_categories, and no exclusions or prerequisites.

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?

Beyond the annotations, the description adds meaningful behavior: it searches only published profiles, returns up to 20 profiles with page links, and excludes contacts. It does not explain result ordering or pagination behavior, but annotations already cover read-only, idempotent, non-destructive behavior.

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 three tight sentences with the tool's scope and result cap front-loaded, followed by the important contact handoff. Every sentence carries useful information with no redundant repetition.

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 search tool with no output schema, the description gives enough to call it correctly: scope, filters, result cap, and contact handoff are all covered, and annotations carry the safety profile. It could be stronger by mentioning ordering or pagination, but misses nothing critical for 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?

The description summarizes the main filter dimensions (text, category, city, video), which maps to several parameters, but the schema already documents those parameters in more detail. It adds little for limit and offset, and with 67% schema description coverage this is a baseline-level contribution.

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 verb ('Поиск') and resource ('опубликованных анкет артистов и коллективов') along with the catalog scope, geography, and supported filters. It also distinguishes itself from get_artist by explicitly handing off contacts to that sibling.

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 clearly indicates the search use case and routes contact retrieval to get_artist, which is a useful alternative-tool handoff. However, it does not explicitly say when to prefer this tool over list_categories/list_cities or when not to use it, so some guidance remains implicit.

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