iGods GEO Visibility Tool (GVT)

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

Annotations already indicate destructive and non-read-only behavior, but the description adds significant context: the action cannot be undone, associated results are deleted, and existing schedules are preserved. These are non-obvious behaviors that the agent cannot infer from the schema or annotations.

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?

Three sentences with no wasted words. The first sentence states the core action and scope, the second flags permanence, and the third covers both the alternative and the schedule caveat. Every sentence earns its place.

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?

The description is complete for a destructive single-parameter tool. It covers the action, side effects, reversibility, and alternative routing. An output schema exists, so explaining return values is unnecessary, and the annotation profile already covers safety semantics.

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?

The single parameter 'tid' is already fully documented in the schema as 'The 8-character test ID of the test to delete.' The description does not add further meaning about the parameter beyond what the schema provides, so the baseline score 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 clearly states a specific action, resource, and scope: 'Permanently delete a test session and all its associated results.' It explicitly distinguishes itself from the sibling gvt_set_test_visibility, leaving no ambiguity about what this tool does.

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?

The description says exactly when to choose an alternative: 'Use gvt_set_test_visibility instead if you only want to hide a test from public view.' It also clarifies the boundary with scheduled tests, telling agents that recurring runs continue unless removed via gvt_schedule_test delete mode.

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?

Beyond the readOnly/idempotent/non-destructive annotations, the description discloses important behavior: it returns the oldest baseline, includes expired tests, and uses exact string equality matching on scheme, host, path, and trailing slash. This materially affects correct invocation.

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?

Every sentence earns its place: purpose, alternative tools, companion usage, and exact matching caveat. It is front-loaded with the core action and remains tightly organized without redundancy.

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?

Given a single required parameter, high schema coverage, an output schema, and annotations covering safety, the description supplies all needed selection and invocation context. It also routes to appropriate sibling tools for related use cases.

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?

The schema already documents the url parameter, so the baseline is 3. The description adds value by specifying exact string-equality semantics and trailing-slash sensitivity, going beyond the schema's 'must match the URL used when the test was run.'

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: 'Get the oldest baseline test snapshot for a single URL, including expired tests.' It clearly distinguishes this tool from related siblings by naming what it is not and how it differs.

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?

The description gives explicit alternatives: use gvt_get_score_trend for pre-computed deltas, gvt_list_baselines for many URLs, and gvt_get_latest for comparison. It also advises discovering the exact URL form with gvt_list_tests when uncertain.

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 cover readOnly/idempotent/non-destructive, but the description goes further: rate-limit consumption without test credits, 404 on unknown/pruned/foreign batchId, account-lifetime retention with no pruning, and deduplication so counts sum to totalUrls. These are non-obvious behaviors an agent needs.

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?

Front-loads purpose, then polling loop, then routing, then edge-case behaviors. Every sentence contributes distinct, actionable information with no filler.

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?

Output schema exists, so return values need no explanation. For an async batch-polling tool the description still covers the full lifecycle: polling termination, follow-up routing, retention, error handling, and counting semantics.

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 description coverage is 100% and the single batchId param is fully documented there, so the description's restatement that it comes from gvt_run_visibility_batch adds little. Baseline 3 is appropriate when the schema carries the parameter semantics.

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?

States a specific verb (retrieves) and resource (visibility testing batch) plus the exact payload (progress, state, tids). It is clearly distinguished from sibling readers like gvt_get_batch_summary and gvt_get_test_results, which it explicitly routes to.

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?

Gives an explicit polling loop: call with the batchId from gvt_run_visibility_batch until status is completed or failed. It also names the follow-up tools and the condition (tid present after a test completes) that selects each, leaving nothing to inference.

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 cover the read-only/idempotent safety profile, and the description adds substantial non-obvious behavior: in-flight batches silently return status without per-page data, the call consumes rate limit but never test credits, and it quantifies context savings (~1.6 MB to a few KB for 10 URLs).

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?

Front-loaded with the payload description before the routing and prerequisite notes, and every clause carries distinct information. The sentences are long and comma-chained, which costs some readability, but nothing is padding.

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?

For a single-parameter read tool with an existing output schema and full annotation coverage, the description covers purpose, prerequisites, cost, edge-case behavior, and sibling routing. An agent has everything needed to invoke 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?

Only one parameter with 100% schema description coverage, so the schema already documents batchId and its provenance. The description adds no additional syntax or format detail beyond what the schema states, 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?

