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

Annotations (readOnlyHint=true) already indicate it's a read operation. The description adds that it runs the verdict engine, returns a sorted table, and can use sitemap_url or explicit urls. This provides useful behavioral context beyond annotations. No contradiction.

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 two sentences, directly stating the action and a practical use case. No redundant information, front-loaded with the core functionality. Efficient and clear.

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

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

Given that an output schema exists and annotations are present, the description provides a high-level overview and a use case. However, it lacks explanation of how cohort filtering works with the available parameters (e.g., the missing tag parameter). Overall, reasonably complete but 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 low (40%). The description adds meaning by explaining min_age_days as a filter and mentioning 'tag' (though not in schema), but does not elaborate on window, limit, or the interaction between urls and sitemap_url. Partially compensates for low schema coverage but leaves gaps.

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

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

The description clearly states the tool 'Run the verdict engine across a cohort... return a ranked table sorted by verdict priority then confidence'. The title 'Cohort report across posts' aligns, and the practical use case differentiates it from siblings like posts.verdict (single post) or posts.list (listing without verdicts).

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 a concrete use case: 'which three posts should I refresh this week?' indicating when to use (cohort evaluation for refresh decisions). It mentions filtering by tag and min-age, but the schema lacks a tag parameter, slightly reducing clarity. No explicit exclusions or alternatives are 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?

The description adds that the tool is a read-only GSC pull (consistent with readOnlyHint and idempotentHint) and returns sorted results. It does not disclose behavioral details like rate limits, authentication needs, or data freshness. Since annotations already provide safety and idempotency, the description adds moderate value.

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

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

The description consists of two short sentences that front-load the core purpose and end with sorting and source details. Every sentence adds distinct value without redundancy, making it highly concise and well-structured.

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

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

The tool has 5 parameters with 0% schema coverage and an output schema, yet the description omits parameter details and does not mention the output format. While the purpose is clear, the lack of parameter semantics and output specification leaves the tool incomplete for effective usage.

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%, so the description must compensate for parameter meaning. However, it only vaguely references positions and impressions, without explaining any of the 5 parameters (min_position, max_position, min_impressions, window, limit). This leaves a significant gap for the agent to understand parameter semantics.

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

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

The description clearly states the tool's purpose: scanning GSC for (page, query) pairs in positions 5-15 with non-trivial impressions and low CTR relative to position expectation, returning top results sorted by impressions. It specifies the tool is for title-rewrite wins and is platform-agnostic, distinguishing it from sibling tools that may be platform-specific or focus on other metrics.

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 the tool is used for identifying quick title-rewrite opportunities, but it does not explicitly state when to use or not use it compared to alternatives. No guidance is given on prerequisites or exclusion criteria, leaving the agent to infer usage context from the purpose.

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 indicate read-only, idempotent, non-destructive, open-world. The description adds that the tool requires configuration and optionally includes replacement URL, without contradicting annotations.

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

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

Two sentences, both essential: first explains what the tool returns, second states a critical prerequisite. No redundant content.

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 a single parameter, output schema present, and low complexity, the description covers all necessary information: output details, optional replacement, and configuration requirement.

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

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

The single parameter 'url' is fully described in the schema (100% coverage) with format and meaning. The tool description does not add further parameter details, so baseline 3 is appropriate.

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

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

The description clearly states that the tool returns a list of LLMs that no longer cite a given URL, including prior query and last-seen date, and optionally the replacing URL. This is specific and distinguishes from siblings like 'posts.decay_curve'.

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 notes the prerequisite of a configured citation-intelligence MCP endpoint, and the behavior when not configured (returns empty list). It does not explicitly compare to alternatives but provides clear context for use.

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 provide readOnlyHint, destructiveHint, idempotentHint, and openWorldHint. Description adds that it is a read-only GSC query and classifies trends, but does not reveal additional behavioral traits beyond annotations. No contradiction.

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 concise sentences front-loaded with main purpose. Every sentence adds value: first states the action, second provides context and read-only hint. 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?

With existing output schema and annotations, description covers key aspects. Mentions trend classification which adds value. Could be more complete regarding return values, but output schema likely covers that.

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 covers 50% of parameters with descriptions (only 'url' has description). Description adds context for 'weeks' (default 12) which is already in schema as default. No additional semantic meaning beyond 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?

Description uses specific verbs ('bucket', 'classify') and clearly states the resource (GSC clicks/impressions/avg-position). It differentiates from siblings by mentioning it underpins the verdict engine's decay rules.

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

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

