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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, covering the safety profile. The description adds substantial behavioral context beyond annotations: it specifies the ordering, page size, summary-only return, absence of a total count, and the meaning of statuses (preview_failed = failed to publish, preview_draft = published in draft). These details inform the agent about the tool's output and paging contract, which annotations do not provide. 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?

The description is three sentences long and every sentence earns its place. It front-loads the core listing behavior (newest first, 20 per page, status and keyword) before moving to filters, then to return behavior and pagination, and finally to the website_id nuance. There is no fluff or repetition, and the structure is logical and easy to parse.

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 presence of an output schema (not shown but indicated) and annotations covering the safety profile, the description covers everything an agent needs to call this tool correctly: what it lists, filtering options, pagination semantics, the summary-only return, how to get full content, and when to pass website_id. It also explains the meaning of statuses that might otherwise be opaque. No essential usage information is missing.

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

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

Schema description coverage is 100% and each parameter has a basic description. The tool description adds meaningful semantics beyond the schema: it clarifies the status enum values (preview_failed and preview_draft are explained), explains that website_id is optional when the account has a single website, and clarifies the date range filtering is inclusive. It also explains the pagination behavior tied to the page parameter and has_more, which the schema does not. This adds value beyond the structured 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 lists generated articles with a specific ordering (newest first), pagination (20 per page), and the fields returned (publication status and target keyword). It distinguishes itself from get_article by explicitly saying it returns summaries only and directing the agent to call get_article with include_content=true for full body content. This is a specific verb+resource with clear scope and differentiation from siblings.

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 provides explicit usage guidance: it names the alternative tool (get_article) and the condition for using it (to read an article's body), explains pagination behavior (keep paging while has_more is true) since there is no total count, and instructs when to pass website_id (when the account has several websites, referencing get_account). It also enumerates the available filters (search, status, date range). This leaves no ambiguity about when and how to use the tool.

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