Server Quality Checklist

Tool Scores

• get_specsA
  3.6/5.0
  Behavior3/5

  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 transparently indicates a read operation and describes the nature of the data returned (min/typ/max, unit, conditions). It does not mention error behavior, unknown part numbers, or fallback logic, though the parameter schema does mention family fallback.

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

  Conciseness5/5

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

  Two concise sentences that front-load the core purpose and immediately cover the key optional behavior. No filler or redundant information; every word earns its place.

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

  Completeness4/5

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

  Given the tool's low complexity (2 params, 1 required), full schema coverage, and presence of an output schema, the description is sufficient for an agent to invoke the tool correctly. The only notable omission is explicit guidance on when to prefer this over sibling read tools like lookup or get, but this is a minor gap.

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

  Parameters3/5

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

  Schema description coverage is 100%, with both parameters already well-documented. The description adds only a restatement of the optional canonicals filtering ('Optionally restrict to specific canonical parameter names'), providing no additional semantic value beyond the schema.

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

  Purpose4/5

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

  The description uses a specific verb ('Read') and resource ('canonical extracted specs') for known IC part numbers, clearly identifying the tool's function. It goes beyond the mere name by listing what the specs contain (min/typ/max, unit, conditions). It does not explicitly differentiate from siblings like 'lookup' or 'get', but the domain-specific resource provides enough distinction for most cases.

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

  Usage Guidelines3/5

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

  Usage is implied: call this tool when you need specs for known IC part numbers, and optionally filter by canonical parameter names. There is no explicit when-not-to-use guidance or comparison with sibling tools such as compare_parts or find_parts, leaving some routing ambiguity.

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

• compare_partsA
  3.8/5.0
  Behavior4/5

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

  With no annotations, the description carries the behavioral burden, and it does disclose the key trait: the result is a relative ranking based on a distributor snapshot, not a live quote. This manages expectations about freshness and absolute accuracy. It does not discuss auth or errors, but for a read-only comparison tool the main caveat is present.

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

  Conciseness5/5

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

  One compact sentence delivers the output dimensions first and the important caveat in a parenthetical. There is no filler or repeated schema content; every word earns its place.

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

  Completeness4/5

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

  For a single-parameter tool with a full output schema, the description covers what is compared, what dimensions are returned, and the snapshot/live-quote caveat. It does not explicitly guide selection among siblings like find_parts or get_specs, but the input contract is fully specified in the schema.

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

  Parameters3/5

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

  Schema description coverage is 100%, and the schema already explains that parts must be two or more IC part numbers with at least two priced for a verdict. The description only restates the concept of a set and adds no syntactic or formatting value, so baseline 3 applies.

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

  Purpose4/5

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

  The description names the input resource (a set of IC part numbers) and the outputs (relative price tier, stock posture, library class), making the tool's function recognizable. It lacks an explicit verb and does not differentiate from siblings like get_specs or lookup, 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.

  Usage Guidelines3/5

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

  The phrase 'from a distributor snapshot, not a live quote' gives useful context and an implied exclusion, and the schema adds the requirement of at least two priced parts. However, no alternative sibling tools are named and there is no explicit when-to-use statement, so usage guidance is mostly implied.

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

• find_partsA
  4/5.0
  Behavior4/5

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

  With no annotations, the description carries the behavioral burden. It discloses the ranking criterion, return granularity (per-constraint pass/fail/unknown), and the strict case-sensitive canonical requirement. It does not explain error behavior or the meaning of 'unknown', but the core behavior is transparent.

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

  Conciseness3/5

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

  The opening two sentences are concise and front-loaded with purpose and behavior. However, the description includes a very long canonical-name list that duplicates the schema enum, making the overall description unnecessarily large.

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

  Completeness4/5

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

  The description is mostly complete for a parametric search tool: it explains the constraint model, ranking behavior, and return granularity. Minor gaps like the meaning of 'unknown' and tie-breaking are not blocking for correct invocation.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the baseline is 3. The description adds a compact constraint structure overview and an explicit case-sensitivity warning, but the large canonical list duplicates the schema enum and adds little beyond what the schema already provides.

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

  Purpose5/5

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

  The description states a specific verb ('Shortlist'), a clear resource ('IC part numbers'), and a distinguishing method ('by parametric spec constraints'). This clearly separates it from generic search/lookup sibling tools even without naming them.

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

  Usage Guidelines4/5

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

  It clearly conveys when to use the tool: when the agent wants to filter/shortlist parts by parametric constraints and rank by constraint satisfaction. However, it does not explicitly list when not to use it or name alternatives such as search or lookup.

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

• getA
  4/5.0
  Behavior3/5

  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 discloses that the tool resolves opaque refs into full segment content, implying a non-destructive read/expansion operation. It does not discuss failure behavior, ordering, or permissions, which is a modest gap.

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

  Conciseness5/5

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

  A single sentence front-loads the action, the input origin, and the output type with no filler. Every word contributes to the agent's understanding.

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

  Completeness4/5

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

  With one required parameter, a fully described schema, and an output schema present, the tool is largely complete for a simple ref-expansion operation. The only minor gap is the absence of explicit alternative-tool routing, but the 'from search/lookup' signal already orients the agent.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the refs parameter is already fully documented in the input schema. The tool description essentially restates that information without adding meaningful new semantics beyond the schema.

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

  Purpose5/5

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

  The description names a specific action ('Expand') and resource ('full datasheet segment content'), and clarifies the input tokens come from search/lookup. This clearly differentiates it from siblings like search, lookup, compare_parts, and get_image.

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

  Usage Guidelines4/5

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

  The phrase 'from search/lookup' tells an agent this is the follow-up tool for expanding opaque refs obtained from those operations. It does not explicitly list exclusions or alternatives like get_specs/get_image, but the intended usage context is clear.

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

