catalog

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.

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial behavioral context beyond this: no authentication required, rate limit of 60 requests/min, error response for unknown region, data source (МФОХА) and attribution requirement, plus detailed explanation of the 'top' field's semantics (pre-made selections with specific criteria). No contradiction with annotations.

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?

While the description is lengthy (approximately 150 words), every sentence contributes essential information. It front-loads the core purpose and mode behavior, then systematically covers slug sourcing, alternatives, top field semantics, special-case handling for Kyiv, error behavior, data source, and attribution. No filler or redundancy; the density is justified by the tool's complexity.

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?

Given the absence of an output schema, the description must convey return structure and behavior. It covers both region and city modes, the contents of the showcase (MFO table with conditions, canonical_url, markdown_url), the 'top' field with its three sub-selections, the Kyiv special case, error handling, language behavior, and usage constraints. An agent has everything needed to call this tool correctly and interpret its results.

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% (all three parameters have descriptions). The description adds meaning beyond the schema by explaining the effect of omitting 'city' (region page with city list) versus including it (city page with canonical_url and markdown_url), and clarifies that 'lang' only changes language, not data set. This is a meaningful augmentation over the schema's 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?

The description opens with a specific verb and resource: 'Витрина області або міста за slug' (showcase of region or city by slug). It clearly distinguishes the two modes (region vs city) and explicitly names the alternatives search_offers and get_mfo, making it easy for an agent to select the correct tool among 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?

The description gives explicit when-to-use scenarios ('кредит у Львові', 'МФО Одеської області'), tells the agent exactly where to source slugs (list_regions and get_city responses), and names the alternatives for other use cases (search_offers for amount/term, get_mfo for single MFO details). No ambiguity remains about when to invoke this tool.

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 indicate readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable context beyond that: it is a reference rather than legal advice, includes a reviewed_at field, and provides a source link, setting expectations about provenance and recency. No contradiction with annotations.

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 a single dense paragraph but is front-loaded with the resource summary and then proceeds through specific legal topics, usage guidance, and exclusions. It contains no filler or schema duplication, though bullet formatting could have made the list of legal topics slightly easier to parse.

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 read-only reference lookup with one optional parameter and no output schema, the description covers scope, content, provenance, usage, and sibling routing. It does not give a precise return-shape description, but it mentions reviewed_at and source link, which is sufficient for an agent 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?

The only parameter, lang, is fully documented in the schema with an enum, default value, and an explanation that it changes language only, not the dataset. The description does not add parameter-level meaning, so the baseline of 3 for high schema coverage 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 clearly states that this tool provides the legal context of microlending in Ukraine and enumerates specific content: the 1% daily rate cap, mandatory creditworthiness assessment, penalty limits, collector rules, and military credit holidays. It also explicitly says there is no data on individual MFOs, which distinguishes it from sibling tools like get_mfo and get_reviews.

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 gives explicit usage guidance: use this tool to verify the legality of terms or explain market rules. It also states a clear non-use condition — no data on specific MFOs — and names get_mfo and get_reviews as alternatives, making the when-to-use decision straightforward.

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 read-only/idempotent/non-destructive behavior, and the description adds meaningful details beyond them: no authorization required, 60 req/min limit, unknown-slug error behavior, null semantics for first_loan_zero_percent and rating, and data-source attribution. It also clarifies that first_loan_promo_days is not a grace period, preventing misinterpretation.

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 dense but front-loaded with purpose and output contents, then usage guidance, behavior, and attribution. Every sentence adds value, and despite the length, the format remains structured and scannable rather than padded.

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 full burden of explaining return values and does so thoroughly: loan terms, rates, first-loan promotions, borrower requirements, legal entity, license, documents, rating, and update date. It also covers error behavior, null semantics, and attribution requirements, making the tool effectively self-contained.

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 lang and slug fully, including defaults and examples. The description reinforces that the slug must come from list_mfo or search_offers and gives usage context, but it does not add much new parameter-level meaning beyond the schema.

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 ('повна картка однієї МФО за slug') and enumerates the returned content in detail. It also distinguishes itself from siblings by naming get_reviews, search_offers, and get_category for other tasks, so an agent can identify when get_mfo is the right tool.

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 explicitly says to use this tool when the company is already known, tells the agent where to get the slug (list_mfo or search_offers), and routes alternatives: get_reviews for text reviews, search_offers or get_category for comparisons. This is unambiguous and complete.

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 readOnlyHint/idempotentHint/destructiveHint annotations, the description discloses the rate limit (60 requests/min), no-auth requirement, the no-pagination cap ('типово і максимум 10, без пагінації'), and both edge cases: an MFO without reviews returns an empty list with total: 0, and an unknown slug produces an error with a hint to use list_mfo. Nothing contradicts the annotations.

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 four dense sentences, each earning its place: purpose and return fields, usage routing, safety/rate-limit info, then return behavior with edge cases. Core purpose is front-loaded before alternatives and edge behavior, with zero filler or redundancy.

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 compensates by specifying every returned element (rating, date, text, author name, total) as well as the empty-list and error response shapes. Combined with full annotations and 100% parameter coverage, nothing an agent needs to invoke this tool 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 description coverage is 100%, so the schema already fully documents slug (with format guidance and the /mfo/{slug} example), lang (with enum and default), and limit (1–10, default 10). The description adds only marginal context beyond the schema — the no-pagination consequence of limit and the error behavior for a bad slug — which keeps it at the baseline of 3.

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 opens with a specific verb+resource+scope: 'Останні відгуки позичальників про одну МФО за slug' (latest borrower reviews about one MFO by slug), and enumerates the returned fields (rating 1–5, date, text, author name, total). It explicitly distinguishes itself from siblings by noting that get_mfo or list_mfo suffice for an average rating, so an agent can tell this tool apart from the other read-only 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?

