DatasheetVend

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

Goes well beyond annotations: discloses per-module credit costs, that the twin is not saved (stored=false, dashboard won't find it), repeat calls re-extract and re-bill, rescued_features behavior, and that unextractable modules cost nothing. This is rich behavioral context an agent needs and annotations don't provide.

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?

Front-loaded with the core action and the 'not saved / re-bills' warning, and dense with useful detail. It is long and somewhat run-on in the credit enumeration, but nearly every sentence carries actionable 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?

With an output schema present, the description needn't explain returns, yet it still summarizes the extraction block and checks. Combined with billing and non-persistence disclosures, an agent has everything needed to 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 coverage is 100%, so baseline is 3; the description adds real value by mapping module names to credit costs and explaining max_facts/truncated and only_passed semantics. It adds meaning beyond the schema without fully restating each 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 and resource ('Extract a datasheet... return its Unified Component Model (UCM) digital twin in one call') and explicitly positions it against the sibling datasheetvend_get_component_twin. An agent can tell it produces a one-shot twin versus reading a stored one.

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?

Clear context: use modules to pick what to extract, omit for all; use get_component_twin to read a stored twin instead. It doesn't explicitly route against the many datasheetvend_extract_* siblings (e.g., when to use this instead of calling extract_pinout individually), leaving some inference.

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?

Beyond annotations, the description discloses substantial operational behavior: Fast Extraction routing, fallback to the deep monolith_rescue engine, engine naming in results, billing as delivered, a recommended 10-minute client timeout, and FAILED status only when both engines fail. This is rich and actionable context for an agent.

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 purpose and then provides operational details, each of which adds useful behavioral context. It is dense and could be structured more cleanly, but it does not waste sentences on repetition of schema or annotations.

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 and rich annotations, the description covers what the agent needs to know about execution behavior, fallback, timing, and failure. It does not need to explain return values because the output schema exists.

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%, so both partName and documentPath are already documented in the schema. The description adds no additional semantics about these parameters beyond what the schema provides, making 3 the appropriate baseline.

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 pair: decode ordering nomenclature, including per-position suffix meanings and an enumerated orderable_part_numbers list. It is clear what the tool does, but it does not explicitly differentiate itself from sibling extraction tools such as datasheetvend_extract_absolute_max or datasheetvend_extract_pinout.

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 what the tool produces and how the engines behave, but it does not say when to use this tool versus sibling extraction tools. There are no explicit when-to-use, when-not-to-use, or alternative-tool statements.

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?

Goes well beyond the readOnly/idempotent/openWorld annotations: it names the engine used, explains the Fast Extraction pipeline, discloses the automatic fallback to the slower deep engine (engine.runtime = monolith_rescue), warns that a rescue can take minutes and advises a 10-minute client timeout, and states the exact FAILED condition with billing implications. That is exactly the latency, cost and failure-mode context annotations cannot 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?

The purpose and the sibling distinction are front-loaded in the first two sentences, and the operational detail follows in a logical order. The middle passage is dense and semicolon-chained, and phrases like 'the same normalization and completion checks as a dashboard job' are padding, but nothing is redundant or misordered.

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 an output schema, full annotation coverage and 100% parameter documentation, the description fills the remaining gaps an agent needs: what the extraction contains, latency expectations, timeout guidance, fallback behavior, and terminal failure semantics. Nothing material is missing for 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?

The description says nothing about documentPath or partName; both are fully documented in the schema, including the https-only restriction and the multi-part disambiguation role. With 100% schema description coverage, the schema does the work and the 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 (Extract) and resource (Absolute Maximum Ratings) and immediately enumerates the contents: never-exceed supply/pin voltages, max currents, storage temperatures. It also explicitly distinguishes itself from the sibling extract_logic_levels, so an agent can pick between them without opening either 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?

Explicitly routes the agent away from this tool for operating supply ranges and names extract_logic_levels as the alternative, which is strong when-to-use guidance. The gap is that it never mentions the closely related sibling extract_thermal_limits, leaving a plausible source of confusion (stress temperatures vs. thermal limits) unresolved.

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, openWorld, so the safety profile is covered. The description adds real context beyond them: deterministic, no model call, and the accepted input format. It omits failure behavior (e.g. what happens on a binary file) and any size/rate limits, keeping it short of a 5.

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, front-loaded with the action and extraction scope, then the non-goal and the determinism note. Dense but every clause carries information; the parenthetical asides add a little clutter.

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 an output schema present, return values need not be explained, and the description still names the payload components. It covers input format, scope, non-goal, and determinism — enough for correct invocation; only error/edge-case handling is left implicit.

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%, so baseline is 3. The description's format constraint ('a text file — NOT a binary .PcbLib/.SchLib') reiterates what the documentPath schema already states, and partName is not mentioned at all in the description text.

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 ('Parse an Altium Designer ASCII footprint export') and enumerates exactly what is extracted (footprint name, pad geometry, layer map, review verdict). It explicitly excludes binary .PcbLib/.SchLib and the build-from-PDF sibling, so an agent can separate it from datasheetvend_extract_kicad_* and the Altium build path.

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 clear condition ('This reads an EXISTING Altium file; it does not build one from a datasheet PDF') and names the alternative for the build case ('Altium Assist output pack on a completed extraction job'), though that alternative is not a literal sibling tool name. The when-not is explicit; the when-to-use is implied by 'existing Altium ASCII export'.

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 behavior, and the description adds substantial operational context beyond them: Fast Extraction routing, deterministic readers, rescue fallback via `monolith_rescue`, billing as delivered, a 10-minute client timeout, and FAILED status if both engines fail. This is exactly the kind of behavioral disclosure an agent needs before invoking a potentially slow extraction.

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 extracted specification categories, followed by operational details about Fast Extraction and rescue behavior. It is dense and somewhat long, but nearly every sentence carries useful selection or invocation 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 an output schema, rich annotations, and a two-parameter input schema, the description is complete: it covers what is extracted, fallback behavior, timeout expectations, and failure semantics. An agent has enough context to invoke and interpret the tool 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 100%, so both `documentPath` and `partName` are already documented in the schema. The description does not add input-syntax or parameter-level meaning beyond that, so the baseline 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?

Starts with a specific verb and resource: 'Extract analog conversion and signal-conditioning specs.' It then enumerates the exact analog data domains (ADC/DAC, op-amps, VREF, comparators), which clearly distinguishes it from sibling extraction tools such as power, timing, and pinout extractors.

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 analog-domain scope clearly indicates when this tool is appropriate versus the sibling extractors, but it does not explicitly state when not to use it or name a preferred alternative. Usage is strongly implied by the enumerated spec categories rather than phrased as direct routing 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?

Annotations already declare readOnly/idempotent/destructive=false, and the description adds substantive behavior beyond them: deterministic with no LLM, SHA-256 keyed caching for repeat calls, physical 1-based page numbering versus printed labels, and a review.required/warnings degradation path. It also describes the { contractVersion, documentRef, review, map } envelope and where total page count lives.

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 critical routing instruction is front-loaded and the anatomy vocabulary plus output paths are enumerated compactly. It is dense and runs long with parentheticals and a warning clause, but nearly every sentence carries operational information rather than restating the name.

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-parameter indexing tool with an output schema and full annotations, the description covers determinism, caching, output envelope, page-count semantics, primary-page unreliability, and degraded-map handling. Nothing needed to call it correctly or interpret the result 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 single documentPath parameter is fully documented in the schema, including the https-only constraint for the remote endpoint. The description adds no syntax or format detail about the parameter itself; its extra clarification concerns output page numbering rather than the input. 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 — 'Build the Document Map of a datasheet PDF' — and enumerates exactly what the map contains (topic locations plus per-page physical form and geometry census). It is unmistakable against siblings like extract_pinout or inspect_document_page.

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 explicit ordering ('USE IT FIRST, before reading any page'), an explicit exclusion ('Do NOT use it to get pin names, dimensions, or ratings — use datasheetvend_extract_pinout'), and a follow-on routing rule ('pick your tool per page from anatomy.dominant_form'). When-to-use, when-not, and alternatives are all present.

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?

Goes well beyond the readOnly/idempotent/openWorld annotations: it discloses that kicad-cli loading is a file-format check and explicitly not a DRC/ERC, that the same deterministic copper/courtyard/pin-1/pad checks as the dashboard apply, and what each of the three bundle_status values means, including provenance fallbacks (KiCad library, JEDEC/IPC-7351B). It also states credits are refunded automatically on cannot_extract, which is a substantive billing behavior an agent must know.

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?

Front-loaded with the core action, then dense status semantics with no filler sentences. The final sentence is long and parenthetical-heavy, which costs a little readability, but every clause carries 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?

An output schema exists, so return values need not be enumerated, yet the description still explains the outcome taxonomy (completed / needs_review / cannot_extract) and the provenance fields an agent must inspect to judge trustworthiness. Nothing needed to invoke or interpret a call 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?

All three parameters are fully documented at the schema level (100% coverage), including the https-only restriction and the stdio-mode exception. The description adds no additional meaning about partName, packageSelection, or how they interact with provenance selection, so the 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?

The first sentence names a specific verb ("Generate"), both concrete artifacts (.kicad_mod and .kicad_sym), the source (a datasheet), and the bundling scope ("in one call"). That scope distinguishes it from the single-artifact siblings datasheetvend_extract_kicad_footprint and datasheetvend_extract_kicad_symbol without ambiguity.

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 "in one call" implies this replaces making two separate calls, and the bundle_status semantics tell the agent how to interpret outcomes. However, the description never explicitly names the footprint-only or symbol-only siblings as alternatives, nor states a condition for choosing this over them.

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?

Goes well beyond the annotations: it states the land-pattern strategy (datasheet-recommended pattern preferred, otherwise IPC-7351B fillet math) and explicitly bounds the kicad-cli (sym/fp upgrade) check as a file-format check, not DRC or ERC. It also defines what 'completed' versus 'needs_review' mean and warns that a needs_review file may come from a library or generic math rather than this document - exactly the caveats an agent needs before trusting the output.

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?

Front-loads the action and artifact, and the dense later sentences about status semantics genuinely earn their place. The prose is somewhat run-on with nested quoted literals, which slightly reduces scanability but not information density.

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 an output schema present, return shape need not be restated, and the description instead supplies the status/provenance semantics that matter for judging the result. The missing piece is routing guidance relative to the sibling kicad_bundle and kicad_symbol extraction tools.

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 documentPath, partName and packageSelection each documented, so the baseline is 3. The description adds the conceptual source ('the datasheet's package mechanical drawing') but no field-level guidance such as how packageSelection interacts with partName for variant disambiguation.

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?

A specific verb and artifact: 'Write a KiCad PCB footprint (.kicad_mod) from a datasheet's package mechanical drawing,' followed by the contents it covers (pad geometry, pitch, thermal tabs, courtyard). The extension makes it distinguishable from datasheetvend_extract_kicad_symbol in practice, but no sibling is named, so mapping to extract_kicad_bundle versus this tool 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?

Usage is only implied by the artifact type; there is no explicit 'use this instead of extract_kicad_bundle' or prerequisite statement about which document must be mapped first. The detailed guidance that is present concerns interpreting bundle_status and footprint_provenance after the call, not when to choose this tool.

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?

With annotations already covering readOnly/destructive/idempotent/openWorld, the description adds real context: pin groupings are derived from resolved pin functions, no IEEE/IEC drawing standard is applied, and the output is validated only via kicad-cli 'sym upgrade' as a file-format check, not DRC/ERC. One residual tension: the leading verb 'Write a ... library' implies file emission while readOnlyHint=true, and the description never clarifies whether a file is written server-side or content 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?

Three dense sentences with zero padding: artifact and groupings first, generation source second, validation caveat last. Every sentence carries distinct information an 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?

An output schema exists and the safety profile is annotated, so the description only needs to carry generation semantics and caveats, which it does. The one missing piece is the write-vs-return behavior of the emitted file, which matters given the 'Write' phrasing against a readOnly hint.

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% (documentPath URL/local-path distinction, optional partName and packageSelection are fully documented in the schema), so the schema does the heavy lifting. The description adds no parameter-level meaning, which is acceptable at this coverage level but earns only the baseline.

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 artifact: emit a KiCad .kicad_sym symbol library from a datasheet pinout, with named logical pin groupings. The scope is unambiguous against generic extraction siblings, but it never names the closely related datasheetvend_extract_kicad_footprint or datasheetvend_extract_kicad_bundle, so a caller must infer which KiCad artifact it wants.

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: 'generated from the pin functions the pinout module resolved' hints that extract_pinout should run first, and the 'no IEEE/IEC standard applied' note hints this is a functional rather than standards-grade symbol. There is no explicit when-to-use / when-not-to-use statement or comparison to the footprint and bundle siblings.

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 the safety profile is covered, and the description goes well beyond by disclosing the two-stage engine (Fast Extraction scout + deterministic readers, then deep-engine rescue), that `engine.runtime` becomes `monolith_rescue` on rescue, that a rescue is billed as delivered, and that a rescue may take minutes. It also states the terminal failure mode (status FAILED with reason), which annotations cannot 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?

The core extraction scope and the sibling disambiguation are front-loaded in the first two sentences, and the operational detail that follows is genuinely actionable rather than filler. It is dense but runs long on pipeline internals, which slightly dilutes the opening.

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 read-only extraction tool with an output schema and full annotation coverage, the description supplies everything else an agent needs: what is extracted, when to choose it over the never-exceed sibling, the engine fallback path, billing implications, the recommended 10-minute client timeout, and the FAILED outcome. Return-value shape is correctly left to the 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 description coverage is 100% and both parameters (documentPath, partName) are documented in the schema, including the https-only constraint, so the description need not repeat them and does not. It adds no syntax or format meaning beyond the schema, which is the expected baseline when the schema does the work.

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 ('Extract DC electrical characteristics') and enumerates exactly which quantities are returned: VIH/VIL/VOH/VOL thresholds, Schmitt hysteresis, and the VCC/VDD supply range. It explicitly contrasts itself with the sibling extract_absolute_max, so an agent can route between the two without opening either 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?

Gives a clear selection rule: 'Use this for supply-range questions; extract_absolute_max gives never-exceed limits,' which is exactly the disambiguation an agent needs against the closest sibling. It does not address other plausible neighbors such as extract_power_domains or extract_analog_specs, so the routing guidance is strong but not exhaustive.

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/openWorld), and the description piles on genuinely non-obvious behavior: Fast Extraction routes page scout + deterministic readers, the deep engine may re-run a module as `monolith_rescue` and is billed as delivered, rescues can take minutes, and only a double failure yields status FAILED. That is exactly the kind of cost/latency/failure-mode context an agent cannot get from 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?

Purpose and the extract_pinout routing come first, then engine/timeout/failure details, which is the right order. The engine paragraph is long but every clause carries decision-relevant information (latency, billing, timeout, failure status); only mild tightening would improve it.

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 an output schema present, the description needn't explain return values, and it covers what the schema cannot: extraction depth, fallback path, latency expectations, billing, and terminal failure semantics. Nothing an agent needs in order to call this correctly 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 description coverage is 100% and both parameters (documentPath, partName) are already well documented in the schema, including the https-only vs local-stdio distinction. The description adds no parameter-level meaning beyond that, so the 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 ('Extract') plus a concrete resource list — package outline dimensions D, E, A, A1, e, L, b — and a nominal IPC-7351B-style land geometry estimate, with an explicit caveat that it is review-level, not a manufacturer land pattern. It also distinguishes itself from the sibling extract_pinout by scope, so an agent can route between them without opening either 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?

Names the alternative explicitly ('For the package variant/pin count from the pin table, prefer extract_pinout'), giving a concrete condition that selects the sibling over this tool. It also gives operational guidance (set a 10-minute client timeout due to rescue). It stops short of a full when-not-to-use statement for the dimensions case itself, so a 4 rather than a 5.

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 only cover readOnly/idempotent/openWorld, so the description carries the interesting behavior: page-scout Fast Extraction, automatic fallback to a slower deep engine ('monolith_rescue'), a several-minute worst case with an explicit 10-minute client timeout recommendation, billing as delivered, and FAILED status with reason on double failure. This is exactly the operational context an agent cannot infer from structured fields.

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?

Front-loaded with the extraction target before any engine mechanics, and every clause about fallback/timeout/billing carries actionable information. It is dense and long, but not padded; a slightly tighter split of the engine paragraph would make it a 5.

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 an output schema present, the description needn't explain return values, and it still adds the non-schema-visible semantics of `engine`/`engine.runtime` and the FAILED path. Combined with the timeout warning, an agent has everything needed to call it correctly and wait appropriately.

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% (both documentPath and partName are documented in-schema), so baseline 3 applies. The description adds nothing about either parameter, though it does mention the `engine` field, which is a result field rather than an 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 and resource ('Extract the recommended passive support components') and enumerates exactly what is returned: decoupling/bypass caps, crystal load caps, pull-up/down resistors with values and connected pins. That enumeration distinguishes it from siblings like extract_pinout or extract_power_domains without needing to name them.

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 use case (you want a passive support BOM from a datasheet) but never states when to choose this over sibling extractors such as extract_pinout or extract_peripheral_matrix, nor any prerequisites. The only conditional guidance given is about internal engine fallback, not tool selection.

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 cover read-only/idempotent/open-world, and the description adds genuinely non-derivable behavior: a Fast Extraction pipeline with page-scout routing, an `engine` field on every result, an automatic monolith_rescue fallback that is slower and billed as delivered, a recommended 10-minute client timeout, and FAILED status only after both engines fail. That is exactly the operational context annotations cannot carry.

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?

Front-loaded with the verb and resource, then the class inventory, then routing, then runtime semantics. The 13-class enumeration is long but earns its place by defining scope; the pipeline paragraph is slightly verbose but conveys fallback and timeout facts 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 an output schema present, return values need no explanation, and the description still covers scope, exclusions, latency expectations, fallback behavior, and failure signaling. Nothing an agent needs in order to call this correctly and set an appropriate timeout 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 both parameters (documentPath, partName) are fully documented in the schema, including the https-only constraint for the remote endpoint. The description adds no parameter-level detail of its own, 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+resource ('Extract the on-chip peripheral inventory, one row per instance') and enumerates the 13 covered classes, so the agent knows exactly what comes back. It also names the sibling tools that handle adjacent data (analog_specs, power_domains), so the boundary is 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?

Explicitly routes the two likely-confused cases elsewhere: ADC/DAC/comparator electrical specs to datasheetvend_extract_analog_specs, and per-mode current / wakeup timing / reset thresholds to datasheetvend_extract_power_domains. Every exclusion names the condition that selects the alternative.

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?

Beyond the readOnly/idempotent annotations, the description discloses the full execution model: a page scout routing targeted model reads plus deterministic readers, seconds-scale completion, `engine` naming on every result, a deep-engine rescue path flagged as `monolith_rescue`, that rescue gets billed as delivered, and a recommended 10-minute client timeout. It also states the terminal failure mode (status FAILED with reason), which is exactly the operational context an agent needs to set timeouts and handle errors.

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?

Purpose is front-loaded, but the opening sentence is a long and-chained enumeration and the engine paragraph carries implementation detail ("page scout routes targeted model reads and the module's own deterministic readers, then the same normalization and completion checks as a dashboard job") that could be compressed. The timeout and billing facts earn their place; the pipeline internals are close to filler.

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 an output schema present, the description need not explain return values, yet it still highlights provenance fields (source_page, source_text_snippet, bounding-box evidence in PDF points and normalized 0..1000 space) that matter for auditability. Combined with explicit latency, rescue, billing, and failure behavior, an agent has everything needed to call this correctly and set expectations.

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 both parameters (documentPath, partName) are documented in the schema itself, including the https-only constraint and local-stdio caveat. The description adds nothing about parameter handling, so the baseline 3 applies; the source_page/snippet/bbox text describes output fields, not inputs.

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 ("Extract") and a well-scoped resource ("hardware design cautions") and enumerates the exact sub-categories covered: bootstrap/mode strapping, 5V-tolerant boundaries, NRST/SWD precautions, crystal guardrails, VDDA/VBAT isolation, reserved-pin handling. That enumeration implicitly separates it from siblings like extract_pinout or extract_logic_levels, but no sibling is named, so the differentiation is inferential rather than explicit.

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 context is only implied by the content list; there is no statement of when to reach for this tool versus extract_pinout, extract_power_domains, or extract_logic_levels. The fallback narrative explains what happens when extraction fails, which is runtime guidance rather than tool-selection 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?

Annotations already cover the safety profile (readOnly/idempotent/non-destructive), yet the description adds substantial context beyond them: the review-state flag and when it triggers, engine naming on every result, the Fast Extraction → monolith_rescue fallback with a concrete 10-minute client-timeout requirement, and the error path when both engines fail. That is exactly the runtime-behavior disclosure annotations cannot express.

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?

Front-loaded with the outcome and the differentiators, and every sentence carries operational weight (routing, trust-the-review-flag, timeout). It is a single dense block where the package-resolution detail and the sibling exclusions slightly overlap, which keeps it from a 5.

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?

An output schema exists, so return-value description is not required, yet the description still names the contract (pinout_evidence_v1) and the key fields plus the review-state semantics. Failure modes, fallback behavior, and timing expectations are all covered for a multi-minute-capable extraction 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 description coverage is 100%, so the schema already documents documentPath (https-only vs local stdio), partName (disambiguation), and packageSelection. The description does add interpretive value by explaining that the package is resolved from the terminals and can be cross-checked against the package drawing, which reframes packageSelection as an override for multi-package datasheets rather than a required input. With full schema coverage this is at minimum a solid 3, and the added framing lifts it.

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 and resource: extracts a component's pin/pad table from a datasheet PDF as a PinoutEvidence document, and explicitly states it also resolves package family/variant/pin_count. That second capability is called out as a distinguishing purpose, which lets an agent separate it from extract_package_dimensions and decode_part_number without opening schemas.

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?

Explicit routing: use for package-variant and pin-count questions, not extract_package_dimensions (mechanical geometry) or decode_part_number (ordering codes), and 'Prefer this over reading the PDF yourself.' It also tells the agent to trust review.required before acting, which is a usage rule rather than a description of behavior.

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 cover only the safety profile, and the description adds substantial behavior beyond them: the engine name is returned on every result, a failed Fast Extraction triggers a slower 'monolith_rescue' re-run that is still billed, the call can take several minutes requiring a 10-minute client timeout, and FAILED status only occurs after both engines fail. This is exactly the cost/latency/fallback information an agent cannot get from structured fields.

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 dense sentences, front-loaded with the extracted content before the engine/latency details. Every sentence carries operational information, though the engine-rescue passage is long enough that a short bulleted structure would have been easier to scan.

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 an output schema present, return values needn't be explained, and the description still covers the two things an agent most needs: the engine field on results and the failure/timeout semantics. Nothing required to invoke or interpret the call correctly 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 description coverage is 100%, and the schema itself explains partName disambiguation and the https-only documentPath restriction. The description adds no parameter-level detail, 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?

The description opens with a specific verb ('Extract') and enumerates the exact resource set: power domains (VDD/VDDA/VBAT), low-power/sleep modes with consumption, and battery-backup configuration. That field list is clearly distinct from siblings like extract_thermal_limits or extract_absolute_max, though it never explicitly names an alternative tool to contrast against.

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 documents the operational flow (Fast Extraction, fallback to deep engine, 10-minute client timeout) but gives no guidance on when an agent should choose this tool versus a related sibling such as build_component_twin or extract_peripheral_matrix. Usage context is implied by the extracted content rather than 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, open-world), and the description still adds substantial behavior: which engine produced the result is surfaced via `engine`, a slow `monolith_rescue` fallback may re-run a module and is billed, a 10-minute client timeout is advised, and only double failure yields status FAILED. That is exactly the context annotations cannot 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?

