lighting

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

With no annotations provided, the description carries the full burden of disclosure. It goes beyond a simple action statement by revealing the model's backing (522 learned pairs, 95% agreement) and, crucially, its failure behavior: returning null rather than guessing when the phrase names no category. This is strong, decision-relevant 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?

Three sentences, all earning their place: the primary action with examples, the underlying reliability evidence, and the null-return behavior. The most important information is front-loaded, and there is no filler or repetition of 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?

For a single-parameter tool with no output schema, the description is complete: it states what input is expected, shows valid examples, explains how the mapping works, and explicitly covers the null case. An agent has everything needed to call the tool correctly and interpret an unexpected result.

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

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

Schema coverage is 100% and the schema already describes 'term' as 'A product type, in Persian or English.' The description adds illustrative examples and clarifies that a 'phrase' is acceptable, but it does not substantially extend the schema's parameter meaning, so the 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?

The description names a specific verb ('Map') and resource ('any Persian or English lighting phrase onto canonical taxonomy'), with concrete examples like «داون‌لایت توکار» and 'high bay'. This clearly distinguishes the tool from product/brand lookup siblings such as get_product or list_brands.

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 establishes clear usage context: use this when you have a lighting phrase, in Persian or English, that needs mapping onto a canonical category. It does not explicitly name alternatives or exclusions relative to sibling tools, but the domain and intent are unambiguous enough for an agent to select it appropriately.

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 burden of behavioral disclosure. It adds meaningful context by clarifying that coverage reflects what each supplier's SOURCE stated, not product quality, and that a one-supplier category is reported honestly rather than presented as a comparison.

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. The first sentence states the core output, and the second provides an essential caveat about data interpretation. It is front-loaded and each sentence earns its place.

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

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

Given the single enum-constrained parameter and no output schema, the description communicates the key output dimensions: counts, share, and per-facet data coverage. It does not fully define these terms, but the tool is simple enough that an agent can select and invoke it 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 schema covers the single parameter fully with an enum and a description pointing to list_categories. The tool description does not add new parameter-level meaning, so the baseline score 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 the tool's purpose: reporting which suppliers cover a category, with counts, share, and per-facet data coverage. It is specific about the resource and scope, though it does not explicitly differentiate it from siblings like list_brands or get_brand.

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 is implied: when you want supplier coverage for a category. However, there is no explicit guidance on when to choose this tool over sibling tools such as list_brands, nor any exclusions or alternative 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?

With no annotations, the description carries the behavioral disclosure burden. It adds valuable nuance by explaining that doesNotDo is computed from absence in the product list rather than inferred from marketing, and it previews the response contents. It stops short of stating read-only behavior or error behavior, but no write semantics are implied.

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 that leads with 'One supplier in full' and spends zero words on filler. Every clause adds information, including the differentiating doesNotDo detail.

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

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

For a one-parameter read-style tool with no output schema, the description provides a good preview of the response (what they make, product families, doesNotDo). It lacks explicit handling of invalid slugs or a fuller return-shape list, but nothing essential is missing for an agent deciding to call it.

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 fully documents the sole slug parameter (including where to get it: list_brands). The description adds no additional parameter semantics, so it meets the baseline but does not exceed it.

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 operation and resource: retrieving one supplier profile in full, including product families and the distinctive doesNotDo field. The phrase 'one supplier in full' distinguishes it from sibling list/compare tools such as list_brands and compare_brands.

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 explicit when-to-use or when-not-to-use guidance is given. The wording 'One supplier in full' implies the tool is for detailed single-supplier lookups rather than enumeration, but it never names alternatives or conditions for choosing compare_brands or search_products.

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 usefully discloses that the response includes provenance details and read timing, which goes beyond what the schema shows. However, it does not mention error behavior, permissions, or whether this is a safe read operation.

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 sentence with no filler, and the core purpose is front-loaded. The parenthetical and the trailing provenance clause make it slightly dense, but 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 one-parameter fetch with no output schema, the description adequately previews the return contents, including provenance and timestamp. It does not describe a structured return shape, but the tool's simplicity makes this 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 coverage is 100% and the schema already provides an example id. The description adds value by explaining where the id comes from (search_products) and confirming the 'brand/product-slug' format, clarifying the parameter's meaning beyond the schema alone.

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

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

The description states a specific verb and resource ('get one product') and clearly identifies the input as the id returned by search_products, with a concrete format example. This distinguishes it from siblings like get_brand and search_products without needing to inspect the schema.

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 clearly implies the tool is used after search_products, since the required id is exactly what search_products returns. It does not explicitly state when not to use it, but the context is clear enough for an agent to infer the appropriate workflow.

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 carry the burden of behavioral disclosure. It states what is included (coverage, completeness, last read) and explicitly excludes contact details, but it does not disclose whether the operation is read-only, requires authentication, or has side effects. It also hints at server instructions but doesn't elaborate. This is partially transparent 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 two sentences with no wasted words. The primary function is stated first, followed by a clear limitation. It is concise, front-loaded, and avoids redundancy.

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

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

