Kariwood Product Knowledge

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world. The description adds genuine semantics beyond that: missing facts stay missing (no interpolation) and unlike tests/units are not conflated. That tells the agent how to interpret incomparable results, which no annotation covers.

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 tight sentences, front-loaded with what is returned, followed immediately by the interpretation caveat. No filler 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?

With no output schema, the description usefully characterizes the return ('source-scoped facts and full technical context') and its interpretation rules. It does not detail structure or language behavior, but safety is covered by annotations, so it is nearly complete for 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 coverage is 50%: the 'products' parameter has an enum and min/max bounds but no description, while 'language' is documented in the schema. The description restates the 2-3 bound but adds no meaning about the product identifiers or language codes, so it does not compensate for the coverage gap.

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 (compare/return side by side) and resource (products), reinforced by the 2-3 count that matches the schema constraints. It implicitly separates itself from the single-item siblings like get_product, but 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: the 2-3 product count signals this is for multi-product comparison rather than single lookups. There is no explicit 'use this when...' or 'use get_product instead for single items' routing, leaving the 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?

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so safety is covered. The description adds genuine scope detail: it returns a citation URL and content date, and explicitly cannot retrieve external URLs, files or private data. Auth requirements and rate limits are not mentioned, but for a public read tool that is a minor 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?

Three short sentences, front-loaded with the core action, then ID format, then scope limits. No filler 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?

With no output schema, the description helpfully names two returned fields (citation URL, content date), which compensates for the missing return documentation. It is nearly complete for a one-parameter read tool, though it does not describe error behavior for unknown IDs.

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 carry the burden – and it does, defining the id as language/slug with a concrete example (tr/hus-kontrplak). That is exactly the format information the bare string schema omits.

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 ('Read') and resource ('a complete public source') and ties the resource to the sibling that produces it ('returned by search'). An agent can distinguish it from search, get_product, and list_products 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?

The phrase 'returned by search' establishes the workflow context (use after search to get full content) and the exclusion list rules out external URLs, files and private data. It stops short of explicitly naming an alternative tool or stating when another sibling should be preferred.

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 openWorld=false, so the safety profile is covered. The description adds genuinely new behavioral context: results are candidates requiring project-specific confirmation and are explicitly not an engineering calculation, which sets expectations about output reliability.

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 clauses – purpose, usage tip, caveat – with no filler and the core action front-loaded. Every sentence carries distinct 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 two-parameter, read-only lookup with no output schema, the description covers the purpose, the parameter workflow, and the nature of the results. It stops short of describing the shape of the returned candidate list, which would be helpful given there is no 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 50% because the application enum lacks a description, and the description compensates by explaining the omit-to-list-then-select behavior for that parameter. The language parameter's meaning is left entirely to its schema description, which does cover it 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 states a specific verb+resource ("Find candidate products") and scopes it to Kariwood published application guidance, which is more specific than a generic search. It does not explicitly differentiate itself from siblings like search or list_products, so the agent must infer the boundary.

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: omit the application parameter to enumerate supported application IDs, then select one. That is a clear usage path, though it never states when to prefer this tool over search or list_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?

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description contributes by reinforcing the no-side-effect boundary and disclosing that the contacts are public sales contacts, which tells the agent the data source is static rather than a live CRM record. No auth, rate-limit or return-shape detail is added.

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 tight sentences, no filler. The retrieval purpose is front-loaded, with usage triggers and the negative constraint following in priority order.

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-optional-param read-only lookup with rich annotations and no output schema, the description covers what the tool returns at a high level (contacts plus quotation guidance) and what it will not do. It leaves the exact response shape and language-selection behavior implicit, which is a minor gap given the schema handles the parameter.

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

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

