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

Goes well beyond the readOnly/idempotent/non-destructive annotations: it discloses cache-served reads ('reading does not put pressure on the platform'), the account_budget and next_check_after_seconds pacing contract with an explicit 'Do not poll faster', and the fact that filtered pages can return fewer than limit items so paging must continue while next_cursor is set.

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?

Front-loaded with purpose and paging, then filters, then budget guidance. Nearly every sentence adds new information, but the paragraph is dense and runs long, and the budget/business-brief guidance sits far from the operation it governs, making it easy to skim past a constraint like 'Do not poll faster.'

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 an 11-parameter read tool with no output schema and no parameter descriptions, the definition supplies the return fields, paging semantics, per-filter behavior, cache source, and rate-budget mechanics. Nothing an agent needs to call this correctly or interpret the response envelope 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?

With 0% schema description coverage, the description carries the full burden and does so: it defines unread, unanswered ('last message is from the customer', capped at 30 a page), tag, owner ('none, me, a workspace user id or an email'), handed_over, starred, archived, requests, and cursor round-tripping. Only limit and account_id are left to the schema, which is appropriate for an obvious required UUID and an obvious page size.

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?

Opens with a specific verb+resource and scope: 'Chats of one connected account, newest first', followed by the returned fields. It clearly states what is listed and the default order, but it does not distinguish itself from plausible siblings such as list_messaging_messages or list_attendee_chats, leaving the agent to infer that this is the inbox-listing tool.

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 routes the agent elsewhere: 'To learn about new messages, call wait_for_events instead of calling this again', plus 'Before you reply to a customer, read the business brief with get_business_brief'. It also gives a hard when-not rule ('never write in a handed-over chat') and per-filter conditions for each option.

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