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

The description goes far beyond the annotations by disclosing crucial behavioral details: 'refresh: May be PAID unless free refresh is available', 'remove: delete a finished advert PERMANENTLY — cannot be undone', and the requirement to confirm with the user for paid or destructive actions. This adds significant value over the destructiveHint and idempotentHint flags, which are generic. The description paints a clear picture of side effects and prerequisites.

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 compact bullet list that front-loads the main purpose and then breaks down each action with necessary details. Every line adds value: the intro clarifies it mirrors the 'My ads' page, and each bullet includes a definition plus any caveats (paid, permanent, confirmation). No wasted words, and the structure is easy to scan.

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 tool's complexity—multiple state changes, potential costs, and a permanent deletion option—the description covers all essential aspects: what each action does, when it's paid, when confirmation is required, and the irreversibility of removal. There is no output schema, so return values are not needed. An agent has everything required to invoke the tool correctly and safely.

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 0%, but the description thoroughly explains the 'action' enum by detailing each possible value with its semantics and implications. For 'advert_id', the parameter name is self-explanatory and the schema already provides type and constraints. The description does not explicitly describe advert_id, but the action parameter's rich explanation compensates for the lack of schema descriptions.

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's purpose: 'Change the state of one of the account's adverts' and enumerates six specific actions with detailed explanations. It distinguishes itself from sibling tools like olx_list_my_adverts (listing) and olx_get_my_advert (viewing) by focusing on state mutations, leaving no ambiguity about its function.

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 provides concrete guidance for each action, including when to use them (e.g., 'activate: re-activate a finished/inactive advert') and important cautions (e.g., 'refresh: ... May be PAID unless free refresh is available — confirm with the user first'). While it doesn't explicitly name alternative tools, the context makes it clear this is for modifying adverts, not for listing or viewing them. The guidance is strong but stops short of explicit 'when not to use' statements.

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, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds the detail that it collects live listings and returns recommendations, but does not elaborate on internal behavior like potential rate limits or data freshness. The added context is useful but not extensive, fitting a baseline 3 given annotation coverage.

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 well-structured with a bulleted list of outputs, making it easy to scan. It front-loads the core purpose and provides targeted use cases and a practical tip, with no wasted words.

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 tool's complexity (11 params, no required params, no output schema), the description clearly explains the return values and usage guidance. It could mention limitations like the need for category filtering, but the tip already covers a key edge case. It's nearly complete for an agent to invoke 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 all 11 parameters are documented with descriptions (e.g., query, city_id, sample_size). The description does not add extra parameter-level guidance beyond the tip about category_id, which is helpful but minor. Baseline 3 is appropriate since the schema already covers the parameters well.

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 tool performs market analysis for a product/segment, listing specific outputs (price stats, competition level, seller split, recommendations). It distinguishes itself from siblings like olx_find_competitors and olx_compare_my_advert by focusing on aggregate market data rather than individual competitor comparison.

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 explicit use cases such as 'how much should I sell X for' and 'how competitive is this niche', and notes no auth needed. It also gives a tip to narrow with category_id to avoid irrelevant matches, helping agents decide when to apply this tool over other search 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 provide readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context: it loads advert stats, searches live listings by title/category, requires a session, and produces recommendations. There is no contradiction with 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 front-loads the core purpose in the first sentence, then compactly summarizes the behavior and the key outputs. The Args block is terse and each line conveys a meaningful constraint or provenance detail. No filler or repetition of the schema is present.

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 tool's moderate complexity and six parameters, the description covers the main behavioral flow, input provenance, and the nature of the generated report. The response_format parameter already tells the agent how results will be returned, so an output schema is not required. It is not a 5 only because it does not explicitly tell the agent when to prefer this over closely related siblings.

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 83%, so the baseline is 3, but the description adds meaning beyond the schema by explaining that advert_id comes from olx_list_my_adverts, query defaults to the first 5 title words, and city_id/region_id restrict competitors. It also clarifies the purpose of sample_size as the number of listings to compare against. This is genuinely useful guidance above the structured 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 ('Compare'), a clear resource ('one of the logged-in account's adverts'), and the comparison target ('similar live listings on OLX'). It also enumerates the output report components, leaving no ambiguity about what the tool produces. It is clearly distinguishable from siblings like olx_find_competitors or olx_analyze_market because it operates on the caller's own advert.

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 clear context: it needs a session, uses title keywords within the same category, and can be restricted by location. It references provenance helpers such as olx_list_my_adverts and olx_find_location. It does not explicitly name when-not-to-use it or list exclusion criteria against sibling tools, so it stops just short of a 5.

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, and the description adds substantial behavioral context: it samples listings, groups by seller, ranks by listing count, enriches top sellers with profile and active-listing data, and states that no auth is needed. The explicit list of returned per-competitor fields also goes well beyond the annotation hints.

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 compact and well ordered: purpose first, then method, then return fields, then follow-up, then auth note. Every sentence earns its place, and there is no redundant restatement of schema constraints.

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 12-parameter tool with no output schema, the description covers the core behavior, return fields, next-step tool, and authentication requirements, while the schema covers all parameter details. The remaining ambiguity is that all parameters are optional and the description does not clarify what happens or what is required for a valid call with no filters.

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 every one of the 12 parameters is already documented with type, constraints, and examples in the input schema. The tool description adds no additional parameter semantics, so the baseline score 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 a specific verb and resource: identifying the main competitors/sellers for a product/segment on OLX. It also explains the method (grouping sampled listings by seller, ranking by count, enriching top sellers), which makes the tool's function concrete and distinguishable from listing-search and seller-profile 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 explicitly indicates when to use the tool — when competitor discovery for a product/segment is needed — and gives a clear follow-up path with olx_get_seller(seller_id). It does not, however, state when not to use it or how it compares to olx_search_offers or olx_analyze_market, so it lacks full exclusion 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?

Annotations already cover read-only, idempotent, non-destructive behavior; the description adds 'No auth needed', which is a useful access/behavioral fact beyond the schema and annotations. It also makes clear the operation is a pure lookup by place name, with no side effects.

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, each earns its place: function and examples, auth requirement, and downstream usage. The core action is front-loaded and there is no 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 single-parameter, low-complexity lookup with rich annotations, the description is nearly complete: input, output kinds, auth, and downstream use. It doesn't specify the exact return shape, but the absence of an output schema is compensated by the explicit list of IDs returned.

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?

Input schema already documents 'name' with 100% coverage, so baseline is 3; the description adds concrete examples ('Samarqand', 'Chilonzor', 'Ташкент') and clarifies the parameter is a place name that maps to OLX location IDs. That extra semantic detail justifies a 4.

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 ('Find'), the exact resource ('OLX city_id / district_id / region_id'), and the input ('by place name'). The purpose is sharply distinct from sibling tools like olx_search_offers or olx_get_profile, so an agent can select it unambiguously.

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 says when to use the tool ('Use the IDs for market search filters ... and for advert location') and notes no auth is needed. It doesn't name alternative tools or exclusions, but the use-case statement is clear enough.

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 annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description adds 'No auth needed' and clarifies that the response is a category's configuration, including parameter constraints and allowed values. This gives the agent a concrete expectation of what will come back. It does not cover error handling or rate limits, but for a safe, read-only lookup the annotations already cover the key behavioral traits. 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?

Four short, information-dense sentences with no filler. The primary result fields are front-loaded in the first sentence, followed immediately by the actionable use case, auth note, and sibling-tool pointer. It avoids repeating schema text and every sentence earns its place.

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 lookup with no output schema, the description covers what the category data contains, where to get the category_id, and why the result is useful for posting adverts. The optional response_format and include_children parameters are explained in the schema, so the description does not need to repeat them. The only minor omission is not mentioning error behavior for an invalid category_id, which is acceptable for a safe operation.

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 schema already describes response_format and include_children, and the description adds meaning to the undocumented category_id by framing it as an OLX category lookup and pointing to olx_list_categories as the source of ids. It also explains why the returned parameter codes and value keys matter, connecting the output back to ad posting. With two of three parameters already documented in the schema, the description's added contribution is moderate but useful.

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 'Get an OLX category' and enumerates the exact payload: name, path, is_addable/leaf, max photos, validity days, subcategories, and advert parameter definitions including codes, types, required flags, units, and allowed values. This resource-level specificity clearly separates it from olx_list_categories, which returns category ids, and from olx_suggest_category.

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 says to use the returned parameter codes and value keys when posting an advert, giving the agent a concrete downstream use case. It also directs the agent to olx_list_categories for finding category ids, establishing the proper lookup sequence. It does not spell out when to prefer olx_suggest_category or olx_list_categories, so the guidance is clear but not exhaustive.

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, fully covering the safety profile. The description adds what data is returned (totals, daily history, paid promotions) but does not disclose additional behavioral traits such as rate limits, auth requirements, or response structure. This is acceptable given the annotations, but no extra behavioral caveats are provided.

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 two sentences long, front-loads the most important information (what the tool returns), and ends with a clear usage statement. Every word earns its place with no redundancy or 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 tool with two fully documented parameters, strong annotations, and no output schema, the description covers all essential aspects: it names the specific data returned, the daily history, paid promotions, and the intended use case. The schema handles parameter details, so nothing critical 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 both advert_id and response_format are already documented with formats, defaults, and sources. The description does not add parameter-specific meaning beyond what the schema provides, matching 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 clearly states a specific verb and resource: 'Get one of the account's adverts with totals ... and the DAILY statistics history ... plus paid promotions history.' It also mentions concrete data types (views, phone views, saves, messages), distinguishing it from sibling tools like olx_list_my_adverts and olx_compare_my_advert.

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 provides clear context: 'Use to see how an advert's traffic changes over time.' It does not explicitly state when not to use it or mention alternative tools, but the intended usage is unambiguous and helpful for an agent.

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 establish read-only, idempotent, non-destructive behavior, lowering the burden on the description. The description adds value by scoping to the logged-in account and detailing the returned categories (counters by status, saved ads/search, wallet balance). It does not cover auth-failure behavior or rate limits, but those are not required given 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 front-loaded with the core action and resource, and its first sentence carries a dense but useful list of returned data. The second sentence earns its place by routing to a sibling. It is slightly list-heavy, but there is no waste 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 enumerating the profile sections an agent can expect. It also provides the key cross-tool routing for advert stats. It stops short of explaining session failures or exact response shape, but the 'logged-in' qualifier and sibling set make the remaining gaps minor.

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%: the only parameter, response_format, has an enum, default, and explanatory description in the schema. The tool description contributes no additional parameter-level meaning, 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?

Description states a precise action ('Get') on a specific resource ('logged-in OLX account profile') and enumerates the major data groups returned. It explicitly distinguishes itself from olx_list_my_adverts by directing advert-level views/phone stats to that sibling, so an agent can discriminate without opening other 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?

The tool's context is clear: it is for account/profile-level data rather than per-advert statistics. The final sentence explicitly names the alternative tool and the exact condition ('advert list with views/phone stats') that should route to olx_list_my_adverts, leaving 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 operation as read-only, open-world, and idempotent. The description adds useful behavior: it works on public details and include_phones mirrors the OLX 'Show phone' button, which is the main non-obvious action. The seller-statistics side effect appears in the schema, so it is not lost.

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 purposeful sentences with no filler: the first covers the operation and returned data, the second covers the optional phone flag, and the third states the use case. Everything earns its place and the most important information is front-loaded.

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?

Without an output schema, the description still enumerates the major fields an agent can expect and mentions the markdown/json response switch. It does not detail error cases or auth, but 'public details' and the strong safety annotations make this sufficient for a read-only lookup tool.

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 description supplies important semantics the schema lacks for offer_id: it is a numeric id coming from search results. It also reinforces include_phones's behavior, while response_format is already fully explained by its enum-specific schema descriptions.

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 concrete operation—get full public details of an OLX listing by numeric id—and enumerates the returned content: description, parameters, price, seller, location, promotion flags, dates, and contacts. This clearly distinguishes it from narrower siblings like search, seller profile, or phone-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?

It gives clear context: the id comes from search results and the tool is useful for studying how a competitor writes and positions a listing. It does not explicitly name alternatives or say when not to use it, but the intended scenario is evident.

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 and destructiveHint annotations, the description adds valuable behavioral details: exact return fields, hidden-phone behavior (phones [] and phone_available=false), the fact that each reveal counts in seller statistics, and the OLX 429 daily limit. This is an excellent disclosure of side effects and constraints.

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 compact, front-loaded with the core behavior, and every sentence earns its place. It packs return fields, edge cases, authentication needs, and rate-limit guidance without unnecessary 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 lacking an output schema, the description covers the return shape, hidden-phone case, auth requirements, rate limits, and where to get inputs. This is complete enough for an agent to invoke the tool correctly and interpret 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?

The schema already documents both parameters with 100% coverage, so the baseline is 3. The description adds useful meaning by telling the agent where offer_ids come from and reinforcing the practical limits, which goes beyond pure schema documentation.

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 ('Reveal') and resource ('contact phone numbers of one or more OLX listings') and clearly differentiates the tool from siblings by explaining it provides phone data from the 'show phone' button and listing text. This is precise and distinguishes it from likely-confused tools like olx_get_offer or olx_get_seller.

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 clear usage context: no login is needed, offer IDs come from olx_search_offers / olx_get_seller, and users should request only what they need due to the daily limit. It does not explicitly contrast with alternative tools, so it falls just short of full alternative-based 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?

Annotations already declare readOnly, idempotent, openWorld, and non-destructive behavior. The description adds useful context by specifying what data is analyzed and returned, such as business flag, registration date, response time, promoted share, and latest listings. No contradiction with annotations exists; the only minor gap is lack of detail on edge cases like invalid seller_id.

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, front-loaded sentence: it starts with the primary action and input, then compresses the output contract into a parenthetical list. Every phrase adds information; there is no filler, repetition of the title, or redundant detail.

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 analysis tool with three parameters and no output schema, the description is complete enough to invoke correctly. It identifies the required input, its source, the analysis scope, and the main output components. Missing details like pagination or error behavior are not necessary given the annotations and simple schema.

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 67%, leaving seller_id undocumented. The description compensates by explicitly defining seller_id as a user id from search results. It also ties listings_sample to 'a sample of their latest listings', while response_format is already self-documented in the schema. This adds meaning beyond the raw JSON 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 uses a specific verb and resource: 'Analyze any OLX seller by user id'. It enumerates the exact outputs—public profile fields, active listings, categories, price levels, promoted share, and a sample of latest listings—making the tool's purpose unmistakable. The word 'any' also distinguishes it from olx_get_my_profile, which targets the caller's own profile.

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 clear usage context: the seller_id comes from search results and the tool works for any OLX seller, implying competitor analysis. However, it does not explicitly name alternatives or state when not to use it, such as 'for your own profile use olx_get_my_profile', so it stops short of full exclusion 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?

Annotations already declare readOnly, idempotent, and non-destructive, and the description adds relevant behavior: no auth required, argument-dependent outputs, and search full paths. This is useful additional context 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?

Three short, front-loaded sentences with no filler: the primary purpose, each argument mode, and the relationship to other tools. Every sentence earns its place.

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 browse/search tool with two optional parameters and no output schema, the description supplies the necessary invocation patterns and downstream id usage. It does not detail the exact response shape, but the no-output-schema case is simple enough that this is a minor gap, not a blocker.

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 baseline is 3, but the description enriches the parameters by explaining parent_id enumerates subcategories and search matches by Russian/Uzbek names and returns full paths. This meaningfully goes beyond the raw schema definitions.

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/resource pair: 'Browse or search the OLX category tree' and immediately distinguishes modes (no args, parent_id, search), so an agent knows exactly what it does. It also names the downstream consumer, olx_get_category and market tools, which helps separate it from the sibling 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 clear selection context: use without args for top-level categories, parent_id for subcategories, and search by name. It does not explicitly discuss when to avoid this tool versus olx_suggest_category, but the invocation guidance is concrete enough for correct use.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavior: returned fields, sorting newest first, stats structure, pagination behavior, and markdown-specific totals/conversion. This goes beyond the annotation baseline.

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 well organized with a lead sentence, an Args block, and a Returns block. Every sentence adds useful information, and the most important scoping ('logged-in account's adverts') is front-loaded.

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 five optional parameters and no output schema, the description is complete: it documents all parameters, lists per-advert return fields, explains the stats object, states ordering, and describes output format differences. An agent has enough information 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 only 40%, so the description carries the burden, and it succeeds. It explains the meaning of all five parameters: status values and default, query filtering by title, limit/offset pagination, and response_format choices. This is meaningful guidance beyond the raw 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 uses a specific verb ('List') with a clear resource ('the logged-in account's adverts') and a differentiating scope ('by status with performance stats'). It clearly distinguishes itself from sibling tools like olx_get_my_advert, which retrieves a single advert.

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 conveys a clear use case: listing the current account's adverts with status and performance stats. However, it does not explicitly state when to prefer this over alternatives such as olx_get_my_advert for a single advert, or mention any prerequisites like having an active session.

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 say readOnlyHint=false (mutation), idempotentHint=true, and destructiveHint=false. The description adds valuable behavior beyond that: it opens a visible window on the user's machine, waits until login is detected, saves session cookies locally, and does not type credentials. This covers the important non-obvious behavior (interactive user involvement, no automation of credentials, cookie persistence). It could have mentioned that it blocks until timeout or returns a session-status result, but the main behavioral risks (no credential entry, cookie saving) are clearly disclosed.

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 sentences, all load-bearing: what the tool does, key constraint (never types credentials/waits and saves cookies), and when to call it plus user instructions. No filler, and the critical caveat ('never types credentials') is front-loaded in the first sentence.

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 login tool with 1 optional param and no output schema, this is complete. It covers the purpose, the interaction model, the trigger condition, the timeout parameter, the side effect (saving cookies), and the user-facing message. An agent can invoke this correctly and knows what to tell the user. 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?

With 1 parameter and schema description coverage at 100%, the baseline is 3. The description adds meaning though: it explains wait_minutes corresponds to 'waits until login is detected (up to wait_minutes)', which ties the parameter to the login-wait behavior. It doesn't describe what happens when the timeout is reached (e.g., error vs. return), but for a single optional parameter with reasonable schema docs, this is more than minimum.

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 ('open a visible Chrome window... to log into their OLX account') and clearly differentiates it from siblings: it's the only tool that performs interactive login, while siblings like olx_session_status and olx_get_my_profile require an existing session. Even without knowing the sibling definitions, an agent can tell this is the login/session-restoration 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?

Explicitly says when to call it: 'Call this when any account tool returns a session error.' It also says what the tool does NOT do ('never types credentials') and what the user must do, plus it gives a concrete first step ('Tell the user a Chrome window has opened'). This is strong usage 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?

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior; the description adds genuinely useful operational context: no auth needed, live public data, pagination via has_more/next_offset, and a maximum offset bound. It does not mention error behavior or rate limits, but it goes beyond what 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 front-loaded with purpose and usage, followed by a compact args list and return summary. The length is justified by the tool's 13 parameters and no output schema, though the Args enumeration slightly duplicates schema content.

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 detailing return fields, pagination fields, and the maximum accessible offset. It also routes users to the correct sibling for aggregated statistics. Minor gaps like error conditions and rate limits prevent a perfect score.

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 high (85%), so the schema already documents most parameters. The description lists the arguments and adds small clarifications like UZS currency and accepted enum values, but largely repeats what the schema provides rather than adding new semantic depth.

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: 'Search live OLX listings' with filters and sorting. It clearly differentiates itself from siblings by noting it works on public site data without auth and by pointing to olx_analyze_market for aggregate stats instead.

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 states when to use the tool: looking at competitor listings, checking current prices, or browsing a category/region. It also names the alternative for aggregated stats ('For aggregated stats use olx_analyze_market instead of paging manually'), giving the agent a clear decision rule.

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, so safety traits are covered. The description adds value by disclosing the specific state it inspects (saved/valid session, account identity, SMS verification) and the rationale tied to posting adverts. There is 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?

Two sentences, no filler. The core checking behavior is front-loaded, and the parenthetical about OLX's phone requirement adds essential context without bloating the description.

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 zero-parameter status-checking tool, the description is nearly complete: it states what is checked, why it matters, and which sibling domain does not need it. It does not describe the exact response shape, but with no output schema and openWorldHint=true, the missing return details are a minor gap rather than a blocker.

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 input schema is empty with zero parameters, so schema coverage is trivially 100%. With no parameters to document, the baseline of 4 applies, and the description does not need to add parameter-specific semantics.

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 ('Check') with a clear resource ('OLX account session') and lists the exact facts returned: session saved/valid, account identity, and SMS-verification status. This is distinct from sibling tools like olx_login or olx_get_my_profile, so an agent can identify it without opening 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?

The description provides clear context for when this tool matters: OLX requires a verified phone before posting adverts, so checking session and phone-verification status is a prerequisite step. It also gives a when-not signal by noting that competitor/market tools do not need a session, though it does not explicitly name alternative tools or spell out a full decision rule.

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, openWorldHint, idempotentHint, and non-destructive behavior. The description adds valuable beyond-annotation context: authentication requirement ('Needs a logged-in session') and the exact return shape ('category ids with full path'). 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?

Four short sentences, each earning its place: what it does, the posting-form behavior it reproduces, the auth prerequisite, what it returns, and the natural next call. Front-loaded with the core action and no 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 one-parameter tool with no output schema, the description is fully sufficient: it states input semantics, auth requirement, return values, and the recommended follow-up call. An agent has everything needed to invoke it correctly and understand 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 description coverage is 100% and the single parameter 'title' is already documented with an example. The description reinforces that it is an 'advert title' but does not add significant new meaning beyond the schema. This matches the baseline for high schema coverage.

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: 'Suggest OLX categories for an advert title' with a precise reference to the olx.uz posting form suggestion behavior. This clearly distinguishes it from sibling tools like olx_list_categories and olx_get_category, especially by pointing the agent to olx_get_category for the next step.

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 clear usage context: needs a logged-in sessionchers, and directs the agent to follow up with olx_get_category(id) to see required parameters. It does not explicitly enumerate when-not-to-use alternatives, but the context is clear enough for an agent to select this tool over list/get category tools.

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