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 readOnlyHint=false, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds the meaningful behavioral fact that restoreAll reverses every dismissal on the site, but says nothing about reversibility of a single dismissal, permissions, or what happens when neither key nor restoreAll is supplied.

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 primary action first and the alternate mode second, with the list_checks pointer tucked into a parenthetical. No filler or restatement of the title.

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 three-parameter tool with no output schema, the description covers both operating modes and the scope of each. It is only slightly incomplete: it does not state the behavior when siteId is given but neither key nor restoreAll is set, nor any permission requirements.

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 all three parameters and the baseline would be 3. The description goes slightly beyond the schema by clarifying the interaction between the parameters — restoreAll overrides/supersedes key and operates site-wide — which is genuine semantic value.

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+resource ("Stop recommending a monitor for a site") and explicitly covers the dual mode (dismiss one vs. restore all). It distinguishes itself from the surrounding write/read tools by tying into list_checks, though it does not explicitly contrast with siblings like accept_structure_change or ignore_finding.

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 the two conditions under which the tool is used: dismissing a single recommendation and restoring all dismissed recommendations via restoreAll. It also points at list_checks as the place where recommendations are surfaced. No explicit "when not to use" or alternative tool is named, 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 destructiveHint=true and non-idempotent, but the description adds genuinely new context: the existing recipe is discarded, a new one is AI-generated, and it must be re-approved before the monitor runs again. That explains *what* is destroyed and the follow-up workflow. It stops short of saying whether monitoring pauses in the meantime or whether the edit is reversible.

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, both load-bearing: the first lists the changeable fields, the second discloses the destructive/approval consequence. Front-loaded with zero 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, non-idempotent mutation with no output schema, the description supplies the consequence and the approval requirement an agent needs before invoking it. Only minor gaps remain (state of the monitor during re-approval, error behavior), which is reasonable at this length.

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 all six parameters are already documented in the schema, and the description essentially restates the same fields (goal, page, name, mode). It adds no format, constraint, or interaction detail beyond what the schema provides, 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 concrete verb (change/edit) plus the exact resource (a custom monitor) and enumerates the mutable fields: goal, page, name, mode. The 'custom monitor' qualifier separates it from the other mutation siblings in the list (update_check, update_visual_monitor) so an agent can route 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?

Usage is implied by the field list ('give a monitor a new goal, page, name or mode') and the description hints at the consequence of using it, but it never names an alternative such as reauthor_custom_check or update_check_settings, nor states when *not* to use it. Adequate but leaves 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 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 declare readOnly=true, destructive=false, openWorld=false, so safety is covered structurally. The description adds genuine behavioral context beyond them: newest-first ordering, the 7–365 day history window tied to the plan, and a privacy detail (sign-ins expose the network, not the full address). It says nothing about pagination or truncation at the 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?

A single front-loaded sentence ('WordPress sites: who did what') followed by a compact em-dash list of event categories, ordering, and window. Dense but every clause carries distinct information; no filler or restated title.

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, but for a read-only listing tool with full parameter documentation the description covers scope, ordering, and time window adequately. Minor gaps remain around return shape and default result ordering interaction with filter, none 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?

Schema description coverage is 100%, so the schema already defines all five parameters, including the filter enum and the search meaning. The description largely restates the filter categories and adds only the 7–365 day numeric range. Baseline 3 is appropriate when the schema carries the parameter burden.

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 (activity log for WordPress sites) and enumerates the event categories it returns — sign-ins, roles, application passwords, updates, edits, PHP errors. An agent can tell it isn't a settings or health read. It doesn't explicitly differentiate from overlapping siblings like get_updates or get_notifications, which also touch update/alert 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?

The description implies usage (audit 'who did what') but gives no explicit when-to-use or when-not-to-use guidance, nor does it point at alternatives such as get_updates or get_site_health. Intent is inferable from the enumerated content, which is the definition of 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?

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 safety burden is partly carried. The description adds value with the persistence semantics ('from now on') and the undo path, but says nothing about what exactly gets destroyed or the scope of impact.

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?

