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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered; the description still contributes useful context on result shape (product count per node, category slug) and tree scale. It doesn't warn about response size or pagination when browsing a node with thousands of sub-categories, which is the main unclosed loop for a large read.

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 with zero filler; the mode split is front-loaded immediately after the scope statement, and the return-value hint sits last where it is most useful. Nothing repeats the schema or annotations.

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, three-parameter browsing tool with a fully documented schema and no output schema, the description covers what it returns and how to traverse. The one real omission is guidance on result volume or pagination when a top-level category expands to thousands of children.

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 baseline is 3, but the description meaningfully adds what changes behaviorally when 'category' is supplied versus omitted, and tells the agent the returned slug is the preferred input form elsewhere. It adds no detail on 'depth' or 'language', though the schema documents those adequately.

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 and resource ('Browse the Özdisan category tree') and quantifies scale (5 main groups → thousands of sub-categories, ~1M products). It also states the two operating modes (with/without 'category'). However, it never contrasts itself with the closest sibling, search_categories, so an agent still has to guess which entry point to use.

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 states the call pattern: omit 'category' to get top-level groups, supply one to drill into sub-categories, and that returned slugs are reusable in other tools. It gives no explicit exclusions or guidance on when search_categories is the better choice, so it stops short of full when/when-not coverage.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses the computation performed per line — MOQ/order multiples, price-break selection, lead time when stock is short — and the return shape: line totals plus BOM total with VAT excluded. It also discloses throughput and the hard 60-line cap, which are practical constraints an agent must plan around.

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, both front-loaded: the first defines the operation and its outputs, the second gives the call-size limit and remedy. Dense but every clause carries information an agent needs; 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?

With no output schema, the description responsibly explains what comes back (line totals, BOM total, VAT-excluded, EOL/price-on-request flags) and covers the batch limit. The one omitted behavior is what happens to lines whose part cannot be resolved or that are ambiguous — a meaningful gap for a batch tool fed arbitrary part numbers.

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 75% and the schema already documents part formats, quantity bounds, currency and language. The description adds only marginal semantic value — it clarifies that MOQ and order multiples are applied to the supplied quantity and that prices are VAT-excluded — while never mentioning the 'boards' multiplier or 'language' parameter.

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

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

The description states a specific verb and resource ('Check a bill of materials against Özdisan') and then enumerates the per-line work: part resolution, MOQ/order-multiple application, price-break selection, stock and lead-time checks, end-of-life/price-on-request flagging, and line plus BOM totals. This is unmistakably a batch BOM pricing/availability check, clearly distinct from single-part siblings like get_product or search_products.

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 concrete operating guidance: up to 60 lines per call at roughly 1 s per line, and instructs splitting larger BOMs into several calls. What it does not do is name an alternative for the single-part case (e.g. get_product) or state when not to use it, so it stops short of explicit routing.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the description's job is to add context, which it does by disclosing the shape of the result: aligned specs with differences highlighted plus stock, MOQ, lead time, and price. It does not address failure modes such as an unresolvable product identifier or mixed-category comparisons, which would have pushed this 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?

A single sentence, front-loaded with the action and product-count constraint, followed by a compact list of compared dimensions. Nothing is redundant and no clause could be removed without losing information.

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 what comes back, and it lists the compared fields and difference highlighting clearly. It stops short of noting edge-case behavior (invalid codes, out-of-range counts, unavailable price at quantity), which is the remaining 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%, so parameter documentation is already complete. The description adds only marginal framing ('2-10 products', 'price at a given quantity') that overlaps the minItems/maxItems and quantity descriptions in the schema, 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?

The description opens with a specific verb and resource ('Compare 2-10 products side by side') and enumerates the compared dimensions: specs aligned by property with differing properties highlighted, stock, MOQ, lead time, and price. That is enough to separate it from single-product siblings like get_product or get_alternatives, though it never names an alternative explicitly.

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 only implied by the verb 'compare' and the 2-10 range; there is no statement of when to prefer this over get_alternatives, check_bom, or repeated get_product calls. An agent can infer the multi-product comparison scenario, but nothing tells it when this tool is the wrong choice.

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 declare a non-read-only, open-world, idempotent, non-destructive operation, and the description explains why it is idempotent (existing files are reused unless overwrite=true) and discloses the filesystem side effect and default location. It stops short of describing failure cases, such as products with no datasheet available or permission errors.

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

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

Four short sentences, front-loaded with the purpose and return value, then the configuration default, then caching, then the sibling redirect. No redundant or filler wording.

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 usefully states that a file path is returned, and it covers defaults and overwrite semantics for a 4-parameter tool. Error behavior for missing datasheets and the exact response shape are the only notable omissions.

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 baseline is 3, but the description adds the default folder value (~/Downloads/ozdisan-datasheets) and the OZDISAN_DOWNLOAD_DIR environment override with its precedence, neither of which appears in the schema.

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

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

