Server Quality Checklist

Tool Scores

• get_offer_detailsA
  3.9/5.0
  Behavior3/5

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

  No annotations are provided, so the description must cover behavioral traits. It discloses the tool provides multiple types of data (text, photos, seller info) and implies a read-only operation. However, it doesn't specify return format limits (e.g., max photo URLs, pagination of characteristics), auth requirements, or whether the offer must be active/visible. Lacks full transparency.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness4/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is a single concise sentence that front-loads the key action and lists contents efficiently. It earns its place without extraneous words. Could be improved by slightly greater precision on what constitutes 'full details' but is very clear overall.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the tool has only one parameter, no nested objects, high schema coverage, and no output schema, the description is reasonably complete. It explains what data is returned (text, photos, seller, etc.) and how to use the parameter. Without an output schema, it would benefit from mentioning return structure, but the context signals reduce that need.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 100% and already describes the offer_id parameter well, including format and example. The description adds value by confirming the id comes from search_offers results, but doesn't add semantic details beyond the schema. Baseline 3 is appropriate given high schema coverage.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool retrieves full details for a single OLX offer by ID, listing specific content (plain-text description, characteristics, photo URLs, seller, status, dates). This is a specific verb+resource combination that distinguishes it from sibling tools like search_offers, which returns multiple results rather than one item's complete details.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description implies usage when you need comprehensive information for a particular offer, contrasting with search_offers which returns a list. It states the required input is an offer_id obtained from search_offers results, giving clear context for when to use this tool vs alternatives, though it does not explicitly say when not to use it.

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

• list_regionsA
  4.2/5.0
  Behavior3/5

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

  No annotations provided, so description carries burden. It discloses the tool lists regions/cities with ids – a safe read operation. No mention of performance, caching, or region scope, but adequate for a simple lookup.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Single sentence, no wasted words. Front-loaded with action and resource, and includes purpose context (ids for search_offers).

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given zero params and no output schema, the description is nearly complete. It could mention whether cities are grouped under regions or are flat, but the core need (getting ids for search_offers) is met.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema has zero parameters and coverage is 100%, so no param info needed. Description adds value by explaining the output ties to search_offers parameters.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  Description states specific verb (List), resource (OLX regions and major cities), and output (ids for search_offers). Distinguishes from siblings like search_offers (which uses the ids) and list_categories.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  Clear context for use – provides ids needed by search_offers. No explicit when-not or exclusions, but sibling tool names hint at alternatives.

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

• prom_search_offersA
  4.3/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the full burden. It mentions the return structure (total, returned, offers with fields) but does not explicitly state that the operation is read-only or idempotent. It also omits authentication requirements or rate limits. For a search tool, the behavioral implications are mostly clear, but explicit safety disclosure would improve transparency.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is two sentences plus a usage tip—concise and front-loaded with the action and return structure. Every sentence adds value, and there is no extraneous information.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  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 usefully lists the return fields (total, returned, offers with id, title, price, currency, url). It also covers marketplace context and sibling differentiation. With 100% schema coverage, the description is sufficient for an agent to understand and invoke the tool correctly.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 100%—all parameters already have descriptions in the schema. The description adds minimal value beyond the schema, only clarifying that price is in UAH (already stated in schema). The baseline is 3 for high coverage, and the description does not significantly enhance parameter understanding.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description explicitly states the tool searches Prom.ua (Ukrainian B2C marketplace) and returns matching products. It differentiates from the sibling 'search_offers' by specifying that Prom sells new products from shops, while the other is for used/individual listings. The verb 'Search' and resource 'Prom.ua' are clear and specific.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description provides explicit guidance on when to use this tool versus alternatives: 'For used/individual listings use search_offers (OLX).' It also gives context that Prom sells new products and compares it to Hotline, helping the agent decide 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.

• list_categoriesA
  4.5/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden. It discloses that the data is a static snapshot of the most useful categories and that the live OLX category endpoint is deprecated. This gives important behavioral context about data freshness and completeness, which goes beyond a simple 'list' command.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is two sentences long, front-loaded with the action and purpose, and every word adds value. There is no repetition or irrelevant information, making it highly efficient for an AI agent to parse.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given no output schema, the description sufficiently explains the return format (id and name), the tool's limitation (static snapshot), and its practical use (feeding category_id to search_offers). For a zero-parameter tool, this level of detail is complete.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The tool has zero parameters, so baseline is 4. The description adds value by clarifying the output structure (id and name) and the static nature of the list, which supplements the empty schema adequately.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states it lists OLX categories with id and name for the purpose of obtaining a category_id to use with search_offers. It distinguishes itself from siblings by specifying its unique output and relationship to search_offers, making it easy for an agent to select this tool over list_filters or list_regions.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description provides explicit guidance on when to use this tool (before search_offers to get a category_id) and when to omit category_id in search_offers (if the category is not listed). However, it does not explicitly exclude usage for other scenarios or compare to sibling tools like list_filters, leaving some ambiguity.

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

