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

With no annotations provided, the description carries the burden of behavioral disclosure. It signals a read-only public fetch by describing the returned fields, but it does not mention error behavior, invalid tokens, missing posts, or rate/access limitations. This is minimally adequate but not comprehensive.

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 one well-structured sentence that front-loads the purpose and then efficiently lists the concrete data fields returned. Every clause adds useful information and there is 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 single-parameter tool with no output schema, the description thoroughly covers what will be returned, including dates, location, attributes, and category info. It even connects the district id to a sibling tool for follow-up search. It could still mention invalid-token behavior, but nothing essential to invoking 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?

There is only one parameter and the schema already fully documents it as 'Post token (gaxi5lYL) or any divar.ir post URL.' The description adds no additional parameter-level semantics, so the baseline of 3 applies.

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

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

The description clearly identifies a specific action (retrieve full public detail) on a specific resource (one divar.ir post) and enumerates what is included. This distinguishes it from sibling tools like divar_search or divar_similar_posts, which handle lists or related posts.

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 phrase 'for one post' implies it should be used when a specific post token or URL is available, and the mention that district id is usable as a divar_search filter hints at downstream use. However, it does not explicitly say when to use this tool versus alternatives or 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.

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

No annotations are provided, so the description carries the full behavioral burden. It discloses useful traits such as Persian/English text matching and that results include breadcrumb parents, but it does not explain behavior when the optional query is omitted or describe the return format.

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 compact, front-loaded sentences with no filler. It states the purpose first and then the practical follow-up usage, making every sentence valuable.

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 low-complexity tool with one optional parameter and no output schema, the description covers purpose, supported languages, returned parent breadcrumbs, and downstream usage. The only notable gap is not addressing behavior when 'query' is omitted.

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 'query' with 100% coverage, so the baseline is 3. The description adds useful context about matching Persian or English text and the intended slug usage, but it does not need to provide much more for a single simple 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 states the verb and resource: 'Look up divar.ir category slugs by Persian or English text.' It also clarifies the output includes breadcrumb parents and explicitly connects the result to downstream tools like divar_search/divar_price_analysis, distinguishing this lookup from search/post tools.

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

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

The description gives explicit usage context: 'Use the slug in divar_search/divar_price_analysis.' This tells an agent when this tool is relevant, though it does not explicitly mention alternatives or 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.

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

No annotations are provided, so the description carries the burden of behavioral disclosure. It states the tool can either look up a specific city or list all cities, which is useful. However, it doesn't disclose details like whether the query is case-sensitive, whether it returns partial matches, what the output format looks like, or whether it makes a network request. For a simple lookup tool, this is adequate but not rich.

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 sentence that is concise and front-loaded. It states the primary action ('look up divar.ir city ids'), the input ('by Persian name'), and the alternative behavior ('or list them all') without any wasted words. Every part 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 lookup tool with one optional parameter and no output schema, the description is nearly complete. It tells the agent what the tool does and how to use it. The only missing context is the exact output format (e.g., a list of {id, name} pairs), but since there is no output schema, a brief note on the return shape would have been helpful. Still, the tool is simple enough that an agent can likely infer the output.

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 'query' is described as a Persian city name with an example. The description adds the behavior that omitting the query lists all cities, which is valuable and not in the schema. However, it doesn't add more detail about the parameter's format (e.g., normalization, exact match vs. fuzzy). Baseline 3 is appropriate since the schema already covers the parameter 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 clearly states the tool's function: looking up divar.ir city IDs by Persian name, with the option to list all cities. It uses a specific verb ('look up') and resource ('divar.ir city ids'), and the optional listing behavior is explicitly mentioned. This distinguishes it from sibling tools like divar_search or divar_list_categories, which focus on other aspects of the Divar API.

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 implies when to use this tool: when you need to map a Persian city name to its ID, or when you need the full list of city IDs. It doesn't explicitly state when not to use it or name alternatives, but the context is clear enough for an agent to select it over siblings like divar_search or divar_list_categories. A small gap is the lack of explicit exclusion, but the purpose is so specific that it's nearly self-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?

No annotations are provided, so the description carries the behavioral burden. 'Show' reasonably implies a read-only operation, and the filter examples give some sense of the output, but the description does not disclose response format, optional-parameter behavior, or any limitations. It is adequate but not rich.

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 with no filler. Every element—the action, resource, and representative filter examples—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 introspection tool with two optional, well-described parameters and no output schema, the description adequately conveys what the tool returns at a conceptual level. It could specify behavior when no city/category is provided, but this is a minor gap.

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 schema already explains 'city' and 'category' clearly with examples. The description mentions 'city/category' in passing but adds no new semantic detail, so the baseline of 3 applies.

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

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

The description uses a specific verb ('show') and resource ('which filters divar.ir exposes'), with concrete examples (price range, districts, photo-only). It clearly identifies a filtering/introspection purpose, though it does not explicitly contrast with sibling tools like divar_search or divar_search_url.

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?

