Whatic IC Datasheets

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

With no annotations, the description carries full burden. It discloses the ranking is from a distributor snapshot (not live) and requires at least two parts with prices for a verdict. This is helpful but could be expanded to mention data freshness or error handling for unmatched parts.

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, well-structured sentence that front-loads the key output dimensions (price tier, stock posture, library class) and includes the important caveat about not being a live quote. It is concise without omitting critical 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?

Given the tool's complexity (one parameter, simple input), the presence of an output schema (so return values need not be described), and the description covering what the tool does and its constraints, the description is sufficiently complete for an agent to understand its purpose and usage.

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%, with the 'parts' parameter clearly documented as requiring two or more IC part numbers and needing at least two priced parts. The tool description adds no additional parameter details, so it meets the baseline for parameter semantics.

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 clearly states the tool returns a relative ranking of IC part numbers across price tier, stock posture, and library class from a distributor snapshot. The verb 'compare' is implied by the name and context, and it distinguishes from sibling tools like find_parts or get_specs. However, it could explicitly state 'compares' to be more direct.

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 specifies that the ranking is not a live quote, implying it should not be used when real-time pricing is needed. However, it does not explicitly state when to use this tool versus alternatives like find_parts or get_specs, leaving some ambiguity.

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

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

No annotations are provided, so the description bears the full burden. It discloses that results are ranked by constraint satisfaction and returns per-constraint pass/fail/unknown, but does not state whether the tool is read-only, idempotent, or has any side effects. This is partially transparent but leaves gaps.

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 constraint format. The long canonical list is necessary for correctness and could be considered a resource, but it makes the description verbose. Overall, it is well-structured and every sentence serves a purpose.

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 complexity (parametric search with constraints) and the presence of an output schema, the description sufficiently covers input requirements, ranking, and result details. It does not mention pagination or error handling, but these are inferable from the simple interface.

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

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

The description adds significant value beyond the input schema: it provides the exact list of allowed canonical names, explains that unit is informational only, and describes the ranking behavior. With 100% schema coverage, the description enriches understanding of each parameter substantially.

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 it shortlists IC part numbers by parametric spec constraints, ranking by how many constraints are satisfied. This distinguishes it from sibling tools like 'search' (text lookup) and 'compare_parts' (comparison), making 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 explains that constraints must use exact canonical names and specifies the ranking logic, giving clear context for when to use this tool. However, it lacks explicit guidance on when not to use it or when alternatives like 'search' or 'compare_parts' are more appropriate.

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

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

No annotations are provided, so the description must disclose behavioral traits. It only describes the core function without mentioning side effects, idempotency, authentication requirements, or error handling. This leaves the agent unaware of critical behavioral aspects for a tool that likely performs a data retrieval operation.

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

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

The description is a single, concise sentence with no redundant text. It front-loads the action and resource, maximizing clarity in minimal space.

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 tool with one parameter and an output schema to describe return values, the description adequately states its purpose. It could mention what happens with invalid refs, but overall completeness is sufficient for this complexity.

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% with a well-described parameter. The description adds minimal value beyond the schema by reiterating that refs are from 'search/lookup'. It provides context but no new semantic details about format or constraints, so 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 clearly states the tool's action: 'Expand opaque `ref` tokens into full datasheet segment content.' This includes a specific verb ('expand') and resource ('ref tokens into full datasheet segment content'), distinguishing it from siblings like search (which generates refs) and get_image/get_specs (which retrieve other data types).

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 context by stating refs come 'from search/lookup', indicating this tool is used after those operations. It does not explicitly exclude other uses or compare to alternatives, but the context is clear enough for an agent to infer when to invoke it.

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

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

No annotations are present, so the description carries the full burden. It discloses that non-image segments return an error record, but does not address authorization, rate limits, or side effects. The behavior is mostly transparent but lacks depth.

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 three sentences, front-loaded with the primary action, and each sentence adds necessary detail without redundancy. No wasted words; it is efficient and easy to parse.

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 lack of output schema, the description explains the return structure (image, caption, description, page metadata) and constraints. It covers prerequisites and error cases. While it could mention limits on the number of refs, the description is largely complete for this simple tool.

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

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

The input schema already describes the parameter 'refs' with 100% coverage. The description reinforces that refs are opaque tokens from specific tools and that only image segments are valid. This adds marginal value beyond the schema, so the baseline score of 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 clearly states the tool fetches datasheet figure images (PNG/JPEG) for opaque ref tokens. It distinguishes from sibling tools like 'get' or 'search' by specifying that only image segments have image data, and it details what is returned (image, caption, description, page metadata).

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: after obtaining ref tokens from search/lookup/get, and only for image segments. It does not explicitly state alternatives or when not to use, but the context of sibling tools and the mention of error for non-image segments provides clear 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?

No annotations are provided, so the description carries the full burden. It states 'read' indicating read-only, and outlines output content. However, it lacks details on error handling, data freshness, or behavior for unknown part numbers. Additional transparency would improve trust.

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, each serving a distinct purpose: first defines the core action, second specifies optional filtering. No wasted words. Front-loaded with key 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?

Given the presence of an output schema, the description does not need to detail return values. It adequately covers input and what the tool produces. It could mention handling of missing parts, but overall complete for a read tool with 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 100%, but the description adds significant meaning: 'optionally restrict to specific canonical parameter names' for the canonicals param, and explains family fallback for part_numbers. This goes beyond the 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?

The description uses a specific verb ('read'), identifies the resource ('canonical extracted specs' for IC part numbers), and details what is included (min/typ/max, unit, conditions). This clearly distinguishes it from siblings like compare_parts or find_parts.

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 when retrieving canonical specs for IC part numbers. It mentions optional filtering but does not explicitly state when not to use or offer alternatives. Context from sibling names helps, but exclusions are missing.

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

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

No annotations provided, so description carries full burden. It discloses that the tool returns full content of relevant segments, is one-shot, and groups by part. No mention of mutability, but retrieval nature is clear.

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, 34 words, front-loaded with purpose. No extraneous information. Highly 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 retrieval tool with output schema, description covers purpose, usage guidance, parameter roles, and distinguishes from siblings. Complete given context signals.

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%, but description adds context: groups results via 'parts', gives query example, and explains the combined search+get nature, enhancing parameter understanding.

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?

Clearly states verb (retrieve) and resource (datasheet segments), distinguishes from 'search' by noting it groups per part and is a one-shot retrieval combining search+get.

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 advises preferring 'lookup' over 'search' when part numbers are known, with rationale about result grouping. Clearly frames usage context vs sibling.

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?

Despite no annotations, the description covers behavior by explaining return format (hit records with ref), how to use ref with `get`, and the role of scope to avoid cross-part contamination. Lacks details on pagination or error handling but sufficient for typical use.

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 no redundancy: first states purpose and return, second links to sibling, third gives specific usage. Every sentence adds value.

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 complexity (3 params, output schema exists), the description covers purpose, return structure, linking to sibling, and parameter usage. Adequate for an AI agent to select and invoke 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 covers all parameter descriptions (100%), so baseline is 3. The description adds value by explaining the `ref` concept linking to `get` and giving a concrete scope example, enhancing understanding 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?

Clearly states the tool searches the datasheet corpus and returns hit records with metadata and an opaque `ref`. Distinguishes itself from sibling `get` by explaining that `ref` lists can be passed to `get` for full 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?

Provides explicit guidance on using the `scope` parameter for part-specific queries with a concrete example. Also hints at when to use `get` for full content. However, does not explicitly mention when not to use this tool.

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