ChangeDetection.io (official MCP)

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed world), so the description's job is to add nuance — and it does: the search covers 'the saved (filtered) text' only, and matching is case-insensitive plain text by default unless regex=true or case_sensitive=true. It also discloses that the scan is exhaustive across every snapshot in one call, which hints at cost. It does not discuss truncation behavior when max_lines is hit, which is the main remaining behavioral gap.

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 content density is good and the use cases are front-loaded, but the opening sentence is a fragmented, hard-to-parse clause chain ('...searching every snapshot line by line in one call: every different line that matched with when it was first and last seen, and the periods with a match...'). It rewards re-reading rather than delivering a clean verb-first statement, so structure costs it a point despite little outright 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 eight parameters, no output schema, and a read-only analytical tool, the description does the important work: it describes the shape of the return (distinct lines plus first/last seen and match periods) so an agent knows what comes back. What is missing is the format of from/to (string vs integer timestamps) and what happens when results exceed max_lines, both of which matter for a tool that scans everything.

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 75%, and the description adds real meaning on top: it clarifies the default matching mode (plain text, case insensitive) and the two flags that change it, and it explains group_by=year as counting new matching lines per year rather than just repeating the schema's 'Also count...'. The from/to bounds and max_lines truncation 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?

The description names a concrete verb and resource: it searches a monitor's snapshots line by line and returns each distinct matching line with first/last seen times and match periods. That is far more specific than the title alone. It does not, however, explicitly contrast itself with close siblings such as line_timeline, get_changes, or get_history, so an agent must infer 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?

It gives two concrete use cases with an example each: dating a change ('when did the price become 319?') and tracking a topic over time via group_by=year. That is clear context for when to reach for this tool. It stops short of stating when NOT to use it or naming an alternative sibling for overlapping cases.

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, idempotent, non-destructive behavior, so the bar is lower. The description does add real value beyond them: monitors with no changes are omitted, and a monitor that changed and reverted is reported as "no net difference" — output-shape behavior the agent couldn't infer. It says nothing about the default 50-item limit or how many monitors a call can cover.

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 scope and output form, then use case, then exclusion rule, then mode and edge case. No filler and no repetition 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?

The description covers the essentials for a read-only, nine-parameter query tool with no output schema: what it returns, what it omits, and how to choose the mode. It leaves out pagination and truncation behavior, meaning an agent may not know how to page through large result sets or that diffs are capped.

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 44%, below the point where the schema carries the load, so the description should compensate. It explains mode semantics well beyond the enum labels, but says nothing about the other undocumented parameters: limit, offset, context, watches scope, or max_lines_per_watch truncation.

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 concrete verb and resource ("every change across many monitors between two dates") plus the return form ("unified diffs under a header per monitor"), which distinguishes it from single-diff or history siblings. It stops short of naming an alternative tool like get_diff or get_history explicitly, so the contrast 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?

It gives an explicit example query ("what changed on my competitor pages this month?") and explains the mode choice as a when-to-use decision: net_change compares period endpoints, each shows every step. It lacks explicit exclusions such as "use get_diff for a single page" and does not mention paging behavior.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the default comparison window, but it does not disclose that output is capped by max_lines (default 400, max 5000) or how truncation manifests — a behavioral trait an agent calling this on large monitors 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?

One front-loaded sentence with the core purpose first and the word_diff alternative after a semicolon; no wasted 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 6-parameter read tool with no output schema, the description covers the essential diff semantics but leaves out output truncation, what the diff looks like, and the meaning of the context parameter. Adequate to call it, not complete enough to predict its 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 coverage is 67% and the description only restates the word_diff mode, which the schema already documents in detail. The two undocumented parameters, context and max_lines, get no explanation in either place, so the description does not compensate for the coverage gap.

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 ('Unified diff of one monitor between two of its snapshots') plus the default snapshot pair, which clearly separates it from siblings like get_snapshot, get_history, and list_snapshots.

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: the agent can infer this is the tool for comparing snapshots, and the word_diff clause gives one concrete when-to-use case ('better when a word changes in a long paragraph'). There is no explicit guidance on when to prefer get_snapshot or get_history instead, or on prerequisites such as having at least two snapshots.

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/idempotent/non-destructive, so the safety profile is covered. The description adds meaningful behavior beyond that: the >50 snapshots sampling-down rule, truncation via max_chars on the first snapshot and max_lines across diffs, and the relative_to diffing semantics. It stops short of describing failure behavior or what the combined output looks like, 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?

