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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description adds genuinely useful behavior beyond them: fixed page size of one Joist page per call, A-to-Z ordering, and the empty-page termination condition for the cursor loop. It does not describe error behavior or what a partial/invalid cursor returns.

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 tight sentences with no filler, and the key constraint (pagination termination) is front-loaded before the downstream-handoff note. The opening is a fragment ('Clients in your account with name, email...'), which reads slightly clipped but wastes no words.

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 two-optional-parameter read tool with no output schema, the description covers what is returned, ordering, pagination, search semantics, and how client_id is reused downstream. The one gap is that client_id itself is never listed among the returned fields, though its downstream use is implied.

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%, so baseline is 3; the description earns an extra point by clarifying that search matches partial tokens across name, email, phone or address and by spelling out the cursor termination rule (empty page) which the schema alone does not state. It largely echoes the schema's own parameter wording rather than adding new syntax detail.

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 (lists clients) along with the returned fields (name, email, phone, address) and the two operating modes: full A-to-Z pagination or search matches. An agent can immediately tell this is a read/list tool rather than a single-record fetch like get_client or a write like add_client.

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 concrete operating guidance: one page per call, pass next_cursor back as cursor, an empty page ends the list, and use search to narrow by name/email/phone/address. It also tells the agent where the resulting client_id is consumed (create_estimate, create_invoice, list_estimates/list_invoices filters). It stops short of explicitly routing to get_client for single-record lookups.

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