Yelp Remote MCP Server

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered elsewhere. The description adds a useful behavioral note about domain targeting and the breadth of the returned payload, but says nothing about rate limits, auth needs, or what happens for an unknown ID.

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?

Purpose is front-loaded in the first sentence, followed by one sentence of payload detail and one of use cases. The field list is long but earns its place given there is no output schema; a small amount of redundancy remains between the title and the first line.

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 correctly compensates by listing the return fields. Both parameters are fully documented in the schema, so the only meaningful gaps are error behavior for invalid IDs and any note on which domain to prefer when the business is ambiguous.

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 both parameters (placeId and domain) carry their own descriptions plus an enum for domain. The description only restates 'by Yelp ID or alias' and 'domain targeting,' adding no format or selection guidance beyond the schema, so the baseline of 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 specific verb and resource — 'Fetches a single Yelp business by Yelp ID or alias' — and enumerates the returned fields, so an agent knows exactly what it produces. The distinction from siblings (search results, place reviews) is implicit in the singular, ID-based scope rather than stated outright.

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?

Three concrete use cases are given: enriching leads/listings, monitoring a competitor's rating/review count, and validating hours/amenities before display. There is no explicit when-not-to-use guidance or naming of the sibling tools as alternatives, which keeps 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 establish read-only, non-destructive, open-world access, and the description adds real behavioral context: cursor vs. offset paging, the requirement to keep other filters fixed across pages, the hasNextPage termination condition, and the fact that notRecommended reviews lack photos/videos/reactions. No rate limits or auth requirements are mentioned.

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?

It is front-loaded with purpose, then pagination mechanics, then the response shape, then use cases. It is longer than average but each block carries information; the closing use-case list is the most expendable part.

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 ten parameters and no output schema, the description does the right thing by describing the returned review fields, business rating/language totals, and pagination echo fields. Combined with the exhaustive schema, an agent has what it needs to call it 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 the schema already documents every parameter in detail, including the rating/query interaction and the start vs. nextPageToken exclusivity. The description mostly restates these at a higher level (sort modes, star filter, language, free-text, cursor), adding little beyond 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 names a specific verb and resource ("Fetches the review feed of a single Yelp business by Yelp ID") and enumerates the supported sorting and filtering axes. It is clearly distinct from a place-details or search tool, though it does not name the siblings 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?

It gives concrete usage contexts at the end (sentiment monitoring, competitor complaint mining, owner-response tracking, rating-distribution datasets) and a precise pagination procedure. It stops short of stating when to prefer the sibling search or place-details tools instead.

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, destructiveHint=false, openWorldHint=true, so safety is covered. The description goes beyond them by disclosing the shape of the result set (alias/ID, name, categories, rating, review count, price tier, thumbnail) and that pagination is offset-based — valuable given there is no output schema. It omits any note on result caps or rate limits, which keeps it below a 5.

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 purpose and scoping constraints are front-loaded in the first sentence, with follow-up uses in the second. It is compact for the amount of information conveyed, though the trailing list of use cases is slightly padded.

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 compensates by enumerating the returned fields and explaining pagination behavior. Combined with full annotation coverage and a fully described input schema, an agent has what it needs to select and call this tool; only rate/result-limit guidance is absent.

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 all five parameters are already documented, including the `l` example and the `start` offset semantics. The description adds only a light gloss on `l` as a map-bounded radius and on `domain` as targeting; that is marginal value beyond the schema, so the 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?

"Runs a Yelp business search by keyword and location" gives a specific verb and resource, then enumerates the optional scoping (map-bounded radius via `l`, domain targeting, offset pagination). It separates itself from siblings by naming the Yelp Place endpoint as the follow-up for full details, so an agent can distinguish search-listing from detail/review tools 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?

It gives real use contexts (local-discovery UIs, market-share/competitor datasets) and explicitly routes the agent to the Yelp Place endpoint when full details are needed after getting aliases. It does not state when *not* to use it (e.g., when you already have an alias), but the sibling hand-off is clear enough to guide selection.

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