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

Annotations already declare readOnlyHint and idempotentHint, providing the base safety profile. The description adds valuable context about the reliability of vision-extracted data versus text tables and explains the dependency on image_key from read_datasheet, which are behavioral traits not covered by annotations.

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

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

The description is well-structured: it front-loads the purpose, then provides usage guidance, an important caveat, and examples. It is slightly long but every sentence contributes value, and the formatting with an IMPORTANT section and examples improves scannability.

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 there is no output schema, the description adequately conveys what the tool returns through examples (e.g., classifies and describes the image). It also covers the workflow dependency on read_datasheet and the trade-offs between vision and text extraction, making it sufficiently complete 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?

Schema coverage is 100%, so parameter basics are already documented. The description enhances this with usage examples showing how image_key and question interact, and clarifies that image_key is the storage path from read_datasheet output, adding relational meaning beyond the schema.

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

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

The description clearly states the tool analyzes images from datasheets using vision AI, with a specific verb ('Analyze') and resource (image from a component's datasheet). It distinguishes itself from read_datasheet by specifying it handles visual data like graphs, package drawings, pin diagrams, and circuit schematics.

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 explicitly says when to use this tool (when read_datasheet returns images needing extraction) and when not to use it (for precise numeric values, where read_datasheet text tables are preferred). It names the alternative tool, read_datasheet, and provides concrete examples of appropriate use cases.

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 and destructiveHint=false, so the safety profile is clear. The description adds important behavioral context: two-tier validation (structured vs LLM fallback), potential extraction delay (30s-2min) with polling need, and result semantics (PASS/WARNING/FAIL with margins). This adds significant value beyond the annotations.

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

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

The description is well-structured with clear sections: purpose, parameter mapping, result semantics, behavior, and when not to use. While dense with information, each sentence earns its place. It could be slightly more concise, but the clarity and completeness justify the length.

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

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

Given the tool's complexity (7 parameters, no output schema), the description covers purpose, usage, parameter mapping, behavior, and exclusions. It mentions result semantics and the validation_method field but does not fully describe the response structure. For a tool with no output schema, this is a minor gap; however, the description is otherwise highly complete.

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

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

Schema coverage is 100%, so each parameter already has a description. The description enriches meaning by providing per-component-type parameter mappings (e.g., supply_voltage=VDS for MOSFETs) and clarifying that supply_voltage is only compared against VDS(max), not used for power dissipation. This adds critical context beyond the schema.

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

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

The description clearly states the tool's purpose: 'Validate whether a component will work within your operating conditions' by comparing design parameters against datasheet limits. It provides a specific verb (validate) and resource (design fit), and is distinct from sibling tools like read_datasheet which only read raw data.

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 explicitly states when NOT to use the tool (power dissipation, SOA checks, passive parts) and implicitly suggests alternatives (read_datasheet, analyze_image). It provides an example call and clarifies the tool's scope, giving excellent guidance for appropriate use.

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

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

The description adds rich behavioral context beyond annotations: it is free, includes elapsed seconds and document ID, explains the meaning of every status value, notes that no_source may resolve on retry, and discloses that org-uploaded datasheets are private. This goes well beyond the readOnly/idempotent hints, with no contradictions.

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 purpose and usage, then organized into a clear status-value list. Every sentence provides actionable information; the length is justified by the number of distinct statuses and the need to give follow-up actions for each.

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

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

With no output schema, the description fully compensates by enumerating all possible statuses, typical durations, recommended polling, and next-step actions. It also notes response contents (step, elapsed seconds, document ID, error reason), making it complete for practical use.

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 parameter description already explains MPN requirements. The tool's description adds value by explaining the 'rejected' status as a consequence of invalid inputs, and clarifies that each entry corresponds to a part number, reinforcing the semantics without redundancy.

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

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

The description clearly states the tool checks extraction status of one or more parts, with a specific verb and resource. It distinguishes itself from siblings like prefetch_datasheets and read_datasheet by focusing on status polling and listing terminal states.

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 guidance is given on when to use: after prefetch_datasheets or when read_datasheet triggers extraction. It provides polling cadence, stopping conditions, and specific alternative tools for each non-ready status (e.g., prefetch_datasheets for not_extracted, request/confirm upload for no_source/unsupported).

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

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

The description discloses numerous behavioral traits beyond annotations: uses only cached datasheet summaries (does not trigger extraction), validates all MPNs upfront and rejects the entire call if any is invalid, returns per-part 'error' fields for missing parts while still comparing valid ones. This adds rich context that annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) do not cover.

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 well-structured and front-loaded with purpose, usage, and a clear example. The extended DATASHEET STATUS VALUES section is informative but somewhat long and contains guidance tangential to compare_parts itself (e.g., retry logic, upload instructions). Still, every section earns its place for a complex tool with no output schema.

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

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

