Skip to main content
Glama

Mark

by com.use-mark.app
OverviewDiscussionsAdmin

Compare Buyer Question Answers

compare_buyer_question_answers
Read-onlyIdempotent

Two stored check runs of one buyer question in one market, side by side per engine: each side's answer text, whether it cited or named you (youNamed: your current business name in the text), which tracked competitors it named or cited, and its cited pages with their stored titles; plus the pages cited in After and not Before (added), the reverse (dropped), and a count cited in both. Pages match ignoring www., case of the host and a trailing slash. By default After is the newest run and Before is the last run before the question's live answer page was last published or pushed to the CMS (else the previous run); defaultReason says which. Lists every completed or partial run you can pass, same-week reruns included. Reads stored checks only. Related: get_buyer_question_answers, get_ai_visibility.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
marketNoActive market id or exact name. Defaults to the market Performance > AI answers shows.
questionYesActive buyer question id, or its exact text (case and outer spaces ignored).
afterRunIdNoA run id from runs. Defaults to the newest. Before newer than After swaps them.
beforeRunIdNoA run id from runs. Unknown or failed ids fall back to the default.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
foundYes
appUrlYes
reasonYes
comparisonYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedOutput schema / properties / comparison / anyOf
      Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "afterRunId": {
-        "description": "Both null with fewer than two runs.",
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "beforeRunId": {
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "defaultReason": {
-        "anyOf": [
-          {
-            "additionalProperties": false,
-            "properties": {
-              "changedAt": {
-                "type": [
-                  "string",
-                  "null"
-                ]
-              },
-              "kind": {
-                "enum": [
-                  "answer_page_changed",
-                  "no_check_since_change",
-                  "previous_run"
-                ],
-                "type": "string"
-              },
-              "page": {
-                "anyOf": [
-                  {
-                    "additionalProperties": false,
-                    "properties": {
-                      "label": {
-                        "type": "string"
-                      },
-                      "postId": {
-                        "type": "string"
-                      }
-                    },
-                    "required": [
-                      "postId",
-                      "label"
-                    ],
-                    "type": "object"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ]
-              }
-            },
-            "required": [
-              "kind",
-              "page",
-              "changedAt"
-            ],
-            "type": "object"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "Why Mark picked Before; null when you passed beforeRunId. The page and changedAt are the answer page change it keyed on."
-      },
-      "engines": {
-        "items": {
-          "additionalProperties": false,
-          "properties": {
-            "after": {
-              "additionalProperties": false,
-              "properties": {
-                "answerText": {
-                  "type": [
-                    "string",
-                    "null"
-                  ]
-                },
-                "baseline": {
-                  "anyOf": [
-                    {
-                      "additionalProperties": false,
-                      "properties": {
-                        "checkedAt": {
-                          "type": "string"
-                        },
-                        "state": {
-                          "type": "string"
-                        }
-                      },
-                      "required": [
-                        "state",
-                        "checkedAt"
-                      ],
-                      "type": "object"
-                    },
-                    {
-                      "type": "null"
-                    }
-                  ],
-                  "description": "The first answered check for this question and engine in this market (cited, mentioned or not_mentioned, and when); null when none."
-                },
-                "checkedAt": {
-                  "type": [
-                    "string",
-                    "null"
-                  ]
-                },
-                "citedPages": {
-                  "items": {
-                    "additionalProperties": false,
-                    "properties": {
-                      "answerPage": {
-                        "description": "The live URL of a post linked to this question.",
-                        "type": "boolean"
-                      },
-                      "competitor": {
-                        "type": [
-                          "string",
-                          "null"
-                        ]
-                      },
-                      "url": {
-                        "type": "string"
-                      },
-                      "yours": {
-                        "type": "boolean"
-                      }
-                    },
-                    "required": [
-                      "url",
-                      "yours",
-                      "answerPage",
-                      "competitor"
-                    ],
-                    "type": "object"
-                  },
-                  "type": "array"
-                },
-                "competitors": {
-                  "description": "Active tracked competitors the answer named or cited.",
-                  "items": {
-                    "additionalProperties": false,
-                    "properties": {
-                      "cited": {
-                        "type": "boolean"
-                      },
-                      "name": {
-                        "type": "string"
-                      },
-                      "named": {
-                        "type": "boolean"
-                      }
-                    },
-                    "required": [
-                      "name",
-                      "named",
-                      "cited"
-                    ],
-                    "type": "object"
-                  },
-                  "type": "array"
-                },
-                "failedAt": {
-                  "type": [
-                    "string",
-                    "null"
-                  ]
-                },
-                "failedReason": {
-                  "description": "Why the check failed, as recorded; null unless failed.",
-                  "type": [
-                    "string",
-                    "null"
-                  ]
-                },
-                "platform": {
-                  "type": "string"
-                },
-                "state": {
-                  "description": "cited, mentioned or not_mentioned are answers about you. no_answer, unknown, failed, not_set_up and no_data are not, and never mean not mentioned.",
-                  "type": "string"
-                }
-              },
-              "required": [
-                "platform",
-                "state",
-                "failedAt",
-                "failedReason",
-                "checkedAt",
-                "baseline",
-                "answerText",
-                "competitors",
-                "citedPages"
-              ],
-              "type": "object"
-            },
-            "before": {
-              "additionalProperties": false,
-              "properties": {
-                "answerText": {
-                  "type": [
-                    "string",
-                    "null"
-                  ]
-                },
-                "baseline": {
-                  "anyOf": [
-                    {
-                      "additionalProperties": false,
-                      "properties": {
-                        "checkedAt": {
-                          "type": "string"
-                        },
-                        "state": {
-                          "type": "string"
-                        }
-                      },
-                      "required": [
-                        "state",
-                        "checkedAt"
-                      ],
-                      "type": "object"
-                    },
-                    {
-                      "type": "null"
-                    }
-                  ],
-                  "description": "The first answered check for this question and engine in this market (cited, mentioned or not_mentioned, and when); null when none."
-                },
-                "checkedAt": {
-                  "type": [
-                    "string",
-                    "null"
-                  ]
-                },
-                "citedPages": {
-                  "items": {
-                    "additionalProperties": false,
-                    "properties": {
-                      "answerPage": {
-                        "description": "The live URL of a post linked to this question.",
-                        "type": "boolean"
-                      },
-                      "competitor": {
-                        "type": [
-                          "string",
-                          "null"
-                        ]
-                      },
-                      "url": {
-                        "type": "string"
-                      },
-                      "yours": {
-                        "type": "boolean"
-                      }
-                    },
-                    "required": [
-                      "url",
-                      "yours",
-                      "answerPage",
-                      "competitor"
-                    ],
-                    "type": "object"
-                  },
-                  "type": "array"
-                },
-                "competitors": {
-                  "description": "Active tracked competitors the answer named or cited.",
-                  "items": {
-                    "additionalProperties": false,
-                    "properties": {
-                      "cited": {
-                        "type": "boolean"
-                      },
-                      "name": {
-                        "type": "string"
-                      },
-                      "named": {
-                        "type": "boolean"
-                      }
-                    },
-                    "required": [
-                      "name",
-                      "named",
-                      "cited"
-                    ],
-                    "type": "object"
-                  },
-                  "type": "array"
-                },
-                "failedAt": {
-                  "type": [
-                    "string",
-                    "null"
-                  ]
-                },
-                "failedReason": {
-                  "description": "Why the check failed, as recorded; null unless failed.",
-                  "type": [
-                    "string",
-                    "null"
-                  ]
-                },
-                "platform": {
-                  "type": "string"
-                },
-                "state": {
-                  "description": "cited, mentioned or not_mentioned are answers about you. no_answer, unknown, failed, not_set_up and no_data are not, and never mean not mentioned.",
-                  "type": "string"
-                }
-              },
-              "required": [
-                "platform",
-                "state",
-                "failedAt",
-                "failedReason",
-                "checkedAt",
-                "baseline",
-                "answerText",
-                "competitors",
-                "citedPages"
-              ],
-              "type": "object"
-            },
-            "citations": {
-              "anyOf": [
-                {
-                  "additionalProperties": false,
-                  "properties": {
-                    "added": {
-                      "description": "Pages cited in After and not in Before.",
-                      "items": {
-                        "additionalProperties": false,
-                        "properties": {
-                          "answerPage": {
-                            "description": "The live URL of a post linked to this question.",
-                            "type": "boolean"
-                          },
-                          "competitor": {
-                            "type": [
-                              "string",
-                              "null"
-                            ]
-                          },
-                          "url": {
-                            "type": "string"
-                          },
-                          "yours": {
-                            "type": "boolean"
-                          }
-                        },
-                        "required": [
-                          "url",
-                          "yours",
-                          "answerPage",
-                          "competitor"
-                        ],
-                        "type": "object"
-                      },
-                      "type": "array"
-                    },
-                    "dropped": {
-                      "description": "Pages cited in Before and not in After.",
-                      "items": {
-                        "additionalProperties": false,
-                        "properties": {
-                          "answerPage": {
-                            "description": "The live URL of a post linked to this question.",
-                            "type": "boolean"
-                          },
-                          "competitor": {
-                            "type": [
-                              "string",
-                              "null"
-                            ]
-                          },
-                          "url": {
-                            "type": "string"
-                          },
-                          "yours": {
-                            "type": "boolean"
-                          }
-                        },
-                        "required": [
-                          "url",
-                          "yours",
-                          "answerPage",
-                          "competitor"
-                        ],
-                        "type": "object"
-                      },
-                      "type": "array"
-                    },
-                    "inBoth": {
-                      "description": "Pages cited in both.",
-                      "type": "number"
-                    }
-                  },
-                  "required": [
-                    "added",
-                    "dropped",
-                    "inBoth"
-                  ],
-                  "type": "object"
-                },
-                {
-                  "type": "null"
-                }
-              ],
-              "description": "Null when either side has no completed check for this engine."
-            },
-            "notCompared": {
-              "description": "The sides with no completed check for this engine.",
-              "items": {
-                "enum": [
-                  "before",
-                  "after"
-                ],
-                "type": "string"
-              },
-              "type": "array"
-            },
-            "platform": {
-              "type": "string"
-            }
-          },
-          "required": [
-            "platform",
-            "before",
-            "after",
-            "citations",
-            "notCompared"
-          ],
-          "type": "object"
-        },
-        "type": "array"
-      },
-      "market": {
-        "additionalProperties": false,
-        "properties": {
-          "id": {
-            "type": "string"
-          },
-          "name": {
-            "type": "string"
-          }
-        },
-        "required": [
-          "id",
-          "name"
-        ],
-        "type": "object"
-      },
-      "question": {
-        "additionalProperties": false,
-        "properties": {
-          "id": {
-            "type": "string"
-          },
-          "question": {
-            "type": "string"
-          },
-          "topic": {
-            "description": "The question's topic, if set.",
-            "type": [
-              "string",
-              "null"
-            ]
-          }
-        },
-        "required": [
-          "id",
-          "question",
-          "topic"
-        ],
-        "type": "object"
-      },
-      "runs": {
-        "description": "Every completed or partial check run that asked this question in this market, newest first; same-week reruns are separate entries.",
-        "items": {
-          "additionalProperties": false,
-          "properties": {
-            "finishedAt": {
-              "type": "string"
-            },
-            "id": {
-              "type": "string"
-            },
-            "weekKey": {
-              "type": "string"
-            },
-            "weekOf": {
-              "type": "string"
-            }
-          },
-          "required": [
-            "id",
-            "weekKey",
-            "weekOf",
-            "finishedAt"
-          ],
-          "type": "object"
-        },
-        "type": "array"
-      }
-    },
-    "required": [
-      "question",
-      "market",
-      "runs",
-      "beforeRunId",
-      "afterRunId",
-      "defaultReason",
-      "engines"
-    ],
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "afterRunId": {
+        "description": "Both null with fewer than two runs.",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "beforeRunId": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "defaultReason": {
+        "anyOf": [
+          {
+            "additionalProperties": false,
+            "properties": {
+              "changedAt": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "kind": {
+                "enum": [
+                  "answer_page_changed",
+                  "no_check_since_change",
+                  "previous_run"
+                ],
+                "type": "string"
+              },
+              "page": {
+                "anyOf": [
+                  {
+                    "additionalProperties": false,
+                    "properties": {
+                      "label": {
+                        "type": "string"
+                      },
+                      "postId": {
+                        "type": "string"
+                      }
+                    },
+                    "required": [
+                      "postId",
+                      "label"
+                    ],
+                    "type": "object"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ]
+              }
+            },
+            "required": [
+              "kind",
+              "page",
+              "changedAt"
+            ],
+            "type": "object"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Why Mark picked Before; null when you passed beforeRunId. The page and changedAt are the answer page change it keyed on."
+      },
+      "engines": {
+        "items": {
+          "additionalProperties": false,
+          "properties": {
+            "after": {
+              "additionalProperties": false,
+              "properties": {
+                "answerText": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "baseline": {
+                  "anyOf": [
+                    {
+                      "additionalProperties": false,
+                      "properties": {
+                        "checkedAt": {
+                          "type": "string"
+                        },
+                        "state": {
+                          "type": "string"
+                        }
+                      },
+                      "required": [
+                        "state",
+                        "checkedAt"
+                      ],
+                      "type": "object"
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ],
+                  "description": "The first answered check for this question and engine in this market (cited, mentioned or not_mentioned, and when); null when none."
+                },
+                "checkedAt": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "citedPages": {
+                  "items": {
+                    "additionalProperties": false,
+                    "properties": {
+                      "answerPage": {
+                        "description": "The live URL of a post linked to this question.",
+                        "type": "boolean"
+                      },
+                      "competitor": {
+                        "type": [
+                          "string",
+                          "null"
+                        ]
+                      },
+                      "title": {
+                        "description": "The page title the engine returned with the answer; null when it gave none. Pages are never fetched for it.",
+                        "type": [
+                          "string",
+                          "null"
+                        ]
+                      },
+                      "url": {
+                        "type": "string"
+                      },
+                      "yours": {
+                        "type": "boolean"
+                      }
+                    },
+                    "required": [
+                      "url",
+                      "yours",
+                      "answerPage",
+                      "competitor",
+                      "title"
+                    ],
+                    "type": "object"
+                  },
+                  "type": "array"
+                },
+                "competitors": {
+                  "description": "Active tracked competitors the answer named or cited.",
+                  "items": {
+                    "additionalProperties": false,
+                    "properties": {
+                      "cited": {
+                        "type": "boolean"
+                      },
+                      "name": {
+                        "type": "string"
+                      },
+                      "named": {
+                        "type": "boolean"
+                      }
+                    },
+                    "required": [
+                      "name",
+                      "named",
+                      "cited"
+                    ],
+                    "type": "object"
+                  },
+                  "type": "array"
+                },
+                "failedAt": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "failedReason": {
+                  "description": "Why the check failed, as recorded; null unless failed.",
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "platform": {
+                  "type": "string"
+                },
+                "state": {
+                  "description": "cited, mentioned or not_mentioned are answers about you. no_answer, unknown, failed, not_set_up and no_data are not, and never mean not mentioned.",
+                  "type": "string"
+                },
+                "youNamed": {
+                  "description": "Whether the answer names your current business name or an alias, the rule the app highlights with; null with no answer text or no business name. state uses the name at check time, so the two can differ after a rename.",
+                  "type": [
+                    "boolean",
+                    "null"
+                  ]
+                }
+              },
+              "required": [
+                "platform",
+                "state",
+                "failedAt",
+                "failedReason",
+                "checkedAt",
+                "baseline",
+                "answerText",
+                "youNamed",
+                "competitors",
+                "citedPages"
+              ],
+              "type": "object"
+            },
+            "before": {
+              "additionalProperties": false,
+              "properties": {
+                "answerText": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "baseline": {
+                  "anyOf": [
+                    {
+                      "additionalProperties": false,
+                      "properties": {
+                        "checkedAt": {
+                          "type": "string"
+                        },
+                        "state": {
+                          "type": "string"
+                        }
+                      },
+                      "required": [
+                        "state",
+                        "checkedAt"
+                      ],
+                      "type": "object"
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ],
+                  "description": "The first answered check for this question and engine in this market (cited, mentioned or not_mentioned, and when); null when none."
+                },
+                "checkedAt": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "citedPages": {
+                  "items": {
+                    "additionalProperties": false,
+                    "properties": {
+                      "answerPage": {
+                        "description": "The live URL of a post linked to this question.",
+                        "type": "boolean"
+                      },
+                      "competitor": {
+                        "type": [
+                          "string",
+                          "null"
+                        ]
+                      },
+                      "title": {
+                        "description": "The page title the engine returned with the answer; null when it gave none. Pages are never fetched for it.",
+                        "type": [
+                          "string",
+                          "null"
+                        ]
+                      },
+                      "url": {
+                        "type": "string"
+                      },
+                      "yours": {
+                        "type": "boolean"
+                      }
+                    },
+                    "required": [
+                      "url",
+                      "yours",
+                      "answerPage",
+                      "competitor",
+                      "title"
+                    ],
+                    "type": "object"
+                  },
+                  "type": "array"
+                },
+                "competitors": {
+                  "description": "Active tracked competitors the answer named or cited.",
+                  "items": {
+                    "additionalProperties": false,
+                    "properties": {
+                      "cited": {
+                        "type": "boolean"
+                      },
+                      "name": {
+                        "type": "string"
+                      },
+                      "named": {
+                        "type": "boolean"
+                      }
+                    },
+                    "required": [
+                      "name",
+                      "named",
+                      "cited"
+                    ],
+                    "type": "object"
+                  },
+                  "type": "array"
+                },
+                "failedAt": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "failedReason": {
+                  "description": "Why the check failed, as recorded; null unless failed.",
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "platform": {
+                  "type": "string"
+                },
+                "state": {
+                  "description": "cited, mentioned or not_mentioned are answers about you. no_answer, unknown, failed, not_set_up and no_data are not, and never mean not mentioned.",
+                  "type": "string"
+                },
+                "youNamed": {
+                  "description": "Whether the answer names your current business name or an alias, the rule the app highlights with; null with no answer text or no business name. state uses the name at check time, so the two can differ after a rename.",
+                  "type": [
+                    "boolean",
+                    "null"
+                  ]
+                }
+              },
+              "required": [
+                "platform",
+                "state",
+                "failedAt",
+                "failedReason",
+                "checkedAt",
+                "baseline",
+                "answerText",
+                "youNamed",
+                "competitors",
+                "citedPages"
+              ],
+              "type": "object"
+            },
+            "citations": {
+              "anyOf": [
+                {
+                  "additionalProperties": false,
+                  "properties": {
+                    "added": {
+                      "description": "Pages cited in After and not in Before.",
+                      "items": {
+                        "additionalProperties": false,
+                        "properties": {
+                          "answerPage": {
+                            "description": "The live URL of a post linked to this question.",
+                            "type": "boolean"
+                          },
+                          "competitor": {
+                            "type": [
+                              "string",
+                              "null"
+                            ]
+                          },
+                          "title": {
+                            "description": "The page title the engine returned with the answer; null when it gave none. Pages are never fetched for it.",
+                            "type": [
+                              "string",
+                              "null"
+                            ]
+                          },
+                          "url": {
+                            "type": "string"
+                          },
+                          "yours": {
+                            "type": "boolean"
+                          }
+                        },
+                        "required": [
+                          "url",
+                          "yours",
+                          "answerPage",
+                          "competitor",
+                          "title"
+                        ],
+                        "type": "object"
+                      },
+                      "type": "array"
+                    },
+                    "dropped": {
+                      "description": "Pages cited in Before and not in After.",
+                      "items": {
+                        "additionalProperties": false,
+                        "properties": {
+                          "answerPage": {
+                            "description": "The live URL of a post linked to this question.",
+                            "type": "boolean"
+                          },
+                          "competitor": {
+                            "type": [
+                              "string",
+                              "null"
+                            ]
+                          },
+                          "title": {
+                            "description": "The page title the engine returned with the answer; null when it gave none. Pages are never fetched for it.",
+                            "type": [
+                              "string",
+                              "null"
+                            ]
+                          },
+                          "url": {
+                            "type": "string"
+                          },
+                          "yours": {
+                            "type": "boolean"
+                          }
+                        },
+                        "required": [
+                          "url",
+                          "yours",
+                          "answerPage",
+                          "competitor",
+                          "title"
+                        ],
+                        "type": "object"
+                      },
+                      "type": "array"
+                    },
+                    "inBoth": {
+                      "description": "Pages cited in both.",
+                      "type": "number"
+                    }
+                  },
+                  "required": [
+                    "added",
+                    "dropped",
+                    "inBoth"
+                  ],
+                  "type": "object"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Null when either side has no completed check for this engine."
+            },
+            "notCompared": {
+              "description": "The sides with no completed check for this engine.",
+              "items": {
+                "enum": [
+                  "before",
+                  "after"
+                ],
+                "type": "string"
+              },
+              "type": "array"
+            },
+            "platform": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "platform",
+            "before",
+            "after",
+            "citations",
+            "notCompared"
+          ],
+          "type": "object"
+        },
+        "type": "array"
+      },
+      "market": {
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "name": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "id",
+          "name"
+        ],
+        "type": "object"
+      },
+      "question": {
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "question": {
+            "type": "string"
+          },
+          "topic": {
+            "description": "The question's topic, if set.",
+            "type": [
+              "string",
+              "null"
+            ]
+          }
+        },
+        "required": [
+          "id",
+          "question",
+          "topic"
+        ],
+        "type": "object"
+      },
+      "runs": {
+        "description": "Every completed or partial check run that asked this question in this market, newest first; same-week reruns are separate entries.",
+        "items": {
+          "additionalProperties": false,
+          "properties": {
+            "finishedAt": {
+              "type": "string"
+            },
+            "id": {
+              "type": "string"
+            },
+            "weekKey": {
+              "type": "string"
+            },
+            "weekOf": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "id",
+            "weekKey",
+            "weekOf",
+            "finishedAt"
+          ],
+          "type": "object"
+        },
+        "type": "array"
+      }
+    },
+    "required": [
+      "question",
+      "market",
+      "runs",
+      "beforeRunId",
+      "afterRunId",
+      "defaultReason",
+      "engines"
+    ],
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]
  2. Added

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already declare the safe read-only, idempotent profile, yet the description adds substantial behavior: the default After/Before selection logic and defaultReason, the page-matching normalization (ignoring www., host case, trailing slash), and the fact that completed or partial runs including same-week reruns are all listed. This is well beyond what the annotations convey.

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?

Purpose is front-loaded in the first clause and the dense paragraph carries real content (default logic, matching rules, output fields). It is somewhat run-on and long, but nearly every clause earns its place rather than padding.

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?

An output schema exists, so return values need not be fully spelled out, yet the description still characterizes the compared fields (answer text, youNamed, competitors, cited pages, added/dropped/both). Combined with the default-resolution rules, an agent has everything needed to call it correctly.

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 the baseline is 3, but the description adds meaning beyond the schema by explaining the default Before run (last run before the live answer page was last published/pushed to the CMS, else the previous run) and the swap behavior. It reinforces rather than merely repeats 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?

States a specific verb (compare) and resource (two stored check runs of one buyer question in one market) and scopes it per engine. It is clearly distinguishable from the singular sibling get_buyer_question_answers and from get_ai_visibility, which it explicitly names as related.

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 clause 'Reads stored checks only' implicitly routes the agent away from run_answer_engine_check and other run-triggering tools, and the default Before/After selection rules give concrete context. However it never states explicitly when to prefer this over get_buyer_question_answers or get_ai_visibility, listing them only as 'Related'.

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

All Mark toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources