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

Goes beyond annotations by disclosing the dry-run preview path and that tokens are redacted in preview output — meaningful for a write tool. Annotations already flag readOnly=false, idempotent=false, openWorld=true, but the description does not mention that repeated adds are non-idempotent or what permission is needed.

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 terse sentences, purpose front-loaded, then endpoint, then the dry-run caveat and the redaction caveat. Nothing 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 write tool with full schema coverage and no output schema, the description covers purpose, dry-run safety, and output redaction adequately. The main omission is add-vs-replace semantics for existing notification configs, which matters for a non-idempotent write.

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 both parameters including the confirm dry-run semantics and Apprise URL format. The description restates the confirm behavior and adds the redaction note, which is only marginal value over 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 and resource ("Add global notification URLs") and the backing endpoint. "Add" implicitly contrasts with the sibling changedetection_replace_notifications and changedetection_delete_notifications, but the description never pins that contrast down 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?

It explains the dry-run mechanism (omit confirm) but gives no guidance on when to choose add over replace_notifications, or what happens to existing notification URLs when adding. Usage context is only 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 this is a non-read-only, non-idempotent write. The description adds important behavioral detail beyond annotations: confirm must be explicitly set to true to execute, and omitting it yields a dry-run preview. It does not describe auth requirements or return behavior, but the dry-run semantics are a meaningful addition.

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 core action, followed by the endpoint, required field, and dry-run caveat. There is no wasted 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?

For a tool with 56 parameters, nested objects, no output schema, and sparse schema descriptions, the description is far too brief. It explains the dry-run pattern but not what the many optional fields do, what kind of tag settings are supported, or what happens on creation.

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

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

The schema has 56 parameters and only 25% description coverage. The description mentions only two: title (required) and confirm (dry-run). It does not explain the many tag-level or watch-like settings in the schema, leaving most parameters undocumented in both description and schema.

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

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

The description states a specific verb and resource: 'Create a tag.' That clearly distinguishes it from delete_tag, update_tag, and get_tag. It does not explicitly contrast with siblings, but the purpose is unambiguous.

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

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

It says 'Requires title' and explains that omitting confirm produces a dry-run, which is useful operational guidance. However, it never says when to use this instead of update_tag or list_tags, and gives no exclusions or prerequisite context.

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

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

The description goes beyond static input parameters to explain the tool's core behavioral capabilities, specifically listing supported processors ('restock_diff') and advanced AI fields ('llm_intent / llm_change_summary'). This provides crucial functional context missing from the raw schema.

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 definition is incredibly efficient, using two sentences to convey the core function, the API endpoint, major feature sets, and a critical operational workflow (dry-run). There is zero unnecessary fluff.

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?

While the tool has over 50 parameters, the description efficiently directs the agent to the most complex behavioral areas. It adequately covers the 'how' (dry-run mechanism) and 'what' (advanced processor support) needed to use the tool, even if exhaustive parameter details are relegated to 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?

Given the extremely low schema description coverage (28%), the description is highly valuable. It explicitly references several complex or niche parameters like 'restock_diff' and the LLM fields, allowing the agent to understand the tool's feature set despite poor schema documentation.

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 defines the tool's action ('Create a watch') and the execution path ('POST /api/v1/watch'). It differentiates the tool's purpose from other functions by listing key specialized features like processor support and LLM integration.

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 provides an essential workflow constraint: omitting the 'confirm' field facilitates a dry-run. This guidance is critical for agents performing safe initial setup before committing resources.

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

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

Annotations already flag destructive and idempotent behavior, but the description adds valuable context beyond them: every snapshot is deleted, the watch itself survives, and confirm omission triggers a dry run. It does not explicitly discuss irreversibility, but the destructiveHint annotation already covers that safety concern.

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 short sentences, front-loaded with the core action, followed by the endpoint, the key scoping detail, and the dry-run behavior. No filler.

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

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

