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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), but the description adds substantial behavior beyond them: the chat UI it draws (Approve/Ask for changes/Approve all, greyed approved posts, Waiting/Approved/All filter), pagination limits (20 default, 100 max, next_cursor), and derived data semantics (approval.overdue, due_soon under 30 minutes, suggested_times). This is rich context an agent could not get from the structured fields.

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 purpose and trigger are front-loaded, which is good, but the description is a single dense block and contains redundancy: 'list_posts returns the same calendar without drawing anything' and 'Returns the same data as list_posts' say the same thing twice. The long status enumeration also partly restates the schema enum, diluting conciseness.

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 detailed, yet the description still flags notable data fields (targets[].local_time, approval.overdue, suggested_times). For a 7-parameter, zero-required, read-only tool, the coverage of filtering, defaults, paging and rendering behavior is complete enough to call it 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 only 57%, so the description must compensate, and it does for the highest-risk parameter: every status enum value is explained (e.g. changes_requested = 'sent back with notes to fix', failed = 'a target failed or needs action'), plus date format guidance for from/to (ISO 8601 with offset, UTC default) and paging via next_cursor. It adds meaning beyond the raw schema, though the brand parameter is only documented 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?

States a specific verb and resource ('Shows posts') plus the exact rendering scope: 'one approval list in the chat' with waiting posts first and approve/unapprove controls. It also explicitly differentiates from the sibling list_posts, which 'returns the same calendar without drawing anything', so an agent can distinguish the two without opening schemas.

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?

Gives explicit triggering conditions ('For posts just saved (by their post_ids), or when the person asks to see or review posts, such as "what is waiting for my approval?"') and names the alternative (list_posts) with the condition that selects it. Nothing about when to use this versus its sibling is left to inference.

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