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

readOnlyHint=true already establishes this is a safe read, and the description adds genuinely useful behavior beyond that: the 100-record page cap, the differing return payloads with and without include_profile, and the concrete upstream endpoint (GET /clients). It stops short of discussing ordering, total counts, or rate limits, so it is strong but not exhaustive.

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 dense sentences: purpose/search axes first, return-shape and pagination limits second, source endpoint last. Nothing is repeated from the schema and no sentence is 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 10 parameters and no output schema, the description carries the return-value burden and does so by describing both payload shapes and the page limit. It omits result ordering, whether a total count is returned, and behavior when no filters are supplied, which would matter for a zero-required-param search.

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 description coverage is 100%, making 3 the baseline, but the description adds cross-parameter meaning the schema does not: that searching covers name, email, or client number, that custom fields can act as a filter, and that include_profile changes the shape of the response rather than just a flag. This is meaningful value above the per-field schema text.

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 concrete verb+resource ('Search the practice's clients (patients)') and immediately enumerates the five search axes (name/email/client number, date ranges, external id, custom field). It also clarifies the practitioner-side terminology (clients = patients), leaving no ambiguity about what the tool returns. No sibling competes for this purpose.

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?

It implies when the tool is useful by listing searchable dimensions, and the include_profile flag is framed as an optional expansion. However, it never names an alternative (e.g. save_client for writes, get_client_diagnoses for clinical data) or states exclusions such as 'use X to create a client'. Usage is inferable but not prescribed.

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