Cohort report across posts

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.