HORIZON SHIELD

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 by detailing the exact JSON return structure, did_you_mean fallback for unmatched work names, unit_mismatch handling, and data source attribution—providing substantial behavioral context beyond the annotations. No contradictions found.

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

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

The description is well-structured with clear sections: purpose, usage, return details, edge cases, and alternatives. However, it duplicates all information in both Japanese and English, doubling length without adding new content. This redundancy prevents a perfect score, though the structure remains logical and front-loaded.

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?

The description is complete for the tool's complexity: it explains return fields, handling of no-match and unit mismatch, constraints (Japan/JPY), and explicitly points to sibling tools for adjacent use cases. Even in the absence of a visible output schema, the description fully informs the agent about expected behavior and outcomes.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful parameter guidance: it warns that ambiguous 'work' strings increase mismatch risk, and that quoted_price is compared as-is without tax normalization. It also clarifies the unit_mismatch scenario, enriching understanding beyond the schema.

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

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

The description clearly specifies the tool's function with a strong verb ('audits' / '判定する') and a concrete resource (quoted price vs HORIZON SHIELD fair-price ranges). It explicitly differentiates from siblings by naming get_price_range and verify_fair_price as alternatives, making its unique role unmistakable.

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 explicit when-to-use guidance: 'Use when the user already has a specific quoted amount.' It also states contrasting situations for get_price_range and verify_fair_price, and adds a Japan-only/JPY constraint, covering both use and exclusion cases clearly.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds behavioral context beyond that: it returns warnings with actionable advice, covers only representative tactics, and works universally across countries/languages. This supplements the annotations without contradiction.

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

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

The description is bilingual (Japanese and English) and consists of four sentences, each adding necessary information: the core function, examples, universality, and a limitation. It is front-loaded with the primary purpose and is appropriately concise, though the bilingual duplication slightly increases length without adding new information for readers of both languages.

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 simple one-parameter tool with an output schema and annotations, the description is highly complete. It explains the input, the output (warnings and what to do), the scope (representative tactics only), and the universal applicability. No critical information is missing, and the output schema covers return value details.

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% (the 'text' parameter has a description), so the baseline is 3. The tool description adds meaningful semantics by providing concrete examples of what 'text' should contain (e.g., '一式', '今日だけ値引き') and clarifying it is the wording or item from an estimate or sales talk. This goes beyond the schema's generic description, enriching parameter understanding.

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: it checks wording in estimates or sales pitches against known overcharge or high-pressure tactics, then returns warnings and advice. It gives specific examples (lump-sum, today-only discount, free inspection) and distinguishes itself by noting it works for any country and covers only representative tactics, differentiating it from more exhaustive or regional 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?

The description provides clear context for when to use the tool (when you have concerning text from an estimate or sales pitch) and implicitly sets boundaries by stating it covers representative tactics only and works universally. However, it does not explicitly mention alternative tools or state when not to use it, falling just short of full guideline clarity.

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 readOnlyHint=false, and the description goes beyond by stating 'Each call appends one record to the public ledger, so it is not read-only.' This discloses the side effect and non-idempotency in a way annotations alone do not. It also clarifies it does not move funds, which is valuable context. 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 somewhat lengthy and bilingual, but every sentence adds important context, especially the safety disclaimers (no payment, ledger append) and AP2-specific use case. It is front-loaded with the most critical safety information. Slightly over-detailed but justified for a tool with significant side effects.

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?

The description thoroughly covers the tool's role, side effects, verification mechanism (SHA-256, public ledger, verify_url), optional verdict behavior, and domain scope (Japan construction, JPY). Given that an output schema exists, the description does not need to detail return values. It is complete for the complexity of this AP2 bridge tool.

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

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

Schema description coverage is 100%, and the schema descriptions for work, merchant, and quoted_price are already detailed. The description repeats what the schema says (e.g., quoted_price triggers a fair-range verdict) without adding new meaning beyond the schema. Therefore the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: issuing a FairPriceAttestation. It uses a specific verb ('issue') and resource, and explicitly differentiates itself from payment tools by stating it does not initiate, authorize, or execute payments. It also distinguishes from sibling verification/price tools by emphasizing it creates an attestation rather than verifying or reading prices.

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: it is a bridge for AP2 agents and the attestation should be attached to a Cart Mandate before user signing. It also explains optional use of quoted_price for a fair-range verdict. It does not explicitly name alternative tools or exclusions, but the context is strong and the sibling list makes alternatives obvious.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds valuable context by specifying what is returned (URL and skills list) and that it acts as an A2A entry point to the server's services, exceeding what annotations alone 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 bilingual, which duplicates content but remains focused and readable. It front-loads the core function (returns URL and skills) then adds context, making it efficient without being bloated.

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 parameters and an output schema present, the description fully covers what the tool does and when to use it. It explains the return type (Agent Card URL, list of skills) and ties it to the broader service context, making it complete for an agent to invoke correctly.

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

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

