HORIZON SHIELD

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

Annotations already declare readOnlyHint and destructiveHint false. The description adds behavioral details like return JSON fields, did_you_mean for no match, and unit_mismatch handling. 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 front-loaded with the core purpose in the first sentence, then elaborates logically. It is somewhat long but each sentence adds value, covering return values, edge cases, and usage gates. Bilingual content slightly increases length but remains efficient.

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

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

With no output schema, the description fully explains return JSON fields (verdict, level, fair_range, etc.), edge cases (did_you_mean, unit_mismatch), and data source. Given 2 parameters and complexity, it 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?

Schema coverage is 100% with both parameters described. The description adds context: 'work' should be specific Japanese and partial matching behavior, 'quoted_price' expects yen and explains tax handling and type normalization, surpassing 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?

The description explicitly states the tool audits a quoted price for fairness against a database, with specific verb 'audits' and resource 'fair-price ranges'. It distinguishes from sibling tools like get_price_range and verify_fair_price by clarifying different use cases.

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 when to use ('Use when the user already has a specific quoted amount') and when not to use ('For the typical range only use get_price_range; for a signed verifiable attestation use verify_fair_price'), providing clear alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, indicating a safe read. The description adds value by specifying what the tool returns (URL and skill list) and the kind of skills, 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 somewhat verbose, repeating the same information in Japanese and English. Could be shortened without losing meaning, but it is structured and readable.

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 (no parameters, no output schema), the description fully covers its purpose, return value, and usage context. Nothing 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 has no parameters and schema coverage is 100%. With 0 parameters, the baseline is 4, and the description does not need to add parameter details.

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 the A2A Agent Card URL and published skills for the server, using specific verbs like '返す/Returns'. It is distinct from all sibling tools (audit, estimate, price tools) which serve 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?

The description explicitly says 'Use when an external A2A-capable agent wants to discover and connect', providing clear context. It does not list alternatives but the sibling tools are unrelated, so the guidance 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?

Annotations declare readOnlyHint=true and destructiveHint=false, and the description expands on behavioral traits: it returns specific data fields (min, avg, max, danger, unit, trend, notes) and clarifies it is Japan-specific with JPY pricing. 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 reasonably concise but contains both Japanese and English full text, which doubles length. The key information is front-loaded (returns price range etc.), but the bilingual duplication could be trimmed for efficiency.

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

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

Given no output schema, the description adequately explains the return fields and domain context (Japan, JPY). It covers what the tool does and what kind of queries it accepts. It could mention error handling or data availability, but overall it is complete enough for a simple query 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 input schema has 100% coverage for the single parameter 'query', with a description in Japanese. The tool description adds value by providing example keywords (e.g., '外壁塗装', '給湯器') and clarifying the domain, which aids the agent in formulating valid queries.

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 that the tool returns fair price range (min, avg, max), danger threshold, unit, price trend, and field notes for Japanese construction/renovation costs. It gives concrete examples and states the use case. However, it does not explicitly differentiate from sibling tools like verify_fair_price or 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?

The description implies usage context ('Use to numerically check whether a cost is fair') and provides examples, but lacks explicit guidance on when not to use the tool or how it compares to siblings. No alternatives or exclusions are mentioned.

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, indicating a safe read-only operation. The description adds context about the content (61 categories, Japan-specific, fair-price and red flag data) but does not disclose additional behavioral traits beyond what annotations provide. Consistency between description and annotations is maintained.

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 (Japanese and English translation), with no unnecessary words. It is front-loaded with the key action and resource. Every sentence adds value, clearly stating what the tool returns.

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 parameterless tool with no output schema, the description covers the purpose and scope well. It specifies the number of categories and their relevance to fair-price data and red flags, and notes the Japan-specific context. It could be improved by briefly indicating the return format (e.g., a list of category names), but is 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?

