Silicon Analysts

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

Annotations declare read-only/idempotent, but the description goes far beyond by disclosing error behavior (INVALID_PARAMS), uncertainty (±15–20%), default process node, and scenario-specific caveats (energy as delta, CoPoS as forward-looking). No contradictions with annotations, which are reinforced by the 'Pure-function' framing.

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?

Well-structured with clear sections and front-loaded purpose. Every sentence provides operational guidance (defaults, error behavior, scenario caveats). Length is justified by the tool's complexity and the density of useful 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?

No output schema, but description enumerates all returned fields with units, explains conditional blocks (energy, substrateScenario), provides bounds, defaults, accuracy, and references siblings for external data. For a complex estimator with 18 parameters, this is comprehensive.

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 has 0% description coverage for 18 parameters, but the description explains required bounds (1–33 mm), default processNode, energyRegion semantics (scenario delta), energyFacilityOverhead effect (~1.75× multiplier), and substrate scenario behavior—substantially compensating. Remaining numeric params (hbmCost, testCost, etc.) are inferable from names.

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 ('estimates') and resource ('chip cost'), enumerates the computed outputs, and explicitly contrasts with sibling tools (get_accelerator_costs, get_wafer_pricing). This leaves no ambiguity about the tool's 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?

Provides explicit 'USE THIS for' and 'DO NOT USE for' guidance, naming sibling tools for alternatives (get_accelerator_costs, get_wafer_pricing) and even directing users to get_wafer_pricing for valid process nodes. This is model 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 mark the tool as read-only, idempotent, and non-destructive. The description goes well beyond that: it discloses that the estimate is heuristic, directional, low-confidence, NOT a foundry quote, that it returns min/max bands rather than point values, that it echoes resolved inputs, and that it includes assumptions, methodology, and public-source citations. No contradiction with annotations 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?

The description is long but tightly structured into purpose, use-cases, exclusions, input requirements, behavioral thresholds, and citation guidance. Every major section carries decision-relevant information, and the most critical routing information is front-loaded with the USE/DO NOT USE 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?

For a tool with four parameters, no output schema, and twenty siblings, this description covers everything an agent needs to invoke it correctly: inputs, defaults, accepted values, return fields, limitations, methodology, and alternatives. The inclusion of the required mutual-exclusion constraint and the public citation naming removes the remaining ambiguity.

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?

Although schema description coverage is 100%, the description adds meaning the schema lacks: the maskLayers/processNode are mutually exclusive alternatives with 'REQUIRED unless the other is provided', the full accepted processNode list appears only in the description, packagingType is grouped into coarse classes vs platform IDs with a default, and utilization semantics include real behavioral thresholds. This materially improves correct parameter selection.

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 names a specific resource and verb: a heuristic chip-manufacturing LEAD TIME estimator (manufacturing cycle time). It enumerates the returned fields and explicitly distinguishes itself from siblings by stating what it is NOT for—allocation lead time and chip cost—so the agent can disambiguate it from get_foundry_allocation, calculate_chip_cost, and get_accelerator_costs.

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 contains explicit USE THIS FOR and DO NOT USE FOR sections that name the alternative tools to choose instead and the exact conditions that route to them. It also provides decision-relevant boundary behavior for utilization values (≤80% best-case, ≥95% worst-case), making the intended invocation unambiguous.

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

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

Annotations already cover read-only/idempotent/closed-world, and the description still adds substantial behavior: id namespace formats, INVALID_PARAMS on unknown ids, tier-based clamping (anonymous/free/Pro), history_note signalling when a record was clamped, and withholding of source notes that restate invisible values. That is well beyond what the annotation block provides.

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 what is returned, then the USE/DO NOT USE routing, then id formats and tiering. Dense but every block carries information; the tiering/citation paragraph is somewhat long, keeping it short of 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?

