Guardian Engine

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

Annotations already declare readOnlyHint=true and idempotentHint=true, lowering the bar. The description adds valuable context: it returns a detailed audit trace mapping each ingredient to EU Annex II allergen groups with entry numbers and labels, and explicitly states the safety verdict is deterministic with no LLM involvement. This goes beyond the annotation claims.

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 three focused sentences, front-loaded with the core purpose. Each subsequent sentence adds actionable usage detail without redundancy or filler, making it highly 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?

Given the 5 parameters, an output schema, and annotations that cover safety, the description covers the main use cases and behavioral guarantees (deterministic verdict, audit trace). It provides enough context for an agent to decide when to call the tool and what to expect, without needing to explain return values since an output schema exists.

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

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

Schema coverage is 100%, so the baseline is 3. The description enriches parameter semantics by explaining when to use check_all_eu_allergens (food labelling) and restrictions (specific allergies), adding practical usage context that the schema does not fully convey.

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 opens with a specific verb and resource: 'Check ingredients for EU FIC 1169/2011 allergen compliance.' This precisely states the tool's function and clearly distinguishes it from siblings like check_safety or verify_dietary_claim by naming the regulation and the allergen focus.

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 usage guidance for two main modes: check_all_eu_allergens=True for food labelling and restrictions=['dairy','gluten'] for specific user allergies. This gives clear context on when to use the tool, but it does not name alternative tools or explicitly state when not to use it, so it earns a 4 rather than a 5.

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

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

The description discloses behavior beyond the readOnlyHint and idempotentHint annotations: the verdict is 'a deterministic function of (candidate, kb_version_hash) — no LLM involvement' and the checks are precisely enumerated (poultry ≥74°C, 14 allergen groups). It also details the return envelope components, adding valuable transparency about outputs.

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: a lead sentence, a purpose statement, a usage note, and a brief return summary. Each sentence contributes meaning, though some redundancy exists between the first paragraph and the schema description. It is not overly verbose and front-loads the core 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's complexity and the presence of an output schema, the description is complete: it explains what the tool does, when to use it, that it is deterministic and read-only, and what the return envelope contains. No major gaps remain for an agent to 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?

The schema already covers the sole parameter (candidate_json) with 100% description coverage, including the checks performed. The description reiterates these semantics without adding new parameter-level details. Since the schema does the heavy lifting, 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's function: 'Run master-independent safety checks on a candidate recipe.' It specifies the exact checks (poultry temperature and 14 EU FIC allergen groups) and differentiates from siblings by emphasizing 'no dish resolution, no master SOP required' and explicitly contrasting with verify_recipe when no master exists.

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?

Direct usage guidance is provided: 'Use this when verify_recipe has no matching master for the dish: the safety layer still applies to every recipe.' This clarifies the intended context and distinguishes it from the alternative verify_recipe. The phrase 'Works for ANY recipe' also sets boundary conditions.

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 far beyond the annotations by detailing the deterministic process (verify, apply corrections, re-verify), listing the types of corrections applied, and explicitly disclosing what is NOT auto-applied (e.g., adding phases, rewriting instructions, allergen fixes). It also explains the response includes verdict before/after, which is valuable behavioral context. No contradiction with annotations (readOnlyHint=false, idempotentHint=true).

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 front-loaded with the primary purpose, but it contains redundancy: the caveat about structural changes and patches_skipped is repeated in the final note. This slight repetition prevents a perfect score, though each sentence otherwise 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?

For a tool of this complexity, the description is highly complete: it explains the repair process, limitations, return semantics (verdict before/after, patches_skipped), and important caveats. With an output schema and annotations present, the description covers all necessary behavioral and contextual aspects.

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 6 parameters are fully described in the schema (100% coverage), so the description does not need to add parameter-level detail. The description adds minimal parameter-specific information but the schema already provides accurate descriptions, including aliases and optionality. 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 the tool's function with a specific verb and resource: 'Deterministically repair a candidate recipe against a Guardian master.' It distinguishes itself from siblings like verify_recipe by focusing on repair and applying machine-actionable corrections. The scope is explicit and 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 provides clear context on when to use the tool (to repair a candidate recipe) and explicitly warns about limitations (structural changes and allergen findings are not auto-fixed; verdict_after may still be FAILED). It does not name alternatives directly, but the context and caveats guide appropriate use effectively.

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 and idempotentHint, but the description adds rich behavioral context: no LLM in the hot path, transparent content per ADR-009/010, no score, and structured UNKNOWN_DISH error. This goes well beyond the annotation hints.

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 dense but every sentence earns its place: purpose, usage, transparency guarantees, return content, and error handling. Structured with line breaks for readability; appropriately sized for a tool with this complexity.

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?