No guidance is given about when to use this tool versus alternatives, nor are there exclusions or prerequisites. The description states the parameters (city/category) but does not say what happens when they are omitted or how this tool relates to the 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It does reveal that the tool analyzes 'live listings' and 'comparable' items, and it notes the currency unit (Toman). However, it does not explain how pagination/sampling works, whether a city or query is required for meaningful results, or any limits or error conditions. This is partial but not complete transparency.

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 with no filler, front-loading the core purpose before listing the output components. The parenthetical enumeration is information-dense but slightly unwieldy. It earns a 4 for efficiency and clarity, not a 5 because the formatting could be more structured.

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 that there is no output schema and no annotations, the description covers the key contract: what kind of analysis is performed, what metrics are returned, and the unit of measure. It lacks exact return format details and behavior when optional parameters are omitted, but it provides enough for an agent to decide when and how to invoke it. This is strong but not fully complete.

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 already covers all six parameters with 100% description coverage, so the baseline is 3. The tool description adds strategic context ('comparable live listings' and decision purpose) but does not introduce new parameter-level semantics beyond what the schema already states, and it repeats the Toman unit already present in price parameter 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 function: computing the price distribution of comparable live listings for a specific decision (what to ask before posting an ad). It lists concrete output components such as median, p25/p75, suggested ask range, price bands, and samples, which makes the purpose specific. However, it does not explicitly name or contrast sibling tools like divar_search or divar_similar_posts, so it doesn't fully achieve sibling differentiation.

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 a clear when-to-use context: 'to decide what to ask before posting an ad'. This tells an agent the intended scenario and implicitly distinguishes it from listing/search tools. It does not provide explicit exclusions or direct comparisons to alternative tools, which would warrant 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the operation is read-only and requires no account, and it reveals cursor pagination and the exact normalized return fields, all beyond what the schema alone provides.

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 roughly 80 words, front-loaded with the main purpose and followed by compact feature and return-value statements. Every sentence carries useful information, though the enumeration of parameters partially 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?

Given 13 parameters and no output schema, this description covers key contextual aspects: read-only access, no account requirement, live listings, cursor pagination, and exact normalized row fields. It does not describe error behavior or page/limit interaction, but these are minor given the thorough 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 description coverage is 100%, so the baseline is 3. The description restates the parameter categories (query, city, category, Toman price range, photo-only, district ids, brand/model) but adds no new semantic meaning beyond the schema's own parameter 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 opens with a specific action, 'Search live divar.ir listings', naming the resource and context. It clearly states what the tool does, though it does not explicitly differentiate it from sibling tools like divar_get_post or divar_price_analysis.

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 no explicit guidance on when to use this tool versus alternatives such as divar_get_post or divar_similar_posts. It mentions read-only/no account, which implies safe general searching, but it does not tell the agent when to prefer this over 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?

There are no annotations, so the description carries the full burden of behavioral disclosure. It states the tool builds a URL, which implies a pure construction task, but it does not explicitly confirm there are no network side effects, what the return value looks like, or how invalid parameters are handled. This leaves the agent with uncertainty about the tool's actual behavior.

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 sentence with no filler, front-loading the action ('Build a divar.ir web URL') and then stating the human-use purpose. Every word earns its place; it is as concise as possible.

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 low complexity (a URL constructor with 5 optional parameters) and no annotations or output schema, the description covers the core purpose. It does not detail return format or error behavior, but for this simple utility the description is sufficient for an agent to correctly understand the tool's role. The missing annotation coverage keeps it from a 5.

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 80%, so the input schema already documents most parameters (city, category, price units). The description itself adds no parameter-level meaning, but per the rubric the baseline is 3 when coverage is high. The description does not compensate for the one undocumented parameter ('query').

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 ('Build') and resource ('divar.ir web URL for a search'), and adds the purpose 'so a human can open it in a browser.' This clearly distinguishes it from sibling divar_search, which presumably returns programmatic results. The action and scope are immediately understandable.

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 phrase 'so a human can open it in a browser' implies the intended use case, but the description gives no explicit when-not-to-use guidance or mention of alternative tools like divar_search. An agent must infer when this URL-builder should be chosen over the programmatic search tool.

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

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

No annotations are provided, so the description carries the full burden. It discloses key behaviors: filtering by category/brand/model/city and excluding the input post. However, it does not mention potential errors, authentication requirements, rate limits, or output format. The added context is useful but not comprehensive for a tool with zero 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 two sentences with no extraneous words. The function and criteria are front-loaded, followed by concise use cases. Every sentence earns its place, making it highly effective and easy to parse.

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

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

With no output schema and no annotations, the description should explain what the response contains. It states 'comparable listings' but does not specify the format (e.g., list of post tokens, full post objects, or metadata). It also omits error handling or edge cases. Given the tool's simplicity and the availability of divar_get_post for details, it is partially complete but lacks important contextual depth.

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 all three parameters, so the baseline is 3. The description adds context that the token determines category/brand/model and city is a filter, but does not provide extra parameter-level details beyond the schema's own descriptions. It reinforces meaning rather than adding new information.

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 function: returns comparable listings for an existing post, with specific criteria (same category, brand/model, city) and exclusion of the post itself. It distinguishes itself from siblings like divar_search (general search) and divar_get_post (single post retrieval) by focusing on similarity based on an existing token.

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

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

The description gives explicit usage context: 'useful for a seller checking competition or a buyer checking the price'. It clearly implies when to use the tool (when you have an existing post and want comparables) but does not explicitly mention alternatives or when not to use it, such as when a general search is more appropriate.

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