horizon-shield

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

With readOnlyHint already covering safety, the description adds substantial behavioral context: full return payload (verdict, level, fair_range, danger_threshold, vs_avg_pct, advice, source), edge-case handling (did_you_mean, unit_mismatch), and JP-only/JPY scope. Doesn't state rate limits or failure modes, but the fallback behaviors are disclosed.

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?

Dense but earns its length: purpose, usage, return fields, edge cases, alternatives, and trigger phrases, all in two language blocks. Slightly repetitive across languages but well 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?

Output schema exists yet the description still conveys verdict semantics and edge cases, plus sibling routing, JP-only scope, and trigger phrases. Complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100% with rich per-parameter descriptions, so baseline 3 applies. The description adds minor complementary info (total vs unit mismatch, JPY, no tax normalization) already implied by schema.

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

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

States a specific verb (audit/判定) and resource (contractor quoted price vs HORIZON SHIELD fair-price ranges), and explicitly distinguishes from siblings get_price_range and verify_fair_price. Bilingual, front-loaded.

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

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

Explicit when-to-use ('手元に具体的な見積額がある時に使う') and names alternatives with their conditions: get_price_range for range-only, verify_fair_price for signed attestation. Trigger phrases reinforce context.

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

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

The description transparently discloses its limitation (covers representative tactics only) and claims universality across countries and languages. While it doesn't explicitly mention side effects, the read-only annotation already covers that, and the description adds useful behavioral context without contradicting annotations.

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

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

The description is well-structured and concise despite being bilingual. It includes the tool's purpose, examples, applicability, and a limitation in two compact sentences per language. No unnecessary verbosity or redundancy.

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

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

Without an output schema, the description gives a high-level indication that it returns warnings and recommended actions, which provides sufficient context for a simple tool. However, it could be more explicit about the exact output format or structure, so slightly below maximum.

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 single parameter 'text' is fully described in the schema as the expression/item of concern from an estimate or sales pitch, and the tool description reinforces this by referencing examples. The semantics are unambiguous and complete.

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

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

The description clearly states that the tool checks wording in estimates or sales pitches against known overcharge/high-pressure tactics and returns warnings with actions. It provides concrete examples (lump-sum, today-only discount, etc.) and explicitly notes it covers only representative tactics, which effectively distinguishes it from more comprehensive audit 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 implies use for quick red-flag screening by stating it covers representative tactics only, but it does not explicitly compare with alternative tools (e.g., audit_estimate, verify_fair_price) or specify when to prefer this tool. The universal applicability note gives some context, but the guidance is mostly implicit.

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

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

The description goes beyond annotations by explicitly stating that no payment or transfer is initiated and that each call appends one record to the public ledger, making the non-read-only side effect transparent. It also explains the verification mechanism (SHA-256, ledger, verify_url). There is no contradiction with the annotations: readOnlyHint=false and idempotentHint=false align with the stated append behavior.

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

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

The description is front-loaded with the most important safety information and is well organized, but it repeats the same non-payment and attestation concepts in Japanese and English. It contains more sentences than necessary for the additional value it provides, though the bilingual structure may be intentional.

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 covers the domain (Japan construction/renovation, JPY), the integration point (Cart Mandate before user signature), side effects (public ledger append), and verification mechanism. It provides enough context for an agent to call the tool correctly, and an output schema is present, so return-value details need not be in the description.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds context for quoted_price (fair-range verdict with within/above/below) and merchant (not used in judgment), but these are also present in the schema's field descriptions. It does not meaningfully augment 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?

The description states a specific verb and resource: it issues a FairPriceAttestation for AP2 agents and explicitly distinguishes this from payment execution. It clarifies that no funds move, which sharply separates it from any payment-related sibling. The parallel authorization/value framing makes the tool's role in the AP2 flow unambiguous.

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

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

The description tells the agent when to use the tool: before asking the user to sign a Cart Mandate, and it explains when to pass quoted_price to get a fair-range verdict. It does not explicitly name alternatives or state when not to use it, but the usage context is clear enough for an agent to select it among siblings.

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

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

Annotations only establish that this is a safe read on a closed set; the description goes well beyond them by disclosing the fail-closed listing rule, the no-referral/no-listing-fee neutrality, that pending stores are returned separately, and that a zero-match result is returned honestly rather than padded. These are exactly the behavioral traits an agent needs and cannot get from the schema.

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

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

Front-loaded with purpose, then edge-case behavior, then usage routing and triggers, so the ordering is sound. Length is inflated by full Japanese/English duplication, but that is defensible for a bilingual trigger surface rather than pure redundancy.

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

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

An output schema exists so return-value documentation is not required, and the description still covers the notable return behaviors (scores/tiers, separate pending list, honest 0 count). Combined with clear invocation routing and a closed-world small-directory caveat, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100% and both parameters (area, work) carry their own descriptions with examples, so the description adds no syntax or format detail beyond restating that lookup is by area and work name. Baseline 3 is appropriate 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?

States a specific verb and resource (find verified contractors on the Yakumo directory) and immediately scopes what makes the directory distinct: listing depends only on passing the KIRA audit, fail-closed, no fees. It also implicitly separates itself from the price-oriented siblings (get_price_range, audit_estimate) by declaring it never returns 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?

Explicitly names the precondition and the alternative path: use it after a price check when the user asks who to hire or which contractor can be trusted, and lists trigger phrases in both Japanese and English. It also states when-not: price lookup belongs to get_price_range / audit_estimate, not this tool.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds meaningful behavioral context: the tool returns an AgentCard URL and a skill list, and clarifies the boundaries of related services (e.g., property sale is handled by a licensed real-estate agent). This exceeds the annotation baseline without contradicting it.

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

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

The description is front-loaded with the key purpose but is written in both Japanese and English, duplicating the same content. This lengthens it unnecessarily, though the structure is clear and information is presented in a logical order.

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 provides enough context about what the tool returns and when to use it, and there is an output schema so return value details are not required. It could be slightly tighter, but it is complete for its narrow discovery purpose and includes additional useful context on related services.

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 covers 100% of them (none). With no parameters to describe, a baseline of 4 is appropriate. The description does not need to elaborate on parameter semantics.

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 the A2A Agent Card URL and the list of published skills, with a specific verb ('get'/'返す') and a distinct resource (the server's A2A agent card). It is distinct from sibling tools that audit estimates and check red flags, so there is no ambiguity about what this tool does.

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

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

It explicitly says to use the tool when an external A2A-capable agent wants to discover and connect to this server. It provides context for when it applies without giving formal 'when-not-to-use' exclusions, but that is sufficient given the tool's narrow, discovery-focused role.

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 meaningful context: the tool provides general knowledge content rather than a custom assessment, is applicable outside Japan, and is based on 30 years of field experience. 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 efficiently front-loaded with the core purpose and content topics, and every clause adds value—coverage areas, language agnosticism, and basis of authority. The bilingual duplication is acceptable given the tool's context, and there is no wasted content.

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 has no parameters, an output schema is present, and the description fully explains the tool's scope and content. It covers what the tool returns, how general it is, and why it is trustworthy. No additional context is needed 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?

With zero parameters, the baseline is 4. The description appropriately focuses on what the tool returns without needing to explain input semantics. It also indirectly clarifies there is no filtering or user-input dependency by describing the output as universal.

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 verb and resource: 'returns universal principles for judging whether ANY construction or renovation estimate is honest.' It also lists concrete content areas (overhead ratio, 一式 entries, sales tactics), which distinguishes it from sibling tools like audit_estimate or check_red_flags that perform targeted checks rather than provide general principles.

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 communicates clear context for use: it is a language-agnostic, universal guide applicable to any estimate, not a Japan-specific or single-estimate tool. However, it does not explicitly name alternatives or specify when not to use it, so it falls short of a 5.

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

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

The annotations already declare readOnlyHint=true and destructiveHint=false, so the safe read nature is covered. The description adds that it returns 'sources, update date and regional multipliers' and notes 'Japan' context. It does not describe output format or any edge cases, but with such a simple read-only tool and a readOnlyHint, this is adequate but not beyond the annotations.

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

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

The description is two concise sentences with no wasted words. It is front-loaded with the main purpose, includes the Japanese context, and provides a usage hint. Excellent structure for its purpose.

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 is simple, has an output schema, and has annotations for safety, the description covers the essential context. It explains the tool's scope (HORIZON SHIELD data, Japan), what it returns, and when to use it. It could mention that no parameters are needed, but that is implied by the schema. For a zero-parameter tool with an output schema, this is quite 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?

The tool has zero parameters, and schema description coverage is 100% (trivially). The description adds meaning by explaining what data is returned, which is the only semantic needed. Since there are no parameters to describe, the description fulfills its role well.

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. The verb 'get' and specific resource 'fair price sources' make the purpose clear. It does not explicitly differentiate from siblings like get_price_range or verify_fair_price, but the focus on metadata (sources, date, multipliers) is distinct enough.

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: 'Use to check the basis of a price.' This indicates when to use it. It doesn't explicitly mention alternatives or when not to use it, but the sibling tools like get_price_range or verify_fair_price are distinct enough that the usage context is reasonably clear.

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 a harmless read-only operation, and the description adds meaningful context beyond those annotations: it discloses dataset version, record counts, and the categories of metadata returned. This gives the agent a clear idea of what the tool provides without needing to invoke it.

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, bilingual, and information-dense without filler. The core operation is stated first, followed by the supporting dataset details and a one-line use-case sentence, so every sentence earns its place.

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, a present output schema, and annotations already covering the safety profile, the description provides all necessary context: what the tool returns, what dataset it describes, and when to invoke it. Nothing critical 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?

The tool takes zero parameters, so there is no parameter semantics burden on the description. The baseline of 4 applies, and the description appropriately focuses on what the response contains 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 uses a specific verb ('returns') and precisely identifies the resource (JCCDB metadata, scale, license, download links, citation). It also includes concrete dataset details (95,403 items, v4.0 counts) that make the tool's purpose instantly identifiable relative to the cost-related 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?

The description explicitly says to use this when looking for a primary construction-cost data source, giving clear contextual guidance. It does not explicitly name alternatives or state when not to use this tool, but the use case is specific enough to route an agent correctly.

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 declare readOnlyHint=true and non-destructive, and the description adds that it returns not just a range but also a danger threshold for suspected overcharging, unit info, price trends, and field notes. It also discloses Japan-specific pricing in JPY and mentions regional multipliers when a region is given. It does not detail rate limits or data freshness, but given the annotations cover safety, this is solid.

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?

Bilingual, front-loads the core purpose, then examples, then an English summary and trigger phrases. It is appropriately sized for a tool with detailed return fields, though slightly repetitive between the Japanese and English sections.

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 in detail, yet it still summarizes them. It covers purpose, usage context, and regional behavior. Minor gap: no explicit comparison to sibling tools like verify_fair_price, but otherwise complete.

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

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

Schema coverage is 100% and the schema already describes both the query and region parameters, including the regional multiplier behavior. The description adds no parameter syntax beyond what the schema provides, so baseline 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 a specific verb (returns) and resource (fair price range for Japanese construction/renovation jobs), naming the exact fields returned (min/avg/max, danger threshold, unit, trend, notes). It distinguishes itself from siblings like verify_fair_price or audit_estimate by being a lookup/reference tool that returns benchmark ranges rather than auditing a specific estimate.

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: use when you want to numerically check whether a construction or renovation cost is fair in Japan, with example categories and trigger phrases. It does not explicitly name alternative sibling tools or say when NOT to use it versus verify_fair_price or check_red_flags, but the context is clear enough.

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 safety is covered. The description transparently states the count (61), the data specificity (Japan-specific), and the nature of data (fair-price ranges and overcharge red flags). This adds value beyond annotations, though it doesn't detail pagination or return format (output schema exists).

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

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

Two sentences, both dense with relevant information: the count, the data purpose, the region. No filler, no repetition of the title or schema. Front-loaded with the purpose.

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 with 0 parameters and an output schema (which likely lists the categories). However, the description doesn't mention how the list is returned (detailed fields vs. names), or whether any filtering is possible. It is mostly complete for a simple list, but given the output schema exists, the description needn't explain return values. A score of 3 is fair: adequate but would be 4 with a hint about the output's shape.

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 0 parameters, so the baseline for parameter semantics is 4. The description doesn't need to add parameter meaning; it correctly describes the fixed output set. The schema covers everything, and the description complements it by specifying the scope.

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 it lists the 61 construction and renovation work categories for which HORIZON SHIELD maintains fair-price ranges and overcharge red flags. This clearly distinguishes it from sibling tools like search_cost_category (search) and get_price_range (query range), both in verb and resource.

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 is clear that this tool is for retrieving the category list. However, it does not explicitly state when not to use it or mention alternatives. Given the no-parameter nature and simple listing purpose, clear context is provided, but explicit exclusions are absent.

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 annotations (readOnlyHint=true, destructiveHint=false), the description discloses the tool's intentionally limited behavior: it does not return min/avg/max fair range or danger thresholds, only direction. This behavioral limitation is essential for setting correct expectations and is not visible in the schema or 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 bilingual description is somewhat long but each section earns its place: purpose, limitation, usage timing, alternatives, and locale constraints. It is front-loaded with the core behavioral result and avoids unnecessary flourish.

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, a 100% documented input schema, and strong annotations, the description adds the remaining necessary context: early-stage suitability, exclusion of detailed outputs, alternative tools, and Japan/JPY scope. This is complete for an agent to invoke the tool correctly.

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

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

Schema coverage is 100% with detailed descriptions for both parameters, including examples and partial-match behavior for work. The description adds context about comparing against an average but does not materially extend parameter semantics beyond what the schema already provides.

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

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

The description clearly states the tool's specific function: it returns only the direction of a contractor's rough estimate relative to the average (e.g., +20% above). It also explicitly distinguishes itself from siblings by noting what it does not return and naming alternatives like get_price_range and audit_estimate.

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

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

Usage context is explicit: it is for early-stage renovation planning before a detailed breakdown exists. The description gives clear when-to-use guidance and names specific alternative tools for different needs, making it easy for an agent to select correctly.

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 beyond that by specifying that it returns matching categories with red-flag counts and priority, and notes the Japan-specific nature. This gives the agent a clearer picture of the tool's output without contradicting annotations. A score of 4 acknowledges this 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 description is two sentences (in both Japanese and English) that are front-loaded with the core purpose, followed by examples. There is no redundant filler, and the structure effectively conveys the key information in a compact form. Achieves a perfect score for conciseness and clarity.

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 only one parameter, no nested objects, and an existing output schema, the description is sufficiently complete. It covers the search behavior, examples, and return value highlights (red-flag counts and priority). The tool's simplicity and the presence of an output schema mean no additional context is necessary.

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

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

The schema covers 100% of parameters with a simple description (工事名やキーワード), so baseline is 3. The description adds value by providing concrete example queries (外壁塗装, 浴室, 給湯器) and clarifying that Japanese keywords work best, which helps the agent form effective queries. This enrichment justifies one point above 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's purpose: 'Finds a construction-cost category by work name or keyword and returns the matching categories with red-flag counts and priority.' It uses a specific verb ('finds') and identifies the resource (construction-cost category) plus what it returns. It also gives concrete examples (外壁塗装, 浴室) that help distinguish it from siblings like list_cost_categories, which presumably lists all categories without a search query.

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 usage: use this tool when you need to search by a work name or keyword rather than listing all categories. It provides examples of suitable queries and notes that Japanese queries work best, which gives practical guidance. However, it does not explicitly mention alternatives like list_cost_categories or state when NOT to use this tool, so it stops 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 indicate a safe read-only operation, but the description adds meaningful behavioral context: the review is free, neutral, anonymous, and personal/contractor names are redacted before posting. It does not describe the exact return shape, but an output schema exists.

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

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

The description is compact, bilingual, and front-loaded with the core action. Both language versions add complementary value, and the 'Use when' sentence provides practical guidance without waste.

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

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

Given zero parameters, existing annotations, and an output schema, the description fully covers what the tool does, when to use it, and important behavioral caveats like redaction and free review.

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, which gets a baseline of 4. The description needs no parameter explanation and appropriately focuses on the tool's purpose and output.

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 a short guide and the submission URL for EHN,' an anonymous estimate review board. It clearly distinguishes this from sibling tools like audit_estimate or get_price_range by focusing on referral to a third-party review platform.

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 '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 mention when not to use it or name direct alternatives.

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

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

Beyond the readOnlyHint annotation, the description adds that the output is a tamper-evident record with a SHA-256 hash and explains the PTKA concept, providing useful behavioral context about the proof mechanism.

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 and relatively concise, but includes a philosophical explanation that is slightly extraneous. It front-loads the core function and structure is clear.

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, annotations covering safety, and a single parameter, the description provides sufficient context about the tool's purpose, usage, and underlying concept. It lacks some details about potential error cases, but these are likely in the output schema.

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

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

The single parameter 'work' is fully described in the schema with an example. The description does not add additional parameter semantics, but the schema coverage is 100%, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool returns a fair price as a tamper-evident record with a SHA-256 hash, and explicitly notes its use for verifying price authenticity. This distinguishes it from siblings like get_price_range or audit_estimate, which have different purposes.

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

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

It explicitly says 'Use when an agent needs to verify price authenticity,' providing a clear usage context. It does not name specific alternatives, but the context is clear enough from the sibling list.

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

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

The description goes beyond the readOnlyHint and openWorldHint annotations by detailing the fail-closed behavior, the SHA-256 recomputation, and the distinction between 'verified' (hash match) and 'audit ruleset still valid'. 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 thorough but slightly redundant (e.g., 'fail closed' and 'no price layer needed' appear more than once). However, the structure is logical, covering purpose, method, and caveats, and each sentence adds useful information.

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

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

Despite having an output schema, the description provides essential behavior context: return fields (result, failure_reason, etc.), edge cases (scope_check skipped if estimate_version omitted), and the crucial caveat that verified does not imply audit ruleset validity. This makes the tool's behavior fully understandable.

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

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

All three parameters are described with clear semantics: claim_sha256 as expected hash, signed_payload as verbatim string (with warning about mutation causing unverified), and estimate_version as optional for scope checking. This fully complements 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 explicitly states it verifies signed integrity claims from estimate-integrity-audit and distinguishes itself from verify_fair_price by noting 'no price layer needed' and 'opposite posture'. This clearly separates it from the sibling tools.

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

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

Provides explicit guidance on when to use (when you have signed_payload and claim_sha256) and how to invoke (optionally pass estimate_version to also check scope). It also clarifies that no issuer contact is needed and that it fails closed, which helps the agent decide.

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