States a specific verb and resource ("Download a product's datasheet PDF to the local disk") plus the return value (file path). It also distinguishes itself from the sibling read_datasheet by naming it as the tool for reading content.

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: use this tool to save the PDF, use read_datasheet to read the content. Caching behavior (reuse unless overwrite=true) tells the agent it can call this repeatedly without side-effect concerns.

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

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

Annotations already cover the read-only/idempotent safety profile, yet the description adds genuinely new behavior: the AND across properties / OR within a property semantics, VAT-excluded unit pricing, the quantity-driven price break, and the exact return payload (stock, MOQ, price break, specs). None of this is derivable from the annotations or 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?

Three dense sentences, front-loaded with purpose and then the combination semantics; nothing is filler. It is tightly packed but the ordering (what it does, how to combine, what comes back) is logical and easy to scan.

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

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

For a 17-parameter tool with nested objects and no output schema, the description covers the essential return shape and the filter-combination rules that an agent cannot infer. Minor gaps remain around pagination limits and sort defaults, though those are handled in the schema descriptions.

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 already high (88%), so the baseline is 3; the description adds meaning on top by clarifying the boolean combination logic between filters and ranges and what 'quantity' actually changes. The unit/currency nuances remain delegated to schema text, which is acceptable given coverage.

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

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

States a specific verb and resource ('Parametric product search inside a category') and anchors it with a concrete analogy ('like the filter panel on ozdisan.com'). It is clearly distinguishable from the keyword-oriented search_products sibling and from get_product, which it explicitly references for the full price table.

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

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

Gives clear operating context: combine property filters using exact option values from get_category_filters, and use get_product if the full price table is needed. It does not explicitly say when to prefer search_products or browse_categories over this tool, so the routing to alternatives 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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds no behavioral context beyond that — nothing about empty result sets, how many relation types are queried by default server-side, or whether lookups cost quota. With annotations carrying most of the load, a 3 is appropriate.

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 action and resource, then the type glossary, then the trigger conditions — no filler. The type enumeration is dense but each gloss is load-bearing.

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?

Five parameters, no output schema, and the description never indicates what a result looks like — whether each alternative comes with price (and in which currency), stock status, or match confidence. For a tool whose whole value is comparing options, that missing return-shape hint leaves a real gap, though the rich input schema and annotations prevent it from being severe.

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 baseline is 3, but the description genuinely adds meaning beyond the bare enum values by defining what 'substitute' (drop-in/muadil), 'similar' (benzer), 'accessory' (complementary) and 'parametric' (same category, same key specs) actually mean. That disambiguates the most consequential parameter better than the schema does.

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+resource ('Find replacement options for a product') and enumerates the four relation modes it can return, each glossed in parentheses. It is clearly distinct in intent from search/filter siblings, but it never names those siblings or states the contrast explicitly.

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?

'Useful when a part is out of stock, end-of-life or too expensive' gives concrete trigger conditions for reaching for this tool. It stops short of exclusions or alternatives (e.g. when to use search_products or compare_products instead).

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description adds the non-obvious dynamic behavior: when current filters are supplied, returned options are limited to those still available, which is a caching/availability caveat an agent cannot infer from the annotations. It does not mention result size limits or latency beyond what max_values in the schema implies.

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, each earning its place: what the tool returns, when to call it, and how the parameter modes behave. The purpose is front-loaded in the first clause, and the example lists clarify rather than pad.

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 9-parameter tool with no output schema, the description compensates by describing the returned content directly (properties, types, units, options, manufacturers, flags). Remaining gaps are minor: it doesn't mention the language toggle or the max_values truncation default, both of which are documented in the schema but are behaviorally relevant when options are cut off.

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 baseline is 3, but the description adds genuine semantic value by explaining the relationship between parameters: 'property' and 'value_query' are narrowing modes, and the filter parameters act as a feedback loop that prunes unavailable options. It still leaves language, max_values, query and manufacturers to the schema, which documents them well.

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

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

The description opens with a specific verb and resource ("List the parametric filters of a category") and then enumerates exactly what is returned: technical properties, type (numeric/text), units, selectable option values, manufacturers, and stock/RoHS/document flags. It explicitly contrasts itself with the sibling filter_products, so an agent can route without opening either 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 states the workflow position explicitly ("Use it before filter_products to pick exact option values") and names the conditions that select each parameter mode: 'property' for one property's options, 'value_query' to search inside options, and passing current filters to see only still-available options. The alternative tool and the trigger for using this one are both named.

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?

The annotations already declare read-only, idempotent, non-destructive, and open-world behavior. The description adds useful behavioral context by specifying the returned data areas, VAT-exclusive pricing, and optional alternatives, though it does not describe not-found handling or error behavior.

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

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

