MFOXA - Ukraine Microfinance Catalog

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses the rate limit (60 запитів/хв), auth-free access, error behavior for unknown slugs (відповідь-помилка з підказкою), the data source (каталог МФОХА), and an attribution requirement (посилайтеся на canonical_url). This significantly enriches the safety and failure-mode picture beyond what structured annotations provide.

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 clause earns its place: purpose and response contents, usage trigger with examples, alternative routing, then behavioral notes (auth, rate limit, error, attribution). It is front-loaded with the core definition and flows logically from what → when → alternatives → behavior, with zero 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?

Despite having no output schema, the description enumerates the key response fields (criterion, sort order, MFO conditions table, canonical_url, markdown_url), covers error behavior, rate limits, and auth, and routes sibling usage. For a simple read-only fetch by slug, nothing an agent needs to call 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 baseline is 3; both lang and slug are already documented in the schema, including the language-versus-data distinction and slug examples. The description adds one genuinely new operational pointer — «slug беріть із list_categories» — telling the agent where to source valid slugs, which nudges 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?

The description names a specific verb and resource — «Одна тематична добірка за slug» — and enumerates the response contents (критерій відбору, порядок сортування, таблиця МФО з умовами, canonical_url, markdown_url). It explicitly names sibling tools it is not, so an agent can distinguish get_category from search_offers, get_mfo, and list_categories without opening their schemas.

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?

Explicit when-to-use guidance is given: «Використовуйте, коли запит збігається з готовою редакційною добіркою», with concrete query examples («кредит на картку», «позика без відмови»). It also states routing exclusions with alternatives: search_offers for numeric matching, get_mfo for single-MFO details, list_categories for the full list of selections — nothing is left to inference.

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 annotations, the description discloses no-auth access, a 60 req/min rate limit, static text identical across requests, canonical Ukrainian legal norms, lang affecting only the note field, the MFOHA data source, and the canonical_url attribution requirement. This is rich behavioral context.

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 and somewhat long, but every clause carries operational information: scope, content, use cases, alternatives, behavior, rate limit, language, data source, and attribution. It is front-loaded with the core purpose and has no filler, though it could be slightly more compact.

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 reference tool with one optional parameter and no output schema, the description is complete. It enumerates the returned legal topics, references the reviewed_at field and source link, explains language behavior, and gives usage constraints and attribution instructions.

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% for the single lang parameter, so the baseline is 3. The description adds meaningful nuance by clarifying that legal norms remain canonical in Ukrainian and that lang only affects the note field, which helps an agent understand the actual effect of the parameter.

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 identifies the resource: legal context of microcredit in Ukraine, explicitly framed as a reference rather than legal advice. It lists specific legal topics and distinguishes itself from get_mfo/search_offers by stating it contains no data about specific MFIs.

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 provides explicit when-to-use guidance: checking legality of terms or explaining market rules. It also names alternatives (get_mfo or search_offers) for cases where specific MFI data is needed, making the routing decision unambiguous.

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 provide readOnlyHint and idempotentHint, but the description adds valuable behavioral context: no authorization required, 60 requests/minute limit, unknown slug produces an error with a hint rather than empty result, and null semantics for first_loan_zero_percent and rating. These details go beyond what annotations or schema convey.

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 well organized: first the core resource and payload, then usage conditions, alternatives, behavioral constraints, and attribution. Every sentence adds useful information; none are 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?

There is no output schema, but the description compensates by enumerating the expected response fields and edge cases (null values, unknown slug error). It also covers attribution and data source, making the tool sufficiently complete for correct selection and 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% for both parameters, so the baseline is 3. The description mostly repeats slug sourcing guidance already present in the schema and adds little new semantic meaning beyond reinforcing that slug comes from list_mfo or search_offers.

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 the resource clearly: a full card for a single MFO looked up by slug. It enumerates the returned content and differentiates itself from siblings by naming get_reviews, search_offers, and get_category as alternatives.

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 instructs when to use this tool ('коли компанія вже відома'), where to obtain slug values (list_mfo or search_offers), and which sibling tools to use instead for reviews or comparison. This is unambiguous routing guidance.

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?

The annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior; the description additionally discloses no-auth requirements, rate limit of 60 req/min, no pagination with max 10 newest reviews, empty-list/total:0 edge cases, unknown-slug error behavior, data source, and canonical_url attribution requirement. 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 dense but every clause adds value: return contract, usage guidance, behavioral limits, edge cases, data source, and attribution. It is front-loaded with the core purpose and contains no redundancy with the schema or annotations.

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?