The core framing is front-loaded in the first clause, then parameter mechanics, then the sibling pointer—a logical order with no filler. The middle is dense and semicolon-chained, requiring a careful read, but no sentence 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 9-parameter read tool with no output schema, the description covers selection, sampling, truncation, and diff modes well. The main gap is the undocumented 'context' parameter, which an agent would have to guess at; everything else needed to call it correctly 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 78%, and the description goes beyond the schema by explaining interplay between from/to/timestamps/sample (evenly spaced, first and last included, capped at 50) and the meaning of both relative_to modes. It does not clarify the unexplained 'context' parameter, which neither schema nor description covers, so not 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 opens with a specific verb and resource ('Several snapshots of one monitor in one call') and immediately explains the compact representation: first snapshot in full, the rest as diffs. It also distinguishes itself from the sibling line_timeline for list-content questions, so an agent can differentiate 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?

It states the exact question this tool answers ('how did this page/its prices change over time?') and names the alternative plus its selection condition: use line_timeline for 'what was added' on a list because it is smaller. Both when-to-use and when-to-prefer-a-sibling 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 declare readOnly/idempotent/non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavior: only the latest screenshot is retained (retention policy), results are a slice rather than a full page, and screenshots only exist for browser fetchers — a real availability constraint. It stops short of describing the image format or the response when no screenshot exists.

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 what the tool returns, then when to use it, then the paging/retention constraints. 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?

With no output schema, the description correctly states the return type (an image) and that it is a partial view requiring offset paging. The one remaining gap is what happens when no screenshot has been captured yet, though the 'only browser fetchers' note partially signals the failure mode.

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

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