States a specific verb and resource ('Compact per-page results and pre-computed aggregates for a completed visibility testing batch') and enumerates exactly what is returned. It clearly distinguishes itself from siblings gvt_get_test_results (element-level detail) and gvt_get_batch_status (polling).

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?

Names the workflows it serves (audit, status reports), the alternative it replaces (one gvt_get_test_results per URL), the prerequisite (batch must be completed, poll gvt_get_batch_status first), and the fallback for element-level detail. Explicit when-to-use and when-not-to-use.

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, idempotent, non-destructive behavior. The description adds meaningful behavioral detail beyond annotations: responses are static reference content, cacheable, and lookups are exact-match only with no fuzzy fallback. This materially informs the agent's invocation and caching expectations.

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 description is compact and front-loaded: the primary purpose and content list appear first, followed by ID provenance, resource-template equivalence, exact-match warning, and cacheability. Each sentence contributes distinct operational value with no filler or redundancy.

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 one well-documented parameter, an output schema present, and annotations covering safety, the description is complete for selection and invocation. It explains where the ID comes from, how to handle it, and the response characteristics, leaving no critical gap.

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%, with issue_id already documented as a stable identifier matching the fixId field. The description adds extra operational semantics beyond the schema: 'Copy fixId verbatim from the results output' and the not-found behavior for unknown or mistyped IDs. This enriches the parameter's meaning beyond the schema baseline.

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 opens with a specific verb and resource: 'Read the canonical fix record for one GVT issue type,' and enumerates the record's contents (severity range, impact, scoring weight, plain-language description, recommended remediation). This makes the tool's function unmistakable and distinct from generic knowledge or list tools among siblings.

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?

The description gives clear usage context: issue IDs come from the fixId field in gvt_get_test_results outputcars, and IDs must be copied verbatim because unknown or mistyped IDs return not-found. It does not explicitly name alternative tools or state when not to use this tool, but the guidance is sufficient for an agent to invoke it correctly.

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, idempotentHint, and non-destructive. The description adds valuable behavioral detail: exact case-sensitive matching, failure behavior (fail fast with valid list), and the service as MCP resources. This provides extra context beyond annotations without contradicting them.

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?

Three sentences with no wasted words. The main purpose is front-loaded, followed by important matching details and resource alternative. Every sentence earns its place.

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?

The output schema exists, so return values are covered. The description covers purpose, usage, matching behavior, and failure handling. It's complete for a simple read-only knowledge tool with one optional parameter.

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?

The schema description covers 100% of parameters, so baseline 3 is appropriate. The description mentions exact matching and case-sensitivity, which reinforces the enum behavior, but doesn't add additional semantics beyond what the schema already explains.

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 clearly states the tool reads GVT reference knowledge, listing specific content areas (scoring, bands, weights, categories, glossary). It distinguishes itself from sibling tools that run tests or get results, making selection unambiguous.

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?

The description gives clear context: use it to interpret test results instead of guessing. It doesn't explicitly name alternative tools, but given the tool's unique read-only knowledge role among siblings (e.g., gvt_get_test_results), the usage context is clear enough. Lacks explicit when-not conditions.

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, idempotentHint, and destructiveHint false. The description adds valuable specifics: exact string equality matching (not nearest-match), 404 on unrecorded URL, and scoping to the caller's own non-expired tests. While it doesn't detail response contents, the output schema exists to cover that. It goes beyond the annotations without contradicting them.

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 description is concise—four sentences, each serving a purpose: primary function, alternative tool, combination usage, and matching constraint. Information is front-loaded, and there is no redundant phrasing.

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?

For a single-parameter read-only tool with a full output schema and safety annotations, the description covers all necessary operational details: what it returns (latest non-expired snapshot), how to invoke it correctly (exact URL match), what errors to expect (404), and scope (own tests). No critical gap remains.

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% (the url parameter description matches the intent), and the description adds the exact-match requirement and 404 behavior, which the schema does not specify. It also clarifies the operation is for a single URL. This adds meaningful context 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 clearly states the operation: 'Get the most recent non-expired test snapshot for a single URL.' It distinguishes itself from the sibling gvt_get_score_trend by noting that tool is for pre-computed deltas, and also references gvt_get_baseline for full snapshot comparison. This is a specific verb+resource with explicit sibling differentiation.

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?