For a destructive two-parameter tool with no output schema, the description covers what is destroyed, what remains, and how to preview safely. It could say more about the response or confirm behavior edge cases, but annotations and schema already carry the safety profile.

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%, including detailed confirm semantics such as rejecting false and the string 'true'. The description's 'Omit confirm for a dry-run' restates what the schema already says, so it meets the baseline without adding further 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?

States a specific verb and resource ('Delete every snapshot for a watch') and explicitly distinguishes itself from deleting the watch itself ('The watch remains'). The endpoint reference reinforces the exact 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 clear operational guidance: 'Omit confirm for a dry-run' tells the agent how to preview before executing. The 'watch remains' phrase implicitly distinguishes it from changedetection_delete_watch, but does not explicitly name alternatives or exclusions.

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, so the safety profile is known. The description adds genuinely useful behavior beyond that: the endpoint is DELETE-with-JSON-body (unusual and worth calling out) and omitting confirm yields a dry-run preview rather than an error. It does not describe the return payload, which keeps it below 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, front-loaded sentences: the action first, then the transport detail, then the dry-run caveat. No filler and nothing buried.

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 could state what a successful delete (or dry-run) returns — e.g. how many notifications matched or were removed. It also does not clarify whether watch-scoped subscriptions are affected by 'global'. Adequate for invocation, thin for interpreting results.

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 parameters in detail, including that confirm must be the boolean true and that false/string 'true' are rejected. The description's dry-run note restates what the schema says, adding no new semantic detail — 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?

The description names a specific verb and resource ('Delete matching global notification URLs'), which separates it from per-watch notification handling and from its siblings add_notifications/replace_notifications/list_notifications. It does not explicitly name the sibling it is not, but 'global' plus 'delete' pins the operation clearly.

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 dry-run hint ('Omit confirm for a dry-run') gives real operational guidance about how to invoke safely, but the description never says when to choose this over replace_notifications or per-watch operations, and gives no prerequisites. Usage is implied rather than stated.

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

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

Annotations already mark this as destructive, idempotent, and open-world, and the description adds important behavioral detail: deletion removes the tag from every watch. It also discloses the dry-run mechanism via confirm, which is valuable context beyond the annotations. It does not cover auth requirements or the exact dry-run response, 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?

The description is three short sentences and front-loads the action and scope before the endpoint and dry-run detail. Every clause earns its place with no repetition or 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 simple two-parameter destructive tool with no output schema, the description covers the action, scope, and dry-run control adequately. It could add whether the dry-run returns a preview payload or whether deletion is reversible, but the essential information for correct invocation 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?

With 100% schema description coverage, the schema already fully documents uuid and confirm, including the strict const true requirement and rejection of false/string true. The description reinforces the dry-run behavior but adds no parameter semantics beyond what the schema provides, so the 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 states a specific verb and resource ("Delete a tag") plus its scope ("remove it from every watch"), which clearly distinguishes it from sibling tag tools like update_tag and create_tag. The endpoint path further disambiguates the 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?

It gives clear operational context, notably that omitting confirm yields a dry-run preview, which helps an agent invoke the destructive action safely. It does not explicitly contrast this with alternatives such as update_tag for renaming, but the deletion purpose 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 destructiveHint and idempotentHint, so the bar is lower, but the description still adds the key consequence — the watch's entire history is destroyed — and the dry-run-by-default safety pattern. Missing only permission or irreversible-forever caveats.

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 terse fragments — action, endpoint, dry-run caveat — with the destructive consequence front-loaded and zero 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 2-parameter destructive tool with full annotations and no output schema, the description covers what is destroyed and how to preview. Only the absence of post-deletion return information and sibling routing 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%, with both uuid and confirm fully documented including the rejected false/string-true cases. The description restates the dry-run behavior already in the schema and adds no new parameter semantics, 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?

Names a specific verb and resource plus its blast radius ('delete a watch and all of its history'), which meaningfully separates it from changedetection_delete_history, which the description does not explicitly name. An agent can classify it as a destructive watch-level operation 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?

