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

Beyond the readOnlyHint annotation, the description discloses concrete behaviors: it returns compact deals with server-verified human_summary sentences and a highlighted flag, caps results at 5 (max 10), and excludes availability-only matches. It also warns against automatic enablement of Kit's Picks, adding actionable behavioral context.

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 four dense sentences with no filler, and the core purpose is front-loaded. Each sentence earns its place: core behavior, return shape, usage lane, and sibling differentiation.

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 read-only listing tool with a fully documented schema, the description covers purpose, ordering, result caps, return content, special mode, and exclusions. Even without an output schema, an agent has enough to select and invoke this tool 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?

The input schema already covers all four parameters clearly, which sets a baseline of 3. The description adds meaningful semantics for highlighted_only by tying it to Kit's Picks and the 'never enable automatically' guidance, and reinforces the limit behavior. It does not repeat the schema's category or price descriptions, which is appropriate given their existing coverage.

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 a specific resource ('newest approved deals'), a clear ordering ('freshest first'), and a mode switch to Kit's curated picks. It also distinguishes itself from search_deals by noting that availability-only price-target matches are excluded here but included there.

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 explicit usage context: Kit's Picks are for broad discovery, including when the human does not yet know what to watch, and highlight_only should never be enabled automatically. It also explicitly situates the tool as complementing, not replacing, register_watch monitoring, and names search_deals as the alternative for availability-only matches.

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