Explicitly names when to use gvt_get_score_trend instead ('For pre-computed baseline-vs-latest deltas without fetching full snapshots') and when to combine with gvt_get_baseline ('when you need the full snapshot detail on both ends'). It also provides a critical constraint: URL must match exactly, with 404 on mismatch. This gives clear, actionable selection guidance.

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 idempotentHint=true, readOnlyHint=true, and destructiveHint=false, so no contradiction. The description adds value beyond annotations by disclosing that it errors on unknown names/arguments rather than guessing, and that it returns effective arguments with defaults applied. It also states the output includes step-by-step instruction text, which is not in annotations. Minor gap: no mention of output format beyond being text, but with an output schema present, that is acceptable.

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 description is three sentences: the first gives the core purpose and output, the second explains source and error behavior, and the third instructs how to use the output. It is tightly written with no filler, though it front-loads the purpose but leaves the error caveat until the second sentence. Slightly more wordy than ideal but efficient.

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?

Given two parameters with full schema coverage and an output schema present, the description is complete for invoking the tool. It covers argument binding default behavior and error handling. One minor gap: it doesn't explicitly say that the returned steps might require additional context from gvt_list_prompts, but that is strong enough. The output schema likely details the return structure, so this is sufficient.

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%: the name parameter description is clear and provides an example, and arguments is described with a key-value example. The description adds value by clarifying that omitted optional arguments use defaults and that it returns effective arguments, but this is about behavior rather than parameter format. The schema already explains both parameters well, so description doesn't add significant new meaning.

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 clearly states the tool renders a GVT prompt workflow with concrete arguments and returns the instruction text plus bound arguments. It distinguishes itself from sibling tools like gvt_list_prompts by referencing it as the source of prompt names/arguments, and from other get_* tools by focusing on prompt rendering rather than retrieving data.

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?

Explicitly states when to use: when you need a rendered prompt workflow. It references sibling gvt_list_prompts for obtaining valid prompt names/argumentsages, and warns that unknown names/arguments cause errors, guiding the agent to check that list first. It also instructs to call the GVT tools referenced in the rendered text, avoiding misuse.

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?

Beyond the read-only/idempotent annotations, it discloses meaningful behavior: only non-expired tests are considered, deltas are pre-computed, results are limited to scores/deltas (not full snapshots), domain mode is alphabetical and capped by limit, and pagination follows hasMore/nextOffset. No contradictions with annotations.

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 description is front-loaded with the core comparison, then logically moves through scope, pagination, return scope, and alternatives. Every sentence has a purpose, though the pagination explanation partly duplicates the schema and could be tightened.

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?

Given the two-mode behavior, pagination, and likely domain expansion, the description covers all operational essentials: what the call does, how to constrain scope, how to page, what is returned, and which sibling to use for full snapshots. The output schema and annotations handle the remaining detail.

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 description coverage is 100%, so the baseline is 3. The description reinforces the XOR relationship and pagination flow, but most of that detail already exists in the input schema (offset is a row skip, ignored in single-URL mode, default limit 25, max 100). It adds clarity but not much new semantic information.

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 ('Compare'), a clear resource (oldest baseline vs latest non-expired test), and precise scope (single URL or domain). It also distinguishes itself from siblings by stating it returns scores and deltas only, and that full snapshots belong to gvt_get_baseline and gvt_get_latest.

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 explicit usage rules: provide exactly one of url or domain, describes domain-mode matching and pagination, and tells the agent when to prefer siblings ('for complete snapshots of one URL use gvt_get_baseline and gvt_get_latest'). This is actionable, not merely implied.

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 cover read-only/idempotent/non-destructive, but the description adds real context beyond them: results are scoped to the caller's own tests, pending/running states require a wait-and-retry, shareableTid signals public linkability, and the two detail modes have different payload contents. It stops short of pagination/size limits or output-shape guarantees.

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?

One dense paragraph, front-loaded with the returned fields before constraints and mode selection; every sentence carries information. It is longer than strictly needed (repeats some detail-enum content already in the schema), which keeps it from a 5.

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?

An output schema exists, yet the description still characterizes key return fields and the pending/running lifecycle, leaving no ambiguity about when the call is useful or how to interpret its results. Complete for a 2-parameter read tool.

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 baseline is 3; however, the description adds meaning beyond the schema by warning that tid must be copied verbatim (partial/reformatted values fail to match) and by recommending the 'summary' mode for reporting versus the 'full' default.

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?

