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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world scope, so the safety profile is covered. The description adds meaningful behavioral context beyond that: a 100-record cap, ordering by name, and the important scoping rule that members without the whole-book role see only their assigned clients.

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 front-load the resource and returned fields, then add visibility rules, then filtering options. Every clause carries information an agent needs and there is no filler.

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?

With annotations covering safety and an output schema covering return shape, the description supplies the remaining critical context: result cap, ordering, role-based visibility, and filter semantics. The only omission is any explanation of firm_id, which keeps it from being fully complete for a 0%-coverage schema.

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 0%, so the description must carry all parameter meaning. It does well for three parameters—status values (ACTIVE, ARCHIVED), pipeline_stage values (LEAD through ARCHIVED), and that search matches name and email—but leaves firm_id completely unexplained, which is a clear gap given the zero schema 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 names a specific verb (List) and resource (clients and prospects in your firm's book), plus the fields returned and the 100-record cap, so the agent knows exactly what the tool does. It stops short of naming a sibling such as get_client_dossier or get_client_goals to contrast against, so it is clear but not fully sibling-differentiated.

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 implies usage by describing the filters (status, pipeline_stage, search term) and the role-based visibility rule, which helps an agent decide when this list is appropriate. However, it never states when *not* to use it or points to a sibling like get_client_dossier for single-client detail, leaving alternative selection to inference.

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