HORIZON SHIELD Construction Cost Data: JCCDB (Japan) and USCCDB (United States)

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

Annotations already establish readOnly, non-destructive, and closed-world behavior, but the description adds substantive context beyond them: the median is service-computed (computed:true), only identical spec/unit/basis are compared, and counts are broken out by price status. It does not discuss auth, rate limits, or pagination, keeping it from a 5.

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

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

The core purpose and key constraints are front-loaded, and every part of the bilingual text contributes either purpose, comparison rules, or an example. The Japanese and English versions duplicate content, which slightly reduces conciseness.

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 six parameters, an output schema, and annotations covering safety, the description supplies the essential behavioral context: what is aggregated, what may be compared, and how normalization works. It omits explicit country/limit guidance, but the schema covers those details adequately.

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

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

Schema coverage is 100%, so the structured schema already documents all six parameters. The description still adds value by giving a concrete example and explaining that namacon normalizes ready-mix concrete spec notation across bureaus, which goes beyond the schema's terse enum 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?

Names the specific operation (compare latest values across regions), the grouping dimensions (item and spec), and the aggregated outputs (min, median, max, counts by price status). It does not explicitly name or distinguish itself from sibling tools such as get_jccdb_observations, so it falls short of a full 5.

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 comparison purpose implies when to use the tool, and the concrete example (query, spec, layer, normalize) shows a typical invocation. However, the description gives no explicit when-to-use guidance, prerequisites, or alternatives to consider instead.

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 openWorldHint=false, so safety is covered. The description adds genuinely useful behavior beyond that: empty combinations are explicitly listed as absent (not ingested), and detail=true yields per-source rows while the default is a summary (top 5 source lineages, plus US non-public layer counts). 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?

Two front-loaded sentences, each with a distinct job (what is returned, then how/when to use it), with the availability-check instruction up front. The bilingual JA/EN duplication slightly inflates length, but it is deliberate and structured rather than redundant 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?

An output schema exists, so return-value detail need not be restated, and the description covers the one non-obvious semantic (absent rows mean not ingested). For a 4-param, all-optional availability tool this is nearly complete; it only lacks explicit routing to the follow-up tools to call once coverage is confirmed.

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 all four parameters are already documented, including the detail default/true behavior and enum semantics. The description adds little parameter-level detail beyond what the schema provides, which is the expected baseline-3 case when the schema does the heavy lifting.

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 gives a specific verb and resource: it returns what the JCCDB observation layer holds (rows per country x layer x source, priced rows, status counts, source periods). The 'check availability here before answering' framing separates it functionally from data-returning siblings like get_jccdb_observations, but it never names those siblings explicitly, so differentiation is left partly to inference.

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

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

It states a clear when-to-use condition: verify here whether a given country/layer combination has data before answering (the layer param text reinforces this). It stops short of explicit when-not guidance or naming an alternative tool to use instead when coverage exists, so it is clear context without exclusions.

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 (read-only, closed-world, non-destructive), so the bar is lower. The description adds genuinely non-obvious behavior beyond that: the YoY value is service-computed (computed:true) and absent from the source data, and the no-filter case returns a list rather than empty results.

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?

Core behavior, computed-flag caveat, and fallback mode are front-loaded, with the example last. The full bilingual duplication roughly doubles length, which is justified for a JP/US dataset but adds no new information per line.

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

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

An output schema exists, so return-shape explanation is unnecessary, and the description supplies the two behaviors an agent must know (computed YoY, list fallback). Minor gaps remain around pagination/interaction of limit with list mode, but nothing critical 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 description coverage is 100%, so baseline is 3; the description goes further by explaining the conditional role of query and source_id (absent both, the tool lists series) and showing accepted period formats via the example. It does not clarify how country/limit interact with the list mode.

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 a series over a period) and resource (construction cost index series: NHCCI, PPI, construction deflator), and includes the distinctive YoY-change feature. It also distinguishes itself from get_jccdb_coverage by pointing there for source ids and from the broader observation tools by falling back to a series list.

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

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

Gives explicit branching: with query/source_id use them, without either it lists the series, plus a concrete example call. It points to get_jccdb_coverage with detail:true as the alternative for source ids, but does not contrast with close siblings like get_jccdb_observations or get_jccdb_dataset_info.

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, openWorldHint=false, so safety is covered. The description adds real behavioral context beyond that: the wage is defined per 8 hours within prescribed working hours, and results default to the latest period unless history:true. It stops short of documenting row limits or return shape.

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

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