No output schema exists, and the description fully specifies the return envelope ({id, title, text, url, metadata}) plus what lives in `text` and `metadata` (as_of, freshness, basis, cite_as, license_url). An agent has everything needed to call and interpret the result.

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 schema already documents the single `id` parameter with examples, so the baseline is 3. The description compensates further by spelling out the four id grammars (dataset, dataset#series_key, article, tool) inline and specifying the failure mode for unknown ids, adding meaning beyond the schema 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?

Opens with a specific verb and resource ('Fetch one Silicon Analysts record by the id search returned') and immediately enumerates the return shape. It is clearly distinguishable from the sibling `search` and from the `get_*` family, which return typed/filtered data rather than a record rendering.

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?

Contains explicit 'USE THIS for' and 'DO NOT USE for' blocks, names the connector-host scenario, and routes to the alternative (`metadata.structured_tool` names the specialised tool behind the record). When-not guidance is concrete rather than implied.

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

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

Description adds significant context beyond annotations: lists 18 specific chip names, explains filter behavior (empty array on no match, not an error), mentions provenance.confidence_tier for early-ramp parts, and states data refreshes monthly. Annotations already declare readOnlyHint and idempotentHint, but the description deepens disclosure with concrete behavioral traits.

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 in first sentence. Use cases and filter section separated clearly. Every sentence adds unique value with no redundancy.

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?

Despite no output schema, the description enumerates all 18 chips, lists all fields and structures, and documents filter behavior and data provenance. It's complete for agent decision-making, covering scope, edge cases, and data freshness.

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

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

Schema coverage is 0%, so description carries full burden. It explains vendor (enum), chip (substring match), and fields (projection list) with behavioral details. However, it could add value by describing valid field names or projection syntax beyond what the schema implies.

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 explicitly names the resource (18 AI accelerators) and the action (returns structured fields with cost breakdowns and specs). It differentiates from siblings by listing what each chip is and by stating DO NOT USE for other tools like get_market_pulse and calculate_chip_cost.

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?

Clearly states USE THIS for comparing costs/specs across vendors and DO NOT USE for chips not in catalog (use get_market_pulse), custom chip cost modeling (use calculate_chip_cost), or HBM market data (use get_hbm_market_data). This is explicit when-to and when-not-to guidance with relevant 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 readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds substantial behavioral context: the bitemporal nature (as_of vs detected_at), curated backfill, full sourcing metadata taxonomy, grain-dependent rollup semantics, and access-tier behavior (free preview, Pro/Enterprise full, anonymous none). This greatly enhances transparency 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?

Although the description is fairly long, it is well-structured with clear sections (overview, use cases, filters, access) and avoids redundancy. Every sentence contributes actionable information—scope, examples, alternatives, or constraints—making it appropriately sized for a complex tool with many parameters and access tiers.

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 explains return shapes ('month|quarter returns median/min/max rollups', 'raw returns per-source observations') and mentions source metadata fields. It also covers access tiers, filter semantics, and citation guidance, giving a complete picture for an agent to invoke 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 0%, so the description must compensate—and it does thoroughly. It lists all seven filters, marks benchmark_type as required, enumerates its allowed values, explains grain semantics (raw vs month/quarter rollups), and clarifies from/to as as_of bounds. This gives effective meaning to every parameter despite the schema's missing 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 opens with a specific verb and resource: 'Historical Benchmarks — the bitemporal benchmark-observations ledger...' and enumerates the exact data domains (wafer cost, defect density, CoWoS interposer, etc.). It explicitly differentiates from siblings by naming alternative tools for current point values and other APIs, making the purpose crisp and 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 includes a dedicated 'USE THIS for' block with concrete example queries and a 'DO NOT USE for' block that names specific alternative tools (get_wafer_pricing, get_packaging_costs) and API endpoints (/api/v1/snapshot-series, /api/v1/margin-trends). This offers explicit when-to-use and when-not-to-use guidance, going well beyond a generic statement.

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, but the description goes well beyond them: evidence grading scheme (A/B/C/D), the rule that states move only on A or B evidence, that judgments are weekly, dated and never overwritten, that missing numbers are null rather than estimated, the citation string, and that access is fully public at full fidelity for every tier including anonymous. This is unusually rich behavioral disclosure.

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 what the tool returns, then usage, then filters, so an agent can stop reading early. It is dense and long, and a few clauses (the deposit-table and failed-claims sentence) sit awkwardly between the return description and the usage block, but nearly every sentence carries distinct 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 no output schema, the description compensates by describing return contents in detail — per-node evidence, five graded numbers, state-change triggers, dated checkpoints, the customer-deposit table and failed claims. For a read-only, three-parameter board tool, an agent has everything needed to call it and interpret results.

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

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

Schema coverage is 0%, so the description carries the full burden and does so: it enumerates valid node fragments (cowos-l, hbm, n3, hbm-base-die, abf-substrate, t-glass, ate, inp-laser), defines the judged-state vocabulary, and explains include_history as returning every earlier judgment with its date, rules version and reason. Each of the three parameters gains meaning beyond the bare schema types.

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 resource (an eight-node AI hardware bottleneck board) with an explicit enumeration of what each node returns: judged state, evidence with grades and source links, five standard numbers, change triggers, and the next dated checkpoint. It is clearly distinguishable from siblings such as get_foundry_allocation, get_fab_capacity and get_hbm_market_data, 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?

Contains explicit 'USE THIS for' scenarios with example queries and an explicit 'DO NOT USE for' list that routes each excluded need to a named alternative tool. Nothing about when to select this tool is left to 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?

Annotations only declare read-only/idempotent, so the description carries real weight and does: it discloses data provenance (Silicon Analysts estimates, capacity_basis 'sa_estimate', companies do not disclose per-fab capacity), that availability_status is OUR tier not the company's statement, the period_relation vs is_projection pitfall, the no-carry-forward rule for lapsed series, meta.corrections, and differing access per tier (anonymous/free preview vs Pro full series). These are exactly the non-obvious behaviors 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?

Purpose and mode semantics are front-loaded and every sentence carries substantive caveats, but the opening block is a dense wall of parenthetical detail that would benefit from tighter grouping. No sentence is pure filler, so it stops short of 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?

For a 7-parameter, no-output-schema analytical tool this is complete: provenance and quoting rules, tier-based access differences, caveats about stored flags versus derived relations, corrections metadata, citation format, and the sibling routing are all present.

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

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

Schema description coverage is 0%, so the description must compensate, and it names all seven filters with added meaning: as_of is explicitly a latest-state cutoff, series selects full dated history (with its gating), and limit is defined in row terms (fab·class rows in latest state, newest readings when series=true). That clarifies semantics beyond the bare JSON types.

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-scope: per-fab, per-tech-node-class capacity estimates built from fabs + fab_capacity_snapshots time-series, with default latest-state vs series=true modes spelled out. It explicitly distinguishes itself from get_bottlenecks, get_foundry_allocation and get_wafer_pricing, so an agent can route correctly 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?

Dedicated 'USE THIS for' examples and a 'DO NOT USE for' block that names the alternative tool for each excluded case (get_bottlenecks for evidence-graded supply questions, get_foundry_allocation for allocation/lead-time per node, get_wafer_pricing/foundry endpoints for annual wafer starts). This is the explicit when/when-not/alternative pattern at its strongest.

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, closed-world), so the bar is lower. The description still adds meaningful behavior: delays are recorded as their own events and never overwrite the original plan, coverage goes back to 2020, and the 'latest slice for all tiers; full history Pro (never a 403)' note discloses a real access-tier constraint.

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?

