Server Quality Checklist

Tool Scores

• search_businessesA
  3.6/5.0
  Behavior3/5

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

  Annotations already provide readOnlyHint=true, idempotentHint=false, openWorldHint=true, so the read-only nature is clear. The description adds no extra behavioral details (e.g., rate limits, result variability, pagination quirks) beyond what the schema and annotations convey, but does not contradict them.

  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?

  Description is four sentences, front-loads the main action, and every sentence is informative. No redundancy or filler.

  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?

  For a 11-parameter search tool with full schema coverage and annotations, the description adequately summarizes the tool's capabilities and constraints. It misses stating the return format, but no output schema exists, so some inference is needed. However, the overall context is sufficient for an agent.

  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 coverage is 100%, so the baseline is 3. The description only summarizes available filter types (free-text, geo, categories, price, open-now, pagination) without adding new semantic meaning beyond the detailed schema descriptions for each parameter.

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

  Purpose4/5

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

  States 'Search Yelp for businesses matching a term, location, or both' with a clear verb+resource. Mentions discovering restaurants, services, shops. Does not explicitly distinguish from siblings like find_business_by_phone or get_business, but the sibling names are self-explanatory and this tool's purpose is clear.

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

  Usage Guidelines3/5

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

  Provides context: 'Use when the user wants to discover restaurants, services, or shops.' Also notes requirement for location or lat/lng and lists supported features. However, it does not mention when not to use this tool or provide alternatives among siblings.

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

• get_business_reviewsA
  4.2/5.0
  Behavior4/5

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

  Description adds behavioral context beyond annotations: returns up to 50 reviews, use offset for pagination, total field shows total count. Annotations already indicate readOnly and idempotent, so the description adds useful operational details.

  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 concise sentences with front-loaded purpose, then usage guidance, then behavioral trait. No wasted words; each sentence adds distinct 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 no output schema, description covers return fields (ratings, comments, reviewer info) and pagination. Mentions total field. Missing default sort or result structure, but overall adequate for a read-only tool with rich schema descriptions.

  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 coverage is 100%, so baseline is 3. Description adds minimal extra meaning: mentions pagination via offset and limit, and that total field exists. Does not elaborate on sort_by or locale beyond what schema already provides.

  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 retrieves user reviews for a specific Yelp business, with details on ratings, comments, and reviewer info. Distinguished from sibling tools like search_businesses or get_business which serve different purposes.

  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 says 'Use when the user wants to read customer opinions' and describes return content. Provides pagination limits (up to 50) and offset usage. Does not explicitly mention when not to use, but the sibling context makes it clear.

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

• find_business_by_phoneA
  4.3/5.0
  Behavior4/5

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

  Annotations already indicate read-only and idempotent. Description adds behavioral details: results limited to 'a handful of candidates', empty list means not found. This clarifies nondeterminism and false negatives 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?

  Two sentences, zero filler. First sentence defines purpose and usage context. Second sentence covers format and output expectations. Every phrase 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?

  With 1 parameter and no output schema, description covers all essential aspects: action, usage scenario, input format, and result interpretation. No gaps for agent decision-making.

  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 coverage 100% and schema already describes phone format thoroughly. Description merely reaffirms format without adding new meaning. 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?

  Clear verb 'look up' and resource 'Yelp businesses' with specific filter 'phone number'. Differentiates from siblings like 'search_businesses' (generic) or 'get_business' (by ID) by focusing on phone lookup.

  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?

  States when to use: 'when you have a phone number and need to identify the business'. Provides format requirement (E.164) and explains return behavior (few candidates, empty if not found). No explicit when-not, but context implies it's the dedicated phone lookup.

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

• get_businessA
  4.4/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds that it raises an error if the business ID does not exist on Yelp, which is valuable behavioral detail. No contradictions.

  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?

  Two sentences with no waste. First sentence states purpose and scope. Second sentence adds usage guidance and error behavior. Perfectly front-loaded.

  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 no output schema, the description lists key returned fields (hours, photos, address, price tier, categories, URL), which is sufficient for a read-only data fetch. Could mention that it returns a single object, but not necessary.

  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% (both parameters have descriptions). The description adds value by specifying the source for business_id ('Obtain from search_businesses, find_business_by_phone, or match_business') and noting the default locale ('en_US').

  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 action ('Fetch the full Yelp profile') and the resource ('a specific business by its ID or alias'). It distinguishes from siblings like search_businesses (which searches by query) and find_business_by_phone (by phone number).

  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 says 'Use when you already have a Yelp business ID and need complete details.' This provides clear context. However, it does not explicitly state when not to use it or mention alternatives like search_businesses if the ID is not known.

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

• match_businessA
  4.4/5.0
  Behavior4/5

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

  Annotations already declare the tool is read-only and idempotent. The description adds behavioral context by listing required fields and noting that optional fields improve match precision, plus the match_threshold parameter. It does not contradict annotations, but it does not explicitly describe behavior on no match or multiple matches.

  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 three sentences: first declares purpose, second provides usage context, third adds parameter guidance. Every sentence is essential and front-loaded, with no filler.

  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 no output schema, the description adequately hints at return fields (ID, rating, hours, URL) and includes match_threshold options. It could improve by clarifying behavior when no match is found, but it remains sufficiently informative for an agent to decide to use the tool.

  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?

  The input schema has 100% description coverage, so each parameter is documented. The description adds value by grouping required fields and explaining that zip_code and phone improve match precision, which goes beyond the schema's individual descriptions.

  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's function: 'Match a business by name and address to its canonical Yelp listing.' It specifies the purpose of verification/enrichment and distinguishes itself from sibling tools like search_businesses or get_business by focusing on structured address matching.

  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 explicitly says when to use the tool: 'Use when you have structured address data and need to verify or enrich it with Yelp data.' It also notes required and optional fields. However, it does not explicitly state when not to use it or mention alternative tools, leaving room for ambiguity.

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