With zero parameters and 100% schema coverage, the description does not need to add parameter details. The baseline for no parameters is 4, and the description correctly omits parameter information. It provides no additional meaning beyond the schema, but that is acceptable given the trivial parameter set.

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 lists 61 construction and renovation work categories for which HORIZON SHIELD maintains fair-price ranges and overcharge red flags. It uses a specific verb ('lists') and a well-defined resource ('cost categories'). It implicitly distinguishes from siblings like 'search_cost_category' by indicating it returns the full 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 you need the complete list of categories. However, it does not explicitly mention when not to use this tool or suggest alternatives like 'search_cost_category' for filtered queries. The absence of parameters makes the usage straightforward, but an explicit usage context would improve 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 declare readOnlyHint=true and destructiveHint=false, so no destructive behavior. Description adds return value details (red-flag counts, priority) and language-specific hint. 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?

Description is a single paragraph that is front-loaded with the main action and examples. Bilingual nature adds slight verbosity but is justified for Japan-specific 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?

For a simple search tool with one parameter, the description adequately covers return values, usage tips, and purpose. No output schema but return types are implied. Could mention pagination if applicable, but not necessary here.

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 already describes query parameter with 100% coverage. Description adds examples and language guidance (Japanese works best), enhancing meaning 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?

Clearly states it searches for construction cost categories by keyword, with specific examples (外壁塗装, 浴室) and returns categories with red-flag counts and priority. Differentiates from sibling list_cost_categories which likely lists all categories.

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 usage context: best with Japanese query and gives examples. Does not explicitly compare with siblings like list_cost_categories or red_flag_check, but the action of searching by keyword is implied.

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

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

The description adds behavioral context beyond the annotations (readOnlyHint, destructiveHint): it mentions that personal and contractor names are redacted before posting, that the review is free, and that it is a neutral third-party review. 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 extremely concise: two sentences in Japanese and two in English, with no unnecessary words. It front-loads the action and purpose immediately.

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 (no parameters, no output schema), the description covers all needed aspects: what it returns, when to use it, and key behavioral traits (redaction, free). It is fully adequate for an AI agent to understand and use 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?

There are zero parameters, so the baseline is 4. The description correctly does not attempt to describe parameters as none exist.

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 short guide and the submission URL for EHN' (an anonymous estimate review board). It explicitly distinguishes from siblings by specifying the use case: when the user asks for a second opinion on an estimate or where to have one reviewed. The verb 'returns' and resource are specific.

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 usage scenario: 'Use when the user asks for a second opinion on an estimate or where to have one reviewed.' This provides clear context, though it does not explicitly list when not to use it or mention alternatives by name.

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 valuable behavioral context beyond annotations: tamper-evidence, SHA-256 hash, Japan data, and philosophical background. Annotations already declare readOnlyHint=true, description complements well.

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 concise and front-loaded. Two clear sentences per language, no unnecessary 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?

Covers purpose, output type (tamper-evident hash), and data source. No output schema, but description hints at output structure. Could specify exact format, but sufficient for a simple verification 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%, description does not add extra parameter semantics beyond the schema. Baseline score of 3 applies.

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

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

Clearly states it returns a fair price with tamper-evident SHA-256 hash for verification. Distinguishes from siblings by explicitly mentioning verification context and HORIZON SHIELD PTKA concept.

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 usage for verification of price authenticity. Provides context but does not explicitly exclude other uses or name 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 annotations (readOnlyHint), the description reveals critical behaviors: fail-closed posture, exact verification logic, the limited meaning of 'verified', and that audit_ruleset_recheck is always not_performed. This fully informs the agent about behavior and limitations.

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

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

The description is thorough and well-structured, with key points bolded. It is front-loaded with the primary function. However, it is somewhat lengthy due to bilingual repetition, and a slightly more concise version would be ideal.

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 output schema, the description fully compensates by detailing return fields (result, failure_reason, trigger, etc.) and their interpretations. It also covers edge cases like scope_check behavior. All necessary context for correct invocation is present.

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

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

The input schema already has detailed descriptions for all three parameters (100% coverage). The tool description adds little new semantic information about the parameters themselves; it mainly repeats schema content. Some context is added for the optional parameter but does not significantly go beyond schema.

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

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

The description clearly states the tool verifies signed integrity claims by recomputing SHA-256, and explicitly distinguishes from the issuing side (verify_fair_price) with an opposite posture. It is specific and uniquely positions the tool among 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 explains the tool is for third-party verification of integrity claims, contrasting with the issuing side. It mentions optional scope checking but does not provide explicit when-not-to-use guidance or alternatives like audit_estimate. 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.