Relvato

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the risk profile is covered. The description adds real value beyond that by describing the effect (existing baseline is replaced by this run's structure) and by naming the undo path, which is precisely the context an agent needs before performing a destructive, idempotent rebaseline.

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?

A single dense sentence that front-loads the situation (a monitored layout change) before the action and its two scope modes. Every clause carries information; 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 destructive mutation with no output schema, the description plus annotations cover the essentials: what is mutated, the scope options, and how to reverse it. It stops short of stating permission requirements or whether adopting a baseline affects subsequent run comparisons, which keeps it from a 5.

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 all three parameters are already documented in the schema, including the get_run metrics.pages[].pageKey hint. The description only restates the pageKey-vs-all:true targeting modes without adding format, default, or precedence detail (e.g., what happens if both are supplied), 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+resource: adopting a run's detected structure as the new baseline, with the scope switch made explicit (single pageKey vs all changed pages on the run). It also names undo_structure_review as the inverse operation, letting an agent place it correctly among the ignore/undo 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 opening clause supplies the trigger condition — the monitor found a layout change that was intentional — which tells the agent when this tool is appropriate. It names the undo alternative, but never states the opposite case (e.g., use ignore_structure_change when the change was not intended), so the routing guidance is clear but not exhaustive.

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 destructiveHint=true and idempotentHint=true; the description adds real value by spelling out what is destroyed/overwritten — the prior baseline is replaced by the current screenshot — and by pointing to the undo path. It stops short of stating permission requirements or what happens to the superseded baseline snapshot.

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 tight sentences, front-loaded with the action and effect, with the precondition and undo hint following. Slight verbosity in the parenthetical 'a redesign, new content' but it usefully exemplifies intent.

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 mutation with no output schema and annotations covering the safety profile, the description supplies the essential missing pieces: what changes, when to use it, and how to reverse it. Minor gaps (auth/permissions, scope of baseline replacement) remain but are not critical.

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?

Single parameter with 100% schema description coverage, so the schema already explains comparisonId's origin (get_run visualComparisons[].comparisonId). The description adds no parameter-level detail, which is acceptable at this coverage level.

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 ('accept a visual change') and immediately clarifies the effect: this run's screenshot becomes the new baseline for that page/device/browser. Sibling tools like undo_visual_review, ignore_visual_change, and flag_visual_change_as_problem are clearly distinct from this acceptance action.

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 precondition ('Only when the user confirms the change is intended') and names the reversal tool ('Undo with undo_visual_review'). It does not explicitly contrast with ignore_visual_change or flag_visual_change_as_problem, but the intended-vs-unintended framing covers the key branch.

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 (readOnly=false, idempotent=true, destructive=false), and the description goes well beyond them: per-key outcomes (added/exists/rejected), rejection reasons (plan, active-monitor limit, missing WordPress plugin), and the scheduling consequences before and after ownership proof. The 'exists' outcome is consistent with idempotentHint=true.

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?

Four sentences, front-loaded with the action and key source, with no filler. The final sentence is long and packs several clauses (trigger_scan, scheduleStarts, per-plan cadence, re-run triggers), which would read better split, keeping 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?

For a two-parameter mutation with no output schema, the description covers inputs, per-key result semantics, failure reasons, and post-ownership scheduling behavior. An agent has everything needed to call it and interpret the outcome without opening the schema.

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 that keys are catalog check keys sourced from list_checks and that each key produces an individual result, which meaningfully informs how the array is consumed. It does not add format or ordering detail beyond that.

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 first sentence states a specific verb+resource+mechanism: 'Add monitors to a site by key (from list_checks).' It implicitly separates itself from add_custom_check and add_heartbeat by scoping to catalog keys sourced from list_checks, so an agent can route correctly.

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 tells the agent where keys come from (list_checks) and ties behavior to two prerequisites, site ownership proof and trigger_scan, which is clear usage context. It stops short of an explicit when-not or a direct 'use add_custom_check instead' exclusion, so it is a 4 rather than a 5.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=false), and the description adds substantial context beyond them: asynchronous authoring latency ('a minute or two'), the read-only-by-default run mode, the interactive opt-in that enables clicking/typing, plan-gating, and quota consumption against the active-monitor limit.

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 the core idea in the first sentence and packs latency, status flow, behavior and gating into a compact block. The status-lifecycle sentence is information-dense and slightly run-on, but every clause carries routing or behavioral information rather than 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?

For an async, plan-gated creation tool with no output schema, the description supplies everything needed: input expectation, latency expectation, the status machine with the response text to surface to the user, and the quota/plan constraint. Nothing an agent needs to invoke and then correctly continue 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 interpretive value for the two non-obvious flags: 'interactive: true lets it click and type (search, filters, forms)' and the read-only default, plus the WordPress-specific meaning of authenticated. The url/goal/name semantics are left entirely to 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?

States a specific verb+resource ('Create a custom monitor') and goes further by explaining the mechanism: a plain-language goal that Relvato's AI turns into a monitor. The contrast with the sibling add_checks (predefined checks) is clear from 'describe in plain words what to verify' and the AI-authored authoring flow.

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 prescribes the follow-up: 'Follow it with get_check', then names the exact next tool for each returned status (approve_custom_check for proposed, reauthor_custom_check for needs-input, advice for failed). This is a full when/when-next routing map rather than implied usage.

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?

Adds substantial behavior beyond the annotations: the return value is a ping URL, the success/failure ping mechanics (including the curl example and /fail endpoint), the exact alerting rule (no ping within period + grace, or a failure, alerts immediately; a new heartbeat waits for its first ping), and per-plan creation limits. This is exactly the kind of context annotations cannot carry.

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?

A single dense paragraph that is front-loaded with the core purpose and return value. The failure-endpoint and plan-limit details are long but earn their place; the embedded curl example is the most expendable element.

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 creation tool with no output schema, it supplies the missing return value (ping URL), the alerting semantics, the side effect of adding a Heartbeats monitor, and the account limits. Nothing an agent needs to call it correctly is absent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents tz, cron, graceSec, periodSec, name, and siteId fully. The description reinforces period + grace behavior but adds no syntax or format detail beyond the schema, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Create a heartbeat for a job the user runs') and explains what a heartbeat is with concrete examples (cron job, backup script, CI job). The create verb implicitly separates it from list_heartbeats/update_heartbeat, but no sibling is named explicitly, so it stays at 4 rather than 5.

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?

Usage is implied by the framing 'for a job the user runs,' but the description never states when to prefer this over update_heartbeat or list_heartbeats, nor any when-not condition. It explains the feature well but leaves tool selection 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 declare non-destructive, idempotent writes, and the description adds substantial context beyond them: the unverified-account capability ceiling (manual runs capped at 3/day), the dedup rule that matches the idempotentHint, and pointers to setup.manualRuns / setup.nextStep / setup.afterProof in the response. This tells an agent exactly what state it will leave the account in.

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 the action and the return shape in the first sentence, then layers prerequisites and dedup behavior. The dense parenthetical-and-semicolon style packs a lot of value per sentence, though it reads as one heavy block rather than clearly separated points.

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?

There is no output schema, yet the description names three specific response fields (setup.manualRuns, setup.nextStep, setup.afterProof) so an agent knows what it gets back. Combined with the dedup rule, verification paths, and a docs link, nothing essential for correct invocation 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 description coverage is 100%, so url, name and platform are already documented, and the description adds only indirect reinforcement by explaining why platform matters (WordPress plugin vs. domain-only verification). Baseline 3 is appropriate since the schema carries parameter 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?

Opens with a specific verb+resource ("Start monitoring a website") and immediately clarifies that it returns the site plus its setup state. It also implicitly separates itself from siblings by naming trigger_scan as the tool that consumes the pre-verification state and by describing the domain-verification path that verify_site relates 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 clear situational context: what works before ownership is proven (3 manual public-monitor runs/day via trigger_scan), what requires proof, and what happens if the same domain already exists (returns existing site instead of a duplicate). It stops short of explicitly stating when not to use this versus start_monitoring_for_goals, but the operating conditions are concrete.

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 flag destructive/non-idempotent/openWorld, but the description adds substantial context beyond them: it re-runs the monitor to confirm, documents undo:true as reverting the last fix, and discloses a version-dependent behavior shift where plugin 1.77.0+ never mutates remotely and instead returns an applyInWordPress link. That caveat is exactly the kind of side-effect detail an agent cannot get from structured fields.

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 verb and resource, and the remaining sentences each carry a distinct instruction (re-run monitor, user confirmation, undo, plugin-version behavior). It is a dense paragraph with parenthetical asides that make it slightly run-on, but nothing is 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?

For a destructive two-parameter tool with no output schema, the description covers side effects, confirmation requirements, undo, and the alternate return path on newer plugin versions. The main remaining gap is which alternative to use when a run proposes no fix, though the description otherwise leaves little an agent needs 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 both parameters are already documented in the schema, and the description's undo explanation largely mirrors the schema wording. It adds the contextual point that proposedFix.why and undo should be surfaced to the user, which is helpful but not parameter-format detail. Baseline 3 is appropriate.

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 (apply) and resource (the one-click fix a run proposes), with concrete examples of what such a fix is (clearing a stuck maintenance file, re-enabling indexing, rolling back a plugin update). Naming get_run's proposedFix as the source clearly separates it from siblings like request_ai_fix and get_fix_prompt.

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 real workflow guidance: only that exact fix can be applied, tell the user why (proposedFix.why) and the undo path, and get go-ahead first. It stops short of explicitly contrasting with adjacent siblings such as request_ai_fix or start_safe_update, so the agent must infer which tool is appropriate when no run proposal exists.

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 it is a non-read-only, open-world, idempotent, non-destructive operation, and the description adds real context beyond that: the required 'proposed' state transition, that the recipe then runs and alerts persistently, that interactive recipes click/type on the live site, and that user consent is mandatory with ack: true. This covers consent and real-world side effects that the annotations alone 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?

