SkoIA Parts

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, but the description adds a meaningful behavioral boundary: it reports compatibility only when the verified interface system matches, and only for canonical ProductTwins. This goes beyond annotation data and is not contradictory.

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 exactly two sentences, front-loads the operation and scope, and contains no filler. Every word contributes to understanding what the tool does.

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 two-param, read-only tool with an output schema present, the description covers the essential behavior and its key limitation. It doesn't state what happens when interface systems do not match, but the output schema likely handles result presentation, so the description is close to complete.

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 compensate. It does clarify that the two string parameters denote canonical ProductTwins, adding a layer of meaning. However, it doesn't elaborate on the expected format or how to populate them beyond the schema's pattern, so it only partially compensates.

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

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

The description uses a specific verb ('compares') and names a clear resource ('two canonical ProductTwins'), and adds a defining condition ('direct compatibility only when their verified interface system matches'). It does not distinguish from sibling tools by name, so it stops short of a 5.

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

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

The description implies the tool is for comparing two canonical ProductTwins, and the phrase 'direct compatibility only' hints at a specific scenario. However, it gives no explicit guidance about when to prefer this tool over siblings such as get_fit_guidance or resolve_problem, and names no alternatives or exclusions.

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, and non-destructive behavior, so the safety profile is covered. The description adds useful behavioral detail by stating the calculation is deterministic and that an explicit physical-test warning is returned.

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 with no wasted words. It avoids repeating the title and every phrase contributes either what is calculated or what is returned.

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?

Output schema and annotations cover return values and safety, and the core purpose is stated. However, with seven input parameters, no parameter explanations, and no usage guidance, the description is only minimally viable for an agent deciding how to call 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?

Schema description coverage is 0% and the description mentions none of the seven parameters. It does not explain the roles of process, material, measurementBasis, gender, or userCalibrationMm, so the schema names and enums carry nearly all parameter meaning.

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 action ('calculates') and resource ('manufacturing compensation') and adds a concrete output trait (physical-test warning). It is distinct in function from sibling search/list tools, though it does not explicitly name or contrast a sibling.

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 when-to-use guidance is provided. The description does not state prerequisites, alternatives, or situations in which another sibling tool should be chosen instead; the only usage context is implied by the fit-compensation domain.

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 annotation set already notes idempotentHint=true and destructiveHint=false. The description adds meaningful behavioral context by stating it 'never purchases' and emphasizes that it only queries/queries, which is reassuring for agents and clarifies that this tool will not trigger financial side effects. There is no contradiction with annotations.

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

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

The description is two short sentences with no wasted words. The primary action and scope are front-loaded, and the critical safety reassurance ('It never purchases.') is placed at the end without bloat.

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 simple schema, presence of an output schema, and helpful annotations, this description is mostly complete: it identifies the resource, scope, and a key non-behavior. It only falls short in not elaborating on parameter semantics or alternatives, but those are separately scored dimensions and the tool is simple enough to operate with reasonable inference.

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 carries the full burden for parameter semantics, but it does not explain what the `query` string should contain or how `limit` behaves beyond the schema. The agent must infer from parameter names, which is risky for a commerce-provider query.

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

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

The description uses a specific verb ('Queries') and resource ('configured commerce provider') and precisely scopes the output: only outbound offers with attributable URLs. It also clarifies that the tool never purchases, which differentiates it from any commerce action and makes its 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 when to use this tool: when you need attributable outbound offers from the configured provider. However, it gives no explicit guidance about when not to use it or how it compares to sibling tools such as search_parts or get_product, so the usage context is only implicit.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds useful behavioral context: the returned ProductTwin is 'canonical' and includes 'source-level provenance', which goes beyond the annotations. It does not introduce contradictions or disclose additional behaviors like rate limits or error cases, but the annotation coverage lowers the burden.

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 with no wasted words. It states the action ('Returns'), the object ('one canonical ProductTwin'), the additional attribute ('source-level provenance'), and the input mechanism ('by stable identifier'). Every phrase 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?