Conveys how to preview safely ('Omit confirm for a dry-run'), but gives no guidance on when to prefer this over changedetection_delete_history, changedetection_set_watch_state, or how to recover the UUID. Usage is implied rather than routed.

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 annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is clear. The description adds useful behavioral context by saying the document is 'live merged' and returns 'YAML text', though it does not mention auth requirements or rate limits.

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

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

The description is three short sentences, front-loads the purpose, then supplies the endpoint and return format. Every sentence contributes useful information with no repetition or 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 simple no-parameter read tool, the description is complete enough: it states what is returned (YAML text), the exact endpoint, and that the document is live and merged. Combined with the annotations, an agent has what it needs to call this 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 are zero parameters, so the baseline score is 4. The description does not need to explain parameter semantics, and the empty schema is consistent with a no-argument endpoint call.

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: 'Get the live merged OpenAPI document for this instance.' It also gives the exact endpoint GET /api/v1/full-spec, making it clearly distinct from every sibling, which all operate on watches, tags, notifications, history, or system info.

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 resource: an agent should call this when it needs the instance's OpenAPI spec. However, there is no explicit when-to-use or when-not-to-use guidance, and no alternative tool is named because this appears to be the only spec-retrieval tool 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 readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the REST endpoint and output format choices, but says nothing about diff size, truncation, or what the response body looks like for a read-only diff operation.

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 short sentences, front-loaded with the action, then the endpoint and key parameter hints. The raw endpoint path is mildly redundant but does add routing context without bloat.

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 12-parameter tool with 25% schema coverage and no output schema, the description leaves too much unsaid — most notably the diff-filtering booleans that materially change results. An agent cannot confidently compose a call beyond the three required parameters.

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 only 25% across 12 parameters, so the description must compensate and largely does not. It explains from_timestamp/to_timestamp and format (which the schema already documents), but leaves eight parameters — type, added, removed, replaced, no_markup, word_diff, changesOnly, ignoreWhitespace — completely unexplained.

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?

"Diff two snapshots" states a specific verb and resource, and the endpoint path makes the scope (one watch, two timestamps) concrete. It is distinguishable from siblings like get_snapshot, though the description never names that alternative 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 hints that from_timestamp may be 'previous' and to_timestamp may be 'latest' imply the intended common usage (compare last two snapshots). However, there is no explicit statement of when to call this versus get_snapshot or list_history, and no exclusions or prerequisites.

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, open-world behavior. Beyond that, the description adds valuable behavioral detail: small binaries are returned as base64 while large files return only size. This return-shape variability is not captured in annotations or schema.

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 core action and endpoint, then immediately the key return behavior. No filler or redundancy.

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

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

The description provides enough to call the tool correctly: action, endpoint, and critical return-size nuance. Without an output schema, it covers the main behavioral ambiguity. Minor omissions like error behavior or auth are not essential for this simple 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 coverage is 100% and the single uuid parameter is documented as 'Watch UUID' with a pattern. The description does not add further meaning beyond the schema. Baseline 3 applies when the schema already 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 and resource: get the favicon for a watch. It also provides the endpoint path, making the operation unambiguous. It does not explicitly differentiate from sibling getters like get_watch or get_snapshot, but the resource noun 'favicon' is distinctive enough.

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

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

The description gives no guidance on when to use this tool versus alternatives, nor any prerequisites. Usage is only implied by the operation itself. For a simple getter this is less critical, but it still provides no explicit context.

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=true, so the safety profile is covered. The description adds the endpoint and the 'latest' timestamp shortcut, but says nothing about what happens when the timestamp is not in history or what the response looks like for html vs non-html requests.

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 fragments, front-loaded with the action and endpoint. It is telegraphic rather than polished prose, but nothing is 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?

A simple read-only tool with a fully documented schema and safety annotations needs less, but the description still leaves gaps for an agent: the return shape when html=true vs false, behavior for a missing timestamp, and the omitted 'previous' value are all unaddressed.

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's note that timestamp accepts unix time or 'latest' largely restates the schema and actually omits the 'previous' value the schema allows, so it adds no meaningful 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 ('Fetch one snapshot') and pins it to the exact endpoint path, so the agent knows precisely what operation this is. It does not explicitly distinguish itself from close siblings like changedetection_get_diff or changedetection_list_history, which keeps it below 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?

