HORIZON SHIELD — construction & renovation estimate auditor

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

Annotations already declare readOnlyHint=true and destructiveHint=false, making safety clear. The description adds behavioral context: partial match logic, error handling with did_you_mean and unit_mismatch, and return structure with verdict, level, fair_range, etc. This goes beyond 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 lengthy due to bilingual (Japanese and English) repetition. It is front-loaded with key information but could be more concise by avoiding duplication. However, it is well-structured within each language section.

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 annotations, full schema coverage, output schema mentioned, and sibling tools, the description is complete. It covers error cases, unit mismatch, alternatives, and usage constraints, making it fully informative for an AI agent.

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

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

Schema coverage is 100% with detailed descriptions for both parameters (work and quoted_price). The tool description reinforces usage but does not add new parameter semantics beyond what the schema already provides. 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 audits a quoted price against fair-price ranges for Japanese construction, with specific verb 'audit' and resource 'fair price'. It distinguishes itself from siblings like get_price_range and verify_fair_price by specifying when to use each alternative.

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

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

Explicitly says 'Use when the user already has a specific quoted amount.' and provides exclusion criteria: for typical range only use get_price_range, for signed attestation use verify_fair_price. Also notes 'Japan only, JPY' as a usage constraint.

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?

Adds value beyond annotations: notes universal applicability and limited coverage of known tactics. Aligns with readOnlyHint and openWorldHint. No contradictions.

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

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

Bilingual but concise; each sentence adds information. Front-loaded with purpose and examples. 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 output schema exists, description completes the picture: covers purpose, scope, usage, and parameter. No gaps for this simple classification 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% and description reinforces parameter meaning with examples and language flexibility. Adds helpful context for what type of text to input.

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?

Describes specific verb+resource: checks wording for known overcharge tactics. Provides concrete examples and explicitly states coverage is limited to representative tactics. Clearly distinct from sibling tools like audit_estimate or verify_fair_price which have broader scope.

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

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

Explicitly states it works for any language and covers only representative tactics, guiding when to use and scope limitations. Does not directly compare to alternatives but context is sufficient.

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?

There is a contradiction: the description says the tool 'issues' and 'creates' an attestation (a write operation), but the annotation readOnlyHint=true indicates the tool is read-only. This inconsistency confuses the agent about side effects. No additional behavioral context beyond the contradictory 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 includes both Japanese and English, which adds redundancy. It is front-loaded with key information but could be more concise. Each sentence adds some value, but the bilingual repetition increases length unnecessarily.

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 an output schema and the description covers purpose, usage, and verification method, it is mostly complete. However, the annotation contradiction undermines trust, and the description does not elaborate on the return structure (though the output schema exists). Adequate but could be better.

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 100% schema coverage, the baseline is 3. The description adds value by explaining that quoted_price triggers a fair-range verdict and that merchant is optional and not used for judgment. It provides functional meaning beyond the schema descriptions.

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

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

The description clearly states the tool creates a FairPriceAttestation for AP2 agents to attach to a Cart Mandate. It specifies the verb 'issues' and the resource 'FairPriceAttestation', and distinguishes it from sibling tools like verify_fair_price and 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 explains when to use this tool (when agents need a fair-price attestation before user signing) and that passing quoted_price enables a fair-range verdict. It does not explicitly state when not to use it, but context implies it is for creation, not verification.

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=true and destructiveHint=false. The description adds that the tool returns a URL and skill list, which is consistent. It doesn't disclose additional behavioral traits like rate limits or auth needs, but the annotations cover the safety profile adequately.

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 includes domain-specific details (construction audit, property acquisition) that may be extraneous for an agent. It is longer than necessary; a single sentence in English would suffice.

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 no parameters and an output schema present, the description provides sufficient context: it states the return value (URL and skill list) and the purpose (A2A discovery and connection). The output schema likely details the structure, so this is 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?

No parameters are defined (schema coverage 100% with zero params). Per calibration, 0 parameters defaults to baseline 4. The description does not need to add param info.

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 title 'Get A2A Agent Card' and description clearly state the tool returns the agent card URL and published skills. It is distinct from sibling tools which focus on estimate auditing and price verification, so the purpose is well-differentiated.

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 'Use when an external A2A-capable agent wants to discover and connect', providing clear context. While it doesn't state when not to use or name alternatives, the sibling tools are thematically different, making the usage intent 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 declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds non-obvious context: it is based on 30 years of field experience and is language-agnostic, which goes beyond the annotations. No contradictions.

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

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

The description is extremely concise, with two sentences (Japanese and English) that front-load the core purpose. Every sentence adds value: the primary function, topics covered, and key attributes (language-agnostic, experience-based). No redundant 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?

