resolve_court_name

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

With no annotations, the description carries the full behavioral burden; it does disclose that results come from a limited sample, that this is not a complete registry, and that it performs 'один поиск' with call/card accounting, plus explicit ambiguity handling. It omits read-only/safety characterization and the cryptic 'учёт вызова' phrasing does little to clarify 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?

Three short sentences with no wasted bulk, but the ordering buries the most important fact (that name doubles as a text query) after a vague opening line, and the closing sentence about 'обычный учёт вызова и возвращённых карточек' is cryptic rather than informative.

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 5-parameter tool with an output schema and no annotations, the description covers the key fallback behavior and the limited-sample caveat but leaves limit, case_number, and the court_type sections largely to the schema, which documents only 40% of parameters. It is adequate but thin for a disambiguation tool whose siblings overlap in search functionality.

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 40%, and the description usefully clarifies the interplay between name, query, and case_number (name becomes a text query when the others are unset). It adds nothing about limit or the meaning of case_number, and court_type semantics come only from the schema's short enum note.

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 it returns candidate courts ('Кандидаты судов') from a limited sample of cards, which loosely matches the tool name resolve_court_name, but it never says plainly that it resolves a court name to canonical court entries. The domain-specific phrase 'выборки карточек' leaves the actual output ambiguous, though the court focus does implicitly separate it from the case/decision-oriented 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 implies a usage rule — if query and case_number are absent, name acts as a free-text query — and warns 'Это не полный справочник', hinting at when the tool is insufficient. However, no sibling is named as an alternative, and there is no explicit when-to-use/when-not statement for a query that could easily be confused with search_cases.

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