There is no explicit when-to-use guidance and no named alternatives, so the agent must infer from the singular 'one snapshot' phrasing that list_history is for enumeration and get_diff is for comparisons. Usage is implied but never 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 readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds that the response includes 'WatchBase fields plus overrides_watch and LLM controls', which hints at return shape but names jargon without explaining it.

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

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

Two short sentences, front-loaded with the action and resource. The raw endpoint line is mildly redundant with the prose but cheap and useful for API-aware callers.

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 it does so only by naming field groups ('WatchBase fields', 'LLM controls') without what they contain or the error case for an unknown UUID. Adequate for invocation, thin for interpretation.

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 uuid parameter is fully documented in the schema, including a UUID regex pattern, so the schema does the heavy lifting. The description repeats 'by UUID' without adding format, sourcing, or error behavior 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?

States a specific verb and resource ('Get one tag by UUID') and pins the exact endpoint, so it is clearly distinguishable from list_tags and get_watch. It stops short of naming a sibling as the alternative for bulk retrieval.

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 UUID' plus a required uuid parameter signals a single-record lookup, while list_tags is left for the agent to infer. No explicit when-to-use, when-not, or prerequisite guidance is given.

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 readOnlyHint annotation, the description discloses meaningful behavioral traits: the response is the full watch JSON, restock and LLM fields appear only when present, nested history maps are flattened into timestamp lists, and server filesystem paths are stripped. These transformations would otherwise surprise an agent parsing the result.

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 short sentences, front-loaded with the verb and key, then endpoint, then return shape, then transformation caveats. No filler and each sentence adds 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, the description appropriately explains the return payload and its transformations, which is the main risk for a single-parameter read tool. It stops short of noting failure behavior for an unknown UUID, a minor remaining gap.

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

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

Schema coverage is 100% and the single uuid parameter is documented with a regex pattern in the schema, so the schema carries the load. The description adds only the phrase 'by UUID' and no format, error, or lookup semantics beyond what the schema states.

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 ('Get'), resource ('one watch'), and lookup key ('by UUID'), and even names the underlying endpoint. This is clearly distinguishable from list_watches (browsing) and get_tag/get_snapshot (other resources) in the sibling set.

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 'by UUID' phrasing implicitly signals retrieval of a known watch rather than enumeration, so usage is inferable. But no explicit when-to-use/when-not guidance and no named alternative (e.g., use list_watches to discover UUIDs) is provided.

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 not read-only, not idempotent, open-world, and not destructive. The description adds useful behavior beyond annotations: it specifies the POST endpoint, text/plain body, and the important dry-run behavior when confirm is omitted.

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

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

The description is three short, front-loaded sentences with no filler. The dry-run constraint is stated clearly, and implementation details are kept brief.

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 12-parameter bulk mutation with annotations and no output schema, the description covers the core behavior, endpoint format, optional fields, and dry-run preview. It leaves some parameter details to the schema, which is reasonable given the schema's 75% 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?

Schema description coverage is 75%, so most parameters are already documented. The description adds only high-level hints that tag, processor, and other watch fields can be set, and that confirm controls dry-run execution, but it does not explain the remaining fields such as proxy, paused, or notification_muted.

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 bulk verb and resource: importing line-separated URLs as watches. It implies a bulk-import distinction from the sibling create_watch, but does not explicitly name or contrast with that sibling.

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 for importing multiple line-separated URLs, and states that omitting confirm performs a dry-run. However, it does not explicitly say when to use this instead of changedetection_create_watch or what prerequisites exist.

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=true, so the safety profile is covered. The description adds real value beyond that: it lists the returned fields (uuid, count, snapshots with timestamp and iso_time) and notes that server filesystem paths are discarded, a non-obvious data-sanitization behavior. It omits ordering and any pagination/limit 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?

Three short, front-loaded sentences: purpose first, then endpoint, then the return/stripping note. The literal REST path is mildly redundant for an agent but costs little. No 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?