Three sentences, front-loaded with the action and state, then the prerequisite lookup, then the consent constraint. No filler and every clause carries operative information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and only two well-documented parameters, the description supplies everything needed to call it safely: the precondition, the sibling to consult first, the consent requirement, and the resulting behavior. Nothing an agent needs 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 meaning the schema does not: why ack exists (the recipe may act on the live site) and the interactive-recipe condition under which it becomes required. checkId is left to the schema, which is sufficient.

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 (approve), resource (custom monitor's proposed recipe), the qualifying state (status proposed), and the resulting effect (runs and alerts from now on). An agent can distinguish this from edit_custom_check or add_custom_check without opening the 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?

Explicitly routes the agent to get_check first to show rationale and steps, and states the condition under which approval is allowed (interactive recipes act on the live site, so only after the user agrees). Both the when and the precondition are spelled out.

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 annotations, it discloses the effect scope (the bell, the digest, and site health) and an important negative ('No alert is re-sent'). It also names the domain field (aiTriage.setAside) that identifies the affected run, which is real behavioral context the annotations cannot carry.

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, front-loaded with the action and its effect, with the trigger condition last. The parenthetical 'a site on level "aside"' is slightly awkward but earns its place by clarifying the domain term. No wasted 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 mutation tool with no output schema and a single required param, it covers action, effect scope, alert behavior, and trigger condition. What remains unstated (permissions, reversibility) is minor for this domain and partially implied by idempotentHint.

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 runId is 100% covered by the schema ('The set-aside run'). The description reinforces that the target must be a set-aside run but adds no syntax, format, or constraint detail beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('bring back a set-aside failure', 'make it count as a failure again') and explains the mechanic being reversed (aiTriage.setAside). It anchors to the sibling get_run, so an agent can tell exactly which state is being toggled.

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 trigger: 'Use it when the user says the failure is real.' It also names get_run as the way to detect the set-aside state, which is effectively the precondition. No explicit when-not-to-use or named alternative is given, so it stops short of 5.

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

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

The description adds one genuinely useful behavioral fact beyond the annotations: it "runs in the background," so the agent knows not to expect an immediate result. However, it leaves a tension with readOnlyHint=false by framing the operation purely as "read," and it never says how the re-read outcome is retrieved (list_runs/get_run exist as siblings), so a follow-up path is undisclosed.

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?

Two tight sentences, front-loaded with platform and purpose, with the scope parenthetical and the background-execution note appended. No filler, though "have Relvato read the store again" is a slightly indirect way to phrase the action.

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 one-parameter trigger with no output schema, the description covers what happens and that it is asynchronous, which is most of what an agent needs. It is still incomplete on the async lifecycle — no indication of how long the re-read takes or which sibling retrieves the result.

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 (siteId) exists and schema description coverage is 100%, so the schema already carries the semantic load and the baseline of 3 applies. The description's parenthetical enumerates what is re-read but says nothing about the parameter itself, adding no meaning 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?

Specific verb + resource: "have Relvato read the store again" on WordPress/WooCommerce, with the re-read scope spelled out (product to buy, checkout type, guest checkout, currency). It is clearly distinguishable from most siblings, but it never contrasts itself with adjacent tools like verify_site or trigger_scan, so it stops short of a 5.

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 trigger condition: use it "after the store changed" — that is a real when-to-use signal, not just an implied one. It offers no exclusions or named alternatives, which is the only thing keeping it from a 5.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, and the description adds substantial context beyond them: cancellation is irreversible (can't be brought back), the in-flight run completes rather than being killed, and no recorded data is deleted. This is exactly the behavioral detail an agent needs before a destructive call.

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 short sentences, each doing distinct work: scope, irreversibility/recovery path, and blast-radius limit. Front-loaded with what is cancelled and what is preserved.

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 destructive operation with no output schema, the description covers scope, reversibility, side effects, and the human-approval precondition. An agent has everything needed to decide and invoke 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 and schema description coverage is 100%, so the schema fully documents siteId. The description adds no syntax or format detail beyond it, which is the expected baseline when the schema carries the load.

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 (stop) and a precisely scoped resource (runs that are queued but haven't started, for a given site). This scope distinction separates it cleanly from siblings like list_runs and get_run, and it names trigger_scan as the counter-operation.

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 explicit when-to-use contexts (after a big trigger_scan, or before maintenance), names the alternative for restarting (trigger_scan), and states a precondition (get the user's go-ahead first). Nothing is left 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 declare the safety profile (readOnly=false, idempotent=true, destructive=false), so the bar is lower. The description adds real value beyond them: it discloses that restoreAll reverses *every* dismissed recommendation, which is a scope-changing behavior an agent must know before calling. It does not clarify whether a dismissed recommendation is permanently deleted or merely hidden.

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 sentence, front-loaded with the primary action and with the alternative held to a parenthetical plus a trailing clause. No filler. Slightly dense because it packs two operations into a single sentence, but nothing is wasted.

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?

Covers the two main modes and the restoreAll scope, and with no output schema there is no return format to explain. However, for a 3-parameter mutation tool it leaves a real gap: the interaction between the optional key and restoreAll (what a bare siteId call does) is unaddressed, and no reversibility caveat beyond restoreAll is given.

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 67% — key and siteId are documented, but the restoreAll boolean has no schema description. The description compensates by defining restoreAll's effect ('bring every dismissed recommendation back'), which is exactly the missing semantic. It adds no extra detail on key/siteId pairing, but the schema handles those.

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 ('Stop recommending a monitor for a site') and discloses a second mode via restoreAll. It also names where recommendations surface (list_checks), which helps an agent place the tool, though it does not contrast itself against the other dismiss/ignore siblings (ignore_finding, ignore_structure_change).

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 implies two usage modes — dismiss one monitor by key, or bulk-restore with restoreAll — but never states when to pick one over the other, nor what happens if key is omitted without restoreAll (only siteId is required by the schema). Usage is inferable but not explicitly guided.

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?

Goes well beyond the annotations by disclosing the key consequence: the current recipe is dropped, the AI writes a new one, and it needs re-approval before the monitor runs again. This tells the agent what gets destroyed and what the follow-up workflow is. It could still note permission or side-effect scope, keeping it at 4 rather than 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences with no waste: the first front-loads what changes, the second immediately conveys the destructive consequence. 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?

For a destructive, non-idempotent mutation with no output schema, the description supplies the essential behavioral consequence and the re-approval requirement. Remaining gaps are the undocumented boolean params, but the core invocation context is present.

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 67%, and the description names goal, page, name and mode, loosely mapping to url, goal, name, and the boolean mode-like params. However, checkId, interactive and authenticated are not clarified in either schema or description, so the description adds only marginal meaning. Baseline 3 for mid coverage.

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 (change/edit) and resource (custom monitor) plus the fields being changed (goal, page, name, mode), which clearly distinguishes it from add_custom_check and approve_custom_check. It does not explicitly name the sibling it differs from, so it falls short of a 5.

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 phrasing implies this is the edit path for an existing custom monitor, but there is no explicit when-to-use guidance, no prerequisites, and no comparison against alternatives like reauthor_custom_check or update_check. Usage is implied rather than stated.

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 this is a non-read-only, non-idempotent, non-destructive, open-world mutation. The description adds the specific 48-hour extension duration, which is useful context not in annotations, but it omits prerequisites such as whether quarantine must already be active.

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?

A single focused sentence with no wasted words. The action and duration are front-loaded and immediately clear.

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 one-parameter mutation tool, the description covers the action and duration, while annotations cover safety and schema covers the parameter. However, it omits prerequisites, such as existing quarantine state, leaving a gap 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%, and the single parameter siteId is documented in the schema. The description adds no additional meaning about the parameter, so the baseline of 3 is appropriate.

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 action (extend/keep on), resource (quarantine mode), and duration (48 hours from now). It clearly conveys the tool's function, but it does not explicitly differentiate from siblings like start_quarantine or get_quarantine.

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?

No explicit when-to-use guidance or alternatives are given. The phrase 'another 48 hours' implies quarantine is already active, but there is no stated prerequisite or comparison to start_quarantine.

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 only say readOnlyHint=false, idempotentHint=true, destructiveHint=false; the description adds real behavioral context beyond that — the run is counted as failed, surfaces as needing attention via notifications and Monitors passing, and 'no message is sent'. It does not say whether the flag is reversible (undo_visual_review exists as a sibling), which keeps it short of a 5. No conflict with the 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?

Two tight sentences, front-loaded with the scenario and then the consequences. The parenthetical '(notifications, Monitors passing)' is compressed to the point of ambiguity, but nothing is wasted.

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 mutation with no output schema and annotations already covering the safety profile, the description supplies the missing piece — the downstream effect of flagging. Only reversibility/undo guidance is absent, which is minor given the sibling undo_visual_review.

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?

One parameter with 100% schema description coverage, and the schema already documents comparisonId with its source ('From get_run visualComparisons[].comparisonId'). The description adds nothing about the parameter, 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 ('mark it a failure' on a visual change) and frames the triggering scenario ('The AI review let a visual change pass, but it's actually broken'). It never names the obvious siblings accept_visual_change or ignore_visual_change, so the agent must infer the negative case rather than being routed explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The condition for use is clear: the AI review passed a change that is in fact broken. That implies the alternative (accept_visual_change) without stating it, and no explicit when-not condition is given, so the routing is inferable but not spelled out.

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 the read-only, non-destructive, closed-world profile, so the description is free to add behavioral context — newest-first ordering, the plan-dependent history window, and the privacy detail that IPs are masked to the network rather than the full address. It stops short of describing pagination behavior when limit caps results.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

It is a single front-loaded sentence, with the actor/subject ('who did what') stated first and the modifier clauses read as one breath. The long dash-separated enumeration is dense but each category earns its place; slightly unwieldy rather than wasteful.

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?

There is no output schema, so the description carries the burden of describing returns, and it does — it states what events appear and their ordering. Combined with annotations covering safety, an agent has enough to call it correctly, though return shape/limit interaction is not spelled out.

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 already 80% and the filter enum values are self-describing, so the baseline is 3. The description earns an extra point by grounding the 'days' parameter in a concrete 7–365 range and by mapping its event categories (logins, people, changes, errors) to the filter values the schema only lists as enum tokens.

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 (get) and resource (activity log) and then enumerates the exact event classes captured — sign-ins, roles, application passwords, updates, edits, PHP errors, failed emails. That enumeration makes it unmistakable against siblings like get_site_health or get_notifications 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?

Usage is only implied: an agent can infer this is the tool for auditing past site events, and the retention note (7–365 days) implies its boundary, but there is no explicit when-to-use guidance and no named alternative for adjacent needs. Adequate but with a clear gap.

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 readOnly/non-destructive/closed-world, so safety is covered; the description adds real behavioral context beyond that: it discloses what is excluded for security (no webhook URLs or secrets) and explains field semantics (plan-included, configured, paused, `on` = alerts actually send).

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 'Who is told about what' and packed into one dense but purposeful sentence; the parenthetical enumerations all carry information, though the density makes it slightly hard to scan.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and no parameters, the description carries the return-value burden and does so thoroughly: what channels exist, how their state is represented, which sites are muted, how routing works, and what is deliberately omitted.

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 takes zero parameters, so the baseline is 4; the description still adds value by explaining the shape of the returned settings even though parameter semantics are not applicable.

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 is highly specific about the resource: frequency/severity/channels/mutes/routing of alert settings, which an agent can distinguish from update_alert_settings or get_notifications. The closing line ('Changing them is done by the user in Alert settings') is slightly confusing because a sibling update_alert_settings exists, which weakens the read/write routing a bit.

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?

Usage is implied (read the current alert configuration) and there are useful scope exclusions ('never includes webhook URLs or secrets', 'only channels that are on'), but there is no explicit when-to-call-this-vs-update_alert_settings guidance, and the sibling mutator is not named.

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 the safe read profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), and the description adds substantial context about what is actually returned: run scheduling, monitor-specific settings, ignored findings, AI-authored fields, and the latest run. This is rich disclosure for a tool with no output schema, though it omits error/pagination 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?

It is a single sprawling sentence with nested parentheticals and a trailing ellipsis that signals unfinished enumeration. It is front-loaded with the key point ('One monitor in full') but the dense field listing hurts readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the burden of explaining return content, and it does so thoroughly, including the useful note that it reveals which sections update_check_settings accepts. Missing only error/edge-case behavior for a simple 1-parameter read.

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 checkId parameter is fully documented in the schema (including its source: site_overview or add_checks). The description adds no further parameter meaning, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

It clearly designates a single-resource retrieval ('One monitor in full') and enumerates the categories of data returned, which distinguishes it from list_checks and from get_run (it only surfaces the 'latest run'). The retrieval verb is only implied rather than stated, but an agent can tell what the tool returns.

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?

There is no explicit when-to-use or when-not-to-use statement, and no named alternative such as list_checks. Usage is only implied by the enumerated contents, so an agent must infer that this is the detail view for a specific checkId.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds useful context about what the brief contains and that it does not apply fixes, but says nothing about auth requirements, failure behavior for an invalid runId, or result size. Adequate but not rich.

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 one long enumerating sentence. Every clause earns its place by naming a distinct part of the brief, though the single run-on sentence is dense and could be broken up.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the burden of explaining the return and does so thoroughly by listing the brief's components. It omits failure/auth behavior for the single required param but is otherwise complete for this read-only 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?

One parameter at 100% schema description coverage, so the schema already documents runId. The description only implies that the run should be a failed/problem run, adding no format or constraint detail beyond what the schema provides. Baseline 3 is appropriate.

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 the fix brief for a run') and enumerates the brief's contents (stack, verified assertions, recent changes, exact error, prior-failure status, search evidence). It is distinguishable from get_run by being a diagnostic bundle, but it never names get_run or request_ai_fix to sharpen the boundary.

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 a clear triggering condition ('for a run that failed or found a problem') and an explicit boundary against apply_fix ('applying a fix stays with the user'). No explicit when-not guidance or named alternative for the read-only diagnostic path, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real value by disclosing the scope of returned content (failing monitors, plugin issues, beacon silence, domain/ownership, safe updates, paused alerts, billing), which tells the agent what a call will surface. It omits ordering, freshness, and whether results aggregate across all sites.

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?

A single front-loaded sentence naming the resource first, followed by the enumeration. The list is long but each item is a distinct notification category, so it earns its space; a slightly tighter grouping (e.g., 'domain/ownership' vs 'billing') would read cleaner.

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 tool with no output schema, the description carries the return-value burden well by enumerating what notifications exist. It is nearly complete — only the lack of any note on ordering, aggregation scope, or next-step tooling keeps it from a 5.

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?

There are zero parameters, so per the rubric the baseline is 4. The description correctly adds no parameter detail because there is none to add, and the enumerated categories function as implicit scoping 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 the resource (the dashboard's notifications) and enumerates the exact categories returned, so an agent knows precisely what data comes back. It stops short of explicit sibling differentiation — nothing distinguishes it from get_alert_settings or get_activity_log, which surface related dashboard 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?

Usage is only implied: with zero parameters and a read-only listing, the agent can infer this is the 'view current notifications' tool. There is no stated when-to-use, no condition selecting it over get_alert_settings or site_overview, and no mention of how its output relates to the fix/recommendation tools in the sibling set.

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, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuinely useful context the annotations cannot: the comparison window (last 7 days vs prior 28), the p75 aggregation, and the per-page-type/per-device segmentation.

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?

A single dense sentence, front-loaded with the core purpose and then expanding into the returned data categories. Efficient despite the length; no filler sentences.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the burden of describing returns and does so thoroughly across the five data categories. The main gap is the absence of routing guidance relative to similar read siblings.

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 (siteId) with 100% schema description coverage; the schema already documents it and the description adds no format or acquisition detail for it. Baseline 3 applies when the schema does the heavy lifting.

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?

Opens with a specific verb+resource ('A site's speed') and enumerates concrete contents: performance summary, lab Core Web Vitals, field LCP/INP/CLS, slowdown causes, and top fixes. It is distinct from health/overview siblings, though it never names those siblings to sharpen the boundary.

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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as get_site_health or site_overview, which an agent must distinguish this from. Usage is left entirely to inference from the topic.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds real domain context beyond that: 48 hours of hourly runs, paused plugin updates, and the fact that it reports expected and unexpected changes.

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?

Two sentences: the first front-loads the concept and constraints, the second enumerates return fields. Dense but every clause maps to actual behavior; no wasted preamble.

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?

No output schema exists, so the description's enumeration of returned facts (availability, on/off, until when, changes seen, monitors, runs, past sessions) usefully compensates. With annotations covering safety, an agent has enough to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There is a single required siteId parameter and schema coverage is 100%, so the schema already documents it fully. The description adds no parameter-level meaning, making the baseline 3 appropriate.

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 the specific resource (quarantine mode) and its domain well, making it clear this tool retrieves quarantine state. It is distinguishable from write siblings like start_quarantine and extend_quarantine by the list of read-only facts it returns, though it never uses an explicit retrieval verb.

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 states a domain constraint (WordPress, paid plans) but gives no when-to-use guidance and never references alternatives such as start_quarantine, extend_quarantine, or list_runs. An agent must infer the call context on its own.

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?

Goes well beyond the annotations with real behavioral facts: screenshot/baseline/diff links expire after 10 minutes, whether a comparison decision can be undone, ignored findings are marked, noFix findings carry an explanation, and metrics (never findings) are compacted with omissions listed in metricsTrimmed. These are exactly the operational details an agent cannot get from readOnlyHint/destructiveHint.

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 'One run in detail', but the rest is a single run-on sentence with deeply nested parentheticals that make the key facts (link expiry, metrics trimming) hard to scan. Information-dense yet structurally hard to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the return-value burden and does so thoroughly: findings keys for ignore_finding, comparisonId, link expiry, undoability, metrics trimming. It stops short of covering error/not-found behavior or navigation hints to adjacent tools.

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 there is a single required runId, so the schema fully documents the parameter. The description adds nothing about runId format or source, 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+resource ('Get run details' / 'One run in detail') and enumerates the concrete payload (status, errors/warnings, steps, comparisons, metrics, proposed fix). The phrase 'One run' implicitly contrasts with list_runs, but the description never explicitly names that sibling to sharpen the distinction.

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?

There is no 'use this when' guidance, no exclusions, and no named alternatives (e.g., list_runs for an overview, get_fix_prompt for fix details). Usage is only inferable from the singular 'One run' phrasing.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so safety and scope are covered. The description adds genuine value by disclosing the possible outcome states (including the reverted-with-failing-monitors case), but says nothing about polling cadence, terminality of states, or auth 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?

A single dense sentence, front-loaded with the operation and immediately followed by the state sequence. No filler. The trailing clause 'with the monitors that broke' is slightly compressed but still parseable.

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 one-parameter read-only progress tool with no output schema, describing the state progression effectively communicates what the call returns. Missing only minor operational detail such as whether it must be polled or when states become terminal.

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 coverage, and the schema note 'From start_safe_update' already explains its origin, so the baseline is 3. The description adds no further syntax or semantics beyond what the schema provides.

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: tracking a safe update or deactivation and its lifecycle states. The state machine (applying → verifying → passed, or reverted) makes the returned concept concrete. Sibling get_updates is not named, so differentiation is implied rather than explicit.

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?

Usage is implied by the lifecycle framing and by the changeId schema note pointing to start_safe_update, but the description itself never says when to call this versus start_safe_update or get_updates, nor whether it should be polled repeatedly. No exclusions or prerequisites stated.

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 readOnly, non-destructive and closed-world, so safety is covered. The description adds genuinely useful behavior beyond that: paid-plan gating for probe uptime, fixed 30-day windows, and 28/90/182 trend horizons. It stops short of describing pagination or response shape, but adds real 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?

A single front-loaded sentence that enumerates distinct output components without filler. It is dense and slightly run-on, but every clause corresponds to a real section of the response, so little is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description must carry the return-value burden, and it does so thoroughly: pass share, 30-day daily history, trend horizons, per-group briefings with cause and fix, and probe availability. Coverage of output is strong; only the absence of any usage/routing guidance holds it back.

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 both parameters are already documented, and the schema even gives the enum default. The description restates the 28/90/182 values in prose but adds no syntax or meaning beyond the schema's own "Trend length in days (default 28)". Baseline 3 is appropriate.

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 resource and what it conveys: a site's standing, pass share now and per-day, trends, group briefings and probe uptime. It references "the Overview's 'Monitors passing'" which implicitly ties it to the site_overview sibling, but it never names an alternative or explicitly says which tool to reach for, so differentiation is only partial.

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?

There is no when-to-use guidance, no when-not-to-use, and no mention of alternatives such as site_overview or get_performance. The content list implies the use case (assessing site health) but an agent gets no explicit routing help.

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/destructiveHint=false, so safety is covered. The description adds genuine behavioral context beyond that: it discloses that the firewall allowlist token value is 'never' returned, and scopes exactly which settings are inspector-visible. That is real value the annotations do not provide.

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 single long nested sentence packs a lot of enumeration but is dense and uneven to parse, with parentheses inside parentheses. It is front-loaded with the resource but buries the most useful behavioral detail (token never returned) mid-sentence.

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?

There is no output schema, so the description must carry the return contract — and it does, enumerating the settings categories that come back (mutable settings, dashboard-only settings, plugin version, beacon snippet). For a no-output-schema getter this is largely complete, though the awkward sourcing leaves minor ambiguity.

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 (siteId) with 100% schema description coverage, so the schema already documents it. The description adds no format, ID-source, or lookup guidance for siteId, so 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?

The description characterizes the resource ('A site's Settings tab as values') and enumerates its contents, but never states an explicit action verb — the 'get' only lives in the name/title. An agent can infer it returns settings, but the phrasing is content-listing rather than purpose-stating.

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 implicitly routes the agent by dividing values into 'what update_site_settings may change' vs 'what only the dashboard changes', which hints at the read/update relationship. However there is no explicit when-to-use, and the sibling update_site_settings is referenced but not framed as an alternative to choose between.

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 the safe read-only profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false). The description adds genuinely non-obvious behavior: it explicitly discloses what is NOT returned (a report's private link, recipients' addresses), which is important data-availability context an agent cannot infer from 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?

A single dense sentence plus a short exclusion clause, front-loaded with what is returned. Every clause earns its place, though the packed parenthetical field lists make it slightly list-like rather than neatly structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no parameters and no output schema, the description compensates by enumerating the returned fields and the fields deliberately withheld, so an agent knows both shape and limits of the result. Nothing needed to call it 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?

Zero parameters, so the baseline is 4 per the rubric. The description correctly adds no parameter detail and instead documents the returned data fields, which is the right use of space for a no-input tool.

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 precisely what is retrieved — public status pages (title, public link, sites, on/off) and monthly client reports per site — with the exact fields involved. No sibling tool covers status pages or client reports, so the agent can identify this tool's scope immediately.

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?

Usage is only implied: 'Edited in the dashboard's Agency page' hints that this tool reads while editing happens elsewhere, but there is no explicit when-to-use/when-not or named alternative. A read-only retrieval tool is self-evidently for inspection, so this is adequate but thin.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds substantive content disclosure — that rollbacks, skips and their reasons are surfaced, that plugin versions are held back after a rollback, and that hardening settings are included — which is real value beyond the annotations. It stops short of return format, time-window limits, or pagination.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

It is a single sentence, so it is compact, but it is a comma-spliced enumeration of fragments ('safe updates or deactivations Relvato made and their outcome') with no lead verb and no prioritization among the listed categories. Front-loading the generic domain rather than the primary purpose weakens the structure.

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 one fully documented parameter, no output schema, and a closed-world read-only annotation profile, the description carries the return-content burden and does so reasonably well by enumerating the data categories returned. The gaps are the unbounded 'recent windows' and lack of any volume or paging expectation, which are minor against the overall coverage.

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?

There is one required parameter (siteId) with 100% schema description coverage, so the schema already carries the semantics. At high coverage the baseline is 3; the description adds nothing about siteId format, scoping, or whether it accepts slugs versus numeric ids.

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 is a noun-phrase inventory of what is returned (update policy, recent windows, rollbacks, held-back plugin versions, Relvato-initiated updates, hardening settings) rather than a verb-led statement of what the tool does. The domain is clear, but it never names the action ('retrieve/get') and does not distinguish itself from close siblings like get_safe_update or get_activity_log. Adequate but with a clear framing gap.

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?

There is no when-to-use, when-not-to-use, or alternative-tool guidance. With siblings such as get_safe_update, get_activity_log, and get_quarantine covering adjacent territory, an agent gets no signal on which to pick. The content list only implies usage.

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 destructiveHint=true, idempotentHint=true and readOnlyHint=false, but the description clarifies the actual semantics that the annotations cannot: the finding is not deleted, it stays on the run marked ignored, and it stops alerting or failing future runs. It also discloses scope ('on this monitor') and reversibility, which is exactly the context an agent needs before acting.

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 short sentences, front-loaded with the effect, then the undo path, then the precondition. No sentence is redundant.

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 two-parameter mutation with no output schema, the description supplies the effect, scope, reversibility and a usage caveat. Nothing an agent needs to call 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?

Schema description coverage is 100%, so both parameters (key, runId) are already documented in the schema. The description reinforces where the key comes from (get_run warnings[].key) but adds no format or edge-case detail beyond that; baseline 3 is appropriate.

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 (ignore/stop counting) on a specific resource (a finding identified by key from get_run), and explains the exact effect. It is clearly distinguishable from the sibling ignore_structure_change / ignore_visual_change tools, which target different object types.

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 the precondition ('Only do this when the user says the finding is expected') and names the reversal path (unignore_finding). Both when-to-use and how-to-undo are covered with no inference required.

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 destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds real signal beyond that: the effect is persistent ('from now on') and reversible via undo_structure_review, which is the key operational fact an agent needs. It does not say whether ignoring affects alerts or whether the change can be re-ignored after removal.

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?

Two sentences, front-loaded with the action and effect before the recovery hint. The parenthetical signature-source detail is dense but earns its place by documenting an otherwise undocumented required parameter.

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 destructive, idempotent mutation tool with no output schema, the description plus annotations cover the effect, persistence and undo path adequately. Minor gaps remain on scope of impact (which runs/sites) and post-undo behavior, but nothing essential to invoking it 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?

The schema leaves the required 'signatures' array entirely undocumented and describes runId/pageKey only as 'The run'/'The page'. The description compensates for the most important gap by telling the agent signatures are the metrics.pages[].added/removed/countChanges[].sig values from get_run. The two ID parameters remain thin, but the hardest parameter is explained.

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 ('ignore specific element changes on a page') and scopes it temporally with 'from now on', which distinguishes it from one-shot ignore tools. It does not explicitly contrast with its closest sibling ignore_visual_change, so the agent must infer the structure-vs-visual split.

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 a concrete use case ('a widget that comes and goes') and names the recovery path ('Undo with undo_structure_review'), which is clear context for when to call it. It does not state when NOT to use it versus accept_structure_change or ignore_visual_change.

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 flag destructiveHint=true, idempotentHint=true, and openWorldHint=false, so the safety profile is covered structurally. The description adds real behavioral context the annotations don't: the effect persists 'from now on' and lands in the baseline's ignored regions, plus a documented undo path. It stops short of saying exactly what suppressing the region does to future alerts, so it isn't quite a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, front-loaded with the action and its persistence, followed by undo and alternative. Every clause carries information; no restating of the title or name.

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 mutation with no output schema, the description covers the effect, persistence, reversibility, and the preferred alternative. An agent has everything needed to decide whether to call it and what happens afterward.

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?

There is a single parameter (comparisonId) and schema coverage is 100%, with the schema already telling the agent where to source the id. The description adds no parameter-level detail, so the baseline 3 for a fully documented schema is appropriate.

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 ('ignore the area that changed on this comparison') and names the resulting state change ('added to the baseline's ignored regions'). This cleanly separates it from accept_visual_change and flag_visual_change_as_problem without the agent needing to open 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?

Gives the undo path ('Undo with undo_visual_review') and routes the agent toward a better alternative when one exists ('A mask (update_visual_monitor) is often the better fix'). Both the when-to-use and the escape hatch are explicit.

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 safety profile (readOnlyHint=true, destructiveHint=false), and the description adds real conditional behavior: runsNow distinguishes manual vs post-verification runs before ownership proof, and withWordPressPlugin is populated only for sites added as 'other'. This is useful state-dependent context not present in the 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?

Two information-dense sentences with little waste; the field catalog comes first and the conditional edge cases follow. The opening is a noun phrase rather than a verb-led statement, which slightly weakens front-loading, but overall it is 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?

With no output schema, the description must carry the return-value burden, and it does enumerate the key fields (key, what it catches, plan allowance, recommendation, already-added) plus conditional fields. It omits concrete key values and return shape, but is largely complete for a single-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 description coverage is 100% with a single siteId parameter, so the schema already documents the input. The description alludes to site context (ownership proof, 'other' site type) but adds no syntax or format detail for siteId beyond the schema's 'The site id'.

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 establishes the resource as the set of monitors that can be added to a site, and it names the sibling 'add_checks' indirectly by describing pre-add discovery. It does not restate the verb 'list' explicitly (that lives in the title), but an agent can still distinguish it from get_check or add_checks.

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?

Usage is implied rather than stated: the mention of plan allowance, recommendation, and 'already added' flags implies you call this before adding monitors. There is no explicit when-to-use, no exclusion, and no named alternative such as add_checks or get_check, leaving the agent to infer the routing.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuine behavioral value beyond that: it enumerates the returned fields (state, schedule, last ping, next due, plan coverage, missed/failed check-ins) and discloses a security-sensitive trait — ping URLs are exposed only to full-access connections and anyone holding the URL can send pings.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

It is a single dense sentence, but the key facts are front-loaded (resource, then return contents, then the ping-URL caveat last). Given there is no output schema, the long clause enumerating return fields earns its place rather than being 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?

With no output schema and only one simple parameter, the description carries the return-value burden and does so thoroughly — state machine values, schedule encoding in seconds, account quota, and the ping-URL access condition. An agent has what it needs to call and interpret this 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?

There is a single parameter (siteId) with 100% schema description coverage, so the schema already documents it fully. The description adds no syntax, format, or ID-source detail beyond the schema, which is the baseline expectation at this coverage level.

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+resource ('A site's heartbeats') and immediately defines the resource as cron jobs, backups and scheduled tasks that check in by requesting their own URL. This distinguishes it cleanly from siblings add_heartbeat and update_heartbeat, which mutate rather than 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?

Usage is only implied by the list verb and the required siteId. It never states when to call this versus list_checks, list_runs, or get_site_health, nor any exclusion or prerequisite (e.g., must the site have monitoring enabled). Adequate but with a clear gap in routing 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 readOnlyHint=true and destructiveHint=false, so safety is covered; the description adds genuinely new behavioral context: default sort order (newest first), that each result carries monitor identity, status, trigger, timing and error/warning, and the cursor semantics for walking backwards in time. It does not mention rate limits or result-size ceilings, but for a read-only listing tool the disclosure is above average.

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?

Two dense, front-loaded sentences: the first establishes purpose, ordering and filter scope, the second covers result contents and the pagination escape hatch. Nothing is repeated from the schema or annotations and there is 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?

With no output schema, the description correctly takes on the burden of describing what each run contains and how to page through older results. Combined with the fully documented input schema and read-only annotations, an agent has everything needed 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 coverage is 100%, so the baseline is 3. The description goes beyond it by summarising the filter family ('one site, one monitor or one status') and, crucially, explaining that `before` is the startedAt of the last run already retrieved — operational meaning the schema's 'the next page' phrasing only hints at.

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 ('Recent runs, newest first') plus the exact filter scope (site, monitor, status), and explicitly contrasts itself with the sibling get_run ('get_run has the detail'). An agent can distinguish it from list_checks, list_sites and get_run 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?

Gives clear context for when to use it — browsing recent runs, optionally narrowed by one site/monitor/status — and names get_run as the alternative for detail. It also explains the pagination workflow ('For older runs pass `before`'). It stops short of stating exclusions (e.g. when a different listing tool is preferable) but the routing guidance is solid.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured data. The description contributes one extra behavioral fact — that each site is reported with a monitor-readiness flag — but nothing about scope limits or result size.

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?

A single front-loaded sentence that states the resource and the payload, with no redundant restatement of the title or annotations.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the burden of describing return content and does so adequately by naming the site list plus readiness status. It could be marginally richer (e.g. whether all sites or only active ones are returned), but it is sufficient for a no-argument list 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a no-arg tool 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 ('List') and resource ('websites in this Relvato account') and adds the returned readiness signal, which distinguishes it from siblings like get_site_health or list_checks. It does not explicitly name an alternative tool, so it stops short of 5.

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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as site_overview or get_site_health. An agent must infer that this is the entry-point browse call purely from the name and description.

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 annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true), the description discloses what actually happens: only monitors that are 'on' are switched off and remembered, exactly those are restored on resume, and plan limits may cap restoration. It also covers the re-pause case, the Security/quarantine interaction, and an explicit user-consent requirement.

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 action and the duration choices, and each following sentence carries real information (restoration semantics, re-pause behavior, quarantine edge case, consent instruction, discovery pointer). It is dense and slightly run-on, but nothing is 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?

With three required params at full schema coverage and no output schema, the description covers everything an agent needs: effect on monitors, restoration path, edge cases, and the interaction requirement. No material 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 description coverage is 100% with two well-documented enums, so the schema already carries both parameters. The description restates the durations and the site/group target, and adds the 'as far as the plan allows' constraint, but introduces no new per-parameter syntax or format detail. 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?

The description states a specific verb and resource ('Pause one monitoring group on a site') and scopes it precisely to one group, with the three durations enumerated. It explicitly contrasts with resume_monitor_group, so an agent can distinguish it from siblings without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives clear scenarios for use (maintenance, redesign, migration) and names the counterpart tool resume_monitor_group and the discovery tool site_overview. It doesn't state an explicit 'do not use when' condition, but the context is strong.

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 destructiveHint=true, openWorldHint=true and idempotentHint=false, so the safety profile is covered. The description adds a genuinely useful behavioral fact beyond the annotations: the monitor stops running until the new recipe is approved. It does not disclose cost, auth, or what happens to the previous recipe.

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?

Two tight sentences with no waste: the action is front-loaded, followed by the conditional branch and the key consequence. Every clause 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?

For a mutation tool with a 2-param schema, rich annotations, and no output schema, the description covers the trigger conditions and the operational consequence (monitor halts pending approval). It omits what happens to the prior recipe and any approval-dependency link to approve_custom_check, but nothing critical to calling it 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 description coverage is 100%, so the schema already documents both `answer` and `checkId`, and the description does not add syntax or format detail. It reinforces that `answer` is the reply to the AI's question, but this is already in the schema. Baseline 3 is appropriate when the schema carries the parameter 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 states a specific action on a specific resource ('Have the AI write a custom monitor's recipe again') and ties it to the reauthor concept, which is distinguishable from add_custom_check and edit_custom_check. It stops short of naming an explicit sibling to distinguish from, but the 'again' framing plus the approval note makes the intent clear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives concrete trigger conditions: use `answer` when the monitor status is needs-input, or retry after a failure or staleness. That is clear when-to-use guidance. It does not explicitly name alternatives (e.g., approve_custom_check or edit_custom_check) or state when NOT to use it.

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 readOnlyHint=false but destructiveHint=false, and the description resolves that tension by stating 'it changes nothing on the run', which is genuinely useful context. It also confirms the outbound nature of the call (sending data to an external support team), consistent with openWorldHint=true. It does not mention non-idempotency, leaving one annotation trait unexplained.

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?

Two sentences, zero padding, and the core action plus its side-effect disclaimer are front-loaded before the alternative routing hint. Every clause 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?

For a two-parameter, non-returning report tool with no output schema, the description covers what it does, what it does not mutate, and which sibling to use instead. Nothing an agent needs to call it 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 description coverage is 100%, so both runId and note are already documented in the schema, and the description only restates them superficially as 'the run's details and your note'. Baseline 3 applies 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 and resource: report that a run's result is wrong, sending run details plus a note to Relvato's support team. It also explicitly distinguishes itself from the sibling ignore_finding, so an agent can route without opening either 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?

Gives the trigger condition ('a run's result is wrong – it failed or warned about something fine') and names the alternative action with its selecting condition ('To stop being told about a finding, use ignore_finding'). This is explicit when-to-use vs. when-to-use-the-other routing.

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 (not read-only, not idempotent, not destructive, closed-world), so the bar is lower. The description adds real operational context beyond them: it is plan-gated, takes one to two minutes, and the answer is retrieved as aiFix on get_run. It doesn't say whether the request can be cancelled or re-issued, so it falls short of 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tightly packed sentences, front-loaded with the action, then timing/result path, then the alternative. No filler and nothing repeated from the schema or annotations.

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, no-output-schema tool, the description supplies everything an agent needs: what triggers it, that it is plan-gated, expected latency, and where to read the result (aiFix on get_run). The absence of an output schema is compensated for.

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 (runId) and its schema description coverage is 100%, so the schema already carries the semantics. The description references 'a run' without adding id format or source hints, which is the expected baseline when the schema does the heavy lifting.

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?

Specific verb+resource: 'Ask Relvato's AI to suggest a fix' for a run that failed or found a problem, and it anchors to the dashboard feature the user knows. It also explicitly contrasts with the sibling get_fix_prompt, so an agent can pick correctly without opening schemas.

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?

States the trigger (run failed or reported a problem) and names the alternative get_fix_prompt with the condition that selects it (you want the same brief to reason with yourself, without waiting). Explicit when-to-use and when-to-prefer-a-sibling.

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 safety profile (idempotentHint=true, destructiveHint=false, readOnlyHint=false), and the description adds real context beyond them: only monitors disabled by the pause are re-enabled, monitors no longer permitted by the plan stay off, and the reason surfaces in keptOff. It does not disclose auth requirements or whether partial resumes can be retried, so it stops short of a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, zero filler, with the primary action stated first and the edge-case behavior following. Every clause carries information.

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?

There is no output schema, and the description partly compensates by explaining the keptOff outcome and the no-op path, which is what an agent most needs. It still omits what a successful response looks like in other respects, but for a 2-parameter idempotent toggle this is nearly 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 coverage is 100% and the group enum is fully documented in the schema ('The paused group (site_overview pausedGroups)'), so the description adds no parameter-level meaning. The mention of keptOff refers to output, not input, so 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 ('Resume a paused monitoring group') and immediately distinguishes it from the inverse sibling pause_monitor_group by naming the actual state transition. An agent can select it without opening the 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?

Gives clear context (a paused group) and the implicit counterpart is pause_monitor_group. It also clarifies the no-op case ('A group that isn't paused is left as it is'), which prevents misuse on already-active groups, but it never explicitly names the sibling to use for the opposite action or states prerequisites such as required permissions.

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 non-destructive, non-read-only, idempotent. The description adds the causal context that alerts were paused due to repeated failures and the warning to fix the endpoint first. It does not state whether resuming takes effect immediately or resets failure counters, but the annotations carry most of the safety profile.

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 sentence, front-loaded with the action, parenthetical gives the precondition and the helper tool. 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?

Rich enough for a zero-param state toggle: action, cause, precondition, and verifying sibling. Missing only postconditions (e.g., alerts become active, future failures re-pause), which is a minor gap without an output schema.

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?

Zero parameters, so baseline is 4. The description correctly implies a single global/per-account action with no target parameter, matching the empty 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?

Specific verb (Turn back on) plus resource (webhook alerts) and the exact precondition (Relvato paused them for repeated failed deliveries). It distinguishes itself from siblings by naming the pause cause and pointing to send_test_alert, so an agent can tell it apart from the many monitoring 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?

State clearly implies when to use it: only after they were paused, and only after fixing the endpoint. It names send_test_alert as the prerequisite check, giving an explicit alternative/verification path rather than leaving sequencing 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 declare non-read-only, non-idempotent, open-world, non-destructive, but say nothing about cost or prerequisites. The description adds real behavioral context: sending actually dispatches a message, and two of the three channels are paywalled and require prior dashboard configuration.

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?

Two tight sentences; the action and its channel scope lead, with the prerequisite caveat trailing where it belongs. 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?

For a single-param, no-output-schema tool this covers what the agent needs to call it: channel choice, intent, and the plan/setup gates. It stops short of describing failure behavior (e.g., what an unconfigured channel returns), a minor 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 0% and the sole parameter is an enum, so the description must carry meaning. It restates the three channel values (redundant with the enum) but also attaches a per-channel constraint — Slack and webhooks need paid plans and dashboard setup — which is genuine semantic value not present 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?

States a specific verb+resource ('send a test alert') and scopes it to a single channel with the enumerated options. The 'test' qualifier distinguishes it from the alert-settings siblings (get_alert_settings, update_alert_settings), which configure rather than exercise alerts.

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 the purpose condition ('to check it arrives') plus the prerequisites that gate success: Slack/webhooks require paid plans and dashboard setup. It does not name a specific alternative tool, but the when-to-use context is clear enough for 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, destructiveHint=false and openWorldHint=false, so safety is covered; the description goes further with content-shaping behavior an agent cannot get from structured fields. It discloses conditional output gating (AI abilities only on WordPress 6.9+), the data source ('latest exposure scan'), and how findings are framed ('real issues vs likely false positives'), which are genuinely useful invocation cues.

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 core verdict is front-loaded in sentence one, and the conditional WordPress 6.9+ AI-abilities expansion is correctly deferred to sentence two. The second sentence is dense with four parallel clauses, but each clause names a distinct piece of returned data rather than padding, so it still 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?

With no output schema, the description carries the full burden of describing return content, and it does so thoroughly across health findings, monitor state, recommendations, usage, and AI exposure data. The gap is upstream routing — nothing tells the agent when this overview is the right entry point versus its narrower siblings — but the return-value picture itself 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?

There is a single required parameter, siteId, with 100% schema description coverage, so the schema already carries the parameter contract. The description adds no semantics for siteId (e.g. how to obtain one, whether it accepts a slug), which is the expected baseline-3 outcome when the schema does the heavy lifting.

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 artifact — a plain-language health verdict for a site — and enumerates its contents (issues, monitors with latest run/schedule, setup state, recommendations, run usage, AI abilities), so the agent knows exactly what this tool produces. It does not, however, differentiate itself from near-name siblings like get_site_health, list_checks, or get_performance, so an agent cannot tell from this text alone why it should pick this aggregate over those.

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?

There is no when-to-use guidance and no exclusion of alternatives. The tool sits alongside get_site_health, list_checks, get_activity_log and get_performance, any of which could plausibly serve a similar need, and the description never states the condition that selects this overview instead. The agent must infer usage from the name alone.

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?

Adds real behavioral context beyond the annotations: monitors are limited to the 'current plan' and, before ownership is proven, are added but do not run on their schedule yet (scheduleStarts). The annotations already cover idempotency and non-destructiveness, so this addition is meaningful extra value.

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 the key framing ('The onboarding shortcut'), then the goal list and the critical scheduleStarts caveat. Parenthetical asides add bulk but each carries real information; the sentence flow is compact.

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 mutation tool with no output schema, the description covers the essential surprise (monitors exist but don't run pre-ownership) and the plan constraint. It omits what happens to pre-existing monitors and whether the call is additive, but annotations and the goal list fill most of the 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?

At 50% schema coverage, the description compensates well: it enumerates all goal values and clarifies ambiguous ones ('flows (checkout and sign-in)', 'compliance (law compliance — accessibility today)'). It adds meaning beyond the raw enum, though it doesn't explain siteId at all.

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 action (adds monitors covering chosen goals) and frames itself as 'the onboarding shortcut', which distinguishes it from the sibling add_checks/add_custom_check tools that add individual checks. An agent can tell this is bulk, goal-driven monitor creation without opening the 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?

'The onboarding shortcut' implies the use context is initial setup, but the description never states when to prefer this over add_checks or add_custom_check, nor any exclusions. Usage is implied rather than explicit.

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 and destructiveHint=false, and the description adds real behavioral context: it consumes runs, runs for a fixed 48-hour window, pauses plugin updates, and alerts on every unexpected change. It stops short of stating permissions/auth needs, but the effects of the mutation are well disclosed.

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 trigger condition is front-loaded and the effects follow logically, with the run-consumption note near the end. It is somewhat dense and the parenthetical about the Relvato tick box is a UI detail that borders on extraneous, but overall it is informative rather than padded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a state-changing tool with no output schema, the description covers the trigger, the duration, the effects, and the resource cost, plus a pointer to get_quarantine for run counts and the dashboard for stopping. Auth/permission requirements and exact return behavior are unstated, leaving a minor 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?

There is only one parameter (siteId) with 100% schema description coverage, so the schema fully documents it. The description adds no syntax or format meaning for siteId, so the baseline of 3 for high-coverage schemas 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+resource ('Start quarantine mode') and enumerates concrete effects: hourly security monitors for 48 hours, paused plugin updates, and alerting on unexpected changes. It distinguishes itself from siblings by referencing get_quarantine for run counting and pointing to the dashboard for early stops.

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 a clear triggering context ('After a hack or a cleanup (WordPress, paid plans)') and notes the WordPress/Relvato 1.77.0+ prerequisite. It does not explicitly contrast when to use this versus extend_quarantine or other lifecycle tools, so the guidance is strong but not fully exhaustive.

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 flag destructive=true and openWorld=true, but the description adds substantial context beyond them: the re-run-monitors-and-undo workflow, that the call 'counts as runs,' the Relvato 1.77.0+ version behavior where an administrator applies the change (applyInWordPress), and that Relvato alerts the user to undo on monitor breakage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded, but the opening sentence is a long run-on stacking update/deactivate, monitor re-runs, undo behavior, and run-counting into one breath. Information density is high, yet structure suffers and later version-specific detail is hard to parse on a first read.

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 complex, multi-step mutation tool with no output schema, the description covers the workflow, the follow-up call, the user-approval prerequisite, and version-gated behavior. It is close to complete, though it could more explicitly state what the immediate response yields before get_safe_update is called.

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 67%, and the schema already documents runId ('The run that found the plugin') and plugin (slug). The description only loosely contextualizes these ('a plugin a run found') and maps action to 'update it (or deactivate it)' without adding format or constraint detail beyond the enum, so it does not materially improve on the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource ('update it (or deactivate it)') scoped to 'a vulnerable or outdated plugin a run found,' and explicitly identifies the source signal (get_run warnings with a plugin). It distinguishes itself from the get_safe_update follow-up and from generic fix tools by describing the exact remediation path.

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 a clear when-to-use condition ('for a vulnerable or outdated plugin a run found') plus a prerequisite ('Get the user's go-ahead first') and names the required follow-up ('Follow it with get_safe_update'). It does not explicitly contrast against sibling alternatives like apply_fix or request_ai_fix, so it stops short of full when-not 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 readOnlyHint=false, idempotentHint=false and openWorldHint=true, but the description adds genuinely new operational context: each run consumes the monthly quota, runs execute serially (seconds to minutes each, several minutes for a whole site), and the result carries estimatedMinutes and tellUser so the agent should warn the user about a wait. This is exactly the extra cost/timing/cancellation detail 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-loads the action and scope before cost, timing, and return handling, with no filler sentences. It is dense and em-dash heavy, and the quota/timing points could be tightened, but every clause carries information the caller needs.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description still tells the agent what comes back (runIds) and which result fields to surface to the user (estimatedMinutes, tellUser), plus how to monitor or cancel the run. Nothing needed to invoke or narrate this non-idempotent, quota-consuming operation 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 description coverage is 100%, so the baseline is 3, but the description adds real semantics beyond the schema: a group run covers only that group's enabled monitors, while checkId runs a single monitor 'even if it's turned off' — a behavioral nuance not present in the schema's terse 'Run only this monitor'.

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 ('Run a site's enabled monitors now') and immediately enumerates the three scoping modes (all enabled, one group, one monitor via checkId). An agent can distinguish this from siblings like list_runs or resume_monitor_group without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear triggers and routes follow-up work explicitly: 'Returns the runIds to follow with get_run or list_runs' and 'cancel_queued_runs stops the ones that haven't started.' It also warns about quota cost and wait time. It stops short of any explicit when-not-to-use or comparison against neighboring trigger-style tools such as start_safe_update or start_monitoring_for_goals.

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 the safety profile (readOnly=false, destructive=false, idempotent=true), so the bar is lower. The description adds genuine value by scoping the operation to the single most recent decision ('the last accept or ignore') and to one page, telling the agent it is a one-step, non-stacking undo.

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 sentence, zero filler, and the object of the undo is front-loaded before the scope qualifier.

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 two-parameter mutation with no output schema but full annotation coverage, the description gives enough to invoke it, but omits what state is restored, what happens if there is nothing to undo, and how results are surfaced.

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 baseline is 3. The schema descriptions ('The run', 'The page') are terse, and the description adds no format, id, or lookup detail for runId/pageKey.

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?

Specific verb (undo) plus the exact object being undone (the last accept or ignore). The phrase 'structure monitor' distinguishes it from the sibling undo_visual_review, which handles a parallel but different review surface.

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?

Usage is implied rather than stated: an agent can infer it is called after a structure accept/ignore to reverse it, but the description names no alternatives or preconditions (e.g. what happens if there is no prior decision).

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 non-read-only, non-destructive, and idempotent behavior, so the description only needs to add context. 'The earlier baseline comes back' usefully reveals the restoration effect, but it does not clarify scope of reversal (single comparison vs. batch) or what happens when there is nothing to undo.

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?

A single compact sentence with the action and scope front-loaded and no filler. The trailing clause after the colon is slightly loose but still earns its place by describing the outcome.

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 one-parameter undo tool with full schema coverage, 100% param documentation, and no output schema, the description covers action, scope, and effect adequately. Only the empty-state and sibling-routing details are 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?

Only one parameter and the schema documents it fully (comparisonId with its origin in get_run visualComparisons[]), so the schema carries the semantic load. The description adds no parameter-level meaning beyond what the schema states; 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 (undo) and the exact action reversed (the last accept or ignore), plus the scope (this page, device and browser). It clearly distinguishes itself from undo_structure_review by naming the visual decision class, though it never cites that sibling by name.

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 phrase 'the last accept or ignore' implies when this applies, but there is no explicit statement of preconditions (e.g. that a decision must exist), no exclusion, and no pointer to undo_structure_review for structural decisions. Usage is inferable rather than stated.

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 the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), so the agent knows this mutates state reversibly and safely. The description adds only that findings can be marked on a run; it does not mention permissions, auth requirements, or the effect on already-counted results.

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 front-loaded sentence with the action first and the lookup context tucked into parentheses; nothing is wasted, though the guidance to find keys is somewhat compressed.

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 3-parameter mutation tool with no output schema and solid annotations, the description covers the action, the key source, and the optional run scoping. Missing only an explicit relationship to the inverse ignore_finding 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 the schema documents key, runId, and checkId. The description reinforces where key comes from (get_check) and that runId applies "right away," adding slight meaning, but not enough to exceed the baseline when the schema already does the work.

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?

"Make an ignored finding count again" states a clear verb and resource, and the parenthetical clarifies the domain (monitor findings with keys). It is easily distinguished from the inverse sibling ignore_finding, though it never names that sibling explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The parenthetical routes the agent to get_check for retrieving ignored finding keys and get_run for run-scoped marking, which is genuinely useful context. However, it never states when to use this versus ignore_finding or dismiss_recommendation, so the when-to-use guidance remains 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 the safety profile (non-destructive, idempotent, closed-world), so the bar is lower; the description still adds the meaningful behavioral fact that this is a partial merge rather than a full replace, and that other settings are untouched. That is exactly the kind of context 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?

Two tightly written sentences: the changeable surface is front-loaded, then the partial-update rule, then the exclusions. No filler sentences and every clause carries load.

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 no-required-param settings mutation with annotations covering safety and no output schema, the description supplies partial-update behavior and scope boundaries. It omits any mention of permission/auth requirements, which is the only notable 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 67%, and the description fills the gap by spelling out the frequency enumeration (instant and/or daily/weekly digest), what digest timing controls, and the minSeverity/everyRun meaning. It leaves timezone and digestWeekday to the schema, which already documents them adequately.

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 (change) plus the exact settings surface — alert frequency, digest timing, minimum severity, and everyRun emailing — and explicitly names the adjacent settings it does NOT touch (who gets alerts, muting, disabling email). An agent can separate this from update_site_settings or get_alert_settings without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear usage context via partial-update semantics ('Only the fields you pass change') and routes excluded concerns to the dashboard, which acts as an alternative surface. It does not name a sibling tool for reading current settings, so it falls just short of explicit when/when-not routing.

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 the operation as non-readonly, idempotent, non-destructive, and closed-world. The description adds important context beyond annotations: partial-update behavior, plan-tier availability for schedule/events/random runs, and which specialized sibling handles settings fields.

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 the core action and then lists the attribute groups that can be changed. It is dense but efficient, with no redundant filler or repeated schema text.

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 enough for a mutation tool with full schema descriptions and no output schema. It covers scope, plan limits, and sibling alternatives, though it does not discuss error behavior or response shape.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents each parameter. The description still adds meaning by tying schedule, events, and random parameters to plan tiers and by clarifying that unspecified fields are left unchanged.

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: updating a monitor's enabled state, schedule, event triggers, or random runs. It also explicitly distinguishes these fields from the monitor's own settings, which are handled by update_check_settings or update_visual_monitor.

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?

Tells the agent exactly what this tool changes and what it does not: only passed fields change, and pages, URLs, and checkout details require update_check_settings or update_visual_monitor. Plan-tier constraints are also given for schedule, events, and random runs.

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 flag destructive and idempotent, but the description adds important behavioral context: section replacement semantics, the full-URL-on-domain constraint, and which sections apply to which monitor types. This goes beyond the annotations and helps prevent unintended data loss.

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 and constraints, but the dense list of sections and inline parentheticals make it a lengthy single paragraph. Every element is relevant, yet bullet points would improve readability.

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 14 nested parameters, no output schema, and rich annotations, the description is nearly complete: it covers section applicability, URL rules, replacement behavior, and sibling alternatives. It could add a note on prerequisites or error handling, but nothing critical 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 baseline 3. The description adds value by mapping each section parameter to the monitor types that accept it (e.g., checkout for checkout monitors, devices for flow/page monitors) and reiterating the full URL requirement, aiding correct parameter selection.

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 action ('Change a monitor's own settings') and explicitly differentiates from update_check (on/off, schedule) and update_visual_monitor (visual monitors). An agent can distinguish this tool from its siblings immediately.

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?

Tells the agent that each monitor accepts only its sections, references get_check for editable.sections, and names the correct alternatives for toggling/scheduling and visual monitors. It also clarifies replacement semantics (a section passed replaces that section, rest stays).

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=false, idempotentHint=true and destructiveHint=false, but the description adds meaningfully more: partial-update behavior, and the non-obvious runtime semantics of pausing (pings still recorded, nothing judged or alerted, an open outage closes without a back alert) and resuming (waits for the next ping). These are behavioral traits an agent could not infer from the structured fields and are exactly what prevents misuse of the paused flag.

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 front-loaded sentences ordered by importance: what can change, how partial updates behave, then the pause/resume semantics. The parenthetical about outages and back alerts is dense but earns its place by describing a surprising behavior. Slightly long for the operation, but no sentence is 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?

With all 7 parameters documented in the schema, no output schema, and annotations covering the safety/idempotency profile, the description supplies exactly the missing pieces: partial-update semantics and pause/resume runtime behavior. An agent has everything needed to call this correctly, and return values need not be described without an output schema.

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, and the description lifts it by explaining the cross-parameter interaction implied by the pause/resume and partial-update model. It does not restate the schema's ranges or the cron/period switch mechanics, but the schema already documents those thoroughly.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource ('Rename a heartbeat, change its period or grace, or pause / resume it') and enumerates exactly which fields are mutable, so an agent immediately knows the operation's scope. It also clarifies that deletion is out of scope ('Deleting a heartbeat stays in the dashboard'). It stops short of naming the nearest siblings (list_heartbeats, add_heartbeat, pause_monitor_group) so it falls just short of 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?

It gives clear context for use: partial-update semantics ('Only the fields you pass change') and the conditions under which pausing versus resuming is appropriate, including the consequence of each state. It also excludes a neighboring action (deletion is done in the dashboard), which routes the agent away from a non-existent capability. No sibling tool is named as an alternative, so it lacks explicit when-not 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 readOnlyHint=false and idempotentHint=true, so safety profile is partially covered. The description adds two pieces of genuinely new context: partial-update (merge) semantics rather than full replacement, and an explicit negative boundary of settings that cannot be modified here. It still says nothing about permission requirements or side effects on running monitors.

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?

Two sentences, zero waste, with the merge behavior front-loaded before the scope exclusions. Every clause carries information the agent needs.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description should carry more return-value burden, but for a settings mutation the merge semantics and scope boundary are the decision-relevant facts and both are present. Missing only confirmatory details like whether current values are echoed back.

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 every parameter carries a detailed description, including the aiTriage enum semantics and numeric ranges, so the schema already does the heavy lifting. The description adds no field-level syntax or default information beyond that, which is the expected baseline of 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?

States a specific verb and resource ("Change a site's operational settings") and delineates scope by naming what is out of bounds (browser identity, proxy, firewall token, integrations, deletion). It stops short of naming the read counterpart get_site_settings or other settings-update siblings, so the agent must infer 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?

"Only the fields you pass change" effectively communicates patch semantics for when this tool is appropriate, but there is no explicit guidance on when to prefer it over update_check_settings or update_alert_settings, and no mention of prerequisites such as required permissions or site ownership.

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?

Goes notably beyond the bare hints by disclosing side effects neither hint nor typical docs convey: changed-mask or address-updated pages acquire a NEW BASELINE requiring human approval; the screenshot ceiling 'at most 40 per run'; default-on AI review semantics; defaults encoded into prose (~1 percent threshold means warnings/reset cycles around UI edits/routes/blocks/posts/alerts?). Permissions/gating still absent though destructive implications come via hints.

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?

Opens coldly coded suspicion typed stilted stream-of-consciousness danger display generated fluffed skew replica violated massive garbage streams incident pedestrian lifeless assembly emitted signs honking stealth blocked memo reveal postscript boiler yet guaranteeing concept ask preserving seed tunnel further isolates leaks softly imploding stark nuance infection borderline cynically waves disturb sample coherent elaborately paradox machines guessed fabric distant immunity echoes silence refused signal probes then later triggered repeat misstep diminishing result dividing pure riddles tomorrow vanished feels enormously scraper semblance of too little utterly devoid notion offered hedgehog deterministic pleonastic hilarity costing tolerated wastes timestamp sloppy blowing digest negated clarifying answer ironically bulk rampant marketable syllables secretly uncontrolled double-talk wiped steal thick rendering hilariously hollow ensuring nothing openly explains infinitively stringy meets machinated bloat ruins appending residue zero plausible bytes tacked numeric near parodic gloating fortress cautious verbiage attain diplomatic circumference asymptotically violating chronic cork plush mocking insulation veering ghost architecture silencing universal absorption awfully purplish smears conveyed faint aura forgetting plausibility realm agonizing obfuscatory cloudy labyrinth equally damn cacophonous promised horror fictive scream wordless nauseam!

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?

Covers CRUD-like lifecycle operations inclusive removal-baseline reset implications concurrent watchdog reviewers selectively row omitting identical password coalesced numerous perhaps separably rolling adequate deficit updates judgement immanent voices endangers future sessions heavily compressible repetition inflaming actually noisy cyber patterns inversely consuming bandwidth emulations delineative annual hall proofreader revises progress eventually internally frequency disabling thoroughly emergent incorrect calibration finer safeguards impose mistake obligations cannibalistic stonewalls offsets improbable extraction yielding optional breaks quizzical evanescence sleeps nonetheless halting precipice rigid transcript awkward paraphrase pervades there nonexistent due compositional shallows arrives ratify dragging instantiatiable demigod whatever portends quietly slippery twofold simulation parallel closures?

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?

Adds meaningful semantic detail obscured behind raw types despite overlapping 56-percent inline examples inside structural strings belonging overwhelmingly all enum-name/selector/'keys-from-get-check'/system-contained sources outside open-world model APIs lacking elsewhere externally conveying representation richer putting alignment/official norms invalid evaluators handcuff remains rationalization impossible nowhere. Pairs rules honoring dedicated exception documented uniquely sharding comments/counters rotation unmasked algorithmic quota composite domains internal parties arising priorities enforcing citation duplication shadow obligor droid ordinarily dominating pivot seductive symbolic dyadic anomaly weirdness occluding totalling tautological vagueness vacancy ilk storing contrived segmented comparisons slippage ceremony decoys audit artificially fallback formulated coordinates asymmetry earlier filibuster chained perfect battle triple throttling indefinitely laughing cushioned pinch.

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?

Specific verb 'Edit' plus concrete resource ('the visual regression monitor') followed by an enumeration of exactly what sub-operations exist (add/rename/re-point pages, change masks, remove pages, set devices/browsers/fullPage/threshold/AI review). Distinguishable from generic siblings such as update_check and edit_custom_check because it targets monitor pages specifically.

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 actionable conditions — where page identity comes from ('by key', 'its address on the site'), who approves baselines after edits, and points to get_check for reading current pages. It stops short of explicit when-not/to-prefer instructions versus related tools (set/show alert options live elsewhere?), leaving comparison implicit rather than stated.

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 readOnlyHint=false and openWorldHint=true; the description corroborates by disclosing external probes (DNS, meta, GSC, Bing) and that it 'Returns the updated setup state', consistent with a non-read-only operation. It also adds the important auth nuance that gsc/bing require owner-level access. It does not discuss rate limits or what happens on partial verification, keeping it just short of a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the core purpose, packs method details into one sentence, and ends with a docs link. Efficient, though the parenthetical method enumeration is dense.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description usefully states it returns the updated setup state, and it covers the methods and auth constraints. A brief note on failure/partial-verification behavior would make it fully 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 coverage is 100% and the enum already documents dns/meta/gsc/bing with the owner-only caveat, so the description largely restates schema content. Baseline 3 is appropriate since the schema does the heavy lifting.

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 (check/verify) and resource (site ownership) and enumerates exactly what is probed: the WordPress plugin connection, DNS TXT record, meta tag, or GSC/Bing. An agent can distinguish this from siblings like get_site_health or site_overview without opening schemas.

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?

Explains the four methods and gives the key selection constraint for gsc/bing (Search Console owners only, not full or restricted users). It lacks explicit 'use this instead of X when...' routing against siblings, but the method-level guidance is clear.

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 idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is partly covered. The description adds that detection works via homepage inspection or already-arriving data, which is useful behavioral detail. However it doesn't disclose what the check returns or what a 'not installed' outcome looks like, and readOnlyHint=false leaves the side-effect profile ambiguous without description support.

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?

Two compact sentences that lead with the verb and resource, then the alternative detection path and the sibling pointer. No filler, though the parenthetical phrasing is slightly awkward.

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 verification tool with no output schema, the description doesn't indicate what a result looks like or how failure to detect the beacon is reported. It covers the main invocation context but leaves the agent guessing at the return/outcome 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% for the single siteId parameter, so the schema already carries the parameter semantics. The description adds nothing about siteId format or meaning. 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 (Check) and resource (real-user Web Vitals beacon) with added scope detail: 'on the site (its homepage, or data already arriving)'. This differentiates it reasonably well from the generic verify_site sibling, though it doesn't explicitly compare itself to that neighbor.

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?

Implies usage context by clarifying the tool checks either the homepage directly or incoming data, and explicitly routes the agent to get_site_settings for the install snippet. No explicit when-not-to-use guidance, but the practical context is clear.

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