The payload is front-loaded: purpose and returned fields come first, operational caveats after. It is dense but each clause carries decision-relevant information (timeout, billing, failure mode); the Fast Extraction internals (page scout, deterministic readers) are the one stretch an agent does not strictly need.

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?

An output schema exists, so return values need no explanation; the description instead covers the operational envelope — engine routing, rescue latency, timeout guidance, failure semantics — which is precisely what an agent needs to invoke this correctly and to avoid premature timeouts.

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 both parameters carry meaningful descriptions (including the https-only vs stdio path distinction), so the schema does the heavy lifting. The description adds no parameter-level detail of its own, making the baseline 3 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 first sentence gives a specific verb plus resource (extract the register map) and enumerates the exact contents returned: memory addresses, reset values, RO/RW/W1C access permissions, and per-bit field definitions. That enumeration distinguishes it from adjacent extract_* siblings such as extract_peripheral_matrix or extract_pinout, so an agent can choose without opening the 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 description explains the execution model (Fast Extraction, fallback to deep engine) but never states when to reach for this tool versus sibling extractors, nor any prerequisites beyond the schema's URL note. Usage is implied by the content enumeration rather than stated as an explicit selection rule.

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?

Goes well beyond the readOnly/idempotent annotations: it explains the Fast Extraction pipeline (page scout, model reads, deterministic readers), the fallback to the deep engine with engine.runtime = 'monolith_rescue', that rescue runs can take minutes and how they are billed, and that only a double failure yields status FAILED. This is exactly the latency/failure-mode information an agent needs.

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?