There is no output schema, so the description's field list carries the return-value burden and does so adequately, plus it flags dropped filesystem paths. For a single-parameter read tool this is nearly complete; only snapshot ordering and whether history is truncated are unstated.

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 coverage is 100%, with the UUID pattern and 'Watch UUID.' documented in the schema. The description's 'for a watch' merely restates that the uuid identifies a watch, adding no 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?

States a specific verb+resource ('List snapshot timestamps for a watch') and the concrete return shape, which distinguishes it from siblings like get_snapshot (content) and get_diff (changes). An agent can identify this as the lightweight history index 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?

Usage is only implied by the phrase 'for a watch' — an agent can infer you call this to enumerate snapshots before fetching one or deleting history, but no alternatives or preconditions are named. No 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=true and destructiveHint=false, so the description adds value by disclosing that tokens embedded in URLs are redacted — a trait an agent needs to interpret the returned data correctly. It stops short of describing response shape or ordering, but against existing annotations this is solid added 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?

Three short sentences, front-loaded with purpose, then endpoint, then the one behavioral caveat. Nothing redundant or 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 parameterless, read-only listing tool with an empty schema and no output schema, the description covers purpose, API mapping, and the redaction caveat. Only minor gaps remain, such as whether multiple notification URLs can be returned or their ordering.

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 document; baseline 4 applies. The schema is an empty object with 100% coverage and no ambiguity about inputs.

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 ('List global notification URLs') plus the underlying endpoint. It is clearly distinguishable from mutation siblings like changedetection_add_notifications and changedetection_replace_notifications, though the description never names them.

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 guidance on when to use this versus the sibling notification tools (add/replace/delete), and no prerequisites or exclusions. Usage is only inferable from the word 'List'.

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=true, so the safety profile is covered. The description adds only the raw endpoint path (GET /api/v1/tags), and says nothing about pagination, ordering, or the shape of the returned collection.

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 short fragments, front-loaded with the operation. The endpoint path is marginal added value but not bloat; nothing is wasted, though the brevity leaves coverage gaps rather than excess.

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?

This is a simple zero-parameter list operation, so the bar is low, but with no output schema the description should at least characterize the returned collection (array of tag objects). An agent can call it correctly but cannot anticipate the response.

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 no parameter semantics to explain; the schema is empty and complete. Baseline 4 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 gives a specific verb and resource ('List tags'), which is immediately distinguishable from siblings like get_tag, create_tag, or delete_tag. It lacks any explicit statement of scope (all tags vs. filtered) that would fully separate it from get_tag.

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: it is evidently the read-all operation for tags, and the sibling names make the alternative (get_tag for a single tag) inferable. No explicit when-to-use or exclusion statement is provided.

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=true, so the safety profile is covered structurally. The description adds only that the call maps to GET /api/v1/watch and that recheck-all is a distinct write path; it says nothing about pagination, result ordering, or whether the list can be large.

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 short fragments with the core operation front-loaded and the sibling caveat last; nothing is padded. The raw endpoint string is arguably low-value for an agent but is compact enough not to hurt.

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-optional-parameter read tool with full annotation coverage and no output schema, the description covers what the tool does and the one filtering option. It falls short only on return-shape hints (e.g., whether watches include tags/state) that would help an agent decide between this and get_watch.

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 tag parameter is documented as a filter, so the description's mention of 'Optional tag name filter' merely corroborates the schema. No added syntax, matching behavior, or case-sensitivity detail 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 and resource ('List watches') plus the underlying endpoint, so the operation is unambiguous. It also separates itself from recheck-all by labeling that a write tool, though it doesn't differentiate from other read siblings like list_tags or get_watch.

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 clause 'Recheck-all is a separate write tool' implicitly steers an agent away from treating this as a state-changing recheck, which is useful routing. However, there is no explicit when-to-use guidance, no mention of when to filter by tag versus listing everything, and no stated alternatives for fetching a single watch.

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, openWorld, non-idempotent, and non-destructive behavior. The description adds useful context about queuing a recheck and omitting confirm for a dry-run, though it does not describe side effects, return values, or operational limits.

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

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

