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

Beyond the annotations (readOnly, idempotent, non-destructive), the description adds specific behavioral disclosures: no authorization needed, 60 req/min rate limit, unknown-slug error-with-hint behavior, and an attribution requirement (reference canonical_url). It also explains the top field's selection semantics (best_value/max_amount/max_term with exact criteria), providing value well beyond annotation metadata.

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 long but every sentence earns its place: purpose, sibling routing, auth/rate-limit, the complex top-field semantics, error behavior, and attribution. It is front-loaded with the core purpose and usage guidance before the detailed field explanations. Slightly dense, but justified by the tool's complexity and absent output schema.

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 full responsibility for explaining the return shape — and it does so thoroughly: primary fields, the top field with its three variants and limits (up to 10 items, new-client conditions only), error responses for unknown slugs, and data source. An agent has everything needed to invoke and interpret the tool 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 description coverage is 100%, so the schema already fully documents both parameters (lang enum with default, slug with source and examples). The description adds minimal parameter-level meaning beyond the schema — it reinforces where the slug comes from and its thematic meaning, but this largely duplicates schema content. Baseline 3 is appropriate since the schema carries the burden.

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+resource ('Одна тематична добірка за slug') and enumerates exactly what is returned: selection criterion, sort order, MFI table with conditions, canonical_url and markdown_url. It explicitly differentiates from three siblings (search_offers, get_mfo, list_categories), making it impossible to confuse with similar tools.

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 an explicit when-to-use rule: use when the query matches a ready editorial collection ('кредит на картку', 'позика без відмови'). It then names concrete alternatives with their selection criteria: search_offers for numerical filtering, get_mfo for single-MFI details, list_categories for the full list. This is textbook routing with no inference required.

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