The tool has zero parameters, so the baseline is 4. The description does not need to define parameters, and the schema coverage is 100%, so there is no gap for parameter documentation.

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: 'Returns the A2A (Agent2Agent) Agent Card URL and the list of published skills for this server'. This is a specific verb+resource that distinguishes it from sibling tools, which focus on audits, estimates, and price verification.

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 explicit usage context: 'Use when an external A2A-capable agent wants to discover and connect'. This clearly indicates the intended scenario, though it does not enumerate exclusion criteria or alternative tools, which are not needed here given the tool's unique purpose.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable context about the output's nature (principles), its grounding (30 years of experience), and its global applicability, which gives the agent a richer understanding of what to expect. No contradictions with annotations.

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

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

The description is a single bilingual sentence that front-loads the core purpose and key topics. It is concise for the information provided, though the Japanese/English repetition adds length while serving a clear multilingual purpose. Every sentence has a role, so it earns a high score.

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

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

Given the tool has no parameters and an output schema exists, the description fully covers the tool's purpose, content, and scope. It explains what the guide includes, its universal applicability, and its basis, which is sufficient for an agent to decide when and how to invoke it.

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

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

The tool has zero parameters, and the schema leaves nothing to explain. The description does not need to elaborate on inputs; it instead clarifies the content of the returned guide, which is useful for the agent. Baseline for 0-param tools is 4, and this description is consistent with that.

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 universal principles for judging construction or renovation estimates, listing specific topics such as overhead ratio, lump-sum entries, and sales tactics. This specific verb+resource structure distinguishes it from sibling tools like audit_estimate (which likely analyzes a specific estimate) and get_price_range (which returns data).

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

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

The description provides clear context by emphasizing the guide is universal, language-agnostic, and works outside Japan, implying it is for general principles rather than region- or estimate-specific analysis. However, it does not explicitly name alternative tools or provide exclusion criteria, so it falls short of a perfect score.

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 the tool is read-only and non-destructive, so the safety profile is covered. The description adds useful context by detailing the specific data returned (sources, update date, regional multipliers) and noting the Japan scope. There is 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 highly concise, with two sentences plus a brief usage note, all front-loaded. There is no wasted wording; the bilingual format is acceptable and each phrase adds 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 zero-parameter, read-only tool with an output schema, the description covers purpose, usage, and return content sufficiently. The presence of an output schema means return-value details need not be in the description, making it contextually 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?

With zero parameters, the schema provides full coverage (vacuously), and the baseline is 4. The description adds meaning by clarifying that no input is required and that the tool simply returns provenance data, which aligns with the parameterless baseline.

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

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

The description clearly states the tool returns sources, update date, and regional multipliers for HORIZON SHIELD fair-price data, with a specific verb ('returns') and resource. It also includes a usage phrase ('Use to check the basis of a price') that distinguishes it from price-related siblings like get_price_range and verify_fair_price.

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 a clear when-to-use context ('Use to check the basis of a price'), which tells the agent when to invoke this tool. However, it does not explicitly mention alternatives or when not to use it, so it falls short of a full 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds useful dataset specifics (scale, version) but does not disclose any additional behavioral traits such as rate limits or response size. With annotations present, this meets the baseline without going further.

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 parallel sentences (Japanese and English) deliver the return payload and usage context without redundancy. Every clause adds value, and the description is front-loaded with the tool's function.

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

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

For a zero-parameter info tool, the description is complete: it covers purpose, output contents, and when to use it. The presence of an output schema further covers return format, so no meaningful gaps remain.

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

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

The tool has zero parameters, so the schema fully covers parameter semantics. Per the rubric, the baseline is 4 for no parameters, and the description appropriately focuses on output rather than inputs.

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

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

The description explicitly states the tool returns metadata, scale, license, download links, and citation for JCCDB, with a specific verb (returns) and resource. The bilingual text also gives concrete dataset facts (65,520 items, version breakdown), clearly distinguishing it from sibling tools focused on estimation or pricing.

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?