The description is short, front-loaded with the core action and scope, and every sentence adds practical information: scope, API route, and dry-run behavior.

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 tool with no output schema and annotations covering safety characteristics, the description supplies the essential scope and dry-run behavior. It could be slightly more complete with return or permission context, but nothing critical is missing.

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

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

Schema description coverage is 100%, and both tag and confirm are already documented in the schema. The description restates those semantics rather than adding new parameter-level detail, 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?

The description states a specific verb and resource: "Queue a recheck for every watch" with an optional tag limit. The "every watch" scope distinguishes it from recheck_watch, but it does not explicitly distinguish it from recheck_tag, which also deals with tag-based rechecks.

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 dry-run guidance by saying to omit confirm, but it does not explain when to use this tool versus recheck_watch or recheck_tag. The usage is implied by the scope, but alternatives are not explicitly routed.

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 that this is a non-read-only, non-destructive, non-idempotent, open-world operation. The description adds meaningful behavior beyond that: it is a GET endpoint with recheck=1, it queues work for every watch in the tag, and omitting confirm yields a dry-run. It does not mention auth, rate limits, or duplicate-recheck implications, so it is not exhaustive.

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 scope, then the endpoint detail, then the dry-run caveat. Nothing is wasted and the key information is immediately visible.

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 tool with full schema coverage, annotations, and no output schema, the description covers the essential behavior: tag-wide rechecking, confirm-to-execute, and dry-run omission. Minor missing context includes tag-not-found behavior or whether the dry-run preview returns a count, but those are not critical 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 description coverage is 100%, and the schema already explains uuid and confirm in detail. The description reinforces the confirm dry-run behavior and the URL path, but adds no syntax or constraints 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?

The description states a specific verb and scope: 'Queue a recheck for every watch in a tag.' That scope distinguishes it implicitly from recheck_watch and recheck_all, but it does not explicitly name those siblings, so it falls short of the clearest possible 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 a useful dry-run instruction ('Omit confirm for a dry-run') and makes the tag-wide scope clear, but it does not explicitly say when to use this versus recheck_watch or recheck_all. The selection guidance is implied by scope 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 mutation profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false). The description adds value by making clear that the default, without confirm, is a non-writing dry-run and by exposing the underlying endpoint, so an agent understands the safe-preview path. It does not say how the queued recheck completes or whether it can be awaited.

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, with the core action front-loaded and the dry-run caveat immediately after. The raw endpoint string is mildly redundant but is compact and adds a tracing hook.

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 tool with full schema coverage, annotations and no output schema, the description covers action, scope and the default-safe behavior. The only real gap is what happens after queueing, which is minor given the tool's simplicity.

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

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

Schema coverage is 100% and the schema already explains both uuid and the dry-run semantics of confirm in more detail than the description. The description's 'Omit confirm for a dry-run' merely restates 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 ('Queue a recheck') and scopes it to 'one watch', which implicitly separates it from the recheck_tag and recheck_all siblings. It stops short of naming those siblings, but the scope qualifier is enough for an agent to disambiguate.

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 'Omit confirm for a dry-run' line gives real operational guidance on the write path, but there is no explicit statement of when to choose this versus recheck_tag or recheck_all, nor any prerequisite such as the watch existing.

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 the key consequence—every existing URL is overwritten, and an empty array wipes them all—plus the dry-run escape hatch. It doesn't mention permission requirements or the response shape, so a 4 rather than 5.

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

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

Three short sentences, zero waste, and the destructive 'replace every' scope is front-loaded before the endpoint and the dry-run note.

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

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