This is a simple single-parameter lookup tool with an output schema present, so the description need not explain return values. The description, combined with annotations and schema, provides enough for correct invocation: pass a stable identifier to get a canonical twin. The only minor gap is explicit usage routing with sibling tools, but it is not critical for this simple operation.

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 0%, and the schema only defines 'id' as a string with a pattern. The description helps by calling it a 'stable identifier', giving semantic meaning to an otherwise opaque parameter. However, it does not elaborate on the identifier format or where to find it, so it only partially compensates for the missing schema descriptions.

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?

Description uses a specific verb 'Returns' and a specific resource 'canonical ProductTwin and its source-level provenance', which clearly states what the tool does. The phrase 'by stable identifier' explains the lookup mechanism and distinguishes this from search-oriented siblings like search_parts and resolve_problem, which do not retrieve by canonical identifier.

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: call this tool when you have a stable identifier and need the canonical ProductTwin with provenance. However, it does not explicitly name alternatives or state when NOT to use this tool, leaving the agent to infer the boundary with sibling tools like search_parts.

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=false, and non-destructive, so the description need not restate those. It adds the useful scoping point that the list is limited to the current deterministic core, but it does not clarify how the optional intent affects 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?

A single, front-loaded sentence that states the action and scope with no filler. Every word contributes to the tool's meaning.

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 tool's simplicity, rich annotations, and output schema, the description covers the core behavior. However, it leaves the meaning of the sole parameter undocumented, which is a noticeable gap for a tool whose schema descriptions cover 0%.

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 0% and the description never mentions the optional 'intent' parameter or how CONNECT/REPAIR/CREATE affect the returned generator families. The description must compensate for the absent schema documentation but does not.

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

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

The description uses a specific verb 'Lists' and a clear resource: 'generator families implemented by the current deterministic core.' It is unambiguous about scope, though it does not explicitly contrast it with any sibling tools.

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 'Lists only...' implies this is the tool to call when an agent needs generator families available in the current deterministic core, but it gives no explicit when-to-use guidance and does not mention alternatives or exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral detail beyond annotations: the resolver is deterministic and its output is either a best supported next action or the minimum missing information.

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, tightly-worded sentence that front-loads the action and directly states the output contract. No filler or redundant restatement of the title or schema.

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?

While the output schema and annotations cover return shape and safety, the description leaves major gaps: parameter meanings are unexplained, the required `description` field is not tied to the resolver behavior, and there is no guidance for choosing this tool over siblings. An agent would need external knowledge to invoke it correctly with rich input.

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 compensate for undocumented parameters. It does not explain `description`, `intent`, `productA`, `productB`, or `relationship`; it only indirectly implies that the problem text is the core input. This is insufficient for a 5-parameter tool.

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 action ('runs the deterministic problem-first resolver') and the resource ('physical-part problem'), and it says what is returned ('best supported next action or the minimum missing information'). It does not explicitly contrast with sibling tools, but the resolver framing distinguishes it from lookup/get-style 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?

The phrase 'problem-first' implies this tool is for describing a physical-part problem and getting a next action, but the description gives no explicit when-to-use or when-not-to-use guidance and does not mention alternatives like get_fit_guidance or get_compatibility. Usage context is only implied.

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 read-only, idempotent, non-destructive safety, so the bar is lower. The description adds valuable behavioral context: 'verified local' and 'without inventing identities' assure the agent that results are grounded and won't be fabricated. No contradiction with annotations.

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

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

A single, front-loaded sentence with no filler. Every word contributes a distinct piece of meaning—scope, data quality, and behavior—making it appropriately concise and well structured.

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 two-param search tool with a full output schema and safety annotations, the description covers the essential scope and truthfulness guarantee. Minor gaps: no explicit query syntax and no cue to pair it with get_product/product details, but those do not block correct invocation.

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 compensate for undocumented parameters. It implies query targets a product/part-type index, but does not explain query format, accepted values, or the limit parameter at all. This leaves the agent with minimal guidance on how to formulate the input.

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 ('Searches') and resource ('verified local product and part-type index'), with a distinctive qualifier ('without inventing identities') that separates it from a generic search or a retrieval tool like get_product. An agent can immediately tell what it does and how it differs from hallucination-prone search.

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 the tool for finding parts by query against a local index, but it never explicitly positions it against siblings such as get_product, get_cocompatibility, or resolve_problem. Without exclusions or alternatives, usage is inferred rather than stated.

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