Kanal Varna — drains, leaks & plumbing (Varna, BG)

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 needs no restating. The description instead adds genuinely non-obvious behavior: the three-valued outcome and the meaning of 'by_arrangement' (travel terms and timing agreed by phone), which an agent could not infer from 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?

Three sentences, front-loaded with the trigger condition, then input tolerance, then return values. The example place list is dense but each entry illustrates a distinct case type (city, district, resort, village, out-of-region town). No filler wording.

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

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

With an output schema present, the description need not enumerate return fields, and it still supplies the interpretive key for the three statuses plus the accompanying page URL. Combined with annotations and full schema coverage, an agent has everything needed to invoke and interpret this tool correctly.

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

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

Schema coverage is 100%, so a baseline of 3 would apply on schema alone. The description exceeds that by disclosing that the place argument tolerates Bulgarian, Latin and Russian spellings, which clarifies accepted input forms beyond the schema's example strings and directly affects how an agent should pass user text.

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 names a specific verb and resource in user-question terms ('asks whether Kanal Varna comes to a specific city, district (квартал) or village') and enumerates the place types it covers. It is clearly distinguishable from siblings like get_prices, get_faq or find_service, which do not answer coverage questions.

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 opening clause 'Call this when the user asks whether...' gives an explicit trigger plus concrete example inputs ('Младост', 'Аспарухово', 'Добрич'). It stops short of stating when NOT to use it or naming the sibling to use for adjacent questions (e.g. pricing or booking), so it falls just below a full 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so credit goes to what the text adds: the match output shape (services + short description + page URL + starting prices + phone) and the multilingual input handling. It stops short of saying anything about result limits, ranking, or what happens on zero matches.

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 imperative 'Call this FIRST', followed by trigger examples and then the return contract. The example list is long, but each item earns its place as a disambiguation cue; a slightly tighter grouping would make it a 5.

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 two-parameter, read-only lookup with an output schema, the definition covers trigger conditions, input language flexibility, and result contents. Nothing an agent needs in order to call it 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?

Schema description coverage is 100%, so the baseline is 3. The description reinforces that the input is the problem in the user's own words and works in BG/EN/RU, but that duplicates what the schema's `problem` and `language` fields already state, adding no new syntax or format detail.

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+resource ('find ... service') scoped to a concrete domain (home water/plumbing problems in Varna) and enumerates the trigger conditions that distinguish it from siblings like get_prices or list_services. An agent can decide between this and list_services without opening either schema.

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 routes the agent: 'Call this FIRST when a user describes a home problem or need' and backs it with a dense list of concrete user phrasings (blocked drain, hidden leak, high water bill, insurer report, equipment hire). The trigger set is broad enough that the absence of an explicit 'do not use for X' clause doesn't leave real ambiguity.

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, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered by structured data. The description adds real value beyond that by previewing the concrete payload (phone number, daily 06:00–23:00 hours, booking steps, contact page URL), confirming it is a static, side-effect-free info lookup rather than a live availability check.

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, front-loaded with the trigger condition, no filler. The second sentence is a data dump that partly duplicates the output schema, which is slight waste, but it is compact and arguably aids up-front intent matching.

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 annotations covering safety, a 100%-covered single-parameter schema, and an output schema handling return shape, the description carries exactly the load it needs to: when to call and what category of data comes back. Nothing an agent needs in order to invoke it 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?

Schema description coverage is 100% — the single optional 'language' parameter has a full enum explanation and default in the schema — so the baseline of 3 applies. The description says nothing about the language parameter, and the phrase 'languages spoken' refers to the business, not the input, so it adds no meaning here.

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?

Uses an explicit trigger verb ('Call this when...') followed by an enumerated set of intents — contact, booking/appointment, phone/WhatsApp/Viber/email, working hours, languages, payment methods — plus the resource it returns. That enumeration is precisely what separates it from siblings like get_prices, get_faq and list_services, so an agent can route without opening a schema.

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 when-to-use condition is stated concretely through a list of user intents, which is stronger than typical implied usage. There is no explicit when-not clause or named alternative (e.g. 'for price questions use get_prices'), which is the only thing keeping it below 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 the safety profile is covered. The description adds genuinely new behavior: questions are accepted in any language and each answer carries a source URL. It does not mention result limits or pagination, but for a static FAQ lookup that is minor.

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-loads the use case, then lists topics in a compact comma-separated run. The topic list is long but each item maps to a real user intent, and the actionable instruction (pass or omit the question) comes after it. Slightly list-heavy but 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?

