Bezal — Local Business Intelligence for AI Agents

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

Annotations cover the read-only/open-world safety profile, but the description adds critical behavior the annotations cannot convey: opening hours are only available for paid Bezal plan providers, and other listings return open as "unknown". It also discloses the bookings blind spot, which materially affects how an agent should interpret and act on the result.

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: purpose first, then the data-availability constraint, then the practical limitation. No repetition or padding, and the most important caveat is front-loaded after the 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?

For a two-parameter read tool with no output schema, the description covers purpose, data availability semantics, the meaning of an "unknown" result, and the confirm-with-business caveat. An agent has everything it needs to call and interpret this 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 description coverage is 100%, with both business_id and date fully documented (UUID and ISO YYYY-MM-DD). The description adds no parameter-level detail, so the schema is doing all the work here; 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?

States a specific verb and resource: checking whether a business is open on a given date based on posted opening hours. This is clearly distinct from siblings like get_business or search_businesses, which retrieve entity data rather than availability.

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 gives clear when-to-use context and a strong when-not-to-rely caveat: it doesn't know about bookings, so a time should be confirmed with the business. It also states the paid-plan restriction. It does not explicitly name alternative sibling tools, but the usage boundaries are otherwise 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 cover the safety profile (readOnlyHint=true, openWorldHint=false), and the description adds genuinely new behavioral context: which fields are always returned and that phone, website, address, hours, photos and coordinates are gated behind a paid plan, with the description text gated behind a higher plan. This warns the agent that results are legitimately sparse for non-paying providers rather than broken.

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 capability before the field list, and every clause conveys real information. The second sentence is dense and long, but none of it is filler given the plan-gating detail.

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 return-value burden itself and does so by enumerating the standard fields and the conditionally available ones. For a one-parameter read tool, an agent has everything needed to call it and interpret partial results.

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 single business_ids array already carrying minItems=1, maxItems=5 and UUID format. The description reinforces the maximum of 5 and clarifies these are business identifiers, adding a small amount of meaning beyond the schema but no new format or ordering guidance.

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 (compare) plus the resource (businesses) and the batch scope ('up to 5 businesses side by side'), which implicitly separates it from the single-record get_business sibling. It never names an alternative tool outright, so differentiation is inferable rather than explicit.

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?

Usage is only implied by the word 'compare' – the description never says when to prefer this over repeated get_business calls, nor any exclusion such as 'do not use for a single business'. No prerequisites or error conditions are given.

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 readOnlyHint=true and openWorldHint=false, the description discloses a genuinely non-obvious behavioral trait: field visibility depends on the provider's paid plan tier, so agents know some fields may be absent. It omits what happens when the UUID is invalid or the business does not exist.

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 action and return shape, and the sibling redirect is placed last where it belongs. The paid-plan sentence is dense with conditional clauses but each clause conveys real 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?

With one parameter, full schema coverage, annotations covering the safety profile and no output schema, the description's enumeration of returned fields and their plan-based conditionality is sufficient for an agent to call and interpret the result.

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 single UUID parameter fully described, so the schema carries the semantics. The description only restates the key type ('by UUID'), adding no ambiguity resolution such as whether external or internal IDs are accepted.

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 and resource ('Get the public Bezal profile for one business') plus the key ('by UUID'), which immediately separates it from the search_* siblings. It also names the correct sibling for a related but distinct resource type.

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 redirects to get_service_catalog for services, giving a clear when-not rule. It does not, however, tell the agent how to obtain the UUID (e.g., via search_businesses) or address bulk lookups versus compare_businesses.

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 openWorldHint=false, so safety is covered. The description adds useful value by disclosing the composition of the response (Bezal reviews with rating/text/verified/date/reviewer name form, plus Google rating and review count), but says nothing about ordering, pagination, or what happens when limit truncates results.

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?

A single front-loaded sentence that names the resource first and then enumerates returned fields; nothing is wasted. Slightly dense parenthetical but appropriate for the amount of 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 simple two-param read tool with full schema coverage and no output schema, the description adequately covers what is returned, including reviewer anonymization, which is important context. Only ordering/pagination and limit-edge behavior are 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 coverage is 100%, with limit and business_id both documented in the schema, so baseline is 3. The description mentions 'a specific business' consistent with business_id but adds no detail on limit behavior or truncation beyond what the schema states.

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 and resource (get reviews for a specific business) and enumerates the returned fields, which distinguishes it from siblings like get_business or compare_businesses. It doesn't explicitly contrast with a sibling, so it stops short of 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?

Usage is implied by 'for a specific business' (needs a business_id), but there is no explicit when-to-use/when-not guidance or named alternative such as get_business for general business info. An agent can infer the scenario but not the boundaries.

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 establish readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real behavioral value beyond that by disclosing a fallback path: if no priced catalog exists, the tool returns service names only, which tells the agent to expect variable result shape.

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 short sentences, zero padding. The primary behavior is front-loaded and the fallback condition follows 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?

For a read-only, single-parameter lookup with no output schema, the description conveys what is returned (services and pricing, or service names as a fallback). Only edge behavior such as an unknown business_id is left unstated, which is a minor gap.

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 is a single parameter with 100% schema description coverage, so the schema fully documents business_id including its UUID format and pattern. The description adds no further parameter meaning, which is the expected baseline 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?