Front-loaded with the extracted fields, then the execution semantics. It is somewhat long and dense around the rescue engine, but every sentence carries actionable information (timeout, billing, failure status) rather than filler.

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 an output schema present, the description needn't detail return values, and it still covers provenance (datasheet page), engine labeling, timing expectations, and terminal failure behavior. Nothing an agent needs to call this correctly 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 both parameters (documentPath, partName) are fully documented in the schema, including the https-only constraint. The description adds no parameter-level meaning, so the 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?

The description opens with a specific verb+resource ('Extract thermal characteristics') and enumerates exactly which quantities are returned (θJA, θJC, power dissipation limits, operating/junction/storage temperature ranges). That field list implicitly separates it from siblings like extract_absolute_max and extract_power_domains, though those siblings are never named 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?

The description gives operational context (client timeout of 10 minutes, rescue behavior) but never states when to choose this tool over extract_absolute_max, extract_power_domains, or extract_analog_specs. Usage is only implied by the field list.

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 only cover safety (readOnly/idempotent/openWorld), while the description discloses what actually happens: a page scout routing targeted model reads, deterministic readers, engine naming on every result, a slower 'monolith_rescue' engine fallback that is billed as delivered, a recommended 10-minute client timeout, and FAILED status with a reason. This is exactly the operational context annotations cannot carry.

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?

