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

With no annotations, the description carries the behavioral transparency burden. It clearly states the core behavior: returns the full tree by default, and a subtree when parentId is provided. It does not cover edge cases or response format, but for a read-only retrieval operation this is reasonably transparent.

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 front-loaded with the main purpose and uses no unnecessary words. Every word contributes to understanding the tool's behavior.

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 there is no output schema and no annotations, the description is a bit sparse. It clearly explains the main invocation behavior, but does not describe the shape of the returned tree, empty/error behavior, or how this tool compares with sibling category tools. More detail would make it fully self-sufficient.

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 only describes parentId as an 'Optional parent category ID'. The description adds meaningful semantics by explaining that supplying parentId changes the result from the full tree to a subtree. This goes beyond the schema's minimal description and helps the agent understand the parameter's effect.

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 ('Return') and resource ('category tree'), and clearly distinguishes this from flat-list category tools by mentioning the hierarchical 'full tree' and conditional 'subtree'. An agent can immediately understand what the tool does and how it differs from similar tools.

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

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

The description implies usage for retrieving category hierarchy, and the parentId parameter implies subtree queries, but it does not explicitly mention when to use this versus sibling tools like list_categories or search_categories. No alternatives or exclusions are given, so the guidance is only implicit.

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 indicate a read-only action ('List') and the auth scope ('authenticated user's'), but it does not mention pagination, the response shape, ordering, or any other behavioral details. The page parameter suggests pagination, yet the description omits it.

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 concise sentence that front-loads the action and resource. It contains no filler, repetition, or unnecessary detail, making it easy to parse and act on.

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?

The tool is relatively simple with one optional parameter and no output schema, so the description's core task is to identify what is returned and any relevant behavior. It says what is listed, but it omits pagination behavior and any mention of the return format. Given the lack of an output schema, a bit more contextual detail would make it 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?

Schema description coverage is 0% for the only parameter, page, and the description does not mention pagination or explain the page parameter's meaning. The schema's type, default, and minimum offer some intrinsic hints, but the description itself adds no parameter-level context. This is a clear gap given the low 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?

The description uses a specific verb ('List'), a clear resource ('chat rooms'), and a scope qualifier ('authenticated user's'), with a parenthetical disambiguation ('in-app messaging'). This distinguishes it from siblings like get_chat_unread, so an agent can infer the correct tool without ambiguity.

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 the tool—when the authenticated user's chat rooms are needed—but provides no explicit guidance about when not to use it or how it compares to alternatives. The presence of get_chat_unread as a sibling suggests some potential for confusion, but the description's clarity mitigates this. Usage is implied rather than stated.

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, the description carries the full burden of behavioral disclosure, but it only states the return value. It does not explicitly confirm that the operation is read-only, require authentication, or clarify how the count is scoped (e.g., current user's total across all chat rooms).

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 verb and delivering the core meaning immediately. It is appropriately sized for a parameterless tool.

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?

The description covers the return value, which is the most important information for an agent. However, with no annotations and no output schema, it omits prerequisites such as authentication and exact scope, making it adequate 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 tool has zero parameters and schema coverage is 100%, so the description has no parameter details to add. The baseline of 4 applies because no parameters exist.

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 ('Return') and the exact resource ('the number of unread chat messages'), making the tool's purpose immediately clear. The word 'number' differentiates it from sibling get_chat_rooms, which implies returning rooms rather than a count.

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 provided on when to use this tool versus alternatives like get_chat_rooms. The description does not mention authentication prerequisites, whether it returns a global count, or that it should be called after login, leaving the agent to infer context.

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, the description must disclose behavioral traits itself. It clearly states this is a read operation ('Fetch') and enumerates the return payload, but it does not disclose behavior on missing IDs, authentication requirements, or any response shape beyond field names. 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?

One front-loaded sentence with zero filler. It names the operation, the resource, the input mode, and the return fields efficiently.

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 read tool with no output schema, the description is largely complete: it covers the operation, the identifying input, and the return contents. It could add error/not-found behavior or auth requirements, but those are minor gaps at this complexity level.

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 schema already defines id as 'Listing ID' and accepts string/number. The description only adds the qualifier 'numeric', which is slightly narrower than the schema but not significant. Baseline 3 is appropriate because the schema carries the parameter documentation burden.

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

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

The description opens with a specific verb and object ('Fetch full details of a Sheypoor listing') and scopes it with 'by numeric ID'. The enumerated return fields (title, price, seller, images, etc.) make it distinct from sibling tools like get_listing_images (images only) and get_listing_from_url (URL-based lookup).

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 'by numeric ID' implies the precondition for calling this tool, but the description never states when to prefer get_listing_from_url or get_listing_images, nor when not to use this tool. Usage context is implied rather than explicit.

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 does not disclose what 'full details' includes, whether it triggers network requests, rate limits, or auth requirements. Since it's a read operation, but no safety implications are described, this is a gap. The description is very brief, offering minimal behavioral info beyond the action.

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?

One sentence, no filler. It front-loads the verb and resource. It's appropriately concise, though it could be more informative without losing structure.

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 single-parameter tool with a clear output concept, the description is adequate but not complete. It doesn't specify what 'full details' includes, whether errors are returned for invalid URLs, or if there are rate limits. Given no output schema, a bit more detail on return value would help.

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

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

Schema coverage is 100%, so the schema already documents the url parameter with format and pattern requirements. The description adds a tiny bit of context by saying 'canonical URL' and the expected format, which matches the schema. Baseline 3 is appropriate as the schema does the heavy lifting but the description reinforces the constraints.

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 'Fetch' and the resource 'full details of a Sheypoor listing', distinguishing it from sibling tools like get_listing. It mentions the input is a canonical URL, which is specific. However, it doesn't name the sibling get_listing to explicitly differentiate, even though the distinction is implied.

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 usage when you have a canonical URL and need full listing details, but it doesn't explicitly state when to prefer this over get_listing (which likely takes an ID) or other search tools. No exclusions or alternatives are named, leaving some inference.

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

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

No annotations are present, so the description carries the full burden of behavioral disclosure. It signals a read operation and narrowing to full-size URLs only, but it does not mention response format, empty-result behavior, authentication needs, or error cases. This is minimal disclosure for a tool with no annotation support.

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. The core behavior is front-loaded, and the qualifier 'only full-size' adds precision without unnecessary length.

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 one-parameter read tool, the scope is reasonably clear, and the agent can infer it needs a listing id. However, the absence of an output schema and any mention of the response envelope (e.g., whether an array of URLs is returned or what happens when a listing has no images) leaves a meaningful gap in expectations.

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 provides only a required 'id' property with no description, giving 0% schema description coverage. The description adds some meaning by saying 'for a listing', implying that id is the listing identifier, but it does not explicitly confirm the id's role or accepted formats beyond what the schema already states.

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 'Return' and resource 'full-size image URLs for a listing', clearly stating what the tool does. The word 'only' implicitly differentiates it from the sibling get_listing tool, though no sibling is explicitly named.

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 intended use—retrieving image URLs for a listing—is implied by the description, but there is no explicit guidance on when to choose this over get_listing or get_listing_from_url. It provides clear context but relies on inference rather than stating usage boundaries or exclusions.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It correctly indicates a list operation, but does not mention authentication prerequisites, error behavior, pagination semantics, or whether any side effects occur. Given the complete lack of annotation support, this is a notable gap.

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 clear sentence with no filler words. It front-loads the verb and resource immediately, and every word contributes meaning. No unnecessary details or repetition.

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

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

For a simple list operation with two optional pagination parameters and no output schema, the description is adequate but sparse. It does not mention authentication requirements, return value shape, or pagination behavior. Since there is no output schema and no annotations, these omissions leave an agent partly guessing about how to invoke and interpret the 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?

Schema description coverage is 0%, and the description does not mention page or size at all. While the schema provides type, default, and bounds, the tool description adds no semantic meaning about how pagination works or how these parameters affect results. The description fails to compensate for the lack of schema-level 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 uses a specific verb ('List') and a clear resource ('the authenticated user's saved/bookmarked listings'). It unambiguously identifies this as a read operation for bookmarks, distinguishing it from the sibling tool get_my_listings, which would return the user's own listings rather than saved ones.

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 on when to use this tool versus alternatives like get_my_listings or search_listings. It implies the user must be authenticated, but does not state that login is required or refer to any sibling tool or differentiator. The agent receives no contextual direction for choosing this tool.

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

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

With no annotations, the description carries the burden and does add useful context: it requires login and is a read-oriented list operation. However, it doesn't disclose pagination behavior, status filtering, or what fields are returned.

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 short sentences with no fluff. The main purpose is front-loaded, and the login requirement is a necessary, concise addition.

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?

Adequate for a simple list operation with optional, well-specified parameters. The auth requirement is present, but without annotations or an output schema, it omits safety/reversibility context and return-shape details.

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 contains no parameter information and schema coverage is 0%, so it fails to compensate for the missing documentation. The schema itself is self-explanatory for page, size, and status, but the description adds no additional meaning.

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 ('List') and resource ('the authenticated user's listings'), which clearly distinguishes it from general search tools like search_listings or search_listings_all. It doesn't name sibling tools explicitly, but the scope is unambiguous.

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 a clear context: this tool is for the authenticated user's own listings, and the login requirement is stated. It doesn't mention alternatives or exclusions, but the intended use is evident 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?

With no annotations, the description carries the disclosure burden. It signals a read-only operation via 'List' and an authentication requirement via 'authenticated user's,' which is the key behavioral context. It does not discuss error cases or pagination, but for a simple wallet-list endpoint this is adequate.

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 wasted words, and the core action 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?

The tool is a simple, parameterless read operation and the description captures its output scope completely. It does not describe the wallet object shape, but with no output schema and no invocation-time dependency, this is a minor omission.

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 are no parameters and schema description coverage is 100%, so the baseline is 4. The description needs to add no parameter 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 ('List') and resource ('payment wallets') and scopes it to the authenticated user. This clearly separates it from siblings like get_my_listings and get_my_bookmarks.

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 makes the use case obvious: retrieve the current user's payment wallets. It names no alternatives or exclusions, but the resource is distinct enough that no close sibling requires disambiguation.

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 full responsibility for disclosing behavior. It only states the resource and platform, with no mention of authentication requirements, pagination, result format, or side effects. The verb 'get' implies read-only, but no deeper behavioral context exists.

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, efficiently worded sentence that front-loads the action and resource without unnecessary detail. Every word adds value.

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?

While the tool is simple with no parameters or output schema, the description lacks information about authentication or result structure. It gives enough to know what the tool does, but not enough to fully anticipate the response or preconditions, so moderate completeness.

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 has zero properties, so there are no parameter semantics to clarify. The description correctly identifies the resource being requested, satisfying the baseline for a parameterless tool.

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 retrieves trending search terms on Sheypoor, using a specific verb and resource. However, it does not explicitly differentiate from the sibling get_search_suggestions, so the agent must infer the distinction.

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 provided about when to use this tool versus alternatives. The description is purely definitional and does not mention any exclusions or alternative 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only says 'Get', which implies a read-only operation, but it doesn't explicitly state that no data is modified, any authentication requirements, or rate limits. It also implies 'given city' while city is optional with a default, which could mislead an agent into thinking city is mandatory. The description fails to disclose any operational nuances beyond the basic action.

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, concise sentence that front-loads the action and resource. There is no wasted text; every word contributes to understanding the tool's purpose. It is efficiently structured 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?

For a simple tool with two parameters (one required) and no output schema, the description is adequate but not fully complete. It clarifies the input parameters but does not describe the return format (e.g., a list of suggestion strings) or any limitations such as supported cities or error conditions. An agent may be left guessing about the response structure, especially since no output schema is available.

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 schema description coverage at 0%, the description must compensate. It mentions both parameters: 'prefix' and 'city', clarifying that prefix is a search prefix and city is the location. This adds meaning beyond the schema's bare type/default. However, it doesn't address the default value of 'iran' for city or any formatting constraints beyond schema minLength, but the core semantics are clear.

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 action (Get), the resource (autocomplete suggestions), and the context (for a search prefix in a given city). This distinguishes it from siblings like get_popular_searches and search_listings, which serve different purposes. The verb and noun are specific enough that an agent knows exactly what this tool does.

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 when autocomplete suggestions for a search prefix are needed within a city. No explicit exclusions or alternatives are mentioned, but the purpose is self-evident and distinguishes it from related tools. The context is clear enough for correct selection without additional 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?

No annotations are provided, so the description carries the burden of disclosing behavior. It transparently states that this is a list operation and mentions the returned fields (IDs and slugs), but does not address auth requirements, rate limits, or whether the list is paginated. For a simple list call this is acceptable 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?

A single, front-loaded sentence that contains only essential information. Every word adds value, and there is no unnecessary detail or repetition.

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

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

For a zero-parameter tool with no output schema, the description provides enough for an agent to call it correctly: the purpose and the return fields. It lacks explicit mention of authentication or response shape, but given the simplicity of the endpoint, these are minor gaps.

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 tool has zero parameters, so the schema is trivially complete and no parameter documentation is needed. The baseline score of 4 is appropriate since the description cannot add meaning beyond an empty schema and correctly does not attempt to.

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 action ('List'), a specific resource ('top-level Sheypoor categories'), and what is returned (IDs and slugs). This distinguishes it from sibling tools like get_category_tree or search_categories, whose names suggest different resources or actions.

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 'top-level' implies that this tool is for root categories only, offering some usage context. However, it does not explicitly mention when to use an alternative (e.g., get_category_tree for full hierarchy or search_categories for keyword search), so the guidance is implied rather than explicit.

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 only states the purpose and does not disclose any behavioral traits such as pagination, ordering, authentication requirements, or error behavior. This is a significant gap for a tool that might return many cities.

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, well-structured sentence with no redundancy. It front-loads the core action and scope.

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 list tool with one parameter and no output schema, the description provides the essential information to call it. It could mention response format or limitations, but it's acceptable for the complexity.

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 description for the province parameter already explains it is a slug or name fragment. The tool description repeats this and adds the context that it filters cities within that province, which is a small addition. Given 100% schema coverage, this is adequate but not exceptional.

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 action (List), the resource (cities), and the scope (within a province), and specifies the input format (slug or name fragment). This distinguishes it from list_provinces, which lists provinces, and makes the tool's purpose unambiguous.

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 usage when you need cities for a given province, and the sibling list_provinces suggests the alternative for listing provinces. However, it doesn't explicitly state when not to use it or mention alternatives, so it's not fully explicit.

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. Saying 'List all Iranian provinces with their IDs and slugs' clearly indicates a read-only fetch and discloses the output scope. It does not mention auth, ordering, or pagination, but for a zero-parameter list of provinces such details are low-risk and unlikely to be needed.

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 wasted words. The action, scope, and result fields are all front-loaded and immediately usable.

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, parameterless list tool, this description is complete. It conveys what will be returned, and no output schema or additional context is necessary for an agent to invoke the tool correctly.

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

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

The tool has zero parameters, and the schema coverage is 100%. With no parameters to document, the description needs to add no parameter-level meaning, so the baseline of 4 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 ('List'), a precise resource ('all Iranian provinces'), and names the returned fields ('IDs and slugs'). This clearly differentiates it from siblings like list_cities 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.

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

The description implies its usage context: use it when needing the full set of Iranian provinces. However, there is no explicit guidance about when to choose this over alternatives or any exclusions, leaving some inference to the 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?

No annotations are present, so the description carries the behavioral burden. It explicitly discloses a lasting side effect: 'Persists cookies for future sessions.' This signals that the tool is state-changing, though it does not cover failure cases or invalid-code 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?

Two short sentences with no filler. The core action is front-loaded, and the important side effect follows immediately.

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?

The description is mostly adequate for a simple two-parameter tool, but it does not explain where sessionId comes from or what the tool returns, especially with no output schema present.

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 only 50%, with sessionId left undocumented. The description adds no meaning for sessionId and only repeats the code concept already present in the schema, so the missing parameter semantics are not compensated.

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: 'Complete Sheypoor login with the SMS code.' It is unambiguous and distinct from the sibling login_start, logout, and whoami 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 implies when to use it: after a login flow has been started and the user has received an SMS code. It does not explicitly name login_start as a prerequisite or list exclusions, so it stops 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?

With no annotations, the description carries the behavioral burden, and it does disclose the key side effect: an SMS is sent to the user's phone. It also reveals the stateful handoff via sessionId. It could add error or rate-limit caveats, but the core behavior is transparent.

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 short sentences with no filler. The primary action is front-loaded, and the required follow-up with login_complete is stated in sequence.

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 covers what happens, what is returned, and the next call to make. Nothing needed for correct invocation 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 0%, but the description compensates by identifying the parameter as an Iranian mobile number and indicating it receives the SMS code. Combined with the regex pattern in the schema, the agent has enough semantic meaning to supply the correct value.

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

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

The description names a specific action ('Start Sheypoor login'), the mechanism ('sends an SMS code'), and the return contract ('returns a sessionId'). It clearly distinguishes login_start from the sibling login_complete by defining this as the initiating 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?

The description explicitly instructs that the returned sessionId must be passed to login_complete along with the user's code. This tells the agent when to use this tool and what to do next, effectively differentiating it from the completion step without 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states the side effects ('clear cookies and tokens'), which informs the agent that this is an state-changing operation with local session cleanup. It could have added idempotency or already-logged-out behavior, but the core effect is 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?

The description is a single sentence that front-loads the action ('Log out of Sheypoor') and immediately states the mechanism ('clear cookies and tokens'). Every word earns its place; 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 zero-parameter, no-output-schema tool, the description is fully complete: it identifies the action, the target system, and the concrete side effects. No additional information is needed for an agent to invoke this tool correctly.

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

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

The input schema has zero parameters and the schema description coverage is 100%, so there are no parameters needing explanation. The description adds meaning by clarifying the operation's effect, and the baseline of 4 for no-parameter tools 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 uses a specific verb ('Log out') and a clear resource ('Sheypoor'), and states the concrete effect: 'clear cookies and tokens.' This clearly distinguishes it from the login-related siblings such as login_start and login_complete.

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 intended usage is clear: call this tool when the user wants to end their authenticated session with Sheypoor. It does not explicitly state when not to use it or name alternatives, but given its simplicity and the obvious opposition to the login sibling tools, the context is sufficient.

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, the description carries the full burden. It discloses key behaviors: fuzzy matching, substring matching, and language support (Persian or English). This goes beyond a simple restatement of the tool name, though it does not specify response format or result limits.

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?

A single, front-loaded sentence with no filler. Every word adds value, making it easy for an agent to parse quickly.

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 search tool with no output schema, the description provides enough information to invoke it correctly. It could mention what the response contains, but given the low complexity and clear naming convention, the missing details are not critical.

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 only defines 'query' as a string with minLength 1 and no description. The description adds crucial meaning by explaining that the query is a category name and can be a Persian or English substring, effectively compensating for the 0% 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?

The description clearly states the tool performs a fuzzy search on categories by name, with Persian or English substring matching. This specific verb+resource+scope distinguishes it from sibling tools like list_categories and get_category_tree.

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: use this tool when you need to find categories by a name substring, especially with fuzzy matching. It doesn't explicitly mention alternatives or when not to use it, but the usage context is unambiguous given the sibling list.

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. It discloses the one-page pagination behavior and supported filters, but it does not mention result format, default city behavior, or whether filters are required. This is adequate but leaves gaps.

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, with the core action first, then the key pagination behavior, then the supported features. Every sentence contributes 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 tool with 10 optional parameters and no output schema, the description gives a useful overview but does not explain return shape or how city and cityId relate. It is minimally sufficient for an agent to invoke basic searches, 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?

Schema description coverage is 80%, so baseline is 3. The description repeats the parameter capabilities (query, city, category, region, price range, sorting) without adding meaning beyond the schema; no parameter details are enriched.

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 'Search Sheypoor listings', a specific verb and resource, and immediately adds 'Returns one page of results (default 24)', which distinguishes it from the sibling search_listings_all for paginated/all-results searches.

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

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

It states the tool returns one page, giving clear context that this is for single-page searches, but it does not explicitly name alternatives or say when not to use it. The sibling search_listings_all is implied but not referenced.

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 must carry the full burden of behavioral disclosure. It adds the auto-pagination and merged-list behavior, which is useful. But it does not mention whether the operation is read-only, any rate limits, error handling, or what happens when no results are found. For a search tool, read-only is implied, but not stated. The description adds some behavioral context but not enough 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 zero waste. It front-loads the action and then gives the usage condition. It is appropriately concise and well-structured, making it easy for an agent to parse quickly.

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?

The tool has 8 parameters, no output schema, no annotations, and no parameter descriptions in the schema. The description covers only the pagination behavior and usage condition, leaving out parameter semantics, return format details, error handling, and any safety or permission information. For a tool of this complexity, the description is significantly incomplete, making it hard for an agent to call correctly without additional external knowledge.

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%, so the description must compensate by explaining parameters, but it does not. The only indirect reference is 'up to N pages', which hints at maxPages, but it doesn't explain city, sort, query, price ranges, or other parameters. The agent is left to infer meaning from parameter names alone, which is inadequate for an 8-parameter tool. The description adds virtually no semantic value for parameters.

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: 'Search Sheypoor listings and auto-paginate' with the specific resource (listings) and behavior (auto-pagination). It also differentiates from sibling tools by mentioning 'all/many results', implying it is distinct from a single-page search. The verb 'Search' plus the pagination scope makes the purpose unmistakable.

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 'Use this when the user wants all or many results', providing a clear condition for when to choose this tool. However, it does not name the alternative sibling 'search_listings' or state when NOT to use it, which would be stronger guidance. Still, the context is clear enough for an agent to infer.

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, the description carries the full burden; it signals a read-only retrieval ('Return') and notes the authentication requirement ('authenticated user'). It does not describe failure behavior or exactly what a profile contains, but for a side-effect-free, parameterless tool this is minimally adequate.

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 or redundancy. Every word contributes to identifying the tool's function.

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 no-parameter, simple read tool, the description provides the essential context: it returns the authenticated user's profile. A fuller return-shape breakdown would be helpful since there is no output schema, but the current description is unlikely to lead an agent astray.

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 tool has zero parameters and the schema has 100% coverage of an empty property set, so there are no parameters needing documentation. The description adds no parameter semantics, but none are required.

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 ('Return') and a clear resource ('the authenticated user's profile'), which precisely identifies the tool's function and distinguishes it from siblings like get_my_listings or login_start. Even with no parameters, the intended purpose is immediately unambiguous.

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 clearly implies the tool is used to retrieve the current authenticated user's identity/profile, which is the relevant context. It does not explicitly name alternatives or exclusions, but no sibling tool performs this exact function, so the guidance is sufficient.

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