• get_imageA
  4/5.0
  Behavior4/5

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

  With no annotations, the description carries the burden of behavioral disclosure. It adds useful details beyond the schema: supported formats (PNG/JPEG), return contents (image plus caption/description/page metadata), and a type condition. It doesn't explicitly mention error records, but the schema covers that, and the read-only nature is implied by 'Fetch'.

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

  Conciseness5/5

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

  The description is two focused sentences with no wasted words. The primary action is front-loaded, followed by return details and the critical type limitation. Every sentence earns its place.

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

  Completeness4/5

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

  For a single-parameter tool with no output schema, the description is quite complete: it covers input source, behavior, output contents, and the image-only constraint. The only notable omission is an explicit statement of error behavior for non-image refs, but that is already present in the param schema.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the baseline is 3. The description reinforces the semantics of 'refs' by echoing 'opaque tokens from search/lookup/get' and mentioning the image-segment constraint, but it does not add meaning substantially beyond what the schema already documents.

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

  Purpose4/5

  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: 'Fetch datasheet figure images' for opaque ref tokens. It also specifies the output (image plus caption/description/page metadata) and a key constraint ('Only type='image' segments have image data'). While it doesn't explicitly name sibling tools, the image-specific scope and source of refs effectively distinguish it from likely siblings like get_specs or get.

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

  Usage Guidelines4/5

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

  The description gives clear context for when to use the tool: when you have opaque ref tokens from search/lookup/get and need image data. It also warns that only image-type segments have image data, implying non-image refs are inappropriate. However, it does not explicitly contrast with alternatives or state when to use a different tool.

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

• lookupA
  4.3/5.0
  Behavior4/5

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

  No annotations are present, so the description carries the behavioral burden. It discloses that the tool is a retrieval operation, returns 'full content' rather than snippets, selects the 'most relevant' segments, groups results per part, and fuses search and get behavior. It does not mention errors or edge cases like no matches, but the core behavioral profile is clearly conveyed.

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

  Conciseness5/5

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

  Two dense sentences with no filler. The core behavior is front-loaded, and the usage preference is stated immediately after. Every sentence earns its place.

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

  Completeness5/5

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

  The tool has only two simple parameters, an output schema, and no nested objects. The description covers what it retrieves, how results are grouped, and when it should be chosen over `search`. Nothing essential for invoking it correctly is missing.

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

  Parameters3/5

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

  Schema description coverage is 100%, and both `query` and `parts` already have meaningful descriptions. The tool description only echoes the `parts` grouping behavior already stated in the schema, so it adds little semantic value beyond the input schema.

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

  Purpose5/5

  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: 'One-shot spec/section retrieval: full content of the most relevant datasheet segments.' It also differentiates from siblings by saying it 'fuses search+get' and by naming `search` as the lower-preference alternative when part numbers are known.

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

  Usage Guidelines4/5

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

  It gives explicit guidance: 'prefer `lookup` over `search` when you know the part(s).' This clearly states a primary condition and names a concrete alternative. It does not enumerate exclusions for the other siblings, but the 'when you know the part(s)' condition is enough to route an agent correctly in most cases.

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

• searchA
  4.5/5.0
  Behavior4/5

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

  With no annotations, the description carries the behavioral disclosure burden. It explains the return shape (hit records with metadata + snippet), the opaque nature of `ref`, the relationship to `get`, and how `scope` restricts hits to avoid cross-part contamination. It does not mention error behavior or edge cases, but for a search tool this is solid coverage.

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

  Conciseness5/5

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

  Three sentences, each earning its place: the first states the core action and return format, the second connects to `get`, and the third gives scope usage with a concrete example. The most important information is front-loaded and there is no filler.

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

  Completeness5/5

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

  For a simple search tool with an output schema and full param coverage, the description is complete. It tells the agent what the tool returns, how refs feed into `get`, and how to handle part-specific queries. The only minor gap is not explicitly differentiating from all siblings, but the description still gives enough context for correct invocation.

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

  Parameters4/5

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

  Schema coverage is 100%, so the schema already documents q, k, and scope. The description adds meaningful value by providing a concrete scope example ('device:NE5532'), explaining the purpose of the scope restriction, and clarifying the role of the returned refs. This goes beyond what the raw schema states.

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

  Purpose5/5

  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: 'Search the datasheet corpus'. It also describes what the tool returns (hit records with metadata, snippet, and opaque ref) and explicitly distinguishes itself from `get` by telling the agent to pass refs to `get` for full content. This is unambiguous and differentiates it from at least one sibling.

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

  Usage Guidelines4/5

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

  The description gives clear context for when and how to use the tool: part-specific queries should use scope='device:<MPN>', and after searching, the returned refs should be passed to `get`. It does not explicitly name alternatives like `find_parts` or `lookup`, or state when not to use this tool, so it falls short of a full when/when-not alternative comparison.

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