Bronjoy Marketplace

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

Beyond the annotations, the description discloses that the booking is created as 'pending', that the business must still confirm it, that prepayment may require a payment link, and that the slot is not held indefinitely. This is valuable behavioral context not available from annotations alone.

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 organized with a clear WHEN TO USE section and a few focused caveats. It is slightly longer than necessary due to some repetition between the opening line and the usage section, but every sentence still 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?

Given the tool has no output schema and 8 parameters, the description covers the key context an agent needs: prerequisites, required user input, pending status, prepayment behavior, and venue eligibility. Nothing critical is missing for correct invocation and user communication.

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 documents all 8 parameters, so baseline is 3. The description adds useful context beyond the schema, such as the requirement that the contact must match where the code was sent, and reinforces that start_time must come from a check-availability slot.

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 ('Book a slot') and identifies the exact precondition (a code from request-booking-code). This clearly distinguishes it from sibling tools like check-availability and request-booking-code.

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 WHEN TO USE: it is the last step after the user has confirmed venue, service, and exact time and has provided the 6-digit code. It also gives important constraints like requiring the same contact the code was sent to and only working for venues with is_bookable: true.

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, openWorld, and idempotent behavior, and the description complements them with useful behavioral details: explicit refusal for venues not set up for online booking, slot times in the venue's timezone, and the contract with book-appointment. 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 compact and front-loaded: purpose first, then when-to-use, then failure handling, then integration note. Every sentence earns its place and there is no filler or repetition of annotation metadata.

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?

Despite having no output schema, the description tells the agent what to expect on the first call (services and prices) and second call (slots), how to handle refusals, and how results connect to book-appointment. For a three-parameter read-only tool, this is complete enough for safe and correct invocation.

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 schema already documents slug, date, and service_id thoroughly. The description reinforces the two-step usage pattern, but this duplicates the service_id schema note rather than adding substantially new parameter-level meaning.

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, actionable statement: 'Bookable services and open time slots for a venue on a given date.' This clearly distinguishes check-availability from siblings like get-venue and search-venues, and the WHEN TO USE section reinforces that this is the pre-booking step for book-appointment.

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 when to use: the user has picked a venue with `is_bookable: true` and wants a time. It also gives the correct call sequence, explains how to handle non-bookable venues by offering the phone number, and notes that returned slot times are exactly what book-appointment expects.

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, and openWorld; the description adds that the phone number is intentionally masked here, and that this tool leaves booking-related behavior to other tools. These are meaningful behavioral facts 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 front-loaded with the return payload, then gives a short WHEN TO USE block, and closes with the one caveat that matters. Every sentence earns its place with no fluff.

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 one required parameter, no output schema, and helpful annotations, the description tells the agent exactly what fields will come back, how to obtain the slug, when to use it, and when it is not the right tool. Nothing essential 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 coverage is 100% and the schema already explains the slug parameter with provenance and an example, so the description carries little param burden. It reinforces the 'after search-venues' relationship but does not add new parameter semantics.

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 identifies a concrete resource ('full public profile for one venue') and lists the exact fields returned, so the purpose is unmistakable. It also distinguishes itself from search-venues (one venue vs list) and from reveal-phone (masked phone).

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 explicit trigger timing ('after search-venues') and example user questions that should route here. It also names a clear exclusion boundary: use reveal-phone only when the user actually wants to call. This is strong decision 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 annotations, the description reveals critical behaviors: the code is not returned to the agent, it goes to the user's own inbox/phone, it expires in 5 minutes, it covers one booking, and sending is rate-limited. This is exactly the kind of behavioral context the annotations do not provide.

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 action and uses clear sections for usage and behavioral notes. It is somewhat longer than strictly necessary, but each part serves a purpose, especially the 'YOU DO NOT RECEIVE THE CODE' warning and the anti-loop guidance.

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?

The description fully covers when to call, what happens when called, what the agent should expect (and not expect), how the code behaves, and important limits. Even without an output schema, the agent has enough context to invoke the tool correctly and interact with the user appropriately.

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 describes all three parameters with 100% coverage, including the choice between email and phone and the phone format preference. The description adds context about contact ownership but does not materially change or deepen the per-parameter semantics beyond what the schema provides.

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: 'Send the user a 6-digit confirmation code.' It also explicitly links the tool to its sibling book-appointment by noting the code is required before booking, which distinguishes it from the other tools in the 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 WHEN TO USE section gives concrete preconditions: the user has chosen a venue, service, and slot, and has provided email or phone. It also specifies ordering ('Call this before book-appointment') and warns against looping, giving the agent clear action 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?

Beyond the readOnlyHint and idempotentHint annotations, the description discloses that reveals are rate limited per caller and should be requested sparingly. It also clarifies the distinction from get-venue's masked number, giving agents a clear behavioral model.

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 tightly organized with a purpose statement, an explicit when-to-use section, and rate-limiting guidance. Every sentence earns its place, and key constraints are 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?

For a simple single-parameter tool, the description covers what the tool returns, when to use it, how to use it responsibly, and why it exists separately from get-venue. No critical guidance 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 schema already fully documents the only parameter, slug, as "The venue slug from search-venues." The description adds no additional parameter semantics, but the 100% schema coverage means no compensation is needed.

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 identifies the tool as returning "The venue's real phone number," and explicitly contrasts it with get-venue, which "returns a masked number." This makes the tool's purpose and differentiator unmistakable.

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 provides explicit WHEN TO USE conditions: the user wants to call, often because the venue is not bookable online or a question isn't answered by profile fields. It also gives concrete constraints: request one at a time, for a chosen venue, never in bulk across search results.

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, openWorldHint, and idempotentHint. The description goes beyond them by disclosing that results are ranked and compact, that names and addresses are in Russian or Uzbek and should be quoted as-is, and that the is_bookable field drives what the agent can offer next. 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 efficiently organized: a one-sentence purpose, a labeled WHEN TO USE block, and a compact results/behavior section. Every sentence adds actionable context, and the most important 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?

For a read-only search tool with five optional parameters and no output schema, the description provides enough context to invoke it correctly: when to use it, what results look like, the meaning of is_bookable, and how to handle localized names. The output schema is absent, but the description compensates by naming the critical result fields and downstream behavior.

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 of 3 applies. The description does not add significant per-parameter meaning beyond the schema; it reinforces the general search intent but leaves parameter specifics to the well-documented 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 opens with a specific verb and resource: 'Search Bronjoy's catalogue of service businesses in Uzbekistan by keyword, city and category.' It clearly defines the tool's scope and, by naming the downstream flow, distinguishes it from sibling tools that operate on slugs.

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' block explicitly states the use case and says to start here, and it explains that every other tool takes the slug this tool returns. It also gives concrete decision guidance around is_bookable, routing to check-availability, request-booking-code, and book-appointment versus only describing and phoning.

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