States a specific verb+resource ('Get results for a visibility test by tid') and enumerates what is returned (overall scores, findingSentence, shareableTid, per-category resultData). It also distinguishes itself from siblings by naming gvt_get_batch_summary for batch-level scores and citing gvt_run_visibility_test/gvt_list_tests as tid sources.

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?

Explicitly routes the agent away from one-call-per-tid to gvt_get_batch_summary for compact per-page batch scores, and gives the retry condition when status is pending/running. It also advises which detail mode suits reporting workflows, so alternatives and conditions are both covered.

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?

The description adds behavioral details beyond the annotations: it states that results include the URL and its oldest test object (or null if no test exists), that results follow the submitted order, and that the batch limit is 100. While the annotations already cover read-only, idempotency, and open-world hints, the description provides useful additional constraints about batch limits and null handling.

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 description is concise and well-structured: it opens with the core functionality, then explains output structure, differentiators, use cases, batching guidance, and ordering – all in a few sentences. Every sentence adds value without redundancy.

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?

Given the tool's moderate complexity (one parameter, clear output structure, batch limits), the description covers everything needed: purpose, output shape, limitations, alternatives, and usage patterns. The presence of an output schema reduces the need to detail return values, and the description fills the remaining gaps.

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?

The schema already documents the 'urls' parameter with a description, but the tool description adds significant context: it explains that the URLs are used for baseline lookups, that the batch supports up to 100 items, and prescribes how to handle larger sets ('split larger URL sets into consecutive calls of at most 100'). This goes beyond the schema's basic description.

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 clearly identifies the tool's function: retrieving the oldest baseline test snapshots for a batch of URLs in a single call. It explicitly distinguishes it from similar tools like gvt_get_baseline (single URL) and gvt_get_score_trend (pre-computed deltas), making the purpose unmistakable.

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?

The description provides explicit guidance on when to use this tool: for bulk operations and monthly/periodic batch comparisons(via 'ideal for monthly/periodic batch comparisons'), when to use alternatives ('For a single URL use gvt_get_baseline'), and notes that it replaces up to 100 single calls, with clear batch size limits. It also suggests a follow-up step('then call gvt_get_latest per URL').

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 indicate readOnlyHint, idempotentHint, and destructiveHint are all true/false appropriately sums up safety. The description adds value by stating the catalog is static, costs nothing, never queues tests or consumes credits, which goes beyond what annotations provide. This is exactly the kind of behavioral transparency that helps an agent know side-effect-free it is.

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?

Three sentences, all packed with useful information: what it lists, what the entries contain, how to use the result, and the cost/static nature. No fluff. The most critical information (listing workflows and how to render them) is front-loaded.

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?

For a zero-parameter, read-only catalog tool, the description covers everything an agent needs: what it returns, how to act on it, and the fact it's free. The output schema likely lists the structure, so return values are covered. The description is complete for a tool of this simplicity.

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?

The tool has zero parameters, so the schema is complete. The description doesn't add param-specific semantics because there are none. It does explain what each entry in the returned list contains ('Each entry lists its arguments'), which adds context about the output beyond just the schema. Given 0 params, a baseline of 4 is appropriate, and the description meets it.

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 clearly states the tool lists GVT prompt workflows and explains what those are (user-invocable recipes that chain tools into tasks), with examples of the types of workflows. It distinguishes this from siblings like gvt_get_prompt, which renders a specific prompt. The verb 'list' and resource 'GVT prompt workflows' are specific and unambiguous.

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?

The description explicitly says when to use this tool: to get a catalog of workflows, and then use gvt_get_prompt to render a specific one. It also states that it costs nothing and can be called on every session start, implying it's appropriate as an initial step. It does not explicitly say when not to use it, but the routing to gvt_get_prompt is clear, and the context of siblings makes the alternative obvious.

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 declare readOnly, idempotent, and non-destructive, and the description adds meaningful behavioral detail beyond those: pagination, hidden completed one-off rows due to batch-run throwaway entries, the deliberate omission of tid because it is often stale, and the distinction that it consumes rate limit but never test credits. This is rich, honest context.

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?

Five sentences, each carrying a distinct piece of necessary information: function, unique purpose, hidden-row caveat, tid caveat with alternative routing, and read-only/rate-limit behavior. It is front-loaded with the core purpose and contains no filler or repetition of schema content.

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?