An output schema exists, so return values need no explanation, yet the description still notes each answer has a URL. With only two optional params, the purpose, modes, and language handling are all covered; only the overlap with sibling tools remains unresolved.

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 both parameters are already documented, including the omit-for-all-FAQs behavior and the language enum. The description reinforces 'any language' and the omit mode but adds no syntax, matching, or fallback detail beyond the schema, which is the correct baseline.

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

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

States a clear verb ('call this') and a concrete resource (general FAQ answers about how Kanal Varna works), then enumerates the actual topics covered so an agent can pattern-match a user question to it. It stops short of naming siblings, and the listed topics ('prices in advance', 'areas', 'hours') overlap with get_prices and check_service_area, leaving some routing ambiguity.

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 a usable trigger ('general questions about how Kanal Varna works') plus two modes: pass a question to get best answers, or omit it to get all FAQs. No explicit when-not-to-use guidance and no named alternative tools, so the agent must infer that specific price/area lookups should go to siblings.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, and the description adds genuinely new behavioral context: returns official indicative 'from' prices in EUR exactly as on the website, plus an explanation of how pricing works, plus the caveat that the final price is always confirmed by phone before work starts. That caveat is material for how an agent should present the numbers to a user.

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 trigger condition is front-loaded in the first clause, and the whole thing is one tight paragraph with no filler. The parenthetical service list is slightly long and trails off with an ellipsis, but it earns its place by helping match varied user phrasings.

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 annotations covering safety, a full output schema covering return values, and 100% schema coverage on both parameters, the description only needed to supply trigger context and the pricing caveat — both of which it does. Nothing an agent needs to invoke and present results 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?

Schema description coverage is 100%, so both the service filter and the language enum are already fully documented in the schema. The description only restates the optional service filter and never mentions the language parameter, so it adds no meaning beyond structured data. 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 states a concrete verb and resource ('get prices' for drain unblocking, toilet, CCTV camera, boiler installation, etc.) and anchors it to a real source URL (kanalvarna.com/ceni/). An agent can immediately tell this is the pricing lookup, distinct from siblings like list_services or find_service.

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 an explicit trigger ('Call this when the user asks how much something costs') and enumerates representative query topics that select this tool. It also explains the optional filtering behavior. It does not, however, name alternative siblings or state when to prefer find_service/list_services instead, so it stops short of full routing 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?

The annotations already declare this a read-only, idempotent, non-destructive operation, so the safety profile is covered. Beyond that, the description adds two genuinely useful behavioral facts: only real/approved reviews are returned, and there is deliberately no aggregate star rating. The explicit 'do not invent one' instruction guards against a common fabrication failure.

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, each earning its place: trigger condition first, contents second, output caveat last. No repetition, no filler, and the routing information is front-loaded.

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

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

An output schema exists, so return values need no explanation, and the four annotations cover the safety profile. The description covers purpose, triggers, and a key output caveat. It never mentions the optional service or language filtering, which is the only substantive gap for a tool that can be narrowed to a specific service.

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%, with both optional parameters (service and language) fully documented including enum meanings and the detection fallback. The description adds nothing about parameter behavior. Baseline 3 is appropriate because the schema carries this burden entirely.

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 definition states a specific verb and resource ('get reviews') and goes further to specify exactly what is returned: customer video reviews with quotes and video URLs, plus approved text reviews. It is clearly distinguishable from siblings such as get_faq and get_prices, which an agent could otherwise confuse with reputation questions.

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 an explicit trigger set: reviews, testimonials, opinions, or whether Kanal Varna is good/reliable. That covers the realistic invocation conditions well. It does not name a competing sibling or state when-not to use it, which keeps it out of the top band.

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 this as a read-only, idempotent, non-destructive lookup, so the safety profile is covered. The description adds the category taxonomy but says nothing about return shape, ordering, or fallback behavior when a category is empty; since an output schema exists, that omission is minor.

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 trigger condition is front-loaded in one sentence, followed by a compact category glossary. The list is long but each entry carries information an agent cannot infer from the raw enum ids.

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 two-parameter read-only lookup with full schema coverage and an output schema, the description covers intent, scope, and category semantics. Nothing essential is missing, though a one-clause pointer to find_service would make routing airtight.

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 would be 3, but the description adds real meaning by glossing each opaque enum id in English (otpushvane = drain unblocking, naem = equipment hire). The language parameter's behavior is left entirely to the schema.

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

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

The description uses a specific verb (list) and resource (Kanal Varna services) and frames the user intent it answers ('what does Kanal Varna do'). It does not explicitly distinguish itself from the sibling find_service, which is the main gap keeping it from a 5.

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 an explicit trigger condition: when the user asks what the company does, which services exist, or wants all services in a category. It stops short of naming an alternative (e.g. find_service for a single matching service), so the when-not case is left implicit.

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