With no output schema, the description thoroughly explains return values (merged provider data fields, cached datasheet summary, datasheet_status) and edge cases (invalid MPN rejection, missing provider handling, status meanings). It even provides an example call and covers all possible datasheet_status values, making the tool fully usable without external references.

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?

Even though the schema covers the parameter (100%), the description significantly enriches understanding by providing concrete examples ('TPS54302DDCR', 'C2837938'), explicitly prohibiting values/descriptions/reference designators, and explaining the rejection behavior. It also clarifies LCSC numbers are allowed, which is not obvious from 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?

The description clearly states the specific verb 'Compare' and resource '2-5 electronic components' in a single call, listing the exact outputs (pricing, stock, structured parameters, package, datasheet_status). It distinguishes itself from siblings by explicitly framing it as an alternative to get_part_details in a loop and noting it's not for discovery (unlike search_parts/find_alternative).

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 states when to use this tool instead of get_part_details in a loop (parallel fan-out, merge by MPN), and when NOT to use it (for discovery, use search_parts or find_alternative first). Also gives guidance on prefetch_datasheets for missing summaries. This is textbook usage differentiation.

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 mark this as destructive and not read-only, but the description adds specific behavioral details: it creates private Document + Component records, charges a 50¢ upload fee, and queues extraction. It also discloses token expiry (15 minutes) and which failures incur no charge, going beyond the annotations.

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

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

The description is well-structured: an overview sentence, a success response block, and a failure-mode list. Every sentence provides actionable information without filler, and the bullet-style failure modes are easy to scan. It is appropriately concise for a tool with multiple side effects and error conditions.

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?

Without an output schema, the description fully specifies the success response (document_id, mpn, sha256, file_size_bytes, status) and directs to check_extraction_status for progress. It enumerates all likely failure modes with conditions and remedies, making the tool's behavior completely predictable.

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 schema already describes upload_token as an opaque token from request_datasheet_upload (100% coverage). The description adds practical semantics: the token ties to the uploaded bytes, has a 15-minute expiry, and must be passed as-is, enriching the schema's information.

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

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

The description clearly states the tool confirms a datasheet upload initiated by request_datasheet_upload, specifying the exact verb 'Confirm' and the resource. It also distinguishes this step from the request and check_extraction_status siblings by outlining the subsequent actions (creating records, charging fee, queuing extraction).

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 explicitly places this tool after request_datasheet_upload and instructs to poll check_extraction_status upon success. Each failure mode includes a remediation step (e.g., retry curl upload, re-request, restart via request_datasheet_upload), providing clear next actions and alternatives.

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 mark the tool as read-only/idempotent/non-destructive. The description adds substantial behavioral context: filters out eval boards and dev kits, fuzzy package matching, fallback to semantic search, a 'hint' field, and exhaustive datasheet status handling. No contradiction with annotations.

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

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

The description is long but well-organized with labeled sections and front-loaded core purpose. The datasheet status block is verbose, but it is directly relevant to interpreting returned matches and justifies its length. No filler sentences.

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?

No output schema exists, so the description carries the responsibility of explaining return values. It does so: match_score, match_notes, hint field, and datasheet statuses are all described. It also covers edge cases, fallback behavior, and when not to use the tool, making it self-sufficient.

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 parameters are already documented. The description adds value by explaining fuzzy matching behavior for 'same_package' and showing realistic usage via the constraints example. It does not fully explain 'limit' or 'part_number' beyond what schema provides, but the addition is meaningful.

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 and resource: 'Find alternative / second-source components for a given MPN.' It clearly states what the tool does and distinguishes it from siblings by mentioning search_parts for browsing and compare_parts for direct comparison.

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?

Dedicated 'When to use' and 'When NOT to use' sections explicitly name alternatives (search_parts, compare_parts) and give concrete scenarios (out of stock, cheaper equivalent, drop-in replacement). Even includes a usage example with constraints.

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 state readOnlyHint=true and destructiveHint=false, and the description goes far beyond by explaining prefetch_datasheet behavior, no extra charge, and a complete datasheet status lifecycle with recommended polling intervals and retry actions. This adds significant context about asynchronous behavior and error handling without contradicting the annotations.

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

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