For an 8-parameter, 0-required, read-only list tool with an output schema, the description covers purpose, alternatives, behavioral caveats, and parameter edge cases. The output schema handles return-value details. Nothing an agent needs to invoke this correctly is missing.

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?

Input schema coverage is 100%, with each parameter already having a solid description, so the description does not need to restate them. The description does add useful context for includeCompletedOnce (why it is hidden by default and when to include it), but that is a marginal enhancement over an already complete 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?

States a specific verb ('Retrieves'), resource ('paginated roster of the authenticated caller's test monitoring schedules'), and capabilities (filtering by domain, frequency, status). It also distinguishes itself as the only way to discover schedules and schids, clearly separating it from sibling list tools like gvt_list_tests.

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?

Explicitly identifies when to use this tool (discovering existing schedules and schids for gvt_schedule_test's pause/resume/cancel/change_frequency modes) and when not to (for test result lookups, pointing to gvt_list_tests or gvt_get_latest). It also clarifies the edge case around includeCompletedOnce, leaving no ambiguity about selection.

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, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description goes beyond these by revealing concrete behaviors: it 'automatically flags robots.txt-blocked and already-tested pages', applies a '-25 significance penalty' to legal pages, and groups parameters into three jobs (discovery, ranking/paging, filtering). This adds substantive behavioral context that the annotations do not convey.

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 description is about 100 words—informative without being bloated. It front-loads the core purpose and then systematically covers flags and parameter grouping. While it could be tightened slightly, every sentence contributes useful information and no schema detail is needlessly repeated.

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?

For a tool with 9 parameters, an output schema, and rich annotations, the description is remarkably complete. It covers the purpose, the parameter organization, the specific behavioral flags, and the legalPages tri-state use case. The existence of an output schema covers return-value details, so no major gaps remain for an agent to call the tool 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 description coverage is 100%, so each parameter is already documented. The description adds a valuable organizational layer by grouping the nine parameters into three conceptual jobs (discovery, ranking/paging, filtering) and explaining the purpose of the legalPages filter. This helps an agent understand parameter relationships beyond the flat 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 states a specific verb ('discovers and ranks URLs') and a clear resource ('from a domain's XML sitemaps'), and explains the goal ('to find the most significant pages before analyzing them'). This is distinct from all sibling tools, which concern tests, baselines, prompts, and schedules—no other tool targets sitemap discovery. The purpose is unambiguous.

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?

The description positions the tool as a precursor to analysis ('before analyzing them') and gives explicit guidance on the legalPages filter for either dropping legal boilerplate or isolating it for a policy-coverage audit. It doesn't explicitly name alternative tools or state when not to use it, but the sibling set is clearly different, so the use case is well implied.

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 read-only, idempotent, non-destructive behavior, and the description does not contradict them. It adds contextual value by framing the tool as a discovery surface and stating the default ordering (newest first), which supplements the safety profile without duplicating it.

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 description is structured with the primary purpose front-loaded, a concise list of filter capabilities, and a valuable routing note at the end. Every sentence earns its place, and the length is appropriate for an 11-parameter tool.

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?

The description fully complements the rich schema and output schema. It explains the tool's role in the workflow, tells the agent exactly how to use it to obtain tids and URL strings for sibling tools, and provides an alternative for simpler needs. Nothing an agent needs to call or route correctly is missing.

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?

With 100% schema description coverage, the schema already documents all 11 parameters including defaults and enums. The description mentions filter options (domain, URL, date range, status, test type) but adds no new parametric detail beyond what the schema covers; it is a baseline 3.

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 clearly states the tool lists visibility tests for the authenticated user, newest first. It further positions it as the 'tid and history discovery surface' and distinguishes it from gvt_get_score_trend, making its purpose specific and unambiguous.

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?

The description explicitly tells when to use this tool (to find tids and URL strings needed by related tools) and when not to (use gvt_get_score_trend for deltas). It names the alternative and the condition that selects it, leaving no ambiguity.

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 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.

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.

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.

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.

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.

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.

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

Pipelines the async nature explicitly: it says 'returns a tid immediately' and that results are retrieved separately by passing tid to gvt_get_test_results, with polling instructions. This behavior isn't implied by annotations (readOnlyHint=false, no idempotentHint), so the description carries the burden and does so thoroughly. No contradiction with annotations.

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?

Concise but information-dense. Two sentences: first defines the tool's function and scope, second addresses the async behavior and next steps. No filler; every sentence earns its place.

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?

Given an output schema exists (though not detailed here), the description need not explain return values. It covers the core: what the tool does (analyzes 7 categories), the async contract, and how to proceed (poll until status changes). For a tool of moderate complexity with a well-covered schema, this is complete.

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 description coverage is 100%, both parameters (url and waitForJs) already have clear descriptions in the schema. The description adds marginal value beyond the schema—it doesn't mention parameters at all, but the schema is sufficient. Baseline 3 applies because the description adds no extra parameter context but doesn't need to.

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?

States the specific action (run a GEO visibility test on a URL), lists the 7 categories it analyzes (js, nojs, semantic HTML5, heading structure, schema.org markup, social tags, accessibility), and differentiates itself from siblings like gvt_run_visibility_batch (batch) and gvt_schedule_test (scheduled). The purpose is unambiguous.

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?

Explicitly instructs when to use this tool: to run a single visibility test on a URLichelses immediate asynchronous result. It contrasts with gvt_get_test_results (retrieve results by tid) and implies not for batch (run_visibility_batch). It provides clear workflow guidance: pass the tid to gvt_get_test_results and poll until status changes.

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?

The description goes well beyond the annotations by detailing consequences: delete permanently removes entries but never deletes test results; reset is destructive and deletes all matching schedules before upserting; pause is reversible; resume clears auto-pause reasons and failure counts; cancel makes the schid unusable. The destructiveHint annotation is confirmed and enriched with mode-specific scope and side effects.

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 description is dense but every sentence earns its place: it starts with the primary purpose, then immediately routes to sibling tools, then defines each mode with its behavioral consequence. The mode definitions are compact yet complete, and the requirement summary sentence is a useful checklist.

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?

Given the tool's multi-mode complexity and zero required fields in the schema, the description fully compensates by specifying mode-specific argument requirements, destructive behavior, domain scoping, and the relationship to schedule discovery. The presence of an output schema means return-value details are already covered elsewhere, so nothing essential is missing.

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?

Even though the schema covers all parameters, the description adds crucial operational meaning: 'add' upserts without duplicating, 'delete' can target schid or url, 'reset' is domain-scoped or account-wide, and 'change_frequency' requires a new frequency. This clarifies how the optional-looking schema fields (all non-required) actually combine per mode, which the schema alone does not convey.

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 opens with a specific verb and resource: 'Manage recurring GVT test schedules,' then enumerates the seven supported modes (add, delete, reset, pause, resume, cancel, change_frequency). It differentiates from sibling tools by explicitly naming gvt_list_schedules, gvt_run_visibility_test, and gvt_run_visibility_batch as alternatives for discovery and non-recurring runs.

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?

The description gives explicit routing guidance: use gvt_list_schedules to discover schids, use gvt_run_visibility_test for one-off tests, and use gvt_run_visibility_batch for queued non-recurring batches. It also states mode-specific requirements, such as 'Management modes (add/delete/reset) require urls; control modes require schid,' so an agent knows exactly when to invoke this tool versus siblings.

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?

The description goes well beyond the annotations, detailing response behavior (confirmation, share_url), authentication-free recipient access, immediate revocation of prior share URLs, and that is_public is the only control lever. This aligns with idempotentHint and destructiveHint and adds meaningful non-obvious behavior.

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 description is front-loaded with the core action, and every subsequent sentence contributes either behavioral nuance or usage context. There is no filler or repetition of what annotations already provide.

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 only two required parameters, a complete schema, and an output schema, the description covers all operational essentials: state change, response contents, share URL behavior, no-auth access, and revocation. No critical information is missing for correct invocation.

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 baseline is 3. The description adds extra meaning by explaining the consequences of true vs false (publishing and returning share_url vs revoking access) and reinforcing that is_public is the only lever. tid's source is already fully documented in 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 opens with a specific action and resource: 'Toggle the public visibility of a test session.' It then explains the two states and their outcomes, and closes by positioning this as the only way to control who can view a test result, distinguishing it from the sibling list.

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 clearly states when to use the tool: when you want to share or privatize a test session ('This is the only way to control who can view a test result...'). It does not explicitly name sibling alternatives, but the 'only way' framing gives a strong selection signal.

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