Mati Logistics — supplier & product sourcing

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

Annotations already declare readOnly, idempotent, and non-destructive, so safety is covered. The description adds genuinely non-obvious behavior: response content is conditional on authentication ('with an account also spec tables, MOQ and lead time'), which the annotations do not convey.

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 tight sentence, front-loaded with the resource and then the returned fields; every clause carries information with no padding.

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 enumerates the returned fields and the auth-conditional extras, which is what an agent needs to decide whether the call answers its question. Only the identification semantics of the two required slugs are left 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 0%, so the description bears the full burden of explaining supplier_slug and product_slug, yet it says nothing about how a product is identified or where the slugs come from. The parameter names are semi-self-documenting, but the description adds no meaning beyond them.

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 ('One product's full record') and enumerates the content returned, so an agent can distinguish it from the plural search_products sibling. It stops short of naming or contrasting the siblings explicitly, keeping it below 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?

Usage is only implied: 'One product's full record' suggests single-record retrieval versus search, but there is no explicit statement of when to use this over search_products or get_supplier, and no prerequisites or exclusions are given.

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, so the safety profile is fully covered. The description adds useful scope by enumerating what the returned record contains, but says nothing about data freshness, sourcing of the customs/profile sections, or failure behavior when a slug is unknown.

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

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

A single front-loaded sentence that opens with the resource and slug key, then lists the payload. Efficient, though the trailing field enumeration is dense and could be tightened.

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 compensates by listing the record's sections, which is what an agent needs to know before calling. For a one-parameter read tool with full annotation coverage, this is close to complete, missing only error/empty-result behavior.

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

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

There is a single parameter with 100% schema description coverage, so the schema already defines 'slug' as coming from a search result. The description only restates 'by slug' without adding format or lookup semantics, 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 ('One supplier's record') and enumerates the record's contents (country, industry, customs history, profile, catalogue, certifications). The singular 'One supplier's record by slug' implicitly distinguishes it from search_suppliers, but it never names the sibling explicitly, so sibling routing 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 phrase 'by slug' and the schema hint that this is a follow-up to a search, implying usage, but the description never states when to use this versus search_suppliers or get_product. No exclusions or prerequisites are given.

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, openWorld, and non-destructive, so safety is covered. The description adds useful non-annotation context (API key requirement, 'one unit per line'), though the 25-line cap merely repeats the schema's maxItems.

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 compact sentences with no filler, and the core purpose leads. The phrasing is slightly awkward ('whose customs record fits') but 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 tool with a nested array input, zero schema descriptions, no output schema, and nested per-line fields (ref, hs_code, quantity, etc.), the description is too thin: it does not explain the expected shape of the response per line or the role of per_line/countries.

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

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

Schema description coverage is 0% for 3 parameters, so the description must compensate. It only addresses 'lines' marginally ('up to 25 lines', 'one unit per line') and says nothing about 'per_line' (default 3, max 5) or 'countries', leaving two of three parameters entirely undocumented.

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 the resource (suppliers/catalogue products/factories) and the action (matching) against a bill of materials, and specifies scope (up to 25 lines). It is somewhat fragmentary, but an agent can distinguish it from single-entity siblings like get_product or search_suppliers.

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 implies batch BOM matching is the use case but never states when to pick this over search_products or search_suppliers, nor any prerequisites beyond the API key. No when/when-not guidance is given.

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, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: results come from *published* catalogues, each hit carries supplier, summary, links, and price only 'when published' — flagging that price is sometimes absent. It says nothing about rate limits or result-count ceilings.

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, zero filler, with the core operation and query semantics front-loaded and immediately followed by useful illustrative examples and the return shape.

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 correctly takes on the burden of describing return fields (supplier, summary, price-when-published, links), which is exactly what an agent needs. The only mild gap is the absence of any statement about result limits or how the 'limit' parameter bounds the search.

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 67%: 'query' and 'countries' are documented in the schema, while 'limit' has only default/min/max constraints. The description restates the query-by-description idea and confirms country filtering via 'suppliers', but adds no format or syntax detail beyond the schema, 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 states a specific verb (Search) and resource (manufacturers' published product catalogues) with concrete examples ('stainless steel hex bolt', 'PVC ball valve'). It also lists the returned fields, making it distinguishable from the singular get_product and the supplier-oriented search_suppliers / get_supplier siblings.

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: searching 'by description' suggests broad discovery versus the pinpoint retrieval a get_product call provides, but no alternative is named and no when-not condition or exclusion is given. An agent can infer the intent but is not explicitly routed.

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 establish read-only, idempotent, open-world, non-destructive behavior, so the safety profile is covered. The description goes further by disclosing the ranking algorithm (shipment volume under given HS codes first, then product-match quality), which materially affects how an agent should interpret and prioritize results.

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, no filler, and the scope and data source are front-loaded before the ranking rule. Every clause carries information the agent needs.

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 should anchor expectations for results; it explains the source and ranking but not the shape of returned supplier records or what fields come back. Given only 4 parameters and no required ones, this is largely complete but leaves the return contract unspecified.

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%, so most parameters are already documented in the schema, making 3 the baseline. The description adds the useful interaction between hs_codes and query (ranking order), but says nothing about limit or countries beyond what the schema already provides.

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) and resource (manufacturers) plus the distinctive data source — US customs import records — which immediately separates it from sibling search_products. The clause about suppliers with no online catalogue makes the corpus scope concrete.

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 directed: the ranking explanation signals that HS codes and query should be supplied to get good results, but there is no explicit when-to-use/when-not or comparison against sibling tools like search_products or match_bom. An agent must infer the call context.

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