Front-loaded with the core purpose and scope, followed by the default/history behavior and an example. The bilingual duplication is intentional for a Japanese-domain tool but doubles the length, keeping it just short of maximal efficiency.

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

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

An output schema exists, so return-value explanation is unnecessary. The description covers units, scope, defaults, and an example — enough for an agent to call it correctly, with only minor gaps such as limit/pagination behavior that the schema already bounds (1-200).

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 all four parameters are already documented in the schema, establishing a baseline of 3. The description reinforces semantics with examples (pref='奈良県', job='大工') and the history default, but adds little beyond what the schema states.

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 (引く/retrieve) and resource (MLIT public-works design labor rates) with the exact scope: 47 prefectures x 50 trades, wage per 8 hours. This clearly separates it from siblings like get_jccdb_work_unit_price and get_jccdb_index_series.

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 the default behavior (latest per region) and the condition that switches it (history:true for the yearly series), plus a concrete example. It gives clear usage context but does not name when to prefer a sibling tool instead.

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 openWorldHint=false, so the safety profile is covered. The description goes beyond them by disclosing that values appear only where the licence permits redistribution, that each row carries licence/attribution/evidence_url, and that publication_based_not_public is a factual status rather than a missing value.

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

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

Purpose is front-loaded and every sentence carries information (licensing rule, row metadata, the not-a-missing-value clarification, the design-price scope). The parallel Japanese/English text is redundant for a monolingual reader but is a deliberate and consistent choice for this bilingual domain.

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

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

An output schema exists, so row shape need not be explained, and the description still usefully names the licence/attribution/evidence_url fields. With 10 optional params and rich enum coverage in the schema, the description plus schema is sufficient for an agent to call this correctly.

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

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

Schema description coverage is 100%, so the baseline is 3; the schema already documents all 10 params including geo, layer, status and period formats. The description adds value via the worked example and the cross-reference to get_jccdb_coverage for country-level layer availability, slightly exceeding baseline.

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

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

States a specific resource and scope: region, date and price status of an item in Japanese and U.S. public documents, plus the licensing condition on values. It carves out its niche against siblings by clarifying it returns public-works design unit prices rather than renovation estimates, though it never names the closest sibling tools (search_jccdb_items, get_jccdb_labor_rate).

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

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

Gives a concrete calling example (query='生コンクリート', pref='奈良県') and a negative-scope warning (design unit prices, not renovation quotes), and points to get_jccdb_coverage for per-country availability. However, it never explicitly says when to choose this tool over sibling observation/price tools, leaving the routing 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, openWorldHint=false, destructiveHint=false, so the safety profile is covered. The description adds genuine structural behavior (composition-ratio rows are returned attached to their package), but says nothing about pagination semantics beyond what offset/limit already imply, permissions, or result size.

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

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

The core purpose, scope exclusion, and return shape are front-loaded in the Japanese text before the English gloss. Reasonably tight, though the bilingual duplication and parenthetical detail cost a little density.

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

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

With an output schema present, return values need not be explained, and the description still notes the composition-ratio row attachment. All five parameters are documented in the schema, and the exclusion clause covers the main misuse case. A note on when to prefer sibling lookups would complete 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 the baseline is 3. The description goes slightly beyond by supplying a concrete value example (query='掘削', pref='東京都') that demonstrates how the two main parameters combine, which helps an agent build a valid first call.

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 (引き/retrieve) and resource (工事の単価, public-works unit prices), and explicitly names what it is NOT (リフォームの見積単価). Combined with the title and sibling set (get_jccdb_labor_rate, get_us_construction_prices), an agent can distinguish it immediately.

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

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

Gives an explicit exclusion (renovation quote prices) and a worked query example (query='掘削', pref='東京都'), which clarifies intended usage. It does not, however, route the agent to related siblings such as search_jccdb_items or get_jccdb_labor_rate when the query is a labor rate rather than a package price.

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, openWorldHint=false, so the safe-read profile is covered. The description adds genuinely useful context beyond that: the normalization baseline (96 base-city average = 1.00), support for current and yearly series, and that medians carry computed:true. It does not describe pagination behavior, but that is a minor gap.

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 and the content is well-organized with concrete examples. The main cost is the full bilingual duplication, which doubles length without adding information, but the underlying prose is efficient.

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

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

