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

Annotations already declare the safe read-only, idempotent, non-destructive profile, but the description adds real context beyond them: the required BING_WEBMASTER_API_KEY, where to obtain it, the best-effort config_missing failure mode, the sort order, and the structural limitation that results carry no url. That is meaningful disclosure for a data-fetch tool.

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/paragraphs, front-loaded with what it does, then the sibling contrast, then the operational requirement. No filler, and each sentence carries distinct 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?

Output schema exists, so return values need not be explained, and the description still covers the key caveat (no url field) and ordering. Combined with a fully documented input schema and auth/failure notes, an agent has everything needed to invoke and interpret it.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds the rationale behind the position window (5-15 = quick wins) and notes non-trivial impressions, giving semantic framing beyond the raw defaults. It does not document limit/window syntax itself, 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?

States a specific verb and resource (scan Bing Webmaster Tools for queries in positions 5-15 with non-trivial impressions) and explicitly differentiates from the sibling gsc_quick_wins by noting the query-level vs (page, query) distinction. An agent can tell exactly what this returns 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?

Names the alternative (gsc_quick_wins) and the structural reason to choose it or not (query-level only, no url). It also supplies the motivational context for using it at all (Bing index backs Copilot/ChatGPT/Perplexity grounding). No explicit 'when-not-to-use' beyond that contrast, so it falls just short of 5.

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

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

Annotations already declare readOnlyHint, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavior context about result ordering (verdict priority, then confidence) and the sitemap env-var fallback, but says nothing about cost/latency of scanning a cohort or how many rows are returned relative to the limit.

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

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

Two sentences, front-loaded with the core operation and followed by a concrete example; no filler. The example sentence earns its place by making the ranked output interpretable.

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

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

An output schema exists, so return values need not be re-explained, and the description covers selection and ordering. But with 40% param coverage and a phantom 'tag' filter, an agent still lacks details on how cohort membership is actually determined (urls vs. sitemap vs. defaults).

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 40% across five parameters, so the description should compensate. It mentions min-age and a 'tag' filter — but tag is not a parameter at all, and it says nothing about urls, limit, or window semantics. The single nod it gives is partly misleading rather than clarifying.

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

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

It states a concrete verb+resource: run the verdict engine across a cohort, returning a ranked table sorted by verdict priority then confidence. That distinguishes it from the per-post siblings like posts_verdict. However, it claims filtering 'by tag and/or min-age' when no tag parameter exists in the schema, which muddies what the tool actually does.

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

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

The practical-use sentence ('which three posts should I refresh this week?') gives a clear, actionable scenario for selecting this tool and even describes how to read the result. No explicit alternatives or exclusions are named (e.g., vs. posts_verdict), 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 readOnly, idempotent, non-destructive, openWorld, so the safety profile is covered. The description adds real behavioral context beyond that: the ranking behavior ('sorted by impressions desc') and the fact it is a platform-agnostic GSC pull. It stops short of mentioning pagination or the effect of the window on the CTR curve.

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

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

Three tight sentences, front-loaded with the core scan logic before the outcome and the return-ordering note. No filler, and each sentence carries information an agent needs.

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

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

An output schema exists, so return-value explanation is unnecessary, and the description covers the filtering heuristic and sort order well. The main residual gap is the undocumented window parameter, which materially affects which pairs qualify as 'quick wins'.

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 0% across 5 parameters, so the description has to carry the load. It clarifies min_position/max_position ('positions 5-15') and min_impressions ('non-trivial impressions'), which is useful, but leaves the window enum (30/60/90) and the limit/cap undefined in both schema and prose.

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 (Scan) and resource (GSC page/query pairs) with a precise scope: positions 5-15, non-trivial impressions, CTR below position-expected curve. It also implicitly distinguishes itself from the sibling bing_quick_wins by declaring itself a 'Pure GSC pull - platform-agnostic'.

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

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