Names a specific verb and resource ('Get services and pricing') scoped to 'a specific business'. The business-scoping implicitly distinguishes it from search_by_service, which searches businesses by service, though no sibling is named 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?

Usage is implied by the phrase 'for a specific business', which suggests calling this once you already have a business_id rather than searching. However, there is no explicit statement of when to prefer this over get_business, search_by_service, or compare_businesses.

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 openWorldHint=false, so safety and scope are covered structurally. The word 'all' usefully signals a complete, unpaginated enumeration of a closed directory, but the description says nothing about caching/staleness or the shape of each returned category.

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?

A single front-loaded sentence with zero filler; every word carries meaning and the scope qualifier arrives 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?

For a zero-parameter reference-listing tool with annotations covering the safety profile, the description is adequate but thin. With no output schema, it doesn't indicate whether categories come back as names, IDs, or nested objects, which is the one thing an agent would still need to know.

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; there is nothing for the description to disambiguate. No misleading parameter claims are made.

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 (list) and resource (business categories) with an explicit scope ('all available ... in the directory'), which separates it from the search/get siblings in the directory. It doesn't name a sibling or state what the categories are used for, so it falls short of full 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?

No explicit when-to-use or when-not-to-use statement is given; the usage (fetching the category vocabulary, likely to feed search_by_service or search_businesses) is only implied by the tool's name and the sibling set. An agent can infer the purpose but gets no 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuine beyond-schema context: which result fields are tier-gated (phone, website, address, hours, photos, coordinates only for paid plans; description only for higher tiers) and what quote_request_url is for. It omits ordering, total-count, and empty-result behavior, but the data-availability disclosure is substantive.

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 front-loaded sentences: what it does, what every result contains, and what is gated. No filler. The final clause ('and the description only for providers on a higher paid plan') is slightly tangled but each 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?

With no output schema, the description usefully enumerates the returned fields and their tier conditions, which is exactly the information an agent needs to interpret results. Gaps remain around result ordering, pagination/total counts, and behavior with zero matches, but the core completeness bar for a read-only search tool is met.

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 all five parameters are already documented, including the query's coverage of 'business name and description' and the limit range. The description only loosely maps to those parameters ('by name, category, or location') without adding format, matching, or combination semantics. Baseline 3 applies when the schema carries the load.

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 and resource: 'Search local business profiles on Bezal by name, category, or location.' An agent immediately knows this is a discovery/search tool over business entities. It does not, however, explicitly distinguish itself from siblings like search_by_city or search_by_service, which cover overlapping lookup modes.

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?

Usage is only implied by the 'by name, category, or location' phrasing; there is no explicit when-to-use or when-to-prefer-a-sibling statement. It never says whether search_by_city or search_by_service should be used instead when the intent is purely geographic or purely categorical.

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 declare readOnlyHint and openWorldHint, so the description carries most of the burden and does it well: it discloses the exact result field set and, importantly, that phone/website/address/hours/photos/coordinates and the description are gated by paid plan tier — a non-obvious data-availability constraint an agent must know before trusting results. It does not cover result ordering, empty-result behavior, 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?

Front-loaded with the core purpose in the first sentence, then return-shape details. The long second sentence is dense but every clause carries real information about tier-gated fields; nothing is 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?

With no output schema, the description does the necessary work of enumerating returned fields and flagging tier-dependent availability. Remaining gaps are minor: sorting, result count behavior against the limit cap, and what an empty result looks like.

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 all four parameters are documented in the schema, so the baseline applies. The description reinforces that city is the scoping input and category is an optional filter but adds no format or semantics beyond what the schema already states.

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 and resource (search businesses) plus the scope that separates it from the generic search_businesses and search_by_service siblings: a specific city, with an optional category filter. An agent can route to it without opening the 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?

Usage is implied by the city scoping and the optional category filter, but there is no explicit when-to-use guidance, no mention of when search_businesses or search_by_service would be preferable, and no stated prerequisites or exclusion 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?

Annotations already mark this as a read-only, closed-world search, but the description adds substantial behavioral context: it lists returned fields and explains that phone, website, address, hours, photos and coordinates are only available for paid-plan providers. This is exactly the kind of non-obvious data-availability constraint an agent needs before selecting the tool.

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 sentences, front-loaded with the core purpose and the exact-service distinction. Every sentence earns its place by adding usage guidance or return-value constraints.

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?

There is no output schema, so the description compensates by listing core return fields and explaining plan-based field availability. Combined with the annotations and fully described parameters, it gives enough context to call the 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 both parameters are already documented in the input schema. The description reinforces that service_type should be an exact service rather than a category and gives an example, but it does not add syntax or matching details beyond what the schema already provides, so 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 states a specific action and resource: finding businesses that list a specific service. It immediately distinguishes this from category-based lookup with a concrete example, so an agent can tell exactly what the tool returns.

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 states when to use this tool: when you know the exact service rather than the category. The contrast with category lookup is useful, but it does not explicitly name sibling tools such as list_categories or search_businesses, leaving some routing inference to the agent.

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