With an output schema present and safe-read annotations, the description needn't explain return values or permissions. It covers the reference baseline, historical vs current data, and geo formats, which is enough for an agent to call the tool correctly; only pagination guidance (limit/offset interaction) is left entirely to the schema.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters. The description's geo format examples (zip:28533, Cherry Point, NC, country:JP) and its note that medians are computed:true largely restate schema content, so it does not add meaning beyond the structured fields. Baseline 3 applies.

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

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

States a specific verb+resource: it retrieves DoD Area Cost Factors by installation (96 base-city average = 1.00) and USACE CWCCIS state adjustment factors. It also draws a boundary against the sibling verify_fair_price by clarifying it is 'not a test of whether a quote is fair,' letting an agent distinguish it without opening either schema.

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

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

The description gives clear context for use ('budgeting factors') and an explicit exclusion ('not a test of whether a quote is fair'), which implicitly routes fairness checks elsewhere. It stops short of naming the alternative tool explicitly, so it is strong but not fully prescriptive.

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, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: national/uniform rows and USACE regional rows are automatically appended when a state is given, per-m2 conversions are flagged as computed:true, and residential remodeling quotes are explicitly out of scope. It omits any note on rate limits or result-volume behavior, but for a read-only aggregate query this is solid added context.

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

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

The content is front-loaded with the core verb and resource, and each clause carries substantive information (layers, geo formats, augmentation rule, exclusion). The Japanese/English duplication roughly doubles the length, which is intentional for bilingual serving but does inflate token cost relative to a single-language version.

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

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

With an output schema present and 100% parameter coverage, the description need not explain return values, and it correctly focuses on scope, layers, geo/period inputs, the auto-augmentation rule and the exclusion. Combined with the readOnly annotations, an agent has enough to call it correctly; only explicit sibling routing is missing.

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

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

Schema description coverage is 100% with all 9 parameters documented, so the baseline is 3. The description's layer enumeration and geo/period examples (county:06037, cbsa:31080, Austin, TX, FY2026) largely restate what the schema already provides, adding volume of text rather than new semantics. No compensating meaning is introduced for the limit/offset paging behavior.

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 (query/pull) and resource (the U.S. public construction cost database) and enumerates the exact layers returned (labor, wage, work, equipment, index, spending, cost_sqft, cost_limit, bid_item, house_price, material), so an agent knows precisely what data it yields. It also carves out a scope exclusion ("not residential remodeling quotes"). It does not, however, differentiate itself from overlapping siblings such as get_jccdb_labor_rate, get_jccdb_work_unit_price, or get_us_prevailing_wage, which cover some of the same layers.

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

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

The description implies when to reach for it (broad multi-layer cost lookup by layer/geo/period/item) and notes one exclusion, but it gives no explicit when-to-use-vs-sibling routing despite many adjacent tools (get_us_prevailing_wage, get_jccdb_work_unit_price, get_us_permits, get_price_range). The pointer to get_jccdb_coverage appears only in the schema's layer field, not the main description, so the main text leaves routing 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 the safety profile (readOnlyHint, destructiveHint=false, openWorldHint=false), so the description adds real value on top: it discloses that kake_ratio is computed as 1 - discount, that Over-MSRP and Catalog-Off rows are kept in separate columns and excluded from kake_ratio, and that rates are ceilings with list bases varying by row. These are substantive semantic caveats not present in 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 core purpose is front-loaded and the example is useful, but the entire text is duplicated in Japanese and English, roughly doubling length without adding information. Several caveats are packed into dense clauses that would be clearer as separate 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?

An output schema exists, so return-format explanation is not required. The description adequately covers data provenance (specific contract IDs), the computed kake_ratio, and the ceiling/list-base caveats, giving an agent enough to interpret results correctly; only explicit alternative-tool routing is missing.

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

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