With only two parameters, full schema coverage, and annotations covering safety and idempotency, the description supplies everything an agent needs to call it safely—including the dry-run path. Return values are not covered, but no output schema exists and this endpoint's result is a simple state confirmation.

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 both parameters are already fully documented, including the empty-array-clears semantics and the confirm dry-run behavior. The description restates that same meaning rather than adding syntax or constraints beyond the schema, 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 (replace) and resource (every global notification URL) plus the underlying endpoint, which clearly separates it from the add_notifications/delete_notifications/list_notifications siblings even without naming them. It stops short of explicitly naming the alternative tools, so not 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 concrete operational guidance: an empty list clears them, and omitting confirm yields a dry-run. It does not explicitly say when to prefer this over add_notifications or delete_notifications, but the 'replace every' framing implies the bulk-overwrite use case.

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=true, so safety is covered. The description adds the underlying endpoint (GET /api/v1/search?q=), which aids understanding of the call, but says nothing about result limits, pagination, or truncation 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?

Two short sentences, front-loaded with the action, with zero filler. The phrasing 'with optional tag and partial' is telegraphic but efficient.

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

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

For a simple, read-only 3-parameter search with full schema coverage and annotations covering safety, the essentials are present. What is missing is enough to matter: whether results are limited or paginated, and what the response contains (no output schema exists to cover this).

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% – each of q, tag, and partial is documented in the schema itself. The description merely restates that tag and partial are optional and adds no semantics (e.g., matching case, whether partial defaults to false) beyond the schema, 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 ('Search watches') and the match fields ('by URL or title'), so the agent knows this is a lookup tool rather than a mutation. It does not explicitly contrast with changedetection_list_watches or changedetection_get_watch, leaving sibling discrimination to inference.

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 'search by URL or title' versus listing all watches, but no explicit when-to-use / when-not-to-use guidance or named alternatives are given. An agent must infer that this is the right tool for text-based lookup.

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, idempotent, non-destructive, so the bar is lower, and the description adds real value by disclosing the two-step dry-run-then-confirm write protocol. It does not cover failure modes (missing tag, auth) or what the confirmation response contains, 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?

Three short front-loaded fragments with no filler; the dry-run caveat is placed immediately after the action. The raw endpoint path is somewhat incidental scaffolding but is compact and 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?

No output schema exists, so the description need not describe returns, and the dry-run protocol is covered. However, for a state-mutating tool it omits what happens on an invalid/unknown UUID and whether the change is reversible, leaving meaningful gaps.

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

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

Schema coverage is 67%: uuid and confirm are documented in the schema, while muted only appears as an enum without explanation. The description restates the muted/unmuted dichotomy but adds no format detail beyond the enum, so baseline 3 fits.

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: 'Set muted or unmuted on a tag.' An agent can tell it apart from delete_tag or update_tag at a glance, though it never explicitly contrasts with update_tag, which could plausibly also touch the muted field.

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 dry-run note ('Omit confirm for a dry-run') gives one concrete usage rule, but there is no guidance on when to prefer this over changedetection_update_tag or changedetection_get_tag, nor any prerequisite such as tag existence or 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 already declare this a non-destructive, idempotent, non-read-only operation, so the safety profile is covered. The description adds that omitting 'confirm' yields a dry-run, but that exact behavior is already documented in the schema's confirm field, and it discloses nothing further about reversibility of the state change or the dry-run response shape.

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 front-loaded sentences with the core operation first, then endpoint detail, then the dry-run note. The raw 'GET /api/v1/watch/{uuid}' line is mildly noisy but does flag the unusual read-verb-write behavior.

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 4-parameter mutation tool with annotations but no output schema, the description covers the action and dry-run path but leaves the most consequential ambiguity unexplored: what state results if only one of paused/muted is supplied, or if neither is. That is exactly the kind of detail an agent needs before calling a state-mutating 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 description names the two behavioral parameters (paused, muted), which is the main semantic contribution since those two have no schema description text (50% coverage). It does not say whether you may set one without the other or what happens when both are omitted, and the dry-run/confirm semantics are already fully spelled out in the schema's confirm description.

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

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

States a specific verb ('Set') plus the exact attributes ('paused or muted') and the resource ('a watch'), so the operation is unmistakable. It does not name or differentiate from near neighbors such as changedetection_update_watch or changedetection_set_tag_muted, 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?

