Server Quality Checklist

Tool Scores

• search_eventsA
  4.2/5.0
  Behavior4/5

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

  Annotations declare readOnlyHint, idempotentHint, destructiveHint; description adds coverage strengths and output fields. It does not mention default pagination or that past events are excluded by default (handled via schema). Adds context beyond annotations.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Three sentences: scope, return fields, coverage. No fluff, front-loaded with core purpose. Every sentence adds value.

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

  Completeness4/5

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

  Given complex schema (13 params, 2 enums, output schema, annotations), the description covers overall function, return fields, and regional strengths. Lacks explicit note on default date-range behavior but schema handles it. Good for the complexity.

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

  Parameters3/5

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

  All 13 parameters are already described with schema descriptions (100% coverage). The description adds minimal extra meaning (only geographical strength hint). Baseline 3 is appropriate.

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

  Purpose5/5

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

  The description uses specific verbs ('search upcoming events') and resource ('events'), listing return fields and geography. It clearly distinguishes from siblings like get_event (single event) and search_places (places).

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description states when to use (searching upcoming events in covered regions) but does not explicitly exclude cases or name alternatives; the context of sibling tool names provides implicit differentiation.

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

• get_placeA
  4.3/5.0
  Behavior4/5

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

  The description adds value beyond annotations by specifying what data is returned (full details, recent reviews) and clarifying field meanings (listing_type, recent_reviews). Annotations already indicate read-only, idempotent, and non-destructive behavior, and the description aligns with them without contradiction.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is concise—two to three sentences—front-loaded with the primary purpose, followed by necessary clarifications. Every sentence adds value without redundancy.

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

  Completeness5/5

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

  Given the simple tool (one required parameter, well-documented schema, annotations, and an output schema), the description covers all necessary aspects: what it does, how to use it (slug from search_places), and key interpretation details (listing_type, empty reviews). It is complete for an agent to use correctly.

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

  Parameters3/5

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

  The only parameter, slug, is fully described in the schema with 'Place slug from search_places,' and the description repeats 'Use the slug from search_places.' Since schema coverage is 100%, the description adds no new semantic information, meeting the baseline of 3.

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

  Purpose5/5

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

  The description clearly states the tool retrieves full details for one place by slug, including recent reviews, and distinguishes itself from search_places by specifying that the slug comes from that tool. The title 'Get place details + reviews' reinforces the purpose.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  It explicitly instructs to 'Use the slug from search_places,' providing clear context for when to use this tool. It also addresses a common misinterpretation about empty recent_reviews. While it does not explicitly list when not to use it or name alternatives like get_event, the guidance is sufficient for an agent.

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

• search_placesA
  4.3/5.0
  Behavior5/5

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

  Annotations already declare readOnlyHint and idempotentHint. The description enriches transparency by detailing result types (curated vs. directory) and the need to avoid implying recommendations for directory entries, plus disclosure of sponsored placements. 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.

  Conciseness4/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is a single paragraph that conveys purpose and key nuances. It is front-loaded and efficient, though slightly verbose. Could be streamlined but avoids unnecessary fluff.

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

  Completeness4/5

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

  Given the tool's complexity (10 params, output schema exists), the description covers critical behavioral aspects (listing types, sponsored results) and refers to list_categories. It does not explain pagination parameters in detail, but schema covers that. Acceptably complete.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the schema already explains all parameters. The description adds only minor extra context (e.g., repeating the list_categories suggestion for category) but does not significantly enhance parameter understanding beyond the schema.

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

  Purpose5/5

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

  The description clearly states the tool searches Pifini's places directory across the Caribbean and Latin America, listing specific categories (restaurants, bars, etc.). It distinguishes itself from siblings like search_events, get_place, and list_categories by focusing on places search.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description provides clear usage guidance: advises calling list_categories before using the category filter and discloses how to handle sponsored results. However, it does not explicitly state when not to use this tool (e.g., for events) or name alternatives.

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

• create_ticket_checkoutA
  4.5/5.0
  Behavior4/5

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

  Discloses that tickets are emailed after payment and that the checkout is Stripe-hosted. Annotations only indicate non-read-only and non-destructive, so description adds meaningful behavioral context beyond annotations.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Three sentences with zero waste, front-loaded with purpose and outcome, followed by usage guidance. Highly efficient.

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

  Completeness5/5

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

  Given the complexity of a payment tool requiring human confirmation, the description fully covers purpose, input parameter sources, output (URL), and post-payment flow. Output schema exists per context, so no gap.

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

  Parameters4/5

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

  Schema coverage is 100%, but description adds value: explains where to get ticket_type_id (from get_event), specifies quantity range (1-20 not in schema), and flags buyer_email as required with instruction to ask human.

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

  Purpose5/5

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

  Clearly states it creates a Stripe-hosted payment link for event tickets and returns a checkout URL. Distinguished from sibling tools (search/get events, places) which are about information retrieval, not payment.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  Explicitly instructs to confirm details with the human before calling and to give the URL for self-serve payment. Does not mention when not to use, but context with sibling tools makes it clear.

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

• get_eventA
  4.5/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint and idempotentHint. The description adds value by detailing the response contents (available ticket types, prices, remaining stock), which is beyond what annotations cover. No contradiction.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  A single, front-loaded sentence with no extraneous words. Every part earns its place.

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

  Completeness5/5

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

  For a simple one-parameter tool with an output schema, the description adequately covers the return contents and usage context.

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

  Parameters4/5

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

  With 100% schema coverage, baseline is 3. The description adds useful context by specifying the slug source ('from search_events'), enhancing the schema's 'Event slug from search_events' description.

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

  Purpose5/5

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

  The description clearly states the verb ('Get') and resource ('event details'), and lists specific data returned (description, venue, date/time, ticket types with prices and stock). It distinguishes from sibling tools like search_events (list) and get_place (different entity).

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  Explicitly mentions using the slug from search_events, providing clear context for when to use this tool. Although it doesn't specify when not to use, the sibling tools list makes alternatives obvious.

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

• list_categoriesA
  4.9/5.0
  Behavior5/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: it uses Overture Maps taxonomy with over 1,000 specific values, and that guessing will usually miss. This explains why the tool is needed and what it returns, beyond what annotations provide.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is a single paragraph but is front-loaded with the purpose, followed by context and usage instruction. Every sentence adds value; no fluff. It is appropriately sized for the tool's simplicity.

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

  Completeness5/5

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

  Given an output schema exists (so return values are covered), the description is complete. It explains why the taxonomy is needed, how to use the tool, and how to pass results to search_places. The only minor gap is no explicit mention of 'limit' behavior, but schema covers that. Overall comprehensive.

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

  Parameters4/5

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

  Schema coverage is 100%, so each parameter has a schema description. The description adds meaning by explaining that 'query' is a 'rough query' (partial match) and that 'country' filters by country presence. This aids understanding beyond raw schema, though the description does not detail every parameter.

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

  Purpose5/5

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

  Description clearly states the tool's purpose: 'Discover valid category values for search_places.' It uses a specific verb (discover) and resource (category values), and distinguishes itself from sibling tools like search_places by acting as a preparatory step. Examples of specific category values further clarify the scope.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  Explicitly tells when to use: 'Call this first with a rough query... then pass it to search_places' category parameter.' It contrasts with guessing, providing clear context for usage. No alternative tool is mentioned, but the recommendation is direct and actionable.

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