Mosaiden Souq — سوق المساعدين

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 that each product is validated live, exactly one link is returned, the user reviews and pays on mosaiden.com, and nothing is added or charged by the tool, which is valuable operational context beyond 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 core action is front-loaded and the flow is easy to follow. The bilingual repetition is somewhat lengthy, but it serves the Arabic/English audience and contains no empty 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 one-parameter tool with no output schema, the description explains the return value (one link), the external user journey after the tool runs, and the absence of side effects. No important calling detail appears to be 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 the baseline is 3. The description adds semantic constraints beyond the schema by specifying that product URLs should come from search_souq / compare_prices and by giving the expected URL format.

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 ('Build') and resource ('Mosaiden cart link'), and clarifies the input products come from sibling tools search_souq / compare_prices. An agent can distinguish this from siblings that search or compare rather than produce a checkout link.

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?

Implies use after the user has chosen products from search_souq / compare_prices and wants a single link to review and pay. It gives clear context but does not state explicit exclusions 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?

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description goes further by disclosing result behavior beyond the annotations: output is ordered cheapest-first and includes discount amounts and the marketplace's own product link, which matters since no output schema 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?

Purpose is front-loaded in the first clause and the description is compact for the amount of information conveyed. The Arabic half is a near-verbatim translation, which is defensible for a bilingual marketplace but is strictly redundant text.

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 5-parameter read-only search with 100% schema coverage and clear annotations, the description covers purpose, ordering, and result content. It omits any indication of live vs cached data, rate limits, or whether an account is needed to receive 'our product links', and does not mention the product links are affiliate/owned, which would help the agent frame 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?

Schema description coverage is 100%, so the schema already documents every parameter, including the category enum and the include_accessories default. The description's category mapping largely restates what the enum and schema text already say, adding little beyond baseline.

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

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