There is no output schema, but the description fully explains the returned fields, result limits, edge cases, rate limit, authorization, and relationship to sibling tools. An agent has all necessary information to select, call, and interpret the result of this 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 coverage is 100%, so the schema already documents all three parameters. The description adds operational semantics: slug is tied to list_mfo or the /mfo/{slug} URL, and limit is clarified as returning newest reviews with no pagination. Lang is not covered in the description, but the schema fully documents it.

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: it returns the latest borrower reviews for one MFO by slug, and enumerates the returned fields (rating 1–5, date, text, author, total). It also differentiates itself from siblings by explicitly noting that get_mfo/list_mfo suffice for average ratings.

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 instructs to use this tool after get_mfo when qualitative customer opinions are needed, and says get_mfo or list_mfo is enough for average ratings. This gives clear when-to-use and when-not-to-use guidance relative to sibling tools.

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 this as read-only, idempotent, and non-destructive; the description adds concrete behavioral constraints: no authorization required, rate limit of 60 requests/minute, a single response without pagination, and the requirement to cite canonical_url when using the data. It also identifies the data source (mfoxa.com.ua). No contradiction with annotations; the extra context is useful.

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 every sentence carries distinct value: what, examples, usage, alternatives, behavioral limits, attribution. It is front-loaded with the main purpose and then specifies constraints. While slightly dense, it contains no filler or redundancy; a 4 rather than 5 because the structure could be broken into clearer segments.

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 covers purpose, output fields, grouping, usage, alternatives, rate limit, auth, pagination, and attribution. Without an output schema, it still tells the agent what each entry contains. Nothing needed to select or invoke the 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?

The sole parameter lang is fully described in the schema (enum uk/ru, default, effect on language but not dataset), so the description need not add anything. Baseline 3 because schema coverage is 100%; the description adds no parameter-level details beyond the schema. This 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 returns a list of thematic catalog collections divided into credit/loan groups plus a loan hub, with each item carrying name, criterion, and canonical_url. It explicitly names known examples (kredit-na-kartu, pozyka-na-kartku), making the resource and scope unambiguous. It also distinguishes itself from list_mfo and search_offers, so there is no confusion with 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 explicitly instructs when to use this tool: to find a slug for get_category or answer which thematic selections exist. It states what this tool does NOT provide (MFO list, numeric criteria) and points to list_mfo and search_offers as alternatives. This exceeds a generic 'use for X' by giving exclusions.

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 read-only, idempotent, and non-destructive behavior, and the description adds valuable context beyond that: no authentication required, 60 requests/minute limit, no pagination, full list returned, site-rating order, and the meaning of rating: null. It also clarifies the rating_status field and source attribution, all of which improve safe and correct invocation.

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 earns its place: purpose, usage routing, auth/rate-limit context, response shape, ordering, null semantics, and attribution. No fluff or 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 simple no-required-parameter list endpoint with no output schema, the description is remarkably complete. It covers what is returned, ordering, pagination absence, null-value meaning, rate limits, auth requirements, and how to reference results, so an agent has everything needed to call 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%: the only parameter, lang, is fully described with its enum values and default. The description does not add parameter-specific semantics, but it does not need to since the schema already 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 clearly states the tool returns a full list of MFO catalog companies with NBU licenses, including rating, review count, and canonical_url. It explicitly distinguishes itself from sibling tools like get_mfo, get_reviews, search_offers, and list_categories by naming what each is for.

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 guidance is explicit: use list_mfo to obtain slugs for get_mfo/get_reviews or to get a market overview, use search_offers for amount/term matching, and list_categories for thematic collections. This gives the agent clear routing rules 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?

Annotations already mark the tool read-only and idempotent, but the description adds concrete behavioral context: no authorization needed, a 60 requests/min limit, independent filters combined with AND, full catalog when unfiltered, truncation semantics (total/truncated), data source attribution, and a requirement to link canonical_url. No contradictions.

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 carries functional information: purpose, output fields, usage routing, safety, filter semantics, pagination behavior, source, and citation requirement. It is front-loaded with the core matching logic and does not repeat schema details verbatim.

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 tool with five parameters, no output schema, and no nested objects, the description is unusually complete: it enumerates the returned fields, explains filter and limit behavior, identifies the data source, and specifies attribution. An agent has everything needed to select, call, and interpret the result.

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 baseline is 3, but the description adds meaning beyond the schema: it explains that amount/term are matched against the first-loan range, that first_loan_zero is an optional confirmed-loan filter, that limit is a truncation control with total/truncated reporting, and that filters compose via AND.

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 uses a specific verb and resource: it selects MFOs whose first-loan amount/term ranges match the requested sum and term, and lists exactly what is returned for each MFO. It also distinguishes itself from siblings by naming list_mfo and get_mfo as alternatives, so an agent can route correctly.

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 an explicit when-to-use signal ('де взяти 5000 грн на 30 днів'), tells when to use list_mfo instead (full catalog without conditions), and when to use get_mfo (details of one MFO). It also explains filter composition and the no-filter fallback, leaving no ambiguity.

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