• hotline_search_offersA
  4.7/5.0
  Behavior4/5

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

  With no annotations provided, the description bears full responsibility. It discloses critical behavior: returns product MODELS not individual listings, price is a range, location unavailable. It does not mention rate limits or authentication requirements, but for a search tool these are typically less critical. The note about price being minimum shop price adds transparency beyond the schema.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Three sentences, zero wordiness. The first sentence immediately states purpose and return format. The second adds the crucial behavioral note. The third provides usage guidance and sibling differentiation. Information is front-loaded and every sentence earns its place.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given no output schema and 5 parameters, the description explains the return structure ({total, returned, offers}; each offer has id, title, price, currency, url), explains what price means (min shop price, UAH), and covers limitations (model-level, no location). It also references sibling tools. Pagination is covered by schema, but the description is self-sufficient for an agent to understand inputs, outputs, and context.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 100%, so baseline is 3. The description adds value by explaining that price represents minimum shop price in UAH, gives query examples like 'ssd 2.5 sata' or 'монітор 24', and clarifies that min/max price is 'applied to the min shop price'. This interpretation helps the agent understand parameter semantics beyond the schema.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description uses specific verb 'Search' and resource 'Hotline.ua (Ukrainian price aggregator)', clearly stating it returns 'product models with their price range across shops'. It explicitly differentiates from sibling tool search_offers (OLX) by noting Hotline returns models, not individual listings.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description gives explicit guidance: use for 'comparing prices/specs of a product model' and advises to also call search_offers (OLX) 'for used/individual listings (with location)'. This creates a clear when-to-use and when-not-to-use directive.

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

• list_filtersA
  4.7/5.0
  Behavior4/5

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

  The description discloses key behavioral traits: the tool samples offers to extract filter attributes, it requires a query string, and it can be scoped to a category. Since no annotations are provided, the description carries full burden for transparency. It covers intent well but doesn't mention limitations like sample size or missing filters if category is not specified. Still, given no annotations, this is strong.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is extremely concise: two sentences that pack purpose, usage timing, and an edge case example. Every sentence earns its place with actionable information, and it front-loads the purpose without waste.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the complexity of 3 parameters (one required), an output schema (which the description doesn't need to cover), and no annotations, the description is remarkably complete. It tells the agent when to use it, how to handle ambiguous queries, and what to expect as output (filter attributes with sample values). No gaps are apparent.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 100%, so the baseline is 3. However, the description adds meaning by explaining how parameters relate to the workflow (e.g., query should be 'монітор' or 'ssd', category_id comes from list_categories(), limit is for sampling). It doesn't add new param descriptions but enriches the context of usage, justifying a 4.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description uses specific verbs ('Discover', 'find') and a clear resource ('category-specific filter attributes and sample values for a search query'). It explicitly distinguishes this tool from siblings by positioning it as a prerequisite to search_offers, which is listed as a sibling. This makes the purpose unambiguous and well-differentiated.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description provides explicit guidance on when to call this tool: 'BEFORE search_offers when the user mentions an attribute like resolution, capacity, brand, etc.' It also explains the alternative behavior for ambiguous queries ('pass category_id from list_categories() to restrict to one category'). This is a perfect example of usage context with exclusions and alternatives.

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

• search_offersA
  5/5.0
  Behavior5/5

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

  With no annotations provided, the description fully discloses behavior: return format (total, returned, offers), offer structure (id, title, price in UAH, currency, location, url), sorting behavior (price_asc/price_desc sorted client-side), filters handling (string keys or two-number arrays for ranges), and the include_promoted option. It also notes that the server accepts OLX-style wrappers for range filters.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is concise: a one-sentence purpose and return format summary, followed by a clear paragraph of usage guidelines. Every sentence adds unique value, no repetition of schema or annotations, and the structure front-loads the essential purpose.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given 12 parameters, no output schema, and no annotations, the description is remarkably complete. It covers the return format, offer fields, parameter usage patterns (query vs filters, location/category IDs), sorting behaviors, and platform alternatives. The description fully compensates for the lack of structured annotations and output schema.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters5/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  While schema coverage is 100%, the description adds significant meaning beyond the schema: it explains how to use the query parameter for attributes without dedicated filters, clarifies the client-side sorting behavior for price sorts, details the filter value format (string or two-number list) and the accepted OLX wrapper, and specifies that include_promoted controls top_ad, highlighted, and urgent listings. This goes well beyond the schema's field descriptions.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states it searches OLX.ua and returns a page of matching offers plus total count. It specifies the return format and distinguishes from sibling tools (hotline_search_offers, prom_search_offers, list_filters, etc.) by naming them explicitly, making the tool's specific function unambiguous.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description provides explicit when-to-use guidance: call list_filters for category-specific attributes, list_regions for location IDs, list_categories for category IDs. It also tells the agent when to use alternatives (hotline_search_offers and prom_search_offers for price comparison across shops) and warns against deep pagination in favor of filters.

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