Gives clear context for use ('the fastest title-rewrite wins'), which tells the agent what decision the tool supports. However, it does not explicitly state when to prefer this over bing_quick_wins or the refresh_brief siblings, leaving the alternative selection to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive/open-world, so the safety profile is covered. The description adds genuinely non-structured behavioral context: the dependency on a configured citation-intelligence endpoint and the degraded-mode result (empty list) when it is absent, plus the shape of what is returned.

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

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

Two tight sentences: the return content is front-loaded, and the operational caveat follows immediately. No filler or repetition of the name or title.

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

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

For a one-parameter, read-only tool with an output schema and rich annotations, the description covers purpose, degraded-mode behavior, and return content. The only missing element is routing guidance against sibling tools, which is a minor gap.

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

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

Schema description coverage is 100% for the single url parameter, so the schema already carries the meaning. The description adds nothing about the URL's expected format or canonicalization beyond what the schema states. Baseline 3 is appropriate.

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

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

States a specific verb (Return) and a precisely defined resource (LLMs that previously cited this URL but no longer do), plus the payload fields (prior query, last-seen date). This 'citation loss' concept is clearly distinct from sibling tools like posts_decay_curve, posts_snapshot, and posts_verdict.

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 discloses a usage prerequisite (a configured CITATION_INTELLIGENCE_URL, otherwise an empty list), which is useful context. However, it never says when to prefer this tool over alternatives such as posts_decay_curve or posts_verdict, and no exclusions are given. Implied usage only.

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, destructiveHint=false and openWorldHint, so the safety profile is covered; 'Read-only GSC query' largely restates them. The description does add real value by explaining this feeds the verdict engine's decay rules, but it says nothing about rate limits, latency, or data freshness.

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 operation, followed by context and the read-only note. 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?

An output schema exists, so return values need not be explained, and the description still conveys the key output shape (the three trend classes). Combined with annotations covering safety, the definition is nearly complete; only alternative-tool routing guidance is missing.

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

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

