Skip to main content
Glama

iGods GEO Visibility Tool (GVT)

by com.igods
OverviewDiscussionsAdmin

Run batch tests

gvt_run_visibility_batch

Queue up to 500 URLs for batch GEO visibility testing. Returns a batch ID for tracking progress. Optionally add URLs to recurring schedules (daily, weekly, monthly) during the same call. Poll gvt_get_batch_status with the batchId until status is completed or failed; then get the compact per-page score summary with gvt_get_batch_summary, or individual results with gvt_get_test_results. This tool queues paid test runs and consumes credits; for score interpretation, methodology, or reference knowledge, use gvt_get_knowledge instead — it never runs tests. A webhook URL can be provided to receive a completion notification; when set, the response returns webhookSecret, an HMAC key for verifying that the notification genuinely came from GVT. Duplicate URLs in the submitted array are collapsed, so totalUrls may be smaller than the array you sent.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
urlsYesArray of URL objects to test (max 500)
webhookUrlNoOptional HTTPS URL to receive a batch completion webhook

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
statusNoAlways queued at submission time
batchIdNoUUID for tracking the batch
totalUrlsNoURLs accepted into the batch
webhookSecretNoHMAC secret for verifying the webhook, null when no webhook
webhookConfiguredNoTrue when a completion webhook URL was supplied

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedOutput schema / description
      Previous value: -"Batch acknowledgement. Poll gvt_get_test_results per URL once the batch completes."New value: +"Batch acknowledgement. Poll gvt_get_batch_status with the batchId until status is completed or failed, then retrieve results via gvt_get_test_results."
  2. Changed4 schema fields changed
    • addedOutput schema / properties / status / description
      Added value: +"Always queued at submission time"
    • addedOutput schema / properties / totalUrls / description
      Added value: +"URLs accepted into the batch"
    • addedOutput schema / properties / webhookConfigured / description
      Added value: +"True when a completion webhook URL was supplied"
    • addedOutput schema / properties / webhookSecret / description
      Added value: +"HMAC secret for verifying the webhook, null when no webhook"
  3. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "description": "Batch acknowledgement. Poll gvt_get_test_results per URL once the batch completes.",
+  "properties": {
+    "batchId": {
+      "description": "UUID for tracking the batch",
+      "type": "string"
+    },
+    "status": {
+      "enum": [
+        "queued"
+      ],
+      "type": "string"
+    },
+    "totalUrls": {
+      "type": "integer"
+    },
+    "webhookConfigured": {
+      "type": "boolean"
+    },
+    "webhookSecret": {
+      "type": [
+        "string",
+        "null"
+      ]
+    }
+  },
+  "type": "object"
+}
  4. Added

TDQS

A4.8/5.0
Behavior5/5

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

Annotations cover the safety profile (readOnlyHint=false, idempotentHint=false, openWorldHint=true), and the description adds substantial context beyond them: it queues paid runs that consume credits, operates asynchronously with a batch ID, supports an optional webhook that returns an HMAC webhookSecret for verification, and collapses duplicate URLs so totalUrls may be smaller than the input array. This is exactly the extra behavioral detail the annotations cannot 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?

Front-loaded with purpose, then workflow, then cost, then webhook and dedupe caveats. Every sentence carries information, though the paragraph is dense and could be split for scannability. No filler or repetition.

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 an output schema present, return values needn't be described, and the description still covers the async workflow, credit cost, webhook verification, and dedupe caveat. Nothing an agent needs to queue and track a batch 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: webhookUrl's effect (completion notification + returned webhookSecret for HMAC verification), the dedupe behavior affecting totalUrls, and the recurring-schedule option embedded in each URL object. Only the exact addToSchedule semantics remain schema-only.

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 (queue) and resource (up to 500 URLs for batch GEO visibility testing) with explicit scope. It cleanly distinguishes itself from the single-URL sibling and from the read-side batch tools it hands off to. An agent can identify the tool's role without opening any schema.

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?

Explicit workflow routing: poll gvt_get_batch_status until completed/failed, then use gvt_get_batch_summary or gvt_get_test_results. It also carves out the when-not case by directing interpretation/methodology needs to gvt_get_knowledge. Alternatives and conditions are named rather than inferred.

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

All iGods GEO Visibility Tool (GVT) 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