Given zero parameters and the existence of an output schema, the description adequately covers the tool's functionality. It explains what the tool returns and its basis, leaving no obvious gaps for an agent to understand the tool's role.

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 fully covered. The description does not need to add parameter details, and the baseline score of 4 applies. No further semantics needed.

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/renovation estimate honesty, listing specific topics like overhead ratio, lump-sum entries, and sales tactics. It also notes language-agnostic functionality, making the purpose distinct and well-defined.

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?

No explicit guidance is provided on when to use this tool over siblings like audit_estimate or check_red_flags. The description only describes what the tool does, leaving the agent to infer usage context without clear differentiation or prerequisites.

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=true and destructiveHint=false. The description adds that the tool returns specific data (sources, update date, regional multipliers) and scopes it to Japan, which provides 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?

The description is short and front-loaded with the key information in English, but includes a duplicate Japanese version that adds length without new value. It is mostly 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 no parameters and the presence of an output schema, the description adequately covers the tool's purpose and return values. It does not mention error states or edge cases, but for a simple read-only tool this is acceptable.

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 and schema coverage is 100%, so no parameter documentation is needed. The description does not need to add parameter semantics, earning a baseline score of 4.

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 returns 'sources, update date and regional multipliers' for HORIZON SHIELD fair-price data, with a specific use case: 'check the basis of a price'. This clearly distinguishes it from siblings like get_price_range or 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 includes a clear usage context ('Use to check the basis of a price'), but does not provide when-not-to-use information or mention alternatives among sibling tools.

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. The description adds context about the dataset size (65,520 items) and version breakdown (v3.0: 13,207 verified + 52,313 extended), which is beyond 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 sentences (one Japanese, one English) are clear and front-loaded. The bilingual format adds length but doesn't hinder understanding. Could be slightly more concise, but not excessive.

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 no parameters and an output schema (assumed from context signals), the description covers return types and dataset context. It is complete for a simple info retrieval 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?

No parameters exist (0 params), and schema coverage is 100% trivially. Baseline for 0 params is 4; description adds no param details but doesn't need to.

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 the JCCDB, a specific database. It distinguishes from siblings by being the only dataset info tool.

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 says 'Use when looking for a primary construction-cost data source,' providing clear context. No explicit when-not or alternatives, but siblings are distinct tools, so confusion is unlikely.

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 the description adds significant behavioral context: it returns price range, danger threshold, unit, trend, and notes, and specifies Japan-specific pricing in JPY. No contradictions.

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

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

The description is bilingual but tightly written: two sentences per language, front-loaded with the most critical info (what it returns, when to use, examples). Every sentence earns its place without redundancy.

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

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

Despite having an output schema (not shown), the description explains the full set of return fields, usage context, geographic scope (Japan), and currency (JPY). Given the complexity and sibling tools, it provides all necessary context for correct invocation.

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

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

Schema coverage is 100% (one param 'query' described in schema). The description adds real-world examples of valid queries (e.g., 外壁塗装, 給湯器) and states the language is Japanese, which enhances usability beyond the schema description.

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 range (min, avg, max), overcharge threshold, unit, price trend, and field notes for Japanese construction/renovation jobs. It gives examples like '外壁塗装, 給湯器' but does not explicitly differentiate from siblings like 'get_fair_price_sources' or '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 explicitly says to use when checking if construction/renovation costs are fair numerically (e.g., 建設・リフォーム費用が適正か数値で確かめたい時に使う). It does not provide when-not-to-use or mention alternative tools, but the clear context compensates.

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 description adds value by specifying the exact count (61), the data source (HORIZON SHIELD), and the Japan-specific scope, which are not in 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 concise, with two short sentences (bilingual) that are front-loaded and provide all necessary information without redundancy. 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?

Given zero parameters and the presence of an output schema, the description is complete. It explains the purpose and scope of the list, leaving no gaps for the agent.

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

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

There are no parameters, so the baseline is 4. The description adds meaning by explaining what the output list contains, which goes beyond the empty input schema.

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

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

The description clearly states the tool returns a list of 61 construction categories with fair-price ranges and red flags, using a specific verb ('リストを返す' / 'lists') and resource ('cost categories'). It distinguishes from the sibling 'search_cost_category' by specifying the fixed, complete 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?

The description implies use when the full list of cost categories is needed, but does not explicitly state when not to use or compare with alternatives like 'search_cost_category'. Still, the context is clear and the zero-parameter input makes usage straightforward.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false; description adds that it returns only direction (no min/avg/max) and that it is Japan only, JPY, providing additional useful context beyond 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 bilingual paragraphs are front-loaded with purpose and usage; each sentence adds value, though could be slightly more concise without losing 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?