The description gives explicit routing: 'Використовуйте після get_mfo, коли потрібна думка клієнтів словами' (use after get_mfo when you need clients' opinions in words), and names get_mfo/list_mfo as the alternatives when only an average rating is needed. It even references list_mfo again for recovering from an unknown-slug error, leaving no ambiguity about when to use this tool vs its siblings.

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, and non-destructive behavior, but the description adds substantial extra context: no authorization required, rate limit of 60 requests/min, single response without pagination, data source attribution, and the requirement to link to canonical_url. This goes beyond the structured annotations.

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 multi-sentence but every sentence adds distinct value: core output, usage guidance, exclusions, access limitations, and sourcing. It is well-structured and front-loaded with the primary purpose, with no redundant 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 simple read-only list endpoint with one optional parameter, the description fully covers expected output fields, grouping, rate limits, pagination absence, authentication, and data source. No critical operational detail 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 description coverage is 100% for the only parameter (lang), including an explicit note that it changes response language but not the dataset. The description does not repeat or add parameter details, so the baseline of 3 is appropriate.

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 clearly states the tool lists thematic catalog collections split into credit and loan groups, with name, selection criterion, and canonical_url. It explicitly differentiates from siblings by noting that MFO lists belong to list_mfo and numeric conditions to search_offers, so an agent can confidently select this tool.

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 description is explicit about when to use it: to find a slug for get_category or to answer which thematic collections exist. It also gives clear exclusions by naming list_mfo and search_offers as alternatives for different needs, leaving no ambiguity about boundaries.

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 mark the tool as read-only, idempotent, and non-destructive. The description goes further by disclosing no-auth access, the 60 requests/minute limit, no pagination, site-rating ordering, and the meaning of rating: null. This is rich behavioral context beyond the annotations.

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 dense but every sentence serves a distinct purpose: content, usage routing, access constraints, ordering, null semantics, and attribution. It is front-loaded with the core purpose and then adds necessary behavioral details without fluff.

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?

Despite having no output schema, the description sufficiently explains return characteristics: complete list in one response, no pagination, ordering by site rating, and included fields. For a single-parameter tool with strong annotations, nothing essential 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 for the single lang parameter is 100%, and the schema itself already explains that lang changes the response language without changing the dataset. The description does not add parameter-level detail, so the baseline of 3 is appropriate.

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: it returns the full list of MFOs from the catalog with NBU licenses, including borrower ratings, review counts, and canonical URLs. It clearly differentiates itself from siblings by explaining that search_offers is for amount/term matching and list_categories is for thematic collections.

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 description explicitly tells when to use this tool: to obtain slugs for get_mfo/get_reviews or to get a market overview. It also names alternative tools for other use cases, giving clear routing guidance with no ambiguity.

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 readOnly/idempotent/non-destructive annotations, it discloses no auth required, a 60 req/min rate limit, single non-paginated response, the meaning of mfos_count: 0, and the data-model caveat that MFOs attach to regions so all cities in a region share a company list, plus Kyiv's is_city: true special case. These are behavioral traits annotations cannot express.

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?

Purpose is front-loaded and most sentences carry distinct information, but the block is dense and the citation instruction ('При використанні посилайтеся на canonical_url') plus the data-source credit are lower-value padding for tool selection.

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 fully specifies the return shape, pagination behavior, rate limits, and the edge-case semantics of mfos_count: 0, giving an agent everything needed to call and interpret 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 description coverage is 100% for the single lang parameter, so the schema already carries the enum semantics. The description adds no further meaning about lang (e.g., which surfaces the language affects), so the 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 exact fields returned per region (name, city count, MFO count, canonical_url, markdown_url). It explicitly contrasts itself with siblings, stating the city list is not here but comes from get_city without the city parameter.

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 concrete use cases ('щоб знайти slug області для get_city або для параметра region у search_offers, чи щоб відповісти, у яких регіонах є пропозиції') and names the alternative tool plus the condition that routes to it. The exclusion ('переліку міст тут немає') removes the most likely mis-selection.

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?

Discloses read-only behavior, no auth required, rate limit of 60 requests/min, filter combination semantics (AND), behavior with no filters (returns entire catalog), unknown region → error response, and limit truncation with total/truncated flags. All this goes well beyond the annotations, which only state readOnlyHint, idempotentHint, and destructiveHint. No contradiction.

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 each sentence carries essential information: purpose, output, usage, alternatives, constraints, parameter semantics, data source. It is front-loaded with the core purpose and then systematically details behavior. Slightly longer than necessary, but every part contributes; no fluff.

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?

Despite having no output schema, the description explicitly lists all returned fields (amount/term ranges, daily rate, real annual rate, first_loan_zero_percent, rating, canonical_url). It also covers error cases, rate limits, and data provenance, making it fully self-sufficient 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?

Adds significant context to all parameters: explains region is a slug from list_regions and filters by region, first_loan_zero only includes MFOs with confirmed first-loan promo, limit truncates and reveals total/truncated. The schema descriptions are complete (100% coverage), but the description enriches with behavioral details like AND combination and error handling, exceeding 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 clear purpose: filters MFOs based on client's desired amount and term falling within first-loan ranges, optionally filtered by zero-interest promo and region. It also lists the returned fields, making it unmistakable what the tool does. Explicitly distinguishes from sibling tools (list_mfo, get_mfo, get_city) by naming them and their use cases.

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?

Provides concrete usage examples ('where to get 5000 UAH for 30 days', 'credit 3000 UAH in Lviv') and clearly states when to use alternatives (list_mfo for full list, get_mfo for details, get_city for region/city page). This leaves no ambiguity about selection.

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