HACCP Bulgaria

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real behavioral context beyond that: the call is free, needs no personal or company data, creates nothing, and the module reasons come back in Bulgarian. It does not describe pagination/latency or edge cases, so a 4 rather than 5.

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?

Three sentences, front-loaded with the return value, followed by cost/privacy constraints and the asking rule. No filler. Slightly dense but every clause carries 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?

For a tool with a deep nested input schema and no output schema, the description does the important work of summarizing the return payload (modules + reasons + pages + price) and stating that the operation is read-only and free. Remaining gaps (invalid/partial facility data, what a 'final' price implies) are minor.

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?

Top-level schema description coverage is 0% (the single `facility` object has no description), but its nested properties are heavily documented in the schema itself. The description only adds the interaction rule 'ask, don't guess the assortment', which is useful but does not explain what the facility object must contain or how field choices change the result.

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 concrete verb and resource: it returns the HACCP modules, the reason per module (in Bulgarian), approximate page count and the one-time price for a Bulgarian food business. That is a specific, distinctive output that separates it from haccp_options and haccp_prepare_order, though the description never names those siblings explicitly.

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?

Gives clear preconditions and a strong prohibition: 'Ask the person about their facility and food first; do not guess the assortment.' It also clarifies scope (free, no personal/company data, creates nothing). It stops short of explicitly routing to a sibling tool when the user wants something else, so not 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?

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds a genuinely useful behavioral contract not present in annotations: the returned values are authoritative Bulgarian literals that must be passed verbatim downstream. It stops short of describing result size or pagination.

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 with zero filler. The content enumeration comes first and the call-ordering plus value-fidelity rule follows, so the actionable instruction is front-loaded after the essential scope.

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 carries the burden of describing the return value, and it does so by naming the four answer categories. For a zero-parameter lookup tool this gives an agent everything needed to call it and use the result correctly.

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

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

The tool takes zero parameters, so the baseline is 4. The description adds value by clarifying that the payload is an enumeration of allowed values rather than a computed result, though there is nothing parameter-level to explain.

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 ('Lists') and resource ('every allowed answer of the HACCP Bulgaria questionnaire'), then enumerates the answer categories (facility types with prices, rooms, work steps, food groups). This is clearly distinguishable from the two siblings, which consume rather than expose these values.

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?

'Call it first' gives explicit ordering, and 'use only these exact Bulgarian values in haccp_check and haccp_prepare_order' names both alternatives plus the constraint that selects correct usage. Nothing is left to inference about when to reach for 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 only mark this as a non-idempotent, non-destructive write. The description adds real behavior the annotations cannot express: the draft expires after 7 days, only a link is produced rather than a completed order, payment and legal consents stay with the person, and the 'message' field must be surfaced. The ЕГН prohibition is an important safety constraint found nowhere in structured fields.

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 the core effect ('Saves the answers as a draft for 7 days and returns a link'), then the handoff instructions, then the guardrails. Every sentence carries an actionable instruction — expiry, handoff, payment boundary, ЕГН ban, message field — with no filler.

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

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

For a write tool with a deeply nested schema and no output schema, the description covers the essentials an agent needs: the return value (a link plus a message field), the lifetime of the draft, and the boundary of what the agent is not allowed to do. Nothing required to invoke and hand off correctly 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 reported schema coverage is 0%, but the schema itself carries per-field descriptions (ЕИК format, status sets the price, 'a kitchen adds a module, so ask; do not assume'), so parameter meaning is largely available in structured data. The description adds no field-level guidance of its own beyond the ЕГН warning, which is not mapped to any specific parameter. Adequate but not compensatory.

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 concrete action and effect: it saves answers as a draft valid for 7 days and returns a link that opens a pre-filled questionnaire. That is a specific verb plus a specific artifact, so an agent knows what comes back. It never names the sibling tools (haccp_check, haccp_options), so it falls short of full sibling differentiation.

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 spells out the downstream workflow clearly: hand the link to the person, who verifies answers, adds missing items, previews for free and pays. It also states the negative case explicitly — 'You cannot order or pay' — which prevents the agent from attempting a checkout. It does not, however, say when to call this instead of haccp_check or haccp_options.

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