Front-loaded with the extracted field list, then the operational caveats. The engine/rescue/timeout material is long and somewhat dense, but each clause carries actionable information (timeout, failure mode, billing); it is not 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 an output schema present, the description need not explain return structure; it instead covers what remains unknown — runtime engine identity, rescue timing risk, and terminal FAILED behavior. Nothing an agent needs before calling 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 both parameters are already well documented in-schema (including the https-only constraint of the remote endpoint). The description adds no parameter detail beyond the schema, so the 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 ('Extract AC timing') and enumerates the exact quantities produced (tSU/tH, propagation delays, fMAX, rise/fall, bus timing). That field list cleanly separates it from siblings such as extract_absolute_max, extract_analog_specs and extract_logic_levels.

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 enumerated AC parameters make the selection context clear versus DC/absolute-max/analog siblings, and it explains the extraction path taken. It never explicitly names alternatives or says when NOT to use it, so it falls short of a 5.

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?

Goes well beyond the readOnly/idempotent/non-destructive annotations: it discloses the check vocabulary (passed, needs_review, disagrees, failed_sanity_check), instructs that non-passing facts be treated as unverified and cited by page, and states 'never extracts, never bills' so cost/side-effect expectations are explicit. It also notes the max_facts truncation signal in context.

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?

Front-loaded with the core purpose and free of filler, with the scoping/workflow guidance up front where it matters. The middle sentence carrying the check-status list and section taxonomy is long and slightly tangled at 'and checks', but no sentence is disposable.

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 read-only, six-parameter tool with a full output schema, everything an agent needs is present: auth, discovery path, narrowing strategy, how unverified facts must be handled, and the build sibling for the unsupported case. Nothing forces a guess before calling.

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%, so the baseline is 3; the description still adds workflow meaning the schema cannot express — that omitting options yields just the summary, and that a single `pin` or `search` is the way to bound result size. It repeats less than it adds, but the per-parameter semantics themselves are largely left to 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?