Given output schema exists, description adequately covers what the tool returns and does not return; mentions early-stage use case, geographic scope, and currency.

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 description adds little beyond what schema already provides for parameters; description explains 'work' is Japanese, partial match, and 'quoted_price' is number in yen, but these are already in schema 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?

Description clearly states it returns only the direction of a contractor estimate versus average (e.g., +20% above), explicitly distinguishing from siblings like get_price_range and audit_estimate which provide range or detailed diagnosis.

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 it is for early-stage planning before a detailed breakdown exists, and provides alternatives: get_price_range for typical range, audit_estimate for detailed diagnosis.

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?

Descriptions add that tool returns 'red-flag counts and priority', which are not in annotations. Annotations already declare readOnlyHint=true and destructiveHint=false, so no contradiction. Additional info on output complements the behavioral profile.

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 description is front-loaded with the action, includes examples, and stays within two sentences per language. Slightly verbose with both languages but acceptable for a bilingual tool.

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

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

Given the presence of an output schema (not shown but known), the description covers input guidance and hints at return values (red-flag counts, priority). No additional information needed for this simple search 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% with a clear description for 'query'. The tool description adds examples and specifies 'by work name or keyword', which enhances meaning beyond the schema alone.

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?

Clearly states verb 'Finds' (検索する), resource 'construction-cost category', and scope 'by work name or keyword'. Provides concrete examples (外壁塗装, 浴室) and distinguishes from sibling 'list_cost_categories' by implying search vs. 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?

Explicitly notes 'Japan-specific; a Japanese query works best', guiding agents to use with Japanese queries. Does not explicitly exclude alternatives, but context implies it is for targeted search rather than browsing all categories.

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 destructiveHint=false, and the description aligns by stating it returns a guide and URL with no side effects. It adds detail about redaction of personal names and free initial review, enhancing transparency 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 two sentences in both languages, efficiently front-loaded with the key action and use case. Every sentence provides essential information with no redundancy.

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

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

Given no parameters and an existing output schema, the description adequately explains the tool's return value (guide and URL) and process. It could briefly note that it does not perform any submission, but overall it is complete enough.

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 no parameters, so the baseline is 4. The description adds meaning by explaining the output content and context, which is not captured in the empty schema.

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

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

The description clearly states the tool returns a guide and submission URL for EHN, an anonymous review board for estimates. It specifies the verb 'returns' and the resource 'guide and URL', and distinguishes from siblings as no other tool provides this specific board information.

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 when the user asks for a second opinion on an estimate or where to have one reviewed. This provides clear positive guidance, though it lacks explicit negative or alternative suggestions.

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 adds behavioral context: it produces a tamper-evident record with SHA-256 hash, which is beyond what annotations provide. No contradictions.

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

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

The description is two paragraphs (Japanese and English), somewhat verbose. While it front-loads the core function, the repeated bilingual content could be more concise. It is adequate 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 the complexity of the tool (cryptographic signing), the output schema exists and the description explains the tamper-evident nature. The context of PTKA and Japan price data adds completeness. Could mention output schema format but not required.

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

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

Only one parameter (work) with 100% schema coverage. The description does not add extra meaning beyond the schema's property description. Baseline 3 is appropriate since schema already handles it.

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 SHA-256 hash, under HORIZON SHIELD PTKA. It distinguishes from siblings like get_fair_price_sources and audit_estimate by focusing on verifiable signing and tamper evidence.

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 'Use when an agent needs to verify price authenticity.' It provides context about PTKA and third-party recording. However, it does not explicitly exclude alternatives or mention when not to use.

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

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

Beyond annotations (readOnlyHint, destructiveHint), the description discloses behavioral traits like 'fail closed', 'no issuer contact', 'audit_ruleset_recheck always not_performed', and scope check logic. 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 front-loaded with purpose and key warnings, but includes redundant bilingual text (Japanese and English) that could be streamlined. However, each sentence provides essential information without fluff.

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 moderate complexity (3 params, output schema exists), the description covers verification logic, failure reasons, scope check behavior, and the important caveat about not guaranteeing audit rule validity. It is fully self-contained.

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 description adds meaningful context: for signed_payload it warns that any change causes mismatch; for estimate_version it explains its computation and the effect on scope check. This enhances understanding beyond bare schemas.

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

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

The description clearly states it verifies a signed integrity claim as an independent third party, contrasting with the issuing-side tool verify_fair_price. The verb 'verifies' paired with 'signed integrity claim' makes the resource and action 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 explicitly explains when to use (independent verification, distrust default), when-not (no issuer contact needed), and alternatives (verify_fair_price). It also guides parameter choice: pass estimate_version for scope check or omit for skipped scope.

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