Crisp usage guidance is provided: 'Use when looking for a primary construction-cost data source.' This gives clear context for when to select it, though it doesn't explicitly name alternatives or exclusions, so a 5 is not warranted.

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, and the description adds behavioral detail: it enumerates the return fields and states that pricing is Japan-specific in JPY. This adds context beyond the annotations without contradicting them.

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 reasonably concise, with the first sentence stating the tool's function and the second providing usage context. The bilingual sections are not redundant; the English adds the 'Japan-specific pricing in JPY' detail. It is a bit lengthier than necessary but not wasteful.

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 a single parameter and an output schema, the description is quite complete. It covers what the tool returns, when to use it, and gives examples. It doesn't cover error handling or edge cases, but those are not critical for this simple 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 already describes the single query parameter as 'construction name or keyword (Japanese)', and the tool description reinforces this with concrete examples (e.g., outer wall painting, water heater, unit bath, cross). The description adds value with these examples, though the schema alone is fairly clear.

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 ('Returns') and resource ('fair price range') with detailed output components (min, avg, max, danger threshold, unit, price trend, field notes). It clearly distinguishes itself from sibling tools like verify_fair_price or get_fair_price_sources by focusing on the range lookup for construction/renovation jobs.

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 a clear when-to-use context: 'Use to numerically check whether a cost is fair' and includes concrete examples. However, it does not explicitly mention when not to use or name alternative sibling tools, so it falls short of the full 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds context beyond annotations: it specifies the data is Japan-specific and that categories relate to fair-price ranges and overcharge red flags, which is valuable for agent decision-making. No contradictions found.

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 two short sentences, one in Japanese and one in English, providing the key facts without any fluff. It front-loads the main verb and resource, and includes the count (61) and domain context efficiently.

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?

The tool is simple (no params, output schema exists, annotations present), and the description covers its purpose, scope, and relation to the fair-price domain. There is no missing critical information 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?

The tool has zero parameters, so the input schema is empty. Per the rubric, the baseline for 0 parameters is 4. The description doesn't need to explain parameter semantics, and it doesn't attempt to, which is appropriate.

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

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

The description clearly states the tool returns a list of 61 construction/renovation categories, with a specific verb (返す/Lists) and resource. It also distinguishes itself from siblings like search_cost_category by emphasizing it's the complete list, not a search.

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 this tool is used when an agent needs the full set of categories, mentioning '61 categories' and 'Japan-specific data'. However, it does not explicitly state when to use it versus search_cost_category or other siblings, nor does it provide exclusion criteria.

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, and the description adds key behavioral constraints: returns only a preview, not full range or danger threshold, and is Japan-only with JPY. No contradiction with annotations, and it discloses limitations that affect agent decisions.

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 concise and front-loaded, with the first sentence stating the core purpose. It uses bilingual text efficiently, blending Japanese and English without redundancy, and all sentences contribute to explaining functionality, limitations, or usage context.

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?

The tool is simple (2 params), has an output schema, and annotations. The description covers purpose, limitations, usage context, alternatives, and location/currency constraints, making it fully sufficient for an agent to invoke it correctly without needing additional information.

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% for both parameters (work and quoted_price), so the schema already provides full meaning. The description does not add extra parameter-level detail beyond restating the tool's purpose, so the baseline score of 3 is appropriate.

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

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

The description clearly states that the tool returns only the direction and magnitude of deviation from average (e.g., +20% above), and explicitly says what it does NOT return (min/avg/max range, danger threshold). It distinguishes itself from sibling tools get_price_range and audit_estimate, making its purpose unambiguous.

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

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

Explicitly says 'Suited as a first step before a detailed breakdown exists' and provides alternatives: 'Use get_price_range for a typical range, audit_estimate for a detailed quote diagnosis.' This gives clear when-to-use and when-not-to-use 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 and non-destructive behavior. The description adds useful context beyond that: it returns matching categories with red-flag counts and priority, and clarifies that the tool is Japan-specific and Japanese-query-friendly. This enriches the agent's understanding without contradicting the annotations.

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

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

The description is compact, with a clear front-loaded verb and purpose. Each sentence adds value: the first explains the action, the second gives examples and a localization note. No wasted words.

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

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

Given the tool's simplicity (one parameter, read-only, open output schema), the description covers all essential aspects: what it searches, what it returns, and usage tips. The return behavior is stated explicitly, and the output schema handles the rest.

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 input schema fully describes the sole parameter 'query' as a Japanese work name/keyword. The description adds concrete examples (外壁塗装, 浴室, 給湯器, 雨漏り) and emphasizes that Japanese works best, providing practical guidance beyond the schema.

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

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