The description is front-loaded with the core purpose and then lists returned fields in one sentence. The field list is long but purposeful; there is little filler, though it could be more scannable.

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, so the description appropriately carries the return-value burden and comprehensively lists the product fields, pricing basis, and optional alternatives. It is nearly complete for a read-only detail tool, but it omits behavior for missing products or ambiguous identifiers.

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 explains product identifiers, currency, language, and include_alternatives. The description reinforces VAT exclusion and optional alternatives but adds no syntax or format details beyond the schema.

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

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

The description clearly states a specific verb and resource: it returns full details of one product. It enumerates the data included, making the single-product detail scope distinct from list-oriented siblings such as search_products and filter_products.

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 by 'one product' and by the optional alternatives note, but the description does not explicitly say when to use this instead of search_products, get_alternatives, or compare_products. There is no explicit 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?

Annotations already declare readOnly, idempotent, non-destructive behavior, so the safety profile is covered. The description adds valuable output-shape context beyond that: tables come back as plain text while figures and diagrams are silently omitted, which prevents an agent from expecting graphical content. It does not mention rate limits, auth, or what happens when text exceeds max_chars.

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 compact sentences, front-loaded with purpose before the workflow and then the output caveat. Every sentence carries information; the example search keywords are useful rather than filler. Minor length is added by the content-type enumeration, but it 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?

With no output schema and six optional parameters, the description does the necessary work: it explains the search/page workflow and discloses that tables are text and figures are excluded. The absence of any note on error behavior (bad URL, unscrapable PDF, product not found) is the main remaining gap for an open-world 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 each of the six parameters is already documented with type, range, enum, and examples. The description adds only the search-then-pages sequencing, which is light but genuine value. With the schema doing the heavy lifting, baseline 3 is warranted.

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

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

The description opens with a specific verb and resource ('Extract text from a product's datasheet PDF') and enumerates the content types an agent can expect (pinouts, absolute maximum ratings, electrical characteristics, package dimensions), which makes the tool's role unmistakable. It does not explicitly contrast itself with the sibling 'download_datasheet', so it falls short of full sibling differentiation.

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

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

It gives concrete operational guidance: call with 'search' first using terms like 'pin configuration' or 'thermal', then use 'pages' to read the located range. That is a clear recommended workflow with example inputs. It stops short of saying when NOT to use this tool versus download_datasheet or get_product.

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, so safety is covered; the description adds the non-obvious trait that matching spans Turkish and English names and that result sets include categories whose products match, not just name matches. It also states the key output field ('category' slug), though it does not describe ordering, ranking, or empty-result 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?

Three sentences, front-loaded with purpose, then workflow routing, then the selection heuristic. No repetition of schema fields and no filler; every sentence carries decision-relevant information.

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 3-parameter, read-only search with no output schema, the description covers what is returned (categories keyed by a 'category' slug) and how to use it. It stops short of describing the result fields (name, depth/parent, matched-product indication) that the 'most specific category' advice depends on.

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 baseline is 3, but the description earns an extra point by clarifying that the query is matched against both category names and product content and by giving worked examples ('mosfet', 'lineer regülatör', 'MLCC'). The 'language' parameter's effect is only implied through the bilingual examples rather than stated directly.

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?

"Find Özdisan product categories by name or by what they contain" gives a specific verb, resource, and two distinct matching modes. It also names the downstream siblings (get_category_filters, filter_products) that consume its output, so an agent can place it in the workflow without opening any 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 explicitly says to feed the returned 'category' slug into get_category_filters and filter_products, and advises preferring the deepest matching category for parametric filtering — a real decision rule. It does not say when to pick this over search_products or browse_categories, which would have completed the routing picture.

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

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

Annotations already cover readOnly/idempotent/non-destructive, and the description adds real value beyond them: corpus size (~1M), that results include per-category match counts, best matches with stock, VAT-excluded starting prices, key specs, and quick matches from other categories. It stops short of describing pagination behavior or result limits beyond the page_size parameter, so a 4 rather than 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?

Front-loaded with the core purpose and search mode, followed by return shape, then narrowing, then the alternative routing. The parenthetical example lists are dense but functional; a couple of examples would have sufficed instead of five.

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 return-value burden and does so adequately, naming the match counts, product entries with stock/price/specs, and cross-category quick matches. For a 7-parameter read tool with full annotation coverage it is close to complete, missing only pagination/total-count semantics.

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 seven parameters including the enums and the category identifier formats. The description reinforces category scoping and VAT-excluded pricing but adds no format rules or defaults the schema does not already carry, so 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 and resource ('Keyword / part-number search across all ~1M Özdisan products') with concrete query examples ('STM32F103', '10uF 0805'), which makes the retrieval mode unambiguous. It also explicitly separates itself from parametric search by naming the sibling chain to use instead.

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

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

Gives explicit routing: use this tool for keyword/part-number lookups, pass 'category' to constrain to one category, and for parametric selection (with a concrete example, 'LDO 3.3V 500mA SOT-23') use search_categories → get_category_filters → filter_products. Both when-to-use and when-to-use-something-else are stated.

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