Well front-loaded: identity of the log first, then row shape, then USE/DO NOT USE, then filters. It is dense and longer than average, but nearly every clause carries actionable information; only the citation line is 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 9 params at 0% schema coverage and no output schema, the description compensates well by enumerating returned row fields (foundry, fab_name, event_type, event_date, summary, source URL, verbatim quote, is_projection) and the lifecycle semantics. The one shortfall is the undocumented date-range filters, which leaves part of the parameter surface unaccounted for.

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

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

Schema description coverage is 0%, so the description must carry the load. It documents 5 of 9 filters and usefully expands the event_type enum (announced|groundbreaking|topping_out|equipment_move_in|risk_production|hvm_start|expansion|delay|cancellation|conversion), which the schema lacks. However, the date-range parameters (from, to, since, all) go entirely unexplained, leaving a real gap.

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 resource and scope: the dated construction & ramp event log with its full lifecycle (announcement → groundbreaking → move-in → risk production → HVM), including expansions and schedule slips. An agent instantly knows this is the fab-milestone timeline tool and can distinguish it from capacity or allocation tools by name.

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 USE THIS FOR block names concrete queries ('which fabs hit a milestone recently?', 'which projects have slipped?') and a DO NOT USE block routes to two named siblings (get_fab_capacity, get_foundry_allocation) with the condition that selects each. This is exactly the when/when-not/alternative guidance the dimension asks for.

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 read-only, idempotent, non-destructive status, but the description adds material behavior the annotations cannot express: full history requires a free API key, anonymous callers silently get the latest slice with a note and never an error, and group='series' changes the return shape by adding a chains array.

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?