Schema coverage is 67%, and the description supplies the missing context for the undocumented `which` enum by defining that 'error' means the last failed check. It also explains why `offset` exists ('full pages are long, so it's a slice: page down with offset'), reinforcing the schema's 'pixels from the top' note with the paging intent.

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 ('the latest screenshot of a monitor's page as an image') plus a variant ('its last failed check with which='error'), and immediately contrasts it with the text-based siblings ('for what the text can't show'). An agent can distinguish this from get_snapshot/get_diff 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 concrete selection criteria against the text tools — 'layout, images, a banner, a cookie wall, a block page' — and a precondition ('Only the browser fetchers take screenshots'). It implies rather than names the text alternative (get_snapshot), so the routing is clear but not fully explicit.

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

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

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, so the description only needs to add context. It does: default to latest snapshot, default to filter-selected content, pagination for multi-monitor calls, and the retention constraint that unfiltered/html data only survives the newest two snapshots. It does not say what happens when a watch string matches several monitors or when no snapshot exists.

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 with stacked parentheticals, so the useful facts (selection modes, paging, filter default, retention) are present but require re-reading. The purpose statement is front-loaded, yet the fried-cheese example is longer than the rule it illustrates.

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 nine parameters, no output schema, and no required fields, the description covers input selection and filtering well. It leaves the return shape unaddressed: for a multi-monitor or paged call it never indicates whether text comes back per monitor, in what order, or how truncation via max_chars surfaces.

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 89%, so the baseline is 3, but the prose adds genuine meaning: it explains the mutual roles of watch vs watches vs tag (one monitor vs several vs a group) and how unfiltered inverts the default filter behavior. That relational context is not fully spelled out in the schema 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?

The description names a concrete resource (a monitor's page text) and the snapshot-time qualifier, plus the three selection shapes (watch, watches, tag) and paging. It is clearly distinct from get_screenshot or get_diff in substance, but never names a sibling to route the agent 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 gives a real when-to-use cue for the unfiltered mode ('for questions its filters don't cover') with a concrete example, which is genuinely helpful. However, it offers no guidance on choosing this tool over get_diff, get_history, or list_snapshots, so the cross-tool decision 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?

The annotations already establish that this is a safe read-only, idempotent, non-destructive operation. The description adds substantial behavioral context by explaining the returned health/load signals, including failing/paused/overdue counts, queue size, and active worker assignments with durations.

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 front-loads the health/load purpose, then lists the concrete metrics efficiently, ending with a focused diagnostic use case. Every sentence and item 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 zero-parameter, read-only diagnostic tool with no output schema, the description supplies enough detail about what the agent will learn and why to call it. Nothing essential for correct invocation appears to be missing.

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

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

The tool has zero parameters, so there is no parameter meaning for the description to add. The baseline for zero-parameter tools is 4.

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 goes far beyond the vague name by specifying the exact diagnostic resource: monitor health counts, queue size, fetch workers, and current assignments. It clearly distinguishes this system-wide health/load view from the monitor-specific siblings such as get_watch or list_watches.

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

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

It gives a clear when-to-use cue: diagnosing why monitors are slow or not being checked. It does not explicitly name alternatives or when not to use it, so it falls short of full 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 readOnly, idempotent, non-destructive, and closed-world, so the safety story is covered. The description adds genuinely useful behavior content it alone can supply — the shape of the response (settings, status, last error, price/stock, diff) — since no output schema exists. It does not say how ambiguous watch matches are handled, which is the remaining gap.

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 resource and its contents, then the usage trigger. Nothing is redundant and the 'in one call' clause earns its place by signaling efficiency versus composing other tools.

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

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

For a single-parameter read with full schema coverage and clear annotations, the description covers what matters: scope, payload contents, and use case. Only the failure/ambiguity behavior for a non-unique watch match is left implicit by 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%, and the schema entry already explains uuid / partial title / partial URL matching including the single-match constraint. The description's use of 'watch' implicitly maps the parameter to a monitor, but adds no syntax or matching detail 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?

The description names a specific resource ('one monitor') and enumerates exactly what comes back: settings, status, last error, price/stock, and the latest change as a diff. That distinguishes it from list_watches and from the get_changes/get_diff pair without naming them, though naming a sibling explicitly would have pushed this to 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?

'Answers "what changed on X?" in one call' gives a clear usage trigger and implies that this replaces chaining get_changes + get_diff for a single monitor. There are no explicit when-not conditions or named alternatives, so it stops short of full 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 readOnly, idempotent, non-destructive, so safety is covered; the description adds real semantics beyond that: de-duplication by line, first/last-seen timestamps, reappearance not counting as new, and the include_start exclusion. It omits pagination/result-size behavior despite limit/offset parameters, 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?

Front-loaded with what the tool yields, then differentiation, then exclusions, then filters - a logical order with no filler. The compressed phrasing ('Narrow it with 'text' (or a regex) and 'from'/'to'') is efficient but slightly telegraphic.

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 10-parameter read tool with no output schema, the description covers what is returned, the default exclusion rule, and most filters, which is enough to call it correctly. The remaining gap is pagination/limit behavior, which an agent may have to discover empirically.

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

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

At 60% schema coverage, the description partially compensates: it clarifies regex mode for 'text', the from/to narrowing, still_there=false meaning 'removed', and include_start behavior. It says nothing about limit, offset, or case_sensitive, leaving three parameters to the schema alone.

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 exact resource and shape of the result: 'every line that appeared on a monitor's page, once each, with when it was first and last seen,' and lists concrete examples (tour dates, line-up additions, headlines, changelog entries, products). It explicitly distinguishes itself from the sibling get_history, so an agent can pick between them 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?

'Better than get_history for lists that grow and shrink or pages that flip between layouts' gives both the alternative and the condition that selects this tool, plus the rationale (a returning line isn't new again). It also states the default exclusion of first-snapshot lines and how to change it, and points at filters for narrowing.

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

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

Annotations already cover read-only, idempotent, non-destructive, and closed-world, so the safety bar is low. The description adds real value beyond that: secrets are masked in the output, a position index is included for remove_notification, and the level's notification format/title/body are returned — non-obvious details an agent could not infer from the 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?

It is a single short sentence with no padding, which is good, but it is a grammatically incomplete fragment whose clauses ('that level's notification format') are hard to parse. The key facts — what is returned and why the position matters — are buried mid-sentence rather than front-loaded.

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

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

With no output schema, the description carries the burden of explaining returns, and it does list secrets-hidden URLs, positions, format, title and body. It still leaves gaps: what 'that level' refers to, ordering, and whether an empty result means no notifications or an invalid tag/monitor.

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 are already documented, including the 'instead of the global settings' framing. The description restates the same three-way scoping choice without adding syntax or format detail, so it neither helps nor harms beyond the schema baseline.

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

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

The description identifies the resource (Apprise notification URLs) and its three scopes (global settings, tag, monitor), but it is a sentence fragment with no verb — it never says 'list' or 'retrieve'. It also does not distinguish this from the sibling notification_services, which an agent could plausibly confuse with it.

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 signals usage by noting the position number is meant 'for remove_notification', which hints at a read-then-mutate workflow. However, there is no explicit statement of when to pick this tool over notification_services or when to omit tag/watch, leaving 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?

Adds substantial behavior beyond the readOnly/idempotent annotations: default summarization above 60 snapshots, exactly which aggregates the summary contains, the full=true escape hatch, and definitions of the SHRUNK and RECOVERED flags that appear in results. This is the kind of return-shape and semantics disclosure 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?

Front-loaded with what is returned, then the summary/full behavior, then flag definitions, then usage — a logical order with no filler. The flag definitions are dense but each sentence earns its place; minor cost is the telegraphic 'SHRUNK:'/'RECOVERED:' phrasing.

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

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

For a 6-param read-only listing tool with no output schema, the description covers the return payload shape, the summary-vs-full behavior, and the meaning of result flags — precisely the information an agent would otherwise lack. Pagination is left to the schema's limit/offset descriptions, which is acceptable.

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

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

Schema coverage is 67% and the description clarifies full=true ('lists them all') and the summary threshold, adding real meaning. It adds nothing for limit, offset, to, or from beyond what the schema already documents, so the baseline 3 is right.

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 snapshot dates for one monitor) plus what each snapshot contains (size on disk). It is clearly distinguishable from siblings like get_snapshot (single) and get_history by naming the monitor-scoped listing semantics.

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 says 'Use it to see how far the history goes and pick dates', which frames the retrieval purpose, and explains the summary/full distinction. It does not name sibling alternatives (get_snapshot, get_history) or state when not to use it, so it stops 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, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so safety and idempotency are covered structurally. The description's only extra behavioral content is that results include a per-tag monitor count, which is genuinely useful return-shape information. It says nothing about ordering, whether empty tags appear, or whether counts include all/only active 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?

One short sentence with no waste, which is appropriate front-loading for a trivial read tool. However, the grammar is broken ("The tags (groups) monitors are organised in" is missing a relative pronoun), making the sentence harder to parse than a plain 'List all tags with their monitor counts' would be. Brevity is achieved at some cost to 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?

For a zero-parameter, read-only, no-output-schema tool, the description covers the essential return content (tags plus counts). It leaves open ordering, whether zero-monitor tags are included, and how tags relate to the watch-oriented sibling tools, which an agent choosing among the list_* family would want.

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 no parameters (zero-param baseline is 4), and the description correctly spends no words on inputs. It cannot meaningfully add parameter meaning beyond 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?

The fragment "The tags (groups) monitors are organised in, with how many monitors each has" does convey the resource (tags/groups) and what is attached to it (per-tag monitor counts), which is more specific than a restatement of the name. But it is a noun phrase rather than a verb+resource statement, so the act of listing is only inferred from the tool name. It does implicitly distinguish itself from get_watch/list_watches by returning tag-level groupings rather than watches.

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 guidance on when to call this versus the many list_* and get_* siblings (list_watches, list_snapshots, list_notifications). No prerequisite, no context about whether tags must be pre-created or how they relate to watches. The agent must infer usage entirely from the name.

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 establish the read-only, idempotent, non-destructive profile, so the description's job is to add value beyond that and it does: it discloses that history aggregates (snapshot count, first/last date, day span) are computed and returned per monitor, which is non-obvious behavior. It adds nothing about pagination defaults or result-size limits, which are only in the 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?

Two dense sentences that lead with the resource and returned fields, then pivot to sorting; the motivating query is a genuine payoff rather than filler. Slightly long sentence structure but no wasted clauses.

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 explain return values and it does so field by field, including the derived history metrics that an agent would otherwise have to probe. For a six-parameter list tool with strong annotations, this is nearly complete; only paging and filter-combination behavior are left 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 67% and the schema already spells out every sort mode and documents tag, search, and with_errors, so the description's mention of first_snapshot, snapshots, and history_span largely restates structured data. It never clarifies the interaction of tag/search/with_errors filters or the limit/offset paging, so it adds only marginal 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?

"List the web page monitors (watches)" is a specific verb plus resource, and the description enumerates the returned field set (uuid, URL, tags, last change, error, history aggregates), so an agent knows exactly what it gets back. It does not explicitly contrast itself with the singular sibling get_watch, so sibling differentiation is left 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?

The description supplies a concrete motivating query ("which monitors have the longest history?") and states that sort options make it answerable "in one call", which gives clear when-to-use context. It offers no exclusions or named alternatives, 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 cover the safety profile (read-only, idempotent, non-destructive, closed-world), so the description need not restate that. It adds genuinely useful behavioral context beyond annotations: the response describes per-service URL forms, required tokens, secret classification, and provenance for obtaining them, which is exactly what an agent needs to reason about setup.

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 clause about the no-search default; the conditional behavior is front-loaded as a trailing note. Slightly awkward punctuation around 'Without search' but essentially zero 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 one-optional-parameter read-only lookup, the definition is mostly adequate, but it does not clarify the output shape (a list vs. one entry when searching), nor whether the token/secret metadata is exhaustive. With no output schema, a sentence on return structure would improve completeness.

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 percent and the single parameter already documents that it accepts a service name or scheme with the example 'slack' or 'tgram'. The description reinforces the search/no-search duality (omitting it returns the full list) and mentions scheme matching, which adds modest meaning over 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?

The description states specifically what the tool returns: notification service setup details, URL forms, required tokens, which are secrets, and where users obtain them, across Slack, Discord, Telegram, email, ntfy, Teams and 140 more. It is clearly distinguishable from sibling list_notifications (which presumably lists configured notifications) although the name alone could suggest a list of active notification channels.

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 implies usage: call without 'search' to get the full list of services, call with 'search' to look up a specific service by name or scheme. However it gives no explicit when-to-use/when-not guidance relative to siblings like list_notifications, and no workflow context (e.g. use this before creating a notification to find the right URL form).

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

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

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, so the safety profile needs no restating. The description earns credit for disclosing what comes back — lowest/median/highest price, current low/typical/high position, last price change with timing, and notification rules — which matters since there is no output schema. Return volume, pagination, or ordering of results is not addressed.

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 what the tool answers, then usage examples, then scope options. Little waste; the '(processor restock_diff)' aside is the only phrase that does not pay for itself.

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 four-parameter, zero-required read-only tool with full schema coverage and no output schema, this covers purpose, return contents, and all scope modes. An agent has everything needed to decide to call it and how.

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 parameter definitions already do the work and the baseline of 3 applies. The phrase 'All of them, one tag, a name search, or one monitor' usefully establishes that no arguments means everything, a fact the schema does not state. The in_stock filter and the single-match caveat on 'watch' 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?

Opens with a specific query object: which product monitors are in stock, at what price, with price history and notification rules. That is clearly distinct from siblings like get_watch or list_watches in intent, though it never names a sibling to route against. The parenthetical '(processor restock_diff)' is internal jargon that adds little for an agent.

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 two concrete user-intent examples ('what on my wishlist is back in stock?' and 'is anything cheap now?') plus the four scope modes, which tells an agent when this tool fits. It stops short of stating when-not to use it or which sibling to prefer for a single monitor's raw details.

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