States a specific verb and resource — reading the UCM digital twin of one already-extracted datasheet — and enumerates the fact taxonomy (pins, whole_part, interfaces_rails, registers, checks). It explicitly carves itself apart from the extract_* siblings by noting it reads stored results only, and names the build sibling for unextracted 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?

Gives a concrete call sequence: first with no options for the summary, then narrow via `sections`, `pin` or `search` to keep the answer small. It also routes discovery to datasheetvend_list_component_twins and the not-yet-extracted case to datasheetvend_build_component_twin, and states the API key prerequisite.

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 and idempotency, but the description adds substantial context beyond them: cache-served with no billing, never rebuilds, and a payload warning that include_physical can reach hundreds of KB for a dense page. That cost/size disclosure is the kind of thing annotations cannot express. It stops short of describing output structure or failure modes, which is acceptable given an output schema exists.

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, front-loaded with what it returns, then when to call it, then how to call it. No filler; the payload-size caveat is placed exactly where the agent makes the include_physical decision.

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 read-only drill-down with an output schema, all deciding information is present: prerequisite tool, selection criteria, key parameter provenance, and the one optional parameter's cost tradeoff. Nothing needed to invoke it correctly 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%, so the baseline is 3; the description adds real guidance the schema does not, namely that documentRef should be the document.sha256 from a prior map result and that it is served free from cache. It also reinforces include_physical's weight, though some of that duplicates the schema's own 'Heavy — default false' note.

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 ('Tier-2 detail for ONE page of an already-mapped datasheet') and enumerates what is returned: measured anatomy, headings/first lines, and claiming modules. It explicitly positions itself relative to datasheetvend_extract_document_map, so an agent can separate the two without opening a 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?