Well front-loaded with a one-line identity statement, then labeled USE/DO NOT USE and Filters blocks that make scanning easy. It is on the long side and the citation instruction plus the quote/URL field enumeration add bulk, 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?

For an 11-parameter, no-output-schema tool the description is complete: it lists the row shape returned (originator, metric, target_period, value, unit, as_of, URL, quote), covers the auth fallback behavior, and clarifies the relationship to sibling tools. Nothing an agent needs to call 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?

With 0% schema description coverage, the description carries the full burden and mostly delivers: it enumerates originator, originator_type (with all enum values), metric, target_period, entity_id and limit, and explains group='series' in detail. What it does not adequately explain are from/to/since/all, which are only name-dropped as 'full history' without stating how each differs.

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 opening sentence names a specific resource (a vintage archive of third-party forecasts) and immediately scopes it: research firms, company capex/bit-growth guidance, archived with original publication dates. It explicitly distinguishes itself from sibling tools by name — get_wafer_pricing / get_accelerator_costs for current pricing, get_track_record for the company's own graded projections.

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 'USE THIS for' and 'DO NOT USE for' blocks with concrete example queries, each paired with the alternative tool to use instead. The revision-history vs latest-number framing gives the agent a clear decision 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?

Beyond the readOnlyHint, the description adds significant behavioral context: data provenance (public estimates, human-reviewed), confidence tiers per record, intentional omission of wafer_price, citation requirements, and the structure of historical series. This provides a clear picture of what the tool returns and its limitations.

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 longer than typical but well-structured with clear sections (fields, use cases, filters, caveats). Every sentence adds value, and the formatting makes it easy to scan. It is appropriately sized for the tool's 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?

With no output schema, the description fully explains the return fields and historical series structure. It also provides usage boundaries, filter options, and provenance details, making it a complete guide for an agent to select and invoke this 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 0%, so the description must compensate. It lists all filters and explains include_history and the history_metric enum values (lead_time, pct_locked, etc.) in the context of the historical series. However, it does not individually detail parameters like 'limit' or 'node', though their meaning is inferable from context.

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 function: 'Foundry & advanced-packaging ALLOCATION — the current-state snapshot per node/tech...'. It specifies the resource (allocation data) and provides a detailed list of fields, distinguishing it from related tools like get_fab_capacity and get_hbm_market_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?

Explicit 'USE THIS for' and 'DO NOT USE for' sections provide concrete when-to-use and when-not-to-use guidance, listing alternative tool names for each excluded use case (e.g., get_accelerator_costs, get_hbm_market_data).

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 that mark the tool as read-only and idempotent, the description adds extensive context: sourcing from public IR materials, a documented scaling calculation, confidence levels, the free-vs-Pro clamping behavior, the handling of sparse-disclosure foundries with nulls/low confidence, and refresh cadence. It also discloses that node margin estimates are explicitly labelled estimates from public analysis.

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 that length is justified by the tool's complexity and the absence of schema descriptions for 8 parameters. It is well-structured with clear sections for data coverage, usage guidance, filtering behavior, and caveats. Every sentence adds necessary 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?

For a tool with 8 parameters, no output schema, and a mix of free/Pro behavior, the description covers all key aspects: return data, source provenance, confidence levels, node margin estimate details, filter syntax, free-tier limits, error behavior (never an error), and refresh timing. It is exceptionally 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 0%, but the description richly compensates for every parameter. It explains foundry tokens, node canonical examples (n3, 22-28nm, 18a), node_group examples, quarter pattern (2026Q1|2025FY), and include_facts semantics. It also explains the behavioral meaning of the from/to and limit parameters in the context of Pro-key restrictions.

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, resource-rich definition: 'per-foundry, per-process-node, per-fiscal-quarter wafer ASP and fab UTILIZATION'. It also distinguishes from siblings by naming concrete data sets (get_wafer_pricing, get_foundry_allocation) to avoid overlap.

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 includes explicit 'USE THIS for' and 'DO NOT USE for' sections with concrete example queries and alternative tool names. It clearly states when this tool is appropriate and when other tools are the correct choice.

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, yet the description adds substantial operational context: INTERNAL_ERROR on upstream Supabase failure, per-sub-table refresh schedules (qualificationFeed Mon/Thu, bitDemand monthly), which tables are hand-curated vs. frozen, and the meta.table_freshness / meta.data_freshness.stale fields. The spotPrices retirement on 2026-07-28 is disclosed precisely.

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 return shape and the narrowing behavior, followed by well-organized USE / DO NOT USE blocks. It runs long and repeats the ten sub-table names in the opening list and again during explanation, which is a minor redundancy rather than 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 no output schema, the description carries the return-value burden itself, exposing the meta freshness/staleness fields and the error mode. For a ten-sub-table aggregator with one optional enum parameter, an agent has everything needed to select a sub-table correctly and interpret freshness.

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

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