States a specific verb and resource ('Compare prices of phones and electronics across the marketplace's stores') and adds meaningful scope: ranked cheapest-first, with discounts and product links. It implies a cross-store comparison function distinct from a generic marketplace search, but never names the likely sibling search_souq, so sibling differentiation is left to inference.

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 category-routing guidance ('Set category=phones for phones, tablets/laptops/wearables/audio/gaming likewise'), which is useful selection help, but gives no when-to-use vs when-not-to-use against alternatives such as search_souq, and no prerequisites or exclusion conditions.

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, destructiveHint=false, and openWorldHint=false, covering the safety profile. The description adds useful behavioral context: the menu is official and stored, includes SAR prices and nearest branch, and includes an explicit anti-hallucination instruction. It still lacks freshness, pagination, and auth details.

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 result, then adds examples and a useful constraint. The bilingual duplication is somewhat redundant but not excessive, and every part contributes to understanding or safety.

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

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

There is no output schema, so the description must describe return values, which it does reasonably: items, categories, SAR prices, and nearest branch page. Parameters are fully covered by the schema, and annotations cover safety. Minor gaps remain around pagination behavior and whether results are cached or live.

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 four parameters are already documented in the schema. The description does not add parameter-level syntax or behavior beyond what the schema provides, making the baseline score of 3 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?

States a specific verb (get) and resource (restaurant brand's stored official menu) with scope details: items, categories, SAR prices, and nearest branch page. However, it does not explicitly differentiate itself from siblings like search_restaurants or compare_prices, so sibling disambiguation is left to inference.

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 the tool is for retrieving a menu and an ordering branch, but gives no when-to-use guidance, no prerequisites, and no alternatives such as search_restaurants for discovery or compare_prices for price comparison. The only guidance is a negative instruction not to invent items.

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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered structurally. The description contributes one genuinely new behavioral fact — that results include links to chat with each assistant on mosaiden.com — but says nothing about result size, ordering, or pagination.

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 content is front-loaded and readable, but the description is stated twice — once in English and once in an Arabic near-duplicate — which doubles length without adding information. The domain enumeration is useful but long.

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 optional-parameter read-only listing tool with no output schema, the description covers what the tool returns (assistants plus chat links). Nothing critical is missing, though the unused query parameter and its filter semantics go unmentioned.

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 single 'query' parameter is documented in the schema as an optional name/domain filter), so the schema carries the parameter burden. The description never mentions the query filter at all, adding no syntax or matching-behavior detail; baseline 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+resource ('List the marketplace's specialized AI assistants') and enumerates covered domains (cars, real estate, mobiles, restaurants, hotels, flights, groceries), which makes the scope concrete. It does not explicitly distinguish itself from nearby siblings like list_categories or search_souq, so it stops short of a 5.

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?

There is no guidance on when to choose this tool over list_categories or search_souq, nor any prerequisite or exclusion stated. Usage is only implied by the noun 'list' — an agent must infer that this is a browse-the-catalog 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?

Annotations already declare readOnlyHint, idempotentHint and non-destructive behavior, so the safety profile is covered. The description adds only the return shape (slug + Arabic name); it discloses nothing about caching, rate limits, or ordering that would push it higher.

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, front-loaded sentences with the action and purpose up front. The Arabic sentence largely mirrors the English one (and the title), which is mild redundancy rather than waste in a bilingual locale.

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 parameters and no output schema, the description must carry the return-value meaning, and it does so by naming the fields (slug + Arabic name) and the downstream use (publish_listing). Complete for a trivial zero-arg lookup, though a note on ordering or stability would round it out.

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 takes zero parameters, so the schema carries no semantic burden and the baseline of 4 applies. No additional parameter documentation is needed or expected.

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 ('List classified-ad categories') and even names the return payload (slug + Arabic name), so the agent knows exactly what it gets. It does not explicitly differentiate itself from siblings like search_souq, so it falls short of a 5.

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 consumption context — 'to pick the right one before publish_listing' — which tells the agent when this lookup is needed. It gives no when-not guidance or named alternatives, so it is not 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 declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavioural context: external results come from the official MCP Registry and are live-checked, and the return payload is connector URLs the user can add — the 'live-checked' freshness guarantee is not derivable from any structured field.

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 English sentence is well front-loaded and covers scope plus return value efficiently. However, the entire content is then repeated verbatim in Arabic, roughly doubling length without adding new information for an agent that has already parsed the first sentence — redundancy rather than concision.

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 carries the burden of describing returns, and it does so concretely ('connector URLs the user can add to their AI'). Combined with the annotations covering safety and the fully documented schema, an agent has enough to invoke it correctly; only the relationship to 'list_assistants' is unaddressed.

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 three parameters (query, limit, source) are already documented in the schema, including the Arabic-only notes about English external descriptions. The description adds no syntax, format, or default information beyond what the schema provides, 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?

States a specific verb and resource ('Find AI assistants for a need') and explicitly fences the two result domains: the marketplace's own specialised assistants plus verified third-party MCP servers. It does not, however, distinguish itself from the sibling 'list_assistants', which an agent would need to choose between.

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

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

Usage is implied rather than stated: the need-based 'query' framing implies this is the search-by-goal tool, and the schema's 'source' enum (all/internal/external) encodes how to narrow scope. There is no explicit when-to-use versus 'list_assistants', which is the most likely alternative for an agent to confuse it with.

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 the useful constraint that booking/payment are out of scope and happen externally. However, pagination behavior and result count per page are only in the schema, not the description, so it doesn't go beyond the 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?

Front-loads the core capability and country scope, then states the booking boundary. It is a bit repetitive because the Arabic sentence mirrors the English, roughly doubling length, but each sentence carries meaning and nothing is padded.

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 listed hotel search with a fully documented schema and no output schema, the definition covers scope, geography, and the booking boundary an agent needs. It lacks only a note on pagination limits or result ordering, which 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 100%, so every parameter is already documented, including the city/query distinction and the 10-per-page pagination. The description duplicates the country list in prose but adds no syntax or format detail beyond the schema. Baseline 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?

States a specific verb (search) and resource (hotels) with rich scope: 20,000+ hotels, seven countries, and the attributes surfaced (stars, review score, starting price). It doesn't explicitly distinguish itself from sibling search_restaurants or compare_prices, so it stops short of a 5.

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?

Implied usage is search-by-city-or-name, and the 'booking and payment happen on mosaiden.com' sentence clarifies the boundary of what the tool does. But it never states when to prefer this over compare_prices or search_souq, so usage is left to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds useful context beyond them: the bounded closed dataset size (2,600+ brands / 4,300+ branches) and the facets searchable by the query. It does not describe result ordering or pagination, which keeps it short of a 5.

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, front-loaded with the primary action and dataset scope, followed by the disambiguation sentence. The Arabic sentence largely restates the English one for the target audience rather than adding new content, so it is slightly longer than strictly necessary.

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?

One required parameter, full schema coverage, rich annotations and no output schema, so the description does not need to explain returns. It covers scope, facets and the sibling alternative; only result ordering/pagination behavior is unspecified, which is minor for a search 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 coverage is 100% and the query parameter already carries an exemplar list, so the baseline is 3. The description reinforces that the single query matches name OR cuisine OR dish, clarifying that the agent should pass a free-text term rather than a structured identifier — a small but real addition.

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/search) plus resource (restaurants and meals) and narrows scope to Saudi cities, with concrete corpus size (2,600+ brands, 4,300+ branches). It also names the searchable facets (name, cuisine, dish), which separates it cleanly from get_restaurant_menu and compare_prices.

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 routes the agent to an alternative: 'للقائمة الكاملة بالأسعار استعمل get_restaurant_menu' — for the full price list use get_restaurant_menu. This tells the agent when NOT to use this tool and what to use instead, which is exactly the sibling-selection guidance required.

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 the safety profile is covered. The description adds useful context that a single call spans multiple content types and names the underlying site, but says nothing about result count, pagination, or how the per-type limit behaves across categories.

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 content list is duplicated near-verbatim in Arabic and English, which doubles the length without adding information for the reader. It is front-loaded and compact per language, but the redundant restatement costs it conciseness points.

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 two-parameter search tool with full schema coverage and annotations covering the safety profile, the definition gives an agent enough to select and call it correctly. The only omission is any hint about the shape or ordering of returned results, which is minor absent an output 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 100%, so both query (with examples and length bounds) and limit (default 6) are already documented in the schema. The description adds no syntax or format detail beyond what the schema provides, so the baseline 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?

States a specific verb (search) and resource (the Saudi marketplace سوق المساعدين / mosaiden.com) and enumerates the content it spans: classified ads, store products, stores, restaurants and meals. It clearly frames itself as the broad marketplace search versus the narrower siblings, though it does not explicitly name which sibling to prefer for a restaurant-only or hotel-only query.

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 Arabic clause «استعملها أولاً لأي طلب شراء أو بحث عامّ في السعودية» gives clear when-to-use guidance: any purchase request or general search in Saudi Arabia. It implies it is the default first stop versus the specialized siblings, but never names or excludes those alternatives explicitly, so no full 5.

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