Schema description coverage is 100% and all seven parameters carry bilingual schema descriptions, so the baseline is 3. The description adds an example query value and clarifies that the returned 'rate' is a ceiling, but it does not add per-parameter meaning beyond what the schema already provides for basis, vendor, source_id, limit, or offset.

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 and resource — returns published discount rates off list price from U.S. public contracts — and enumerates the exact contract sources (Washington DES 23623 plumbing, 11121 electrical, NASPO ValuePoint MRO) plus named vendors. It is clearly distinguishable from pricing siblings like get_price_range or get_fair_price_sources, though it never explicitly contrasts itself with them.

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

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

An example query ('eaton breakers') and the enumerated sources imply when the tool is useful, but there is no explicit when-to-use statement, no conditions for choosing this over get_us_construction_prices or get_fair_price_sources, and no stated exclusions. Usage is only inferable.

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 openWorldHint=false, so the safety profile is covered. The description goes further by disclosing that unit cost and effective duty rate are computed:true, that Section 232 and other additional duties are included in calculated duty, and that domestic freight and customs clearance fees are excluded — genuinely useful behavioral context 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?

Purpose and inclusions/exclusions are front-loaded and every clause adds substance (duty inclusions, computed flags, exclusions). It is, however, a single dense run-on sentence rendered twice (Japanese and English), which lengthens the payload without adding new information.

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

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

With an output schema present the description need not explain return values, and it covers scope, cost components, computed fields and exclusions for a five-parameter tool. The main missing piece is guidance on when to choose this import-cost source over the sibling domestic price tools.

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

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

Schema description coverage is 100%, so each parameter (hs, limit, query, country, top_countries) is already documented, including the note that top_countries is ignored when country is given. The description adds only the general mention of 'top partner countries or one country', so the baseline 3 is appropriate when the schema carries the detail.

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

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

States a specific verb and resource: returns landed cost of U.S. imports of construction materials and chemicals by HS 10-digit code, drawing on the Census IMDB source. The scope (month and YTD) plus the enumerated cost components (customs value, CIF, duty, quantity, unit cost, effective rate) make it unambiguous and clearly distinguishable from the pricing/estimate 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?

Usage is implied by the scope (import landed cost by HS code) but there is no explicit when-to-use or when-not-to-use guidance, and no routing versus alternatives like get_us_construction_prices or get_us_price_chain. The agent must infer that this is the import-trade data source rather than a domestic price source.

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 carry readOnlyHint/openWorldHint/destructiveHint, so the safety profile is covered. The description adds genuine value beyond that: it discloses the data provenance (declared by applicants, not contract prices or quotes) and that derived values are flagged computed:true, which prevents misinterpretation of the numbers.

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?

Content is front-loaded with the verb+resource and the caveat is well placed, but the entire description is duplicated in Japanese and English, roughly doubling length without adding information for a single-language reader. Each semantic sentence earns its place, but the bilingual redundancy hurts conciseness.

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

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

Given an output schema exists (so return values need no explanation), the description covers sources, coverage geography, the structure breakdown, the computed flag, and the valuation caveat. An agent has everything needed to call the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters including the enums for source and structure. The description only restates the example geo/year pair, adding little meaning beyond what the schema provides; baseline 3 applies.

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

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

States a specific verb and resource (fetch U.S. building permits) and enumerates exactly what data is returned: Census BPS buildings/units/valuation/per-unit plus city permit valuation distributions (median, quartiles, per sqft). No sibling tool deals with permits, so it is clearly distinguishable.

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 a concrete example invocation (geo='Austin, TX', year='2024') and a caveat that valuations are applicant-declared, not contract prices, which implicitly steers agents toward the pricing siblings. However, there is no explicit when-to-use/when-not-to-use statement nor any named alternative, leaving usage 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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description goes further, disclosing the returned structure (base and fringe side by side, decision number, revision, publication date, source URL) and flagging that the total is computed:true – useful context 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?

Purpose and scope are front-loaded and every clause carries meaning, but the content is fully duplicated across Japanese and English, roughly doubling the length for an agent that only needs one language.

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

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

With an output schema present, return values need not be explained, yet the description still summarizes them and adds the crucial domain caveat that these are statutory minimums. Seven optional parameters, a clear example and a stated scope leave nothing an agent needs missing.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds a worked example ('state=CA', county='Los Angeles', trade='carpenter') that shows how the main filters combine in practice. It does not add format or syntax detail beyond what the schema already provides.

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

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