Schema coverage is 0% though the enum supplies the ten valid values; the description compensates by characterizing several of them (marketShare's source/period and its non-bit-shipment caveat, spotPrices' retired status, bitDemand's SKU-class/customer-type cut) and by explaining the semantics of omitting the parameter entirely (returns all 10). It falls short of describing all ten sub-tables equally.

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 (Returns) and resource (10 HBM market sub-tables), enumerates them by name, and explains the optional narrowing behavior. It explicitly differentiates itself from siblings like get_market_dataset, get_accelerator_costs, and calculate_chip_cost by naming the separate sub-resources each covers.

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 'USE THIS for' and 'DO NOT USE for' sections, each routing to a named alternative tool or dataset (e.g., 'use get_market_dataset dataset=hbm-pricing'). It also pre-empts a plausible misuse ('bitDemand is NOT a workload split') and corrects a common conflation (share of revenue vs. share of bit shipments).

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 the safety profile (readOnly/idempotent/non-destructive), and the description layers on substantial extra behavior: Mon/Thu 09:00 UTC refresh cadence, an auto-publish rule with corroboration thresholds, absence of human review before publication, staleness reporting via meta.data_freshness.stale, superseded-event markers, and anonymous-caller timeline truncation with the API-key remedy.

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 identity, then return shape, then cadence/provenance, then USE/DO NOT USE routing, then filters and citation — a logical order where nearly every sentence carries information. It is dense and slightly long, with the citation and API-key notes arguably better placed outside the selection path, but there is little true waste.

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 compensates by naming both return structures (matrix rows with date, source URL, confidence; timelines with status-change history back to 2022 and the sampling → qualified → volume_shipping progression) and provenance/freshness caveats. Combined with annotations and filter docs, an agent has everything needed to call and interpret 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 description coverage is 0%, so the description must carry the load, and it lists every filter with added semantics ('customer' as a substring match, enum values for vendor/generation tied to the domain, include_timelines' link to history depth and anonymous truncation). Gap: no defaults are stated (e.g. whether include_timelines defaults on), so an agent cannot predict default output shape.

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 resource (Sourced HBM qualification tracker) and the exact relationship it covers — memory vendor × AI-accelerator customer × generation × stack height — with named concrete entities. It is immediately distinguishable from siblings like get_hbm_market_data and get_accelerator_costs.

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 'USE THIS for' block with sample queries (Vera Rubin HBM4 supply, Samsung/NVIDIA qualification, Micron HBM4 status) and an explicit 'DO NOT USE for' block routing pricing/market share to get_hbm_market_data and per-chip cost to get_accelerator_costs. Nothing is left to 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?

Annotations indicate read-only, idempotent, non-destructive behavior; description adds tiering (anonymous vs free key vs Pro), methodUrl for methodology, and explains data point typing (Confirmed/Estimate/Projection) 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?

The description is fairly long but well-structured with clear sections and bullet points. Every sentence adds value; minor redundancy could be trimmed but remains efficient 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?

Despite no output schema, description details return fields (value_low/mid/high, confidence, data_type, source), explains methodUrl, and mentions CSV/JSONL export for Pro callers, covering all necessary user context.

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% (baseline 3). Description adds context: dataset='list' enumerates catalog, series_key is optional filter, and tiering affects data access, providing extra guidance beyond 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 it provides curated market-data time series with per-point sourcing, listing specific datasets (HBM pricing, component lead times, wafer price, etc.) and distinguishing itself from sibling tools for current snapshots or IR-derived metrics.

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 sections 'USE THIS for' and 'DO NOT USE for' list appropriate use cases (e.g., HBM contract price history) and forbidden ones (e.g., current HBM snapshot, use get_hbm_market_data instead), guiding the agent to correct 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 already declare readOnlyHint/openWorldHint/idempotentHint/destructiveHint, but the description adds substantial behavior: the daily generation pipeline, that the machine feed returns ALL severities, that Critical is only stored when the fact is verifiably ≤7 days old, that provenance and novelty dating are attached, and that sources are public-only with no insider data.

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 is front-loaded, but the body is an extremely long, densely packed run-on (a single ~200-word sentence enumerating impact/impact_assessment/related/novelty). Most content is valuable, yet the jargon-heavy enumeration and 'No pure-news source does this'/'UNIQUELY' framing exceed what an agent needs to select and invoke 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?

With no output schema, the description compensates fully by describing the returned record structure, the impact-assessment status taxonomy, the novelty verdicts, and the filter set. Nothing an agent needs to call it correctly or interpret results 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 0%, so the description carries the full burden — and it does: it names all five filters (severity, category, since as ISO timestamp, publishedOnly bool, limit 1-100 default 25) and explains their meaning (e.g. the severity enum and 'published flags the Critical/High briefs that also have a public page').

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?

Opens with a specific verb+resource and scope: 'the freshest SOURCED semiconductor market briefs, generated daily from a Tavily + Claude scan.' It also enumerates the exact returned fields (severity, confidence_score, entities, impact, novelty), which clearly differentiates it from siblings like get_market_pulse and get_market_dataset.

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?

Contains explicit 'USE THIS for' examples and a 'DO NOT USE for' block that names three alternatives (get_accelerator_costs / get_wafer_pricing / calculate_chip_cost, get_recent_changes, get_foundry_allocation) with the condition selecting each. This is textbook 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 indicate read-only/idempotent behavior. The description adds valuable non-obvious details: default filters (all categories/trends/no limit), date format caveat (not ISO 8601), server-side cache of 5 minutes, and empty-array behavior when filters match nothing. 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 well-structured with a clear first line stating the primary purpose, followed by usage guidance, exclusions, and caveats. Every sentence adds value, and the USE THIS/DO NOT USE sections make it scannable without excess verbosity.

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 list-returning tool with no output schema, the description is comprehensive. It explains what items contain (headline, trend, source, impact), available filters, default behavior, date formatting, cache behavior, and edge case (empty array). This is sufficient for an agent to invoke the tool correctly and interpret results.

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

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

Schema description coverage is 0%, so the description must compensate. It mentions categories and trend direction in the main sentence and explains defaults ('Defaults to all categories, all trends, no limit'). However, it does not explicitly explain the 'limit' parameter semantics (e.g., maximum number of items) or clarify whether category/trend accept multiple values (schema shows single enum). Partial compensation but not complete.

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 returns curated supply-chain headlines with trend direction, source attribution, and impact analysis. It specifies categories (logic, memory, packaging, etc.) and defaults, making the scope distinct from siblings. The explicit 'DO NOT USE' section further differentiates it from pricing and cost tools.

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

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

Provides explicit USE THIS examples ('what's happening in HBM this quarter?') and DO NOT USE cases with named alternatives (get_wafer_pricing, get_hbm_market_data, get_accelerator_costs). This gives the agent clear decision criteria for 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?

The annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds useful context: returns INVALID_PARAMS for unknown type and refreshes monthly. This discloses error behavior and data staleness, going beyond what annotations 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?

The description is well-structured and front-loaded: it starts with the main return values, then the optional parameter, then usage guidelines, then error and refresh behavior. Every sentence earns its place, with no redundancy.

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 lookup tool with one optional parameter, the description covers the return structure, parameter semantics, error behavior, refresh frequency, and alternative tools. No output schema exists, but the return values are described adequately, making it complete for an agent to select and invoke the tool.

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

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

The schema has no description for the `type` parameter, so the description compensates by explaining it as an optional filter narrowing the packaging array to one technology. It also lists example technologies elsewhere in the description, giving the agent a good sense of valid values, though not an exhaustive list.

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 returns two sub-arrays (`packaging` and `hbmSpecs`) with specific content, using a specific verb and listing technology types. It also distinguishes from sibling tools by naming alternatives in the DO NOT USE section.

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 includes explicit 'USE THIS for' and 'DO NOT USE for' sections, naming get_hbm_market_data and get_accelerator_costs as alternatives. This provides clear when-to-use and when-not-to-use guidance, making the choice straightforward.

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, so the description only needs to add context, and it does: primary-document provenance, verbatim quotes, and the tier note 'full history Pro (never a 403)' signals access limitations. It stops short of describing pagination or ordering behavior.

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

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

Sectioned and front-loaded: identity first, then USE/DO NOT USE, then filters and citation. Dense and largely earning its place, though the field enumeration and citation instruction add mild bulk.

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 describing each row's fields is valuable and the description does it. For an 8-parameter tool the missing date-range filter semantics are the main gap, but an agent can still call it correctly for the documented filters.

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

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

Schema description coverage is 0%, so the description must compensate. It documents jurisdiction (with the full enum of values), agency, event_type, and limit, which is genuinely useful, but it never explains the to/from/since date parameters or the 'all' flag — four of eight parameters remain undifferentiated.

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 resource (dated log of semiconductor trade-policy actions) with concrete scope (export controls, entity listings, tariffs), the anchor source (government primary documents back to Oct 2022 BIS rule), and enumerates the row fields. It is clearly distinguishable from get_market_intelligence 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?

Explicit 'USE THIS for' with three concrete query examples and an explicit 'DO NOT USE for' that names the alternative (get_market_intelligence) plus a scope exclusion (rumored/anticipated actions are not recorded). This is exactly the routing an agent needs.

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 the safety profile (readOnly/idempotent/non-destructive), the description goes well beyond them: it discloses the return shape (direction, pct_delta vs pp_delta, old/new values, as_of/prior_as_of, provenance), explains that window_days_actual may clamp a 30d request because 'the ledger is young,' notes N2/Apple are omitted as conflict-safe, and states that an empty array is returned rather than an error. These are exactly the behavioral traits 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 conceptual definition, then usage, then exclusions, then filters — every block earns its place. It is long, and the 17-item domain enumeration plus the return-field inventory add bulk, but that length is largely load-bearing given the 0% schema coverage and absent 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?

For a 5-param, no-required-args tool with no output schema, the description must supply both input semantics and return semantics — and it does: full domain list, filter behaviors, delta field meanings, clamping caveat, and empty-result behavior. An agent has everything needed to call and interpret 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 description coverage is 0% and there are 5 parameters, so the description carries the full burden — and it does: window is enumerated, since is defined precisely (compare latest snapshot against the newest snapshot at/before that date, overriding window for baseline selection), datasetId is constrained to 'one domain' with all 17 valid values listed, and minDelta/minDelta's significance-threshold role is explained.

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+scope: 'recent MOVEMENTS in Silicon Analysts' public data over a 7d/30d window, derived from the daily snapshot ledger.' An agent can immediately distinguish this delta-feed from absolute-value siblings like get_wafer_pricing without opening any 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?

Explicit USE THIS / DO NOT USE blocks with concrete trigger phrases ('what moved in semiconductor costs this week?') and named alternatives for each excluded case (get_wafer_pricing, get_accelerator_costs, get_foundry_allocation with include_history). Nothing is left to 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description is consistent with them. It adds valuable behavioral context beyond annotations: vintages are write-once and cannot be edited/backfilled, projections never frozen are lost, and the dataset is fully public and ungated. This greatly informs agent 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 detailed but deliberately structured: a definition paragraph, explicit use/non-use sections, and a filter/access summary. Each sentence adds a distinct fact — data lineage, immutability, grading, alternatives, access control, citation. It is long because the tool warrants it, not because of redundancy.

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 supplies a clear mental model of returned rows: model, scenario, series, target period, predicted mid plus low-high band, realized value, resolution category, and error percentage. It also covers filters, access restrictions (none), and citation. Nothing needed to call and interpret the tool 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 0%, so the description carries the full burden. It compensates well by enumerating model allowed values (hbm-pricing-model|dram-ddr4-model|cowos-capacity-model), explaining include_assumptions (include_assumptions=true for frozen assumption-set auditing), and giving a concrete series example (hbm3e). It adds meaning to every 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?

The description states a specific verb-resource pair: retrieving Silicon Analysts' own forecast track record, with detailed row semantics. It explicitly contrasts with get_forecasts (third-party forecasts) and other market-data tools, so an agent can distinguish it from siblings without opening any 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 provides explicit 'USE THIS for' and 'DO NOT USE for' sections, naming exact alternative tools (get_forecasts, get_wafer_pricing, get_hbm_market_data) and the conditions that route to each. This is the strongest possible 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=true, destructiveHint=false, and idempotentHint=true. The description adds significant behavioral context: always read `citation` before using a price, caveat about operating loss quotes, null values where no public basis exists, INVALID_PARAMS error, and monthly refresh. 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?

The description is longer than typical, but every sentence adds value: core data fields, valid nodes, usage guidance, data caveats, and error/refresh behavior. It is well-structured with clear sections (what, usage, important caveat, error/refresh) and no 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 no output schema, the description must explain return values, which it does thoroughly: it lists all data fields (price ranges, defect density, NRE, maturity), mentions source attribution and null values, and states the refresh schedule. Considering complexity (many nodes, multiple fields, caveats), the description is fully adequate for an agent to correctly select and invoke the 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?

Only one parameter `node` exists, and the description gives a full list of valid values, states that it's optional, and explains the consequence of passing an invalid node (INVALID_PARAMS). This far exceeds the 0% schema description coverage, fully compensating for the lack of enum definitions.

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 'Returns 300mm wafer price ranges (min/avg/max USD), defect density, NRE/mask-set cost, and node maturity' for a specific enumerated list of nodes. It uses a specific verb and resource, and explicitly distinguishes itself from sibling tools like get_accelerator_costs and get_packaging_costs.

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 'USE THIS for' and 'DO NOT USE for' sections with named alternatives (get_accelerator_costs, calculate_chip_cost, get_packaging_costs). Also clarifies that the `node` filter is optional and gives error behavior for invalid input.

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, closed-world), but the description adds real context beyond them: the currency is never converted, data tiers differ ('latest slice for all tiers; full history Pro (never a 403)'), and the exact row shape including verbatim quote and source URL. It could still say more about pagination or date-range behavior, but this is well above the annotation baseline.

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 'USE THIS / DO NOT USE / Filters' structure is front-loaded and scannable, and each section earns its place. The opening sentence is dense with parentheticals, but the information density is justified for a nine-parameter 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?

With no output schema, the description usefully enumerates the returned row fields, and it covers sources, currency, tiering, and citation. The only meaningful gap is the unexplained date-range parameters, which an agent would have to guess at from the schema alone.

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

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

Schema coverage is 0%, so the description carries the full load. It documents five of nine parameters with genuine meaning (company with its enum values, metric with an enumerated list beyond the schema's bare string, segment, fiscal_period, limit as max rows), but the date-range parameters to/from/since and the all flag are never explained. Partial compensation for a low-coverage 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 names the specific resource (WFE order-book disclosures from ASML, AMAT, LAM, KLA, TEL), the exact metrics captured (bookings, backlog, segment revenue, guidance), and the currency convention. It explicitly distinguishes itself from siblings get_fab_capacity and get_foundry_economics, so an agent can route without opening any 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?

Explicit 'USE THIS for' examples ('is the equipment order-book turning up or down?', ASML bookings trend) sit directly beside a 'DO NOT USE for' block naming the two competitors and the cases that select them. Nothing about when-to-use is left to 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?

Annotations already cover readOnly/idempotent/openWorld=false, but the description adds behavior annotations cannot express: deterministic keyword matching, no live data read, identical results for every tier, and a documented empty-result contract ({results: []}, not an error). That is exactly the extra context the bar asks for.

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 purpose and result shape, then clearly block-structured by USE/DO NOT USE/behavior. It is longer than strictly necessary (some catalog enumeration is decorative), but every block carries routing or behavioral value.

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

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

No output schema exists, so the description supplies the return shape, the 10-record cap, the empty-result semantics, and the follow-up chain (pass id to fetch). Combined with 22 sibling tools, this gives an agent everything needed to route 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% and the single query parameter is already documented with examples and maxLength, so the baseline is 3. The description adds marginal value by restating the result contract and the id-to-fetch handoff, which slightly exceeds what the schema alone conveys.

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 concrete verb and resource (search across Silicon Analysts records) and names the exact result shape. It explicitly distinguishes itself from the many get_* siblings by scope: search returns ids/titles/urls only, never values.

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?

Unusually explicit: 'USE THIS for' names the target host class (search+fetch-only connectors, deep research) and 'DO NOT USE for' names the alternative (specialised tools like get_market_dataset, get_wafer_pricing) and the condition that selects them. Nothing is left to inference.

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