The description clearly states a specific action: 'Finds a construction-cost category by work name or keyword' and returns matching categories with red-flag counts and priority. It distinguishes itself from the sibling 'list_cost_categories' by focusing on search/filtering, and provides concrete examples.

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 usage context: it is for finding a category by work name/keyword, and notes that Japanese queries work best. However, it does not explicitly name alternatives or state when NOT to use it, so it stops short of a 5.

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

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

The description adds meaningful behavioral context beyond the annotations: it states that posting and initial analysis are free, and that personal/contractor names are redacted before publication. This provides transparency about privacy and cost, which is not covered by the readOnlyHint or destructiveHint annotations. No contradictions with annotations.

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

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

The description is written in both Japanese and English with near-identical content, essentially doubling its length and reducing conciseness. Although the first sentence provides the core information, the redundant bilingual repetition means not every sentence earns its place. A single-language version would be more concise.

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

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

Given the tool's simplicity (0 params, read-only, output schema present), the description fully covers the purpose, usage, and key behavioral aspects. It clearly states what the tool returns (a guide and submission URL) and when to use it. There are no missing critical details.

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 input schema has zero parameters, so the baseline is 4. The description doesn't need to explain parameters and doesn't add any, but it does explain what the tool returns (guide and URL), which is relevant for expected output. No parameter details are missing because there are none.

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: returning a guide and submission URL for the EHN anonymous review board. It uses specific verbs ('Returns', '返す') and identifies the resource, distinguishing it from sibling analysis tools like audit_estimate or check_red_flags by focusing on referral rather than direct analysis.

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

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

The description explicitly provides a usage condition: 'Use when the user asks for a second opinion on an estimate or where to have one reviewed.' This gives clear context, though it does not explicitly mention when not to use the tool or alternative tools, so it falls short of a 5.

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

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

The description adds meaningful behavioral context beyond the annotations (readOnlyHint=true): it states the output includes a SHA-256 hash, making it tamper-evident, and explains the PTKA recording concept. No contradictions with annotations. It does not disclose potential errors or limitations, but for a simple read tool with an output schema, this is sufficient.

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 moderately concise; it front-loads the key function (returning a verifiable fair price with hash) but includes a fairly long explanation of PTKA philosophy and a duplicate English translation. It is not overly bloated, but could be trimmed for tighter structure.

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

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

Given the tool's simplicity (one required parameter, output schema available, read-only annotation), the description covers purpose, use case, and key output characteristics. It does not describe the return structure, but the output schema covers that. It also notes 'Japan price data,' adding scope clarity. Overall adequate for selection and invocation.

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

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

Schema coverage is 100% — the single 'work' parameter is explained in the schema (e.g., construction name). The description does not add further parameter details, but the schema already provides adequate meaning. Baseline 3 applies.

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

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

The description clearly states the tool's function: it returns a fair price for construction work with a SHA-256 hash, making it a tamper-evident record. It explicitly mentions the PTKA concept and the use case 'when an agent needs to verify price authenticity,' which differentiates it from sibling tools like get_price_range.

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 a clear 'use when' statement ('Use when an agent needs to verify price authenticity') but does not explicitly mention when not to use it or compare to alternatives like verify_integrity_claim. This gives clear context but lacks 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?

Beyond the readOnlyHint=true and destructiveHint=false annotations, the description adds significant behavioral context: fail-closed default, recomputation of SHA-256 over the raw string, and the critical caveat that verified does not guarantee audit ruleset validity (audit_ruleset_recheck always not_performed). This fully discloses behavior and edge cases.

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 due to bilingual formatting, but it is front-loaded with the core purpose and structured logically: what it does, how it works, important caveat, optional behavior. Every sentence is informative and contributes value, with 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?

The description fully covers the verification workflow, including failure modes, the exact meaning of the result, and the optional scope check behavior. Even with an output schema present, it explains all critical return fields and the always-not-performed audit_ruleset_recheck, making the tool's behavior unambiguous and 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 description coverage is 100%, so baseline is 3. The schema already explains each parameter's meaning, including verbatim requirement and optional scope check. The description repeats some of this information but adds minimal new semantic detail beyond what the schema 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?

The description clearly identifies the action: verifies a signed integrity claim (signed_payload and claim_sha256) issued by estimate-integrity-audit, as an independent third party. It contrasts with the issuing side (verify_fair_price), distinguishing it from the sibling tool and specifying the exact resource and verb.

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

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

The description explicitly states the fail-closed posture and explains when to pass the optional estimate_version: passing it triggers scope checking, omitting it yields scope_check:skipped. It also clarifies that no issuer contact or price layer is needed, and the role is opposite to verify_fair_price, giving clear usage context and exclusions.

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