The description is long but well-structured: a clear opening summary, usage guidance, and a detailed datasheet status section formatted as a list. Every status value earns its place because it informs actionable next steps, though a few redundant phrases like 'extraction running or scheduled' could have been trimmed.

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

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

Given the tool's complexity (multiple statuses, background extraction, provider options) and no output schema, the description is comprehensive. It covers what the tool does, what it returns, how to handle each datasheet state, and pointers to related tools for additional actions, making it self-sufficient for an agent.

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

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

Schema coverage is 100% with each parameter having a description, but the narrative adds extra meaning: real MPN examples, explicit negative examples for part_number, and semantic details about prefetch_datasheet as a background trigger with no charge. This far exceeds the schema's basic field descriptions.

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

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

The description clearly states it fetches full details for a component by MPN/LCSC number and lists return contents (specs, pricing, stock, datasheet summary). It uses a specific verb ('Get full details') and resource ('specific electronic component'), differentiating it from search_parts and other siblings.

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

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

Explicitly instructs to use after search_parts to drill into a result, and provides concrete restritions on what part_number should NOT contain (bare values, descriptions, reference designators). The extensive datasheet status section also recommends when to call check_extraction_status, read_datasheet, prefetch_datasheets, or upload tools, giving clear alternative routes.

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

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

The description discloses non-blocking behavior, return statuses, retriability, and failure modes in detail. Annotations already declare readOnlyHint and no destructiveHint, and the description consistently aligns with those while adding operational context (e.g., status meanings and retry timing).

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 long but every section earns its place. It is front-loaded with purpose and an example, then systematically organizes status values and retry logic. The structured bullet points make it easy for an agent to parse.

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

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

Given the lack of an output schema, the description fully explains the possible status values and their implications. It covers prerequisites, failure handling, and alternatives, making it complete for an agent to act on.

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 schema covers the parameter but the description adds substantial meaning: concrete examples ('TPS54302'), allowed formats (MPNs, LCSC numbers), prohibited inputs ('100nF', descriptions, reference designators), and a workflow for resolving BOM values via search_parts.

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 action: 'Trigger background datasheet extraction for multiple parts at once (up to 20).' It clearly distinguishes this tool from siblings like read_datasheet and check_extraction_status by emphasizing its role as a prefetch/warm-up step.

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 when-to-use guidance is given: 'Use this to warm up datasheets for a BOM before calling read_datasheet.' It also provides specific alternatives for failure cases (retry, request_datasheet_upload) and exclusions (do not pass bare values, use search_parts for values-only rows).

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 readOnlyHint and non-destructive behavior, the description discloses that first calls trigger extraction (30s-2min), that section names are dynamic and fall back to search, and provides exhaustive status value semantics. It also explains that register-level details are not in the datasheet for MCUs, preventing incorrect expectations.

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 long but densely organized with bold section headers (Section mode, Search mode, Datasheet vs Reference Manual, DATASHEET STATUS VALUES). Each segment earns its place, delivering actionable guidance rather than fluff, though the status value enumeration is extensive and could arguably be trimmed or moved to a linked reference.

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

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

Given the tool's complexity (5 params, no output schema), the description is remarkably complete: it covers prerequisite extraction, caching, status handling, error escalation, and even context about datasheet vs reference manual. The agent is fully equipped to decide when and how to call this tool without needing external knowledge.

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?

While the input schema covers all five parameters, the description adds critical meaning beyond the schema: part_number must be a specific MPN or LCSC number (not bare values), section mode should start with 'summary', and search mode requires a query. It gives concrete examples and explains how section names are dynamic slugified headings, supplementing the schema's basic type enums.

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 'Read from a component's datasheet', a specific verb+resource, and then details two modes (section and search). It distinguishes from sibling tools like search_datasheets by focusing on reading within a single part's datasheet, and the part_number requirement clarifies its scope.

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 explicitly guides usage: section mode default with summary first, search mode for targeted questions, and a detailed 'Datasheet vs Reference Manual' section explaining when to use this tool versus consulting a reference manual. It also maps status values to next actions (prefetch_datasheets, check_extraction_status, request_datasheet_upload), providing unambiguous when-to-use versus alternative tool 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?

The description goes far beyond the annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false) by disclosing token expiry (15 minutes), validation rules and refunds, fee timing (only on confirm), org scoping/privacy, and the exact upload method (PUT with headers). It also explains that uploaded datasheets satisfy other tools' queries. This is rich, honest behavioral context with no contradiction.

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?

