PinMeTo Location MCP

Official

by PinMeTo

Overview Schema Source Related Servers Discussions Admin

TypeScript

Remote

Google review analysis

pinmeto_get_google_review_insights

Read-only

Turn Google reviews into rating and sentiment statistics: averages, sentiment breakdowns, and rating distributions. Analyze location performance over time without reading raw reviews.

Instructions

Summarize Google reviews into rating and sentiment statistics.

Computes aggregates over the matched reviews server-side and returns the summary instead of the raw reviews, which is far more token-efficient than fetching them. The returned data is descriptive statistics, not LLM-written prose: read it and draw your own conclusions for the user.

Analysis Types:

summary: Average rating, sentiment breakdown, rating distribution
comparison: The above, plus per-location metrics ranked by rating
issues, trends, themes: Accepted, but currently return the same payload as summary. No theme extraction, issue clustering, or period comparison is performed, and the response is flagged with warningCode UNDIFFERENTIATED_ANALYSIS_TYPE. To analyze review text, fetch pinmeto_get_google_reviews and read it yourself.

Large Dataset Handling:

<200 reviews: Processed immediately
200-1000: Processed with token estimate in metadata
1000-10000: Returns warning with options (set skipConfirmation=true to proceed)
10000: Requires sampling strategy (representative or recent_weighted)

Sampling Strategies (which reviews get analyzed):

full: Analyze all reviews (default for <10000 reviews)
representative: Stratified sample by rating and location
recent_weighted: Prioritize recent reviews

Caching:

Results cached for 1 hour
Use forceRefresh=true to bypass cache

When NOT to use this tool:

Need raw review text: Use pinmeto_get_google_reviews
Need only aggregate stats: Use pinmeto_get_google_ratings
Need specific review lookup: Use pinmeto_get_google_reviews with filters

Input Schema

TableJSON Schema

Name	Required	Description	Default
`to`	Yes	End date (YYYY-MM-DD)
`from`	Yes	Start date (YYYY-MM-DD)
`themes`	No	Currently ignored - no theme extraction is performed
`storeIds`	No	Optional store IDs to analyze (omit for all locations)
`maxRating`	No	Maximum rating filter (1-5)
`minRating`	No	Minimum rating filter (1-5)
`analysisType`	Yes	Type of analysis: summary, issues, comparison, trends, or themes
`forceRefresh`	No	Bypass cache and regenerate analysis
`response_format`	No	Response format: "json" (default, token-efficient) or "markdown" (human-readable with tables)	json
`samplingStrategy`	No	Sampling strategy: full (default), representative, or recent_weighted	full
`skipConfirmation`	No	Skip large dataset confirmation (set true after receiving warning)

Output Schema

TableJSON Schema

Name	Required	Description
`data`	No	Analysis results (null or absent on error, warning, or no matching reviews)
`error`	No	Error message if the request failed
`warning`	No	Warning message
`metadata`	No	Analysis metadata
`errorCode`	No	Error code for programmatic handling
`retryable`	No	Whether the operation can be retried
`warningCode`	No	Warning code for programmatic handling
`analysisNote`	No	Note about the analysis itself, present when there is no metadata to carry it
`largeDatasetWarning`	No	Large dataset details and options (when requiresConfirmation is true)
`requiresConfirmation`	No	True if user must confirm before proceeding with large dataset

Schema Changelog

Changes observed during successful MCP inspections.

Changed21 schema fields changedv4.3.0Sep 5, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

removedInput schema / additionalProperties
```
Removed value: -false
```
removedInput schema / properties / to / $ref
```
Removed value: -"#/properties/from"
```
addedInput schema / properties / to / pattern
```
Added value: +"^\\d{4}-\\d{2}-\\d{2}$"
```
addedInput schema / properties / to / type
```
Added value: +"string"
```

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