States a specific verb+resource: '引く' / retrieve Davis-Bacon general wage determinations by state, county and trade. It also distinguishes this from private-market rates and contractor billing, so an agent can tell it apart from sibling pricing tools like get_jccdb_labor_rate.

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 frames when this applies – minimums for federally funded construction – and adds a negation ('not private market rates or contractor billing'), which is the key disambiguation for this domain. It gives a concrete example invocation, though it never names an alternative sibling to route away to.

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. The description goes further, disclosing that every row carries a formula, source URLs with sha256, mapping confidence, and a BEA 2007 cross-check, and that values are flagged computed:true estimates. That provenance detail is genuinely additive, though auth/rate-limit behavior is not addressed.

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 content is front-loaded and each element is substantive, but the full text is duplicated verbatim in Japanese and English, roughly doubling the length without adding information. For an agent, the redundancy is tolerable but not tight.

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 a complex multi-stage pricing tool with an output schema and full annotation coverage, the description is largely complete: it covers inputs, data provenance, estimate status, and row contents. Minor gaps remain around when to choose it over sibling pricing tools.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters with examples. The description's examples (query='plywood', hs='2523290000') largely repeat what the schema provides, so the baseline of 3 applies.

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

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

States a specific verb+resource with full scope: computes U.S. prices for construction materials and chemicals at each distribution stage, from landed import cost through wholesale, retail and contractor. It names its data sources and inputs, making it clearly distinguishable from siblings like get_us_import_landed_cost or get_us_trade_margins.

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?

Explains how to invoke it (by HS 10-digit code or English product name) and gives concrete examples, plus a caveat that results are estimates not a verdict on a quote. It does not, however, explicitly say when to prefer this tool over the more granular sibling tools such as get_us_import_landed_cost.

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 a safe read-only, non-open-world operation, so the bar is lower. The description adds genuine value beyond that: source coverage and years, the kake_cost_ratio definition, and the caveat that figures are industry averages rather than a firm's actual purchase cost.

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, formula, optional BEA behavior and the industry-average caveat are front-loaded before the examples. It is dense bilingual text but each clause carries information; only the duplicated EN/JA phrasing adds 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?

An output schema exists, so return format need not be described. The description supplies source coverage, the derived metric definition, the optional BEA branch, and the key scope caveat, which is sufficient for an 8-param all-optional tool.

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

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

Schema coverage is 100%, so the schema already documents each parameter and the baseline is 3. The description goes further by showing the semantic link between commodity/include_bea and the optional BEA 2007 margin structure, and by mapping naics prefixes to trade categories.

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: returns U.S. wholesale and retail gross margins by NAICS, with named data sources (Census AWTS/ARTS/AIES) and the derived kake_cost_ratio. The resource is distinctive, but it does not distinguish itself from the sibling get_us_price_chain, which is also about a producer-to-purchaser price/margin chain.

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?

Examples (naics='4233', '444110') and the scope caveat 'industry averages, not any firm's cost' imply usage without stating when to pick this over alternatives. There is no explicit when-not guidance or named sibling such as get_us_price_chain for a full chain request.

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, openWorldHint=false, and destructiveHint=false, so safety and scope are covered. The description adds that each result includes an evidence URL proving existence in a public document, which is useful behavioral context, but with an output schema present, return-shape detail is largely unnecessary.

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?

Presented bilingually with the Japanese and English sections front-loaded and information-dense, though the bilingual duplication makes it longer than strictly necessary. Every sentence still carries routing or descriptive 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?

For a low-complexity read-only search tool with a full schema, annotations, and an output schema, the description covers what the tool does and when to prefer siblings. It is complete enough for an agent to select and invoke it correctly.

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

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

Schema description coverage is 100%, so all three parameters (query, limit, category) are already documented in the schema, including that query must be Japanese and examples. The description adds no syntax or semantic detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb (search), resource (JCCDB item catalogue, 95,403 items) and the kind of content returned (existence in public document + evidence URL). It also distinguishes itself from the work-category sibling ('工事カテゴリ(search_cost_category)に無い資材はこちら').

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 names what to use instead for regional, temporal, or price data ('地域・時点・価格は get_jccdb_observations') and for renovation work categories ('search_cost_category'). No explicit 'when not to use' exclusion beyond that, but the routing guidance is concrete.

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