Gives an explicit sequencing rule ('Use it AFTER datasheetvend_extract_document_map') plus the triggering condition ('when the Tier-1 index says a page matters and its one-line summary is not enough'). It also names the one real decision point, include_physical, and gates it with 'ONLY when you truly need'.

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?

Beyond the readOnly/idempotent annotations, it discloses that it reads stored results only, never extracts, never bills, and requires an API key — cost and auth behavior an agent cannot infer from annotations. It also summarizes what the response contains.

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?

Front-loaded with the core purpose, then behavior, then routing — good ordering. Slightly dense with the embedded UCM definition and return-field listing, but each clause carries usable 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?

With an output schema present and full param coverage, the description covers what remains: scope, cost/read-only behavior, auth requirement, and sibling routing. An agent has everything needed 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 100% (limit and search are fully documented in-schema), so baseline is 3. The description mentions 'how many runs it has and when it was last run' but says nothing about limit or search semantics 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+resource: listing datasheets that have a UCM digital twin, and defines what the twin contains (pins, rails, interfaces, registers, limits). It is clearly separable from datasheetvend_get_component_twin (fetch one) and datasheetvend_build_component_twin (create one).

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 routes: 'Pass a returned name to datasheetvend_get_component_twin' and 'To twin a datasheet the account has not extracted, use datasheetvend_build_component_twin.' Both the next-step alternative and the when-not condition are named.

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, destructiveHint=false, and openWorldHint=false, giving a complete safety profile for a read-only list operation. The description adds the domain list of modules but no additional behavioral traits such as pagination, rate limits, or output structure. Baseline 3 is appropriate given the annotation coverage.

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 text. The parenthetical examples are compact and directly support the purpose of the tool.

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 zero-parameter list tool with an output schema present and annotations that fully describe its safe read-only behavior, the description provides exactly the domain context an agent needs. Return values are handled by the output schema, so no further explanation is required.

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?