changedOutput schema / properties / data / anyOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "bestPerformer": {
-        "additionalProperties": false,
-        "description": "Best performing location (for comparison analysis)",
-        "properties": {
-          "bestPractices": {
-            "description": "Practices other locations should adopt",
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
-          },
-          "reason": {
-            "description": "Why this location performs best",
-            "type": "string"
-          },
-          "storeId": {
-            "description": "Store identifier of the best performing location",
-            "minLength": 1,
-            "type": "string"
-          }
-        },
-        "required": [
-          "storeId",
-          "reason",
-          "bestPractices"
-        ],
-        "type": "object"
-      },
-      "commonStrengths": {
-        "description": "Strengths shared across locations (for comparison analysis)",
-        "items": {
-          "type": "string"
-        },
-        "type": "array"
-      },
-      "commonWeaknesses": {
-        "description": "Weaknesses shared across locations (for comparison analysis)",
-        "items": {
-          "type": "string"
-        },
-        "type": "array"
-      },
-      "issues": {
-        "description": "Issues identified (for issues analysis)",
-        "items": {
-          "additionalProperties": false,
-          "properties": {
-            "affectedLocations": {
-              "description": "Store IDs of affected locations",
-              "items": {
-                "type": "string"
-              },
-              "type": "array"
-            },
-            "category": {
-              "description": "Issue category (e.g., \"Wait Times\", \"Cleanliness\", \"Staff\")",
-              "minLength": 1,
-              "type": "string"
-            },
-            "description": {
-              "description": "Description of the issue",
-              "minLength": 1,
-              "type": "string"
-            },
-            "exampleQuotes": {
-              "description": "Representative quotes illustrating this issue",
-              "items": {
-                "type": "string"
-              },
-              "type": "array"
-            },
-            "frequency": {
-              "description": "How often this issue appears",
-              "minimum": 0,
-              "type": "integer"
-            },
-            "severity": {
-              "description": "Severity level of the issue",
-              "enum": [
-                "low",
-                "medium",
-                "high",
-                "critical"
-              ],
-              "type": "string"
-            },
-            "suggestedAction": {
-              "description": "Recommended action to address the issue",
-              "type": "string"
-            }
-          },
-          "required": [
-            "category",
-            "description",
-            "severity",
-            "frequency"
-          ],
-          "type": "object"
-        },
-        "type": "array"
-      },
-      "locationComparison": {
-        "description": "Location comparison (for comparison analysis)",
-        "items": {
-          "additionalProperties": false,
-          "properties": {
-            "averageRating": {
-              "description": "Average rating for this location (1-5)",
-              "maximum": 5,
-              "minimum": 1,
-              "type": "number"
-            },
-            "locationName": {
-              "description": "Location name",
-              "type": "string"
-            },
-            "lowConfidence": {
-              "description": "True when location has few reviews (<10)",
-              "type": "boolean"
-            },
-            "recommendations": {
-              "description": "Specific actions to improve this location",
-              "items": {
-                "type": "string"
-              },
-              "type": "array"
-            },
-            "reviewCount": {
-              "description": "Number of reviews analyzed",
-              "minimum": 0,
-              "type": "integer"
-            },
-            "sentiment": {
-              "description": "Overall sentiment for this location",
-              "enum": [
-                "positive",
-                "neutral",
-                "negative",
-                "mixed"
-              ],
-              "type": "string"
-            },
-            "storeId": {
-              "description": "Store identifier",
-              "minLength": 1,
-              "type": "string"
-            },
-            "strengths": {
-              "description": "Key strengths identified",
-              "items": {
-                "type": "string"
-              },
-              "type": "array"
-            },
-            "weaknesses": {
-              "description": "Key weaknesses identified",
-              "items": {
-                "type": "string"
-              },
-              "type": "array"
-            }
-          },
-          "required": [
-            "storeId",
-            "averageRating",
-            "reviewCount",
-            "sentiment",
-            "strengths",
-            "weaknesses"
-          ],
-          "type": "object"
-        },
-        "type": "array"
-      },
-      "summary": {
-        "additionalProperties": false,
-        "description": "Executive summary (for summary analysis)",
-        "properties": {
-          "averageRating": {
-            "description": "Average rating across analyzed reviews (1-5)",
-            "maximum": 5,
-            "minimum": 1,
-            "type": "number"
-          },
-          "executiveSummary": {
-            "description": "2-3 sentence summary of findings",
-            "minLength": 1,
-            "type": "string"
-          },
-          "lowConfidence": {
-            "description": "True when sample size is small (<20 reviews)",
-            "type": "boolean"
-          },
-          "overallSentiment": {
-            "description": "Overall sentiment classification",
-            "enum": [
-              "positive",
-              "neutral",
-              "negative",
-              "mixed"
-            ],
-            "type": "string"
-          },
-          "ratingDistribution": {
-            "additionalProperties": {
-              "minimum": 0,
-              "type": "integer"
-            },
-            "description": "Rating distribution (e.g., {\"5\": 100, \"4\": 50})",
-            "type": "object"
-          },
-          "sentimentDistribution": {
-            "additionalProperties": false,
-            "description": "Sentiment breakdown by percentage",
-            "properties": {
-              "negative": {
-                "description": "Percentage of negative reviews (0-100)",
-                "maximum": 100,
-                "minimum": 0,
-                "type": "number"
-              },
-              "neutral": {
-                "description": "Percentage of neutral reviews (0-100)",
-                "maximum": 100,
-                "minimum": 0,
-                "type": "number"
-              },
-              "positive": {
-                "description": "Percentage of positive reviews (0-100)",
-                "maximum": 100,
-                "minimum": 0,
-                "type": "number"
-              }
-            },
-            "required": [
-              "positive",
-              "neutral",
-              "negative"
-            ],
-            "type": "object"
-          }
-        },
-        "required": [
-          "executiveSummary",
-          "overallSentiment",
-          "averageRating",
-          "sentimentDistribution",
-          "ratingDistribution"
-        ],
-        "type": "object"
-      },
-      "themes": {
-        "additionalProperties": false,
-        "description": "Theme analysis (for summary/themes analysis)",
-        "properties": {
-          "negative": {
-            "description": "Negative themes/areas for improvement",
-            "items": {
-              "$ref": "#/properties/data/anyOf/0/properties/themes/properties/positive/items"
-            },
-            "type": "array"
-          },
-          "positive": {
-            "description": "Positive themes identified",
-            "items": {
-              "additionalProperties": false,
-              "properties": {
-                "exampleQuote": {
-                  "description": "Representative quote illustrating this theme",
-                  "type": "string"
-                },
-                "frequency": {
-                  "description": "How often this theme appears in reviews",
-                  "minimum": 0,
-                  "type": "integer"
-                },
-                "severity": {
-                  "description": "Severity level (for negative themes only)",
-                  "enum": [
-                    "low",
-                    "medium",
-                    "high",
-                    "critical"
-                  ],
-                  "type": "string"
-                },
-                "theme": {
-                  "description": "Theme or topic identified (e.g., \"Service Speed\", \"Staff Friendliness\")",
-                  "minLength": 1,
-                  "type": "string"
-                }
-              },
-              "required": [
-                "theme",
-                "frequency"
-              ],
-              "type": "object"
-            },
-            "type": "array"
-          }
-        },
-        "required": [
-          "positive",
-          "negative"
-        ],
-        "type": "object"
-      },
-      "trends": {
-        "additionalProperties": false,
-        "description": "Trends analysis (for trends analysis)",
-        "properties": {
-          "currentPeriod": {
-            "additionalProperties": false,
-            "description": "Current period summary",
-            "properties": {
-              "averageRating": {
-                "description": "Average rating in current period (1-5)",
-                "maximum": 5,
-                "minimum": 1,
-                "type": "number"
-              },
-              "reviewCount": {
-                "description": "Number of reviews in current period",
-                "minimum": 0,
-                "type": "integer"
-              },
-              "sentiment": {
-                "description": "Overall sentiment in current period",
-                "enum": [
-                  "positive",
-                  "neutral",
-                  "negative",
-                  "mixed"
-                ],
-                "type": "string"
-              }
-            },
-            "required": [
-              "averageRating",
-              "sentiment",
-              "reviewCount"
-            ],
-            "type": "object"
-          },
-          "direction": {
-            "description": "Overall trend direction (based on ±0.2 rating threshold)",
-            "enum": [
-              "improving",
-              "stable",
-              "declining"
-            ],
-            "type": "string"
-          },
-          "emergingIssues": {
-            "description": "New issues that emerged",
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
-          },
-          "previousPeriod": {
-            "additionalProperties": false,
-            "description": "Prior period summary",
-            "properties": {
-              "averageRating": {
-                "description": "Average rating in prior period (1-5)",
-                "maximum": 5,
-                "minimum": 1,
-                "type": "number"
-              },
-              "reviewCount": {
-                "description": "Number of reviews in prior period",
-                "minimum": 0,
-                "type": "integer"
-              },
-              "sentiment": {
-                "description": "Overall sentiment in prior period",
-                "enum": [
-                  "positive",
-                  "neutral",
-                  "negative",
-                  "mixed"
-                ],
-                "type": "string"
-              }
-            },
-            "required": [
-              "averageRating",
-              "sentiment",
-              "reviewCount"
-            ],
-            "type": "object"
-          },
-          "prominenceChanges": {
-            "description": "Themes gaining or losing prominence",
-            "items": {
-              "additionalProperties": false,
-              "properties": {
-                "note": {
-                  "description": "Brief explanation of the change",
-                  "type": "string"
-                },
-                "theme": {
-                  "description": "Theme name",
-                  "minLength": 1,
-                  "type": "string"
-                },
-                "trend": {
-                  "description": "Direction of change",
-                  "enum": [
-                    "increasing",
-                    "stable",
-                    "decreasing"
-                  ],
-                  "type": "string"
-                }
-              },
-              "required": [
-                "theme",
-                "trend"
-              ],
-              "type": "object"
-            },
-            "type": "array"
-          },
-          "ratingChange": {
-            "description": "Rating change between periods (current - previous)",
-            "type": "number"
-          },
-          "resolvedIssues": {
-            "description": "Issues that were resolved",
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
-          }
-        },
-        "required": [
-          "direction",
-          "previousPeriod",
-          "currentPeriod",
-          "emergingIssues",
-          "resolvedIssues"
-        ],
-        "type": "object"
-      }
-    },
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "bestPerformer": {
+        "additionalProperties": false,
+        "description": "Best performing location (for comparison analysis)",
+        "properties": {
+          "bestPractices": {
+            "description": "Practices other locations should adopt",
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "reason": {
+            "description": "Why this location performs best",
+            "type": "string"
+          },
+          "storeId": {
+            "description": "Store identifier of the best performing location",
+            "minLength": 1,
+            "type": "string"
+          }
+        },
+        "required": [
+          "storeId",
+          "reason",
+          "bestPractices"
+        ],
+        "type": "object"
+      },
+      "commonStrengths": {
+        "description": "Strengths shared across locations (for comparison analysis)",
+        "items": {
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "commonWeaknesses": {
+        "description": "Weaknesses shared across locations (for comparison analysis)",
+        "items": {
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "issues": {
+        "description": "Issues identified (for issues analysis)",
+        "items": {
+          "additionalProperties": false,
+          "properties": {
+            "affectedLocations": {
+              "description": "Store IDs of affected locations",
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            },
+            "category": {
+              "description": "Issue category (e.g., \"Wait Times\", \"Cleanliness\", \"Staff\")",
+              "minLength": 1,
+              "type": "string"
+            },
+            "description": {
+              "description": "Description of the issue",
+              "minLength": 1,
+              "type": "string"
+            },
+            "exampleQuotes": {
+              "description": "Representative quotes illustrating this issue",
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            },
+            "frequency": {
+              "description": "How often this issue appears",
+              "maximum": 9007199254740991,
+              "minimum": 0,
+              "type": "integer"
+            },
+            "severity": {
+              "description": "Severity level of the issue",
+              "enum": [
+                "low",
+                "medium",
+                "high",
+                "critical"
+              ],
+              "type": "string"
+            },
+            "suggestedAction": {
+              "description": "Recommended action to address the issue",
+              "type": "string"
+            }
+          },
+          "required": [
+            "category",
+            "description",
+            "severity",
+            "frequency"
+          ],
+          "type": "object"
+        },
+        "type": "array"
+      },
+      "locationComparison": {
+        "description": "Location comparison (for comparison analysis)",
+        "items": {
+          "additionalProperties": false,
+          "properties": {
+            "averageRating": {
+              "description": "Average rating for this location (1-5)",
+              "maximum": 5,
+              "minimum": 1,
+              "type": "number"
+            },
+            "locationName": {
+              "description": "Location name",
+              "type": "string"
+            },
+            "lowConfidence": {
+              "description": "True when location has few reviews (<10)",
+              "type": "boolean"
+            },
+            "recommendations": {
+              "description": "Specific actions to improve this location",
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            },
+            "reviewCount": {
+              "description": "Number of reviews analyzed",
+              "maximum": 9007199254740991,
+              "minimum": 0,
+              "type": "integer"
+            },
+            "sentiment": {
+              "description": "Overall sentiment for this location",
+              "enum": [
+                "positive",
+                "neutral",
+                "negative",
+                "mixed"
+              ],
+              "type": "string"
+            },
+            "storeId": {
+              "description": "Store identifier",
+              "minLength": 1,
+              "type": "string"
+            },
+            "strengths": {
+              "description": "Key strengths identified",
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            },
+            "weaknesses": {
+              "description": "Key weaknesses identified",
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            }
+          },
+          "required": [
+            "storeId",
+            "averageRating",
+            "reviewCount",
+            "sentiment",
+            "strengths",
+            "weaknesses"
+          ],
+          "type": "object"
+        },
+        "type": "array"
+      },
+      "summary": {
+        "additionalProperties": false,
+        "description": "Executive summary (for summary analysis)",
+        "properties": {
+          "averageRating": {
+            "description": "Average rating across analyzed reviews (1-5)",
+            "maximum": 5,
+            "minimum": 1,
+            "type": "number"
+          },
+          "executiveSummary": {
+            "description": "2-3 sentence summary of findings",
+            "minLength": 1,
+            "type": "string"
+          },
+          "lowConfidence": {
+            "description": "True when sample size is small (<20 reviews)",
+            "type": "boolean"
+          },
+          "overallSentiment": {
+            "description": "Overall sentiment classification",
+            "enum": [
+              "positive",
+              "neutral",
+              "negative",
+              "mixed"
+            ],
+            "type": "string"
+          },
+          "ratingDistribution": {
+            "additionalProperties": {
+              "maximum": 9007199254740991,
+              "minimum": 0,
+              "type": "integer"
+            },
+            "description": "Rating distribution (e.g., {\"5\": 100, \"4\": 50})",
+            "propertyNames": {
+              "type": "string"
+            },
+            "type": "object"
+          },
+          "sentimentDistribution": {
+            "additionalProperties": false,
+            "description": "Sentiment breakdown by percentage",
+            "properties": {
+              "negative": {
+                "description": "Percentage of negative reviews (0-100)",
+                "maximum": 100,
+                "minimum": 0,
+                "type": "number"
+              },
+              "neutral": {
+                "description": "Percentage of neutral reviews (0-100)",
+                "maximum": 100,
+                "minimum": 0,
+                "type": "number"
+              },
+              "positive": {
+                "description": "Percentage of positive reviews (0-100)",
+                "maximum": 100,
+                "minimum": 0,
+                "type": "number"
+              }
+            },
+            "required": [
+              "positive",
+              "neutral",
+              "negative"
+            ],
+            "type": "object"
+          }
+        },
+        "required": [
+          "executiveSummary",
+          "overallSentiment",
+          "averageRating",
+          "sentimentDistribution",
+          "ratingDistribution"
+        ],
+        "type": "object"
+      },
+      "themes": {
+        "additionalProperties": false,
+        "description": "Theme analysis (for summary/themes analysis)",
+        "properties": {
+          "negative": {
+            "description": "Negative themes/areas for improvement",
+            "items": {
+              "additionalProperties": false,
+              "properties": {
+                "exampleQuote": {
+                  "description": "Representative quote illustrating this theme",
+                  "type": "string"
+                },
+                "frequency": {
+                  "description": "How often this theme appears in reviews",
+                  "maximum": 9007199254740991,
+                  "minimum": 0,
+                  "type": "integer"
+                },
+                "severity": {
+                  "description": "Severity level (for negative themes only)",
+                  "enum": [
+                    "low",
+                    "medium",
+                    "high",
+                    "critical"
+                  ],
+                  "type": "string"
+                },
+                "theme": {
+                  "description": "Theme or topic identified (e.g., \"Service Speed\", \"Staff Friendliness\")",
+                  "minLength": 1,
+                  "type": "string"
+                }
+              },
+              "required": [
+                "theme",
+                "frequency"
+              ],
+              "type": "object"
+            },
+            "type": "array"
+          },
+          "positive": {
+            "description": "Positive themes identified",
+            "items": {
+              "additionalProperties": false,
+              "properties": {
+                "exampleQuote": {
+                  "description": "Representative quote illustrating this theme",
+                  "type": "string"
+                },
+                "frequency": {
+                  "description": "How often this theme appears in reviews",
+                  "maximum": 9007199254740991,
+                  "minimum": 0,
+                  "type": "integer"
+                },
+                "severity": {
+                  "description": "Severity level (for negative themes only)",
+                  "enum": [
+                    "low",
+                    "medium",
+                    "high",
+                    "critical"
+                  ],
+                  "type": "string"
+                },
+                "theme": {
+                  "description": "Theme or topic identified (e.g., \"Service Speed\", \"Staff Friendliness\")",
+                  "minLength": 1,
+                  "type": "string"
+                }
+              },
+              "required": [
+                "theme",
+                "frequency"
+              ],
+              "type": "object"
+            },
+            "type": "array"
+          }
+        },
+        "required": [
+          "positive",
+          "negative"
+        ],
+        "type": "object"
+      },
+      "trends": {
+        "additionalProperties": false,
+        "description": "Trends analysis (for trends analysis)",
+        "properties": {
+          "currentPeriod": {
+            "additionalProperties": false,
+            "description": "Current period summary",
+            "properties": {
+              "averageRating": {
+                "description": "Average rating in current period (1-5)",
+                "maximum": 5,
+                "minimum": 1,
+                "type": "number"
+              },
+              "reviewCount": {
+                "description": "Number of reviews in current period",
+                "maximum": 9007199254740991,
+                "minimum": 0,
+                "type": "integer"
+              },
+              "sentiment": {
+                "description": "Overall sentiment in current period",
+                "enum": [
+                  "positive",
+                  "neutral",
+                  "negative",
+                  "mixed"
+                ],
+                "type": "string"
+              }
+            },
+            "required": [
+              "averageRating",
+              "sentiment",
+              "reviewCount"
+            ],
+            "type": "object"
+          },
+          "direction": {
+            "description": "Overall trend direction (based on ±0.2 rating threshold)",
+            "enum": [
+              "improving",
+              "stable",
+              "declining"
+            ],
+            "type": "string"
+          },
+          "emergingIssues": {
+            "description": "New issues that emerged",
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "previousPeriod": {
+            "additionalProperties": false,
+            "description": "Prior period summary",
+            "properties": {
+              "averageRating": {
+                "description": "Average rating in prior period (1-5)",
+                "maximum": 5,
+                "minimum": 1,
+                "type": "number"
+              },
+              "reviewCount": {
+                "description": "Number of reviews in prior period",
+                "maximum": 9007199254740991,
+                "minimum": 0,
+                "type": "integer"
+              },
+              "sentiment": {
+                "description": "Overall sentiment in prior period",
+                "enum": [
+                  "positive",
+                  "neutral",
+                  "negative",
+                  "mixed"
+                ],
+                "type": "string"
+              }
+            },
+            "required": [
+              "averageRating",
+              "sentiment",
+              "reviewCount"
+            ],
+            "type": "object"
+          },
+          "prominenceChanges": {
+            "description": "Themes gaining or losing prominence",
+            "items": {
+              "additionalProperties": false,
+              "properties": {
+                "note": {
+                  "description": "Brief explanation of the change",
+                  "type": "string"
+                },
+                "theme": {
+                  "description": "Theme name",
+                  "minLength": 1,
+                  "type": "string"
+                },
+                "trend": {
+                  "description": "Direction of change",
+                  "enum": [
+                    "increasing",
+                    "stable",
+                    "decreasing"
+                  ],
+                  "type": "string"
+                }
+              },
+              "required": [
+                "theme",
+                "trend"
+              ],
+              "type": "object"
+            },
+            "type": "array"
+          },
+          "ratingChange": {
+            "description": "Rating change between periods (current - previous)",
+            "type": "number"
+          },
+          "resolvedIssues": {
+            "description": "Issues that were resolved",
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          }
+        },
+        "required": [
+          "direction",
+          "previousPeriod",
+          "currentPeriod",
+          "emergingIssues",
+          "resolvedIssues"
+        ],
+        "type": "object"
+      }
+    },
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

removedOutput schema / properties / largeDatasetWarning / properties / dateRange / $ref
```
Removed value: -"#/properties/metadata/properties/dateRange"
```
addedOutput schema / properties / largeDatasetWarning / properties / dateRange / additionalProperties
```
Added value: +false
```

addedOutput schema / properties / largeDatasetWarning / properties / dateRange / properties

Added value: +{
+  "from": {
+    "description": "Start date (YYYY-MM-DD)",
+    "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+    "type": "string"
+  },
+  "to": {
+    "description": "End date (YYYY-MM-DD)",
+    "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+    "type": "string"
+  }
+}

addedOutput schema / properties / largeDatasetWarning / properties / dateRange / required
```
Added value: +[
+  "from",
+  "to"
+]
```
addedOutput schema / properties / largeDatasetWarning / properties / dateRange / type
```
Added value: +"object"
```
addedOutput schema / properties / largeDatasetWarning / properties / estimatedTokens / maximum
```
Added value: +9007199254740991
```
addedOutput schema / properties / largeDatasetWarning / properties / locationCount / maximum
```
Added value: +9007199254740991
```
addedOutput schema / properties / largeDatasetWarning / properties / options / items / properties / estimatedTokens / maximum
```
Added value: +9007199254740991
```
addedOutput schema / properties / largeDatasetWarning / properties / options / items / properties / parameters / propertyNames
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / largeDatasetWarning / properties / totalReviewCount / maximum
```
Added value: +9007199254740991
```
addedOutput schema / properties / metadata / properties / analyzedReviewCount / maximum
```
Added value: +9007199254740991
```
addedOutput schema / properties / metadata / properties / cache / properties / ttl / maximum
```
Added value: +9007199254740991
```
addedOutput schema / properties / metadata / properties / locationCount / maximum
```
Added value: +9007199254740991
```
addedOutput schema / properties / metadata / properties / totalReviewCount / maximum
```
Added value: +9007199254740991
```

First observedv4.0.0Aug 10, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Even though readOnlyHint=true already signals a safe read, the description adds substantial behavioral context: analysis types 'issues', 'trends', and 'themes' currently return the same payload as 'summary' with a warningCode, results are cached for 1 hour, forceRefresh bypasses the cache, and large datasets trigger warnings or require sampling. It also clarifies that output is descriptive statistics, not LLM-generated prose.

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 long but well-structured with clear sections: summary, analysis types, large dataset handling, sampling strategies, caching, and exclusions. Each section earns its place by conveying decision-relevant behavior, and the main purpose is front-loaded in the first sentence.

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 tool has 11 parameters, 3 enums, and no nested objects, the description covers all decision-critical context: return behavior, analysis limitations, caching, dataset thresholds, sampling strategies, and alternatives. With the output schema also present, nothing an agent needs to call this tool correctly is missing.

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 already describes all 11 parameters fully, so the baseline is solid. The description goes further by explaining what each analysisType actually returns, including the undifferentiated fallback behavior, what each sampling strategy does, and when skipConfirmation is meaningful. This adds real value 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 opening sentence clearly states the verb, resource, and output: 'Summarize Google reviews into rating and sentiment statistics.' It explicitly contrasts itself with raw review retrieval and aggregate ratings, and later names the sibling tools it is not, making purpose and differentiation unambiguous.

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?

The description includes an explicit 'When NOT to use this tool' section listing the exact sibling tools for raw text, aggregate stats, and specific review lookup. It also provides decision guidance for large datasets and sampling strategies, so an agent knows precisely when and how to invoke this tool.

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

Deploy Server