For a simple list tool with no parameters and no output schema, the description adequately conveys what the tool returns and what it omits. It covers the essential information an agent needs to decide if this tool is appropriate. It could mention the response format (e.g., array) but that is a minor gap given the simplicity of 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?

The tool has zero parameters, so the schema provides no parameter info. Per the rubric, the baseline is 4 for 0 params. The description adds value by specifying the output content (what data each supplier entry includes), which is more than the empty schema conveys. No parameter semantics are needed since there are none.

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 function: it lists every supplier on file and specifies the data returned (coverage, completeness, last read). It distinguishes itself from siblings like get_brand (specific brand) and compare_brands (comparison) by covering all suppliers. The verb 'list' and resource 'suppliers' make 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 for retrieving all suppliers but does not explicitly name alternatives or conditions for when to use this vs. other tools. The note 'No contact details — see the server instructions' provides an exclusion but no explicit pointer to a specific sibling. It gives context but lacks clear when-to-use/when-not-to-use 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?

With no annotations, the description carries the behavioral burden; it discloses the fixed set size (20), the included fields, and the single-supplier flag behavior. It doesn't overpromise dynamic content or hide side effects, though it doesn't discuss freshness or return shape.

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 dense sentences deliver the content, use case, and a useful heuristic (flags single-supplier categories) with no filler. The most decision-relevant facts are 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?

For a zero-param list tool, the description covers what is returned and why an agent might call it. It could be slightly more explicit about the return structure, but the absence of parameters and annotations makes this 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?

The tool has zero parameters, so parameter ambiguity is minimal; per the baseline for 0-param tools, a 4 is appropriate. The description adds no parameter details because none are needed.

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 the tool's output: the 20 canonical lighting categories with Persian/English names, product counts, and suppliers. This differentiates it from siblings like list_brands and get_product by specifying the resource and level of detail.

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 by noting the result is small enough to fetch once and reason over the whole market, signaling when a broad category overview is needed. It does not explicitly name alternatives or 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?

No annotations exist, so the description carries the full burden and does so well: it discloses the return payload (normalized facets plus match reasons), the non-filterable constraint on colour temperature and the reason, and that the response reports excluded results split into 'not stated in our data' vs 'did not match'. That is substantive behavior an agent could not infer from the schema.

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

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

Front-loads what the tool does, then layers the facets, the filterability caveat, and the exclusion semantics. Every sentence carries information, though the exclusion/absence passage is dense and could be tightened slightly.

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 ten parameters, the description supplies what is missing: the shape of the response (facets, match reasons, exclusion report) and the interpretive rule for missing products. An agent has everything needed to call and correctly interpret this 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 100%, so the schema already documents all ten parameters including the price_tier caveat and enum meanings; baseline is 3. The description adds the important caveat that colour temperature is returned but not filterable, which clarifies a capability boundary rather than a parameter's syntax.

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

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

States a specific verb+resource ('Search the catalog of real products stocked by the suppliers on file') and immediately scopes it to the actual supplier catalog, distinguishing it from generic search. The agent can tell it apart from get_product (single lookup) and list_categories (taxonomy listing) without opening a schema.

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?

Routes the agent explicitly: for 'does a supplier make X', use get_brand's doesNotDo instead, and it sets the crucial rule that absence from results is never evidence of non-manufacture. It does not cover the other siblings (compare_brands, list_categories) or state when a keyword search is preferred, so it falls short of a full when/when-not map.

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 full burden. It discloses that the call does not contact anyone, stores nothing, refuses personal data, and returns a link for the user to open. These are key behavioral traits (non-contact, non-storing, input validation) clearly stated.

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 no fluff. The main action (turn need into link) is front-loaded, followed by concrete behavioral constraints. Every sentence earns its place.

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

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

No output schema exists, but the description explicitly states the output is a link the user opens, and covers input constraints and side-effect-free behavior. For a single-required-parameter tool, this is sufficient, though it doesn't detail response format beyond the link.

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 describes both parameters in detail, including the personal-data refusal. The description repeats this but adds no new semantic nuance. Baseline of 3 is appropriate as the schema does the heavy lifting.

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 (turn a need into a link) and resource (adviser builds a brief, matches supplier's stock). It distinguishes itself from product/brand-focused siblings by emphasizing this is the only route to a supplier.

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

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

It gives explicit context: this is how someone actually reaches a supplier, and states there are no contact details in the server. But it doesn't name sibling alternatives or explicitly say 'use this instead of X'. The guidance is clear but not fully explicit about exclusions.

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