Purpose is front-loaded in the first clause, followed by the undo hint. The parenthetical signature path is dense but earns its place by anchoring where the input comes from. Two sentences, minimal waste.

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 idempotent, destructive mutation with annotations covering the safety profile and no output schema, the description supplies the signature source and the reversal tool. Reasonably complete, though impact scope remains implicit.

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 signatures, runId, and pageKey are already documented. The description repeats the signatures source pointer that the schema already contains, adding no syntax or format detail beyond the structured data.

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) and resource (specific element changes on a page), with scope ('from now on') that separates it from one-off actions. Siblings like accept_structure_change and ignore_visual_change are distinguishable from the verb+object pairing.

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 ('e.g. a widget that comes and goes') and names the reversal path (undo_structure_review). It does not explicitly contrast when to prefer this over accept_structure_change, but the context 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 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 already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false and destructiveHint=false. The description adds real value beyond that: the paid-plan and dashboard-setup preconditions that gate Slack/webhook delivery, and the single-channel scoping. It doesn't say what happens when a channel isn't provisioned (error vs. silent no-op), which keeps it from 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. The action and scope lead, and the preconditions follow immediately; 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?

For a one-parameter, no-output-schema tool with annotations covering the safety profile, this is nearly complete: the action, channel options, and provisioning preconditions are all present. The only gap is what the caller gets back (whether delivery is confirmed synchronously or the test result arrives later), which matters given the 'check it arrives' framing.

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

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