The verb and resource imply the usage context (toggling a single watch's pause/mute state), but there is no explicit when-to-use, no exclusion, and no pointer to siblings like set_tag_muted for bulk/tag-level muting. The agent must infer the boundary itself.

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, openWorld, and non-destructive semantics, so the description adds value by disclosing the response payload (version, watch count, uptime, queue fields) and hedging with 'when present'. It does not mention auth requirements or rate limits, but the remaining gap is minor for a read-only status endpoint.

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 compact clauses front-loaded with the action, followed by endpoint and return contents. Nothing is redundant relative to the name and 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?

With no output schema, the description usefully enumerates what comes back, which is the key missing structured information for a zero-parameter read tool. Only a brief statement of when the status matters for troubleshooting would make it 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?

The tool takes zero parameters, so the baseline is 4; the description correctly spends no words on parameter semantics and instead describes outputs.

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 ('Get instance status'), names the underlying endpoint, and enumerates the returned fields. It is clearly distinguishable from siblings, which are all watch/tag/history operations, though the differentiation is implied rather than stated.

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

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

Usage is only implied: an agent can infer this is a health/status check, but the description never says when to call it or points to alternatives such as changedetection_list_watches for watch counts.

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 known. The description reinforces the dry-run/confirm behavior, but it does not specify whether omitted fields are left unchanged or cleared — critical for a PUT-style mutation — and adds little beyond what the confirm parameter's own schema text already says.

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 nothing is padded. The literal HTTP route is arguably an implementation detail rather than agent-facing information, but it costs only a few words.

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 exposing 57 parameters, nested objects, and no output schema, this description is far too thin; it never explains partial-update semantics, the deprecated `tag` field versus `tags`, or what the dry-run returns. The annotations cover the safety hint but cannot carry the semantic load here.

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

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

With 57 parameters and only 25% schema description coverage, the description contributes essentially zero parameter semantics beyond the {uuid} path placeholder already marked required in the schema. The many watch-like fields (browser_steps, processor, notification_urls) are left entirely for the agent to infer.

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 ("Update a tag") and includes the REST route, so an agent can distinguish it from create_tag, delete_tag, and get_tag without opening the schema. It stops short of explicitly naming those siblings or clarifying what aspects of a tag this modifies.

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?

"Omit confirm for a dry-run" gives usable invocation guidance for the safety-critical flag, which is more than nothing. However, there is no guidance on when to prefer this over set_tag_muted or update_watch, nor any statement about prerequisites such as the tag existing.

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 but idempotent and non-destructive, so the safety profile is covered; the description adds the confirm/dry-run gate, which is valuable. However, it never says whether the update is a partial patch or a full replace, what happens to omitted fields, or whether permissions/auth are needed. For a 56-field mutation that ambiguity is material.

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 fragments, zero filler, with the purpose front-loaded before the endpoint and field hints. The brevity is appropriate stylistically, though it is achieved partly by offloading information elsewhere rather than by efficient compression.

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 56 parameters, nested objects, low schema coverage, and no output schema, this description is far too thin. An agent cannot determine update semantics, which fields are required for a valid PUT, or what a successful response looks like without consulting another tool or the full spec.

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 only 29%, so the description needs to compensate, but it delegates almost everything to "same writable fields as create, plus last_viewed." That forces the agent to open changedetection_create_watch to understand the 55 non-uuid fields, and it still leaves partial-vs-full semantics unresolved. The only field-level addition is the last_viewed note, which is already documented in the schema.

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

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

States a specific verb and resource ("Update a watch") and anchors it to an existing resource via the required uuid and the PUT endpoint. It also distinguishes itself from create by saying the writable fields are the same as create, plus last_viewed. It does not, however, distinguish itself from setter siblings such as set_watch_state or set_watch_muted that also mutate a watch.

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 only explicit usage guidance is "Omit confirm for a dry-run," which is a useful call pattern for a destructive-ish mutation. There is no statement of when to prefer this over update_tag, set_watch_state, set_watch_muted, or create_watch. Usage is implied by the verb rather than spelled out.

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