Provides complete context: when to use, what it returns, what it doesn't return (score), and error behavior. Combined with annotations and output schema, the agent has everything needed to invoke correctly.

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

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

Schema coverage is 100% with detailed descriptions for both parameters. The description adds some behavior (unknown dish error) but does not materially enhance parameter semantics beyond the schema. Baseline 3 applies.

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

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

The description clearly states 'Return the canonical master recipe for a dish' with a specific verb and resource. It distinguishes the tool from siblings by positioning it as the reference lookup step before verify_recipe, contrasting with verification 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?

Explicitly describes the compare-then-verify agentic loop, directing the agent to fetch the master, diff, then call verify_recipe. It also clarifies that this is not for scoring (no verdict per ADR-013), preventing misuse.

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 disclose readOnlyHint and idempotentHint, so the safety profile is covered. The description adds value by specifying the return structure (dictionary with schema_version and dishes list) and mentioning that filter is case-insensitive exact match, which goes 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 concise and well-structured, starting with a clear action and then providing necessary return details in a compact format. Every sentence adds useful information 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?

For a simple list tool with one optional parameter and an existing output schema, the description is sufficiently complete. It explains the core behavior, return format, and key fields, while relying on the output schema for deeper metadata details.

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

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

Schema description coverage is 100% for the single parameter, including valid values and matching behavior. The description itself does not describe the parameter, but the schema already provides full semantics, so a baseline score of 3 is appropriate.

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

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

The description clearly states 'List all available master dishes' with a specific verb and resource. It also distinguishes itself from siblings by emphasizing 'all available' and listing rich metadata, which contrasts with tools like get_master that likely fetch a single dish.

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 by describing the list-all scope and optional cuisine filter, but it does not explicitly mention when to use this tool versus siblings like get_master or verify_recipe. No exclusions or alternatives are stated, providing only implied guidance.

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

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

Beyond the readOnly/idempotent annotations, the description discloses that verification combines existing allergen logic with a curated YAML map, and promises a structured verdict with offending ingredients and a short justification, adding strong behavioral specificity.

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 tight sentences lead with the core action, then add implementation and output details; no filler.

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

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

For a read-only verification tool with annotations and an output schema, the description covers purpose, mechanism, and result shape. It lacks only explicit sibling differentiation, but that is already captured by the tool's naming and usage guidelines dimension.

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

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

Schema coverage is 100%, so the baseline is 3. The description itself does not elaborate on claim, candidate_json, or response_format; those are already described in the input schema, and the tool description adds no param-specific information.

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 opens with a specific verb and resource—'Verify that a recipe satisfies a dietary claim'—and enumerates claim types (vegan, halal, gluten-free), clearly distinguishing it from sibling check_allergens by focusing on dietary labels rather than allergen presence.

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 gives clear context: this tool verifies dietary claims and reuses allergen-detection logic, implying a relationship to check_allergens. It does not explicitly name alternatives or state when not to use it, so it stops short of a 5.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses substantial behavioral detail: verdict is strictly PASSED or FAILED with policy thresholds (any CRITICAL or >5 WARNINGs fails), there is no score, issue is machine-readable and must not be shown to users, and both json/text formats are transparent. 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 four focused paragraphs with bold labels, front-loaded with a clear purpose statement. Every sentence carries policy, field-audience, or format information; there is no filler 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?

Coupled with the rich schema and annotations, the description fully prepares an agent: it explains verdict policy, field audience, response formats, and transparency guarantees. Since an output schema exists, not detailing every return field in the description 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?

Schema coverage is 100%, so the baseline is 3. The description adds meaningful context beyond the schema's one-line parameter descriptions by explaining response_format behavior ('structured JSON by default... response_format="text" renders a human-readable report'), verdict/findings semantics, and the candidate_json verification dimensions.

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 opens with a specific verb ('Verify') and resource ('candidate recipe against a Guardian master recipe'), and then enumerates the verification dimensions (technique, temperature, timing, cooking medium, required ingredients). This clearly distinguishes it from narrower sibling tools like check_allergens, check_safety, and verify_dietary_claim.

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 clearly frames when to use this tool—verifying a candidate recipe against a master—and explains when to include original_prompt and how response_format changes output. However, it does not explicitly name alternative tools or state when NOT to use this tool (e.g., for allergen-only checks), so it stops short of full usage exclusion guidance.

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