This tool takes zero parameters, so there are no parameter semantics for the description to clarify. The baseline of 4 applies because schema and description cover all needed input information by omission.

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 ('List') and resource ('all available hardware extraction modules supported by DatasheetVend'), and then enumerates concrete module categories. There are no sibling tools to distinguish from, and the scope is 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 discovery usage but does not state when to call this tool versus alternatives, nor does it include prerequisites or exclusions. With no sibling tools present, the implied usage is adequate but minimal.

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, non-destructive, closed-world, so safety is covered. The description adds genuinely new behavioral facts: the content is static per contract version, hence the once-per-session call pattern, and it names the categories of guidance returned. It stops short of describing output shape, but an output schema exists.

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, with the purpose and content inventory front-loaded and the calling discipline as the closing clause. Every clause carries actionable 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?

With an output schema, full annotation coverage, and no parameters, the description supplies what structured fields cannot: the prerequisite ordering relative to the extraction tool and the once-per-session caching rule. Slightly jargon-heavy ('measured routing discipline', 'dominant_form action table') but sufficient to decide to call it.

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 tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. It correctly focuses on when and how often to call rather than on inputs.

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 ('Return the versioned usage instructions for Document Map consumers') and enumerates the payload (binding rule, field semantics, dominant_form table, routing discipline). It is clearly distinguishable from the data-producing sibling datasheetvend_extract_document_map, which it names.

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 an explicit precondition and ordering ('Call once per session before working with maps from datasheetvend_extract_document_map') plus an explicit exclusion ('do not call repeatedly'). The alternative and the condition that targets it are both spelled out, leaving nothing to inference.

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