Explicitly states it is a read-only GSC query and associates with the verdict engine's decay rules, indicating when to use. However, no explicit 'when not to use' or direct alternatives among siblings.

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 idempotentHint=true. The description adds valuable behavioral context: multiple discovery methods (sitemap, JSON list, Ghost API), bypassing discovery with urls, return fields, and filtering. No contradictions.

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 well-structured into two paragraphs: how it works and when to use. It is concise but could trim some redundancy, e.g., 'Discover posts via...' and 'Pass an explicit urls[]...' are clear but slightly wordy.

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 the tool's complexity (multiple discovery methods, 5 parameters, output schema present), the description covers discovery modes, filtering, and return metadata. It provides enough context for an agent to select and invoke correctly.

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

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

Schema coverage is high (80%). The description adds meaning by explaining the fallback environment variables for sitemap_url and the 'since' and 'min_age_days' filters. It goes beyond the schema by describing how urls bypass discovery, which is not 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?

The description clearly states the tool's purpose: 'Discover posts via an XML sitemap...' listing posts from any platform. It also distinguishes itself from sibling tools like snapshot, verdict, etc., by focusing on discovery and eligibility.

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?

Includes a 'When to use' section that explains the tool's role in discovering URLs for downstream analysis. It provides clear context but lacks explicit instructions on when not to use it or alternatives besides the implied different purposes of siblings.

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. Description adds behavioral context by detailing the brief's contents (verdict, reasons, raw numbers, etc.) and its purpose as a hand-off artefact. This goes beyond annotations without contradicting them.

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 concise sentences that immediately convey the tool's purpose and usage. No wasted words, front-loaded with key 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?

Tool has an output schema, so return values need not be explained. Parameters are simple (url, optional window). Description covers usage context and output content, making it complete for a read-only brief generator.

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 50% (only 'url' described). The tool description does not elaborate on parameters beyond mentioning the output content. Since coverage is not high, description should compensate but doesn't, resulting in a baseline score of 3.

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

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

Clearly states the verb 'Produce' and the resource 'markdown brief' with specific contents. Distinguishes from siblings by tying usage to specific verdict outcomes (refresh/expand/merge/double_down) from the sibling tool 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?

Explicitly says 'Use this as the hand-off artefact when verdict is refresh / expand / merge / double_down.' This provides clear when-to-use guidance and implies when not to use it, differentiating from alternative tools like posts.verdict.

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. The description adds that sources are best-effort (omitted if env vars missing) and that persist optionally writes to a local DuckDB cache, which is a side-effect not captured by annotations. No contradictions.

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 sentences: the first details purpose and sources, the second explains best-effort behavior, and the third summarizes read-only nature and cache option. Front-loaded with key information, no redundant 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?

Given the tool's complexity (multiple sources, optional caching, best-effort), the description covers input parameters, behavior, side-effects, and outputs comprehensively. The output schema exists but is not shown; the description still lists expected metrics. No 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 33% (only 'url' described). The description adds meaning for 'window' (30/60/90-day) and 'persist' (opt-in DuckDB cache), and explains the URL role. It clarifies the overall context (snapshot across sources) beyond the schema, compensating for missing parameter 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 clearly states the tool pulls a 30/60/90-day snapshot for one post across multiple signal sources, listing specific metrics (GSC clicks, Matomo visits, etc.). It distinguishes from siblings like 'posts.list' or 'posts.decay_curve' by focusing on a comprehensive per-URL aggregation.

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 a unified snapshot of a single post's performance but does not explicitly state when to use vs. alternatives like 'gsc.quick_wins' or 'posts.verdict'. No when-not-to or exclusion criteria are 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, and the description confirms 'does NOT mutate anything', adding detail about deterministic reason codes and the composition from snapshot+decay curve. No contradiction with annotations.

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

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

Three sentences, each adding value: purpose, deterministic details, and usage scope. No fluff, front-loaded with the core action.

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

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

Given output schema exists (so return values are covered), the description fully covers tool purpose, behavioral constraints, and mapping location. It is complete for its complexity.

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 low (33%, only url has description). The description does not explain the 'window' or 'persist' parameters, relying on the schema enum/default. With low coverage, the description should compensate but does not.

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

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

The description clearly states it runs a rule-based verdict engine on a single post, combining snapshot and decay curve to emit a verdict with reason codes and confidence score. It distinguishes from sibling tools like posts.refresh_brief by focusing on verdict generation.

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

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

Explicitly states 'Reporting only - does NOT mutate anything' and directs agents to hand the brief to a writer or AI rewrite tool to act on the verdict. It also mentions the deterministic rules file for inspection.

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