CPA: chats for a period (v1, deprecated)

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

Annotations already provide readOnlyHint, destructiveHint false, idempotentHint true, and openWorldHint true. The description adds that it is read-only and spends no money, reinforcing safety. It also mentions pagination and offset usage. However, it does not describe the return format or ordering of chats, which could be useful.

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 well-structured sentences with no filler. First sentence states core function, second adds safety and deprecation, third provides clear migration advice. Every sentence earns its place.

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 deprecated tool with no output schema, the description covers key aspects: purpose, safety, deprecation, and alternative. It implies pagination but could elaborate on the return structure (e.g., list of objects with specific fields). Acceptable given deprecation status.

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% with detailed parameter descriptions (RFC3339 format, page size, offset). The tool description does not add new parameter meaning beyond the schema, 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?

Description clearly states it returns a paginated list of target CPA chats starting from a given moment. It explicitly distinguishes from v2 by noting identical semantics but higher request limit, and includes deprecation status. The verb 'returns' with the resource 'paginated list of target CPA chats' is specific and complete.

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 recommends using cpa_chats_by_time_v2 instead, indicating when not to use this tool. It also mentions the higher request limit of v2 (40 vs 60/min), providing a clear reason for preferring v2. This is exemplary guidance.

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