Schema coverage is 50% – url is documented, but weeks has no schema description. The description partially compensates by giving the default ('default 12'), though it omits the schema's 4-52 bounds. Baseline 3 is appropriate given only half the parameters are documented structurally.

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: bucketing GSC clicks/impressions/avg-position into weekly windows and classifying the trend as decay/plateau/growth. The metric set and output classification make the purpose unambiguous. It does not explicitly contrast itself with the sibling posts_verdict, but the resource is distinct enough 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 description places the tool in context ('underpins the verdict engine's decay rules'), which implies when it matters, but gives no explicit when-to-use versus alternatives such as posts_verdict or posts_snapshot. Usage is inferable rather than stated, which is the definition of a 3.

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/openWorld/non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: the env-var vs arg precedence (sitemap_url overrides POSTS_SITEMAP_URL), the configured Ghost API fallback, and the returned metadata fields.

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

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

Three tight paragraphs: discovery modes first, then return/filter shape, then the when-to-use routing. Every sentence carries information an agent needs, with no restatement of the name or 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?

With an output schema present, the description needn't enumerate return values, yet it does so briefly without harm. Safety and discovery configuration are well covered; the only gap is the limit parameter's role in result truncation and any pagination behavior.

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

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

Schema coverage is already 80%, so the baseline is 3, but the description adds precedence rules not present in the schema chain ('sitemap_url arg overrides POSTS_SITEMAP_URL env var', 'required if neither env var is set') and clarifies urls[] as a full bypass. The limit parameter is still unexplained, but the added meaning is genuine.

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 (discover/list posts) and enumerates the three discovery mechanisms plus the explicit urls[] bypass, which no sibling offers. It also distinguishes itself from the snapshot/verdict/cohort tools by framing itself as the eligibility-discovery step that feeds 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?

It gives a clear 'When to use' line tying the tool to snapshot/verdict/cohort analysis and explains the alternative path (pass urls[] to skip discovery). It stops short of stating when NOT to use it or how it differs operationally from posts_snapshot, but the routing context 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 readOnlyHint, destructiveHint=false and openWorldHint, so safety is covered. The description adds the output artefact type (markdown) and its audience, which is useful, but it does not explain why idempotentHint is false (e.g., numbers shift with the window) or any rate/permission 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 artefact's content before the usage rule. No filler, though the second line could be merged more tightly.

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

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

An output schema exists, so return values need no explanation, yet the description helpfully previews the brief's sections and anchors the verdict vocabulary it hands off from. Reasonably complete for a 2-param read-only tool; only the undocumented 'window' parameter leaves a hole.

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 50%: 'url' is documented in the schema while 'window' has no description anywhere, including its enum of 30/60/90. The description mentions no parameters at all, so it does not compensate for the 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+resource ('Produce a markdown brief') and enumerates the sections it contains (verdict, reasons, raw numbers, top queries, suggested actions). It implicitly distinguishes itself from the sibling posts_verdict as the downstream artefact rather than the verdict itself, but never names a sibling explicitly.

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

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

'Use this as the hand-off artefact when verdict is refresh / expand / merge / double_down' gives a clear trigger condition tied to the sibling tool's output vocabulary. It does not state when NOT to use it or what to use instead, but the context 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 readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuinely useful behavior beyond that: each source is best-effort and silently omits fields when env vars are missing, and it clarifies the local DuckDB cache write under persist=true. Minor tension with idempotentHint=false and the cache write, but not a contradiction of the read-only claim.

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, well-separated blocks that are front-loaded with the core purpose and then the caveats. No redundant sentences; each line (signal list, best-effort behavior, read-only + persist) carries distinct 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?

An output schema exists so return values need not be explained, and annotations cover the safety profile. The description fills the remaining gaps — which sources are queried, best-effort omission behavior, and the optional cache write — leaving nothing an agent needs to call it correctly.

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

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

Schema coverage is only 33%, so the description must compensate. It documents the window values (30/60/90-day) and the persist semantics (local DuckDB cache), effectively covering the two undocumented parameters. The url parameter is left to its schema 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 (pull) and resource (30/60/90-day snapshot for one post), and enumerates exactly which signals are aggregated (GSC, Matomo, GA4, Clarity, AI citations). This makes it disambiguable from aggregation siblings like posts_verdict and posts_refresh_brief, though it never names them 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?

Usage is implied by the content (raw per-URL data gathering vs the sibling report/verdict tools), but there is no explicit when-to-use or when-to-prefer-an-alternative guidance. An agent must infer routing from the tool name and 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, so safety is covered; the description usefully adds that reason codes are deterministic, that the verdict carries a 0-1 confidence, and that it performs no mutation. It does not clarify the tension between the 'does NOT mutate' claim and the schema's 'persist' flag, nor the non-idempotent hint.

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

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

Front-loaded with the operation, then behavior, then the routing alternative in three tight sentences. The pointer to src/verdict/rules.ts is a minor implementation detail that slightly dilutes an otherwise efficient block.

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

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

An output schema exists, so return values need not be described, and the description is adequate on purpose and safety. But two of three parameters (window, persist) remain unexplained, and the persist flag sits awkwardly against the 'reporting only' framing, leaving an agent with real gaps before 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 only 33% — url is documented, but 'window' (30/60/90) and 'persist' are bare. The description never explains what window means (trailing days?) or what persist=true does, which is especially important given the explicit 'does NOT mutate anything' claim.

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 ('Run the rule-based verdict engine on a single post') and names the exact inputs it combines (snapshot + decay curve) and outputs (verdict, reason codes, 0-1 confidence). The 'single post' scope also differentiates it from list-oriented siblings such as posts_list.

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

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

Gives clear context (per-post verdict after snapshot and decay data exist) and an explicit when-not: it is reporting only, and acting on the verdict is routed to a writer or AI rewrite tool. It does not, however, say when to prefer this over sibling read tools like posts_snapshot or posts_decay_curve.

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