Schema coverage is 100% with an enum on the single 'channel' parameter, so the baseline is 3. The description goes further by attaching a channel-specific constraint (slack/webhook need paid plan and dashboard setup), which meaningfully changes how an agent picks a value for that enum.

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 ('send a test alert') plus the scope ('on one channel (email, slack or webhook)') and the intent ('to check it arrives'). No sibling tool performs a test send, so the agent can distinguish it from the settings-oriented siblings (get_alert_settings, update_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 a clear usage context ('to check it arrives') and states prerequisites: Slack and webhooks require paid plans and dashboard setup. It stops short of naming when-not to use it or pointing at the alternative tools for configuring alerts, so it falls just below the explicit-alternatives bar.

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?

Annotations already declare the write/idempotent/non-destructive/safe profile, so the bar is lower, and the description adds real behavioral context: monitors are added per current plan, extra monitors (uptime, SSL, errors, maintenance mode, structure) are included, and before ownership is proven the monitors are created but do not run on schedule yet. That scheduleStarts caveat is exactly the kind of non-obvious behavior worth disclosing.

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 onboarding framing, then the goal list, then the schedule caveat. Dense but every clause carries information; the parenthetical 'plus uptime, SSL, errors, maintenance mode and structure' is slightly list-heavy but informative.

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 annotations covering safety and no output schema, the description supplies plan scoping, the set of monitors created, and the pre-ownership scheduling limitation. It stops short of noting auth requirements or what the response returns, but the core calling 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 100%, so the baseline is 3, but the description enriches the enum values beyond the schema by explaining what each goal covers (flows = checkout and sign-in, compliance = accessibility today). siteId gains no additional meaning, keeping this below a 5.

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 — pick goals and Relvato adds the covering monitors — and frames itself as 'the onboarding shortcut', which separates it from granular siblings like add_checks or add_custom_check. The goal enumeration makes the scope concrete, though it never names an alternative tool 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 onboarding shortcut' implies the usage context (initial setup), but there is no explicit when-to-use versus when-not, and no sibling like add_checks is named as the alternative for non-onboarding cases. Usage must be inferred.

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

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

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 cover destructive/non-idempotent/open-world, and the description adds substantial context beyond them: it counts as runs, requires user approval, behaves differently on Relvato plugin 1.77.0+ (applyInWordPress link answered by an administrator), performs automatic monitor re-runs and verification, and can auto-alert the user to undo. That is real behavioral disclosure, not restatement.

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?

Highly information-dense with each clause carrying operational meaning, but the sentences are long and run-on, and the version-specific Relvato 1.77.0+ caveat is buried rather than front-loaded. No filler, though the density slightly hurts scannability.

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 run-scoped tool with no output schema, the description covers approval, mechanism, verification, and undo paths, which is nearly everything an agent needs. It stops short of describing what start_safe_update itself returns before the get_safe_update follow-up.

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 runId, plugin (slug), and the update/deactivate enum. The description only loosely mirrors that the plugin comes from a run finding and never adds format or edge-case 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+resource chain: update or deactivate a vulnerable/outdated plugin found by a run, via the Relvato plugin, with re-run and undo semantics. It also names the sibling get_safe_update as the required follow-up, so an agent can distinguish it from get_run or apply_fix.

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

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

Explicit trigger ('for a vulnerable or outdated plugin a run found'), explicit precondition ('Get the user's go-ahead first'), and explicit next step ('Follow it with get_safe_update'). The alternative of deactivation is stated inline, and undo is named as the fallback when a monitor breaks.

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 non-readOnly, idempotent, non-destructive, closed-world. The description adds a genuinely useful behavioral trait not in the annotations: 'Only the fields you pass change,' i.e. partial-update semantics, which tells the agent omitted fields are preserved. It does not describe permissions or the response shape, but for a mutation tool with annotation coverage this is solid.

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 what the tool changes before the exclusions. Every clause earns its place, and there is no redundant restatement of the title or schema.

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 full annotation coverage, the description covers scope, partial-update behavior, and out-of-scope tasks. It is complete enough to invoke correctly; only permission/auth requirements are left implicit, which annotations largely neutralize.

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 every parameter already carries its own description and enum. The description restates the affected fields (frequency, digest timing, severity, everyRun) 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?

The description states a specific verb ('Change') and resource (alert settings) and enumerates the affected dimensions: send frequency, digest timing, minimum severity, and every-run emailing. It is easy to separate from get_alert_settings via the verb, but it does not explicitly differentiate itself from near-neighbors like update_check_settings or update_site_settings.

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 strong when-not-to-use guidance by naming tasks that are out of scope and belong in the dashboard: recipient configuration (address, Slack, webhooks), muting sites or monitor types, and turning email alerts off. It stops short of pointing to a specific alternative tool for those tasks, but the boundary is unambiguous.

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 declare destructiveHint=true, readOnlyHint=false and idempotentHint=true, so the safety profile is covered. The description adds genuinely non-obvious behavior: per-section replace semantics ("A section you pass replaces that section; the rest stays") and the full-URL-on-own-domain constraint. It omits error/auth behavior, keeping it 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?

Purpose is front-loaded and the closing sentences efficiently hand off to the sibling tools. The middle is one very long, hard-to-parse sentence enumerating every section with parenthetical detail, which slightly hurts scannability, but for a 14-parameter tool the length is largely earned.

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 params, nested objects, and no output schema, the description supplies what the schema cannot: section-to-monitor applicability, replace semantics, and destination for related fields. It does not cover failure modes or validation errors, so it is strong but not exhaustive.

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 cannot: it maps each section parameter to the monitor types that accept it and clarifies that sections are replaced wholesale. That is real semantic value beyond per-property descriptions.

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 monitor's own settings") and immediately distinguishes itself from siblings by naming update_check (on/off and schedule) and update_visual_monitor (the visual monitor). An agent can route 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?

Explicitly names the alternatives and the conditions that select them, plus a per-monitor-type applicability rule ("Each monitor takes only its sections ... checkout (checkout monitors), devices (flow and page monitors)", etc.). This is routing guidance, not 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?

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?

Annotations already flag destructiveHint=true and non-idempotence, and the description adds genuinely non-obvious operational behavior on top: a page whose masks or address change gets a new baseline that must be approved, and a hard cap of 40 screenshots per run (pages × devices × browsers). These are side effects an agent could not infer from the schema or annotations.

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

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

The core action is front-loaded before the long enumeration, and each parenthetical (masks purpose, screenshot cap, baseline behavior) earns its place. It is dense and runs long as a single paragraph, which slightly hurts scannability, but there is little waste.

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 9-parameter mutation with no output schema, the description covers the important ground: side effects (baseline reset), limits (40 screenshots, 10 custom pages), and where to get keys. It stops short of stating permission/auth requirements or what the response returns, leaving a small 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 description coverage is 100%, so the schema already carries the parameter burden and baseline is 3. The description still adds value by defining masks ('CSS selectors painted over before comparing, for clocks, carousels, ads'), noting the up-to-10 custom-page limit, and restating the threshold unit and defaults, pushing it slightly above baseline.

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

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

Opens with a specific verb+resource ('Edit the visual regression monitor') and then enumerates exactly what can be edited: pages, masks, devices, browsers, capture mode, threshold, AI review. This clearly separates it from siblings like get_check, list_checks, and update_check, which cover reading and other monitor 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?

It routes the agent to a sibling for prerequisite data ('get_check lists the current pages and their keys'), which is real usage guidance for the update path. It does not, however, state when to prefer this tool over e.g. update_check_settings or add_checks, so the routing is helpful 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 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.