Despite being long, the description is tightly structured: purpose sentence, trigger conditions, numbered 3-step flow, validation rules, scoping note, and expiry/retry note. Each sentence carries useful information and the structure mirrors the actual workflow. It is front-loaded with the core purpose and then organized logically, earning 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 no output schema, the description must explain return values, and it does: upload_url, upload_method ('PUT'), upload_headers, upload_token. It also covers the full end-to-end process, validation rules, fee, privacy, expiration, and next step (confirm_datasheet_upload). For a tool with 4 params and a multi-step flow, this is complete guidance.

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 baseline is 3. The description adds flow context (e.g., 'You get back an upload_url...') and validation rules that reference parameters (e.g., MPN on first page), but it does not significantly extend the parameter meanings already provided in the schema. The schema already explains expected_sha256 as content-addressed and tamper-detecting, and size_bytes limits. No new parameter semantics are introduced.

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: 'Request a signed URL to upload a datasheet PDF for a component whose datasheet we don't have.' It clearly distinguishes from siblings by naming the exact trigger conditions (datasheet_status='no_source' or 'unsupported') and contrasts with confirm_datasheet_upload. This is a precise, differentiated purpose statement.

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 explicitly states when to use the tool: 'Use this when search_parts / get_part_details / prefetch_datasheets return datasheet_status="no_source" (and a retry didn't help) or "unsupported".' It also provides exclusion guidance (no dev-kit manuals, BOB schematics, app-notes) and a step-by-step flow that clarifies the tool's role versus confirm_datasheet_upload. This is exemplary usage 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 readOnlyHint, openWorldHint, and idempotentHint, so the baseline is covered. The description adds important behavioral context beyond annotations: the tool is limited to previously extracted datasheets, and it performs semantic (natural language) matching rather than exact keyword search. This helps the agent understand scope and result variability. No contradictions with annotations.

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

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

Four sentences, all purposeful. The first sentence states the core function, the second expands on query types, the third gives usage context with an example, and the fourth provides a caveat and alternative. No redundancy, front-loaded, and well-structured.

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

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

For a straightforward search tool with comprehensive annotations and schema, the description covers the key aspects: what it searches, the extraction-status limitation, and the differentiation from search_parts. It does not mention the optional 'section_type' parameter, but the schema already fully documents that parameter. Given no output schema, the description is sufficiently complete for an agent to decide when and how to invoke 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?

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying what the 'query' parameter expects: natural language about specifications, features, or capabilities, with an example ('low-noise LDO with PSRR above 70dB'). It does not repeat parameter descriptions from the schema but provides richer guidance on how to phrase queries.

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: 'Semantic search across all extracted datasheets.' It clearly states the tool finds components matching natural language queries about specifications, features, or capabilities. It also distinguishes from siblings by explicitly directing users to 'search_parts' for part-number lookups.

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 provides explicit when-to-use guidance: 'Best for broad spec-based discovery across all parts' and gives a concrete example. It also includes a clear exclusion and alternative: 'Only searches datasheets that have been previously extracted — not all parts that exist. For finding specific parts by number, use search_parts instead.' This fully covers usage context.

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?

Even with readOnlyHint=true, idempotentHint=true, and destructiveHint=false, the description adds substantial behavioral context: queries providers in parallel, merges results by MPN, includes private library behavior, and details all datasheet_status values with retry/fallback actions. This goes far beyond annotations without contradiction.

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 long but structured with a clear opening, parameter context, and a detailed datasheet_status breakdown. Every section is purposeful; the length is justified by the need to explain eight status values. Not overly verbose for the complexity.

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?

No output schema exists, but the description fully covers return behavior (merged results, pricing/stock, datasheet_status), provider options, private library augmentation, and related tools for further actions. Complete for a search tool with rich edge cases.

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 value with example queries ('STM32F103', 'buck converter 3A') and clarifies the results-merge behavior tied to providers/limit, though the schema already covers the 3× limit detail. Slight extra enrichment for parameter use.

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

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

The description clearly states the tool searches for electronic components by part number, description, or keyword, and identifies it as the best entry point. It explicitly distinguishes from sibling search_datasheets by directing spec-based natural language discovery there.

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

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

Provides explicit guidance: 'Start here — this is the best entry point' and 'For spec-based discovery in natural language, use search_datasheets instead.' Also explains when to use prefetch_datasheets or read_datasheet based on datasheet_status, giving clear when-to vs alternatives.

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