Schema description coverage is 100% and the single language enum is fully documented in the schema (tr/en/ru/ar with a default). The description says nothing about the language parameter, so it adds no meaning beyond the schema; 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 ('Get public sales contacts') plus the secondary payload ('quotation preparation guidance'). It implicitly separates itself from the product-catalog siblings (get_product, list_products, find_material) by being about contacts and guidance, but never names a sibling or draws an explicit boundary.

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 concrete when-to-use triggers (prices, availability, delivery, unsupported products, missing information) and explicit when-not clauses ('Does not send messages, create leads or place orders'). It stops short of naming which sibling to use instead when the request is actually a product lookup.

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 genuine behavioral context beyond that: it names the categories of returned content and warns against over-generalizing one variant, which is a real behavioral constraint on how results should be interpreted.

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 tight sentences with the return content front-loaded, then the ID prerequisite, then the interpretive caveat. No filler, though the phrasing is slightly terse and could be marginally clearer.

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 carries the return-value burden and does so by listing the content types. Given a read-only 2-param tool with a required enum identifier, this is nearly complete; only sibling alternatives are 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 coverage is 50% — 'language' is documented in the schema, but 'product' has none. The description partly compensates by telling the agent the ID must come from list_products and be exact, which explains the otherwise bare enum. It does not describe the enum values themselves or the 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?

States a specific verb ('Read') and resource ('product') and enumerates the content returned: description, technical tables, source documents, caveats. An agent knows roughly what comes back. It does not explicitly distinguish itself from the sibling compare_products, 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?

Gives a real prerequisite ('Use exact product ID from list_products') and a caveat ('Never generalize one variant to an entire family'). However it never addresses when to choose this over compare_products or find_material, so usage is implied rather than fully specified.

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 read-only, idempotent, non-destructive, closed-world. The description adds important domain context beyond that: it warns that a listing is not a stock availability statement, which prevents a real misinterpretation that annotations do not cover.

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, both earning their place, with the core purpose front-loaded and the stock-availability caveat immediately after.

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 read listing with full schema coverage and no output schema, this is close to complete; an agent knows what it returns and the key interpretation caveat. Only the routing guidance among the six siblings 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 coverage is 100% and the language enum is fully described, so the baseline is 3. The description adds nothing about the language parameter or its default behavior.

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?

Specific verb (List) plus specific resources (public product families and plywood series) and states what identifying data comes back (exact IDs and source URLs), which distinguishes it from siblings like get_product and find_material.

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 this is a broad enumeration but never says when to use it over get_product or find_material, nor when a more targeted lookup is preferable. The distinction is inferable from the 'list all' framing but not 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the lower bar applies. The description adds genuine context beyond them: the return shape ('citable document IDs for fetch') and the downstream workflow, which the annotations cannot convey. It does not mention pagination or result limits, keeping it out of the top score.

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 short sentences, front-loaded with what is searched, followed by what comes back and how to phrase input. Every sentence carries distinct information with no filler 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?

With no output schema, the description usefully sketches the return type (citable document IDs) and the fetch handoff, and it covers scope and query form for a 3-parameter read-only tool. Gaps remain around the limit parameter and any pagination or result-count behavior, so it is strong but not 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?

Schema coverage is only 33% — only 'language' is documented in the schema, and the description adds nothing about it. The description does add real meaning to 'query' (product terms or a concise question), partially compensating. The 'limit' parameter and its 1-10 range are explained nowhere, so this is adequate but incomplete.

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') plus the exact content scope: public products, technical documents, material selection, and contact information. It also clarifies the outcome ('Returns citable document IDs') and the handoff to fetch, which helps separate it from a plain list. However, it does not explicitly differentiate itself from overlapping siblings like find_material, get_contact, or get_product, leaving some ambiguity about when this beats those.

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 concrete query guidance ('Use product terms or a concise user question') and a scope exclusion ('no web-wide search'), which tells the agent what input shape works and what the tool will not do. It stops short of naming alternatives or stating